openshift / openshift/ocm-agent-operator
Document fullsend harness composition conventions in CLAUDE.md to prevent deprecated directory usage
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 3
- Forks
- 59
- Avg merge
- 10h 17m
- Merged PRs (30d)
- 25
Description
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:
- Directory structure: Harness files go in
.fullsend/harness/, NOT in.fullsend/customized/harness/(thecustomized/directories are deprecated per ADR-0064 and their contents are silently ignored). - Base composition pattern: Local harness files should use
base:to inherit from pinned upstream harnesses infullsend-ai/agentswith SHA-256 integrity hashes, adding only local overrides (e.g., Jira CEL triggers). - Agent registration: New agents must be registered under the
agents:key in.fullsend/config.yamlwith their harness source path. - Naming convention: The agent name must be
code(notcoder) — the rolecodermaps to agentcode, andname: coderwould 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 https://github.com/openshift/ocm-agent-operator/pull/338
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing Repo-Specific Constraints section in CLAUDE.md, then read .fullsend/harness/code.yaml, triage.yaml, and .fullsend/config.yaml for the repository's current composition and registration patterns. Add the requested Fullsend Configuration section documenting the non-deprecated paths, base composition, agent name, and registration rules, with those harness files as examples. Done means the guidance is present and matches the stated validation criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100