openshift / openshift/ocm-agent-operator

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

Open Beginner friendly
#339 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation kind/documentation priority/backlog ready-for-triage ready-to-code
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:

  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 https://github.com/openshift/ocm-agent-operator/pull/338

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.