Document fullsend harness composition conventions in CLAUDE.md to prevent deprecated directory usage

[fullsend-ai-retro]

What happened

PR #337 placed Jira CEL trigger harness files in .fullsend/customized/harness/, the deprecated overlay directory (ADR-0064). The overlay loop copies zero files from customized/, so the harnesses were silently ignored and Jira poll dispatch produced zero dispatches. The author (Claude Code + human operator) did not know the directory was deprecated. PR #338 was needed ~1.5 hours later to move the files to .fullsend/harness/ using base: composition — the correct pattern. Neither the review agent ($2.35), the retro agent ($2.97), nor the human reviewer caught the issue on #337.

What could go better

The repo's CLAUDE.md contains extensive documentation for Go development (build commands, test patterns, architectural boundaries, security guardrails) but has no section on fullsend configuration conventions. A code agent or human developer adding fullsend harness files has no in-repo guidance about the customized/ deprecation or the correct base: composition pattern. Adding this context to CLAUDE.md would prevent both AI agents and human developers from repeating this mistake. Confidence is high — the root cause was a knowledge gap, and CLAUDE.md is the established mechanism for providing repo-specific context to code agents in this repository.

Proposed change

Add a ## Fullsend Configuration section to CLAUDE.md documenting:

1. Directory structure: Harness files go in .fullsend/harness/, NOT in .fullsend/customized/harness/ (the customized/ directories are deprecated per ADR-0064 and their contents are silently ignored).
2. Base composition pattern: Local harness files should use base: to inherit from pinned upstream harnesses in fullsend-ai/agents with SHA-256 integrity hashes, adding only local overrides (e.g., Jira CEL triggers).
3. Agent registration: New agents must be registered under the agents: key in .fullsend/config.yaml with their harness source path.
4. Naming convention: The agent name must be code (not coder) — the role coder maps to agent code, and name: coder would silently no-op.

This should be placed after the existing "Repo-Specific Constraints" section and reference the existing .fullsend/harness/code.yaml and triage.yaml as examples of the correct pattern.

Validation criteria

The next time a code agent or human developer adds or modifies fullsend harness files in this repo, they place the files in .fullsend/harness/ (not customized/harness/) and use base: composition. No follow-up fix PRs are needed to correct the directory placement. Measurable over the next 3 harness-related PRs in this repository.

---

Generated by retro agent from #338

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 6:56 AM UTC · Completed 7:00 AM UTC

Commit: 0cff87b · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.71

[fullsend-ai-triage]

This retro-generated issue is well-specified and ready for implementation.

Proposed test case

# Verify the new section exists and covers all four conventions
grep -q '## Fullsend Configuration' CLAUDE.md
grep -q 'customized/' CLAUDE.md  # deprecation warning present
grep -q 'base:' CLAUDE.md        # composition pattern documented
grep -q 'config.yaml' CLAUDE.md   # agent registration documented
grep -q 'coder' CLAUDE.md         # naming convention warning present

Related context

Existing examples of the correct pattern are already in the repo at .fullsend/harness/code.yaml and .fullsend/harness/triage.yaml — the new section should reference these as canonical examples.

---

Labels: Documentation task adding fullsend conventions to CLAUDE.md; low priority preventive improvement.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance