feat(agents): version the Claude subagent definitions and install them as managed links - #655
Merged
Merged
Conversation
The agy-reviewer, codex-analyst and codex-implementer subagent definitions previously lived only at ~/.claude/agents/, outside any git repo, so they had no history and no backup. Bring them into the repo verbatim as the new source of truth, in a top-level agents/ directory kept separate from the skills/*/agents/openai.yaml Codex agent metadata.
Extend install-harness to link the repo's agents/*.md files into ~/.claude/agents/ on the same terms as skills and workflows: managed via symlink, tracked in a dedicated .agent-harness-agents-installation.json manifest, idempotent on re-run, and refusing to clobber an unmanaged user file with a conflict exit before any mutation happens.
Add coverage for the three managed subagent links: they install, a second install-harness run is idempotent, and an unmanaged conflict fails the whole install before touching skills or workflows.
Note the agents/ directory and its ~/.claude/agents/ install target in README's install and layout sections and in the orchestrate skill, which is what actually depends on these subagent definitions.
The new top-level agents/ tree matched no build filter, so an edit to a subagent definition would have skipped the harness job entirely and landed without ever being checked. test_every_tracked_path_matches_at_least_one_build_filter exists to catch exactly that, and it was failing. Claude-Session: https://claude.ai/code/session_01DsDFRG6NVWb2VBNNtVkQ6N
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The three Claude subagent definitions lived only at
~/.claude/agents/and were under no version control at all.~/.claudeis not a git repository and nothing in this product installed them, soagy-reviewer.mdin particular existed as a single unbacked copy on one machine.All three drive
skills/orchestrate/scripts/cf_dispatch.shand encode the orchestrate skill's dispatch contract, so they belong here.What this does
agents/tree holding the three definitions, byte-identical to the originalsinstall-harness --platform claudenow links them into~/.claude/agents/viascripts/install-agentsandscripts/agent_installation.py, wired through the existingmanage_installation.pyplan/execute machinery.agent-harness-agents-installation.json, following the same manifest placement and conflict rules as skills and workflowsagents/is kept separate from the existingskills/*/agents/openai.yamlfiles, which are Codex agent metadata and a different thing entirely.Verification
Byte identity against the live originals:
525594aa5b02dbdf2c5bfea5cc44bb819777fab52c6ba1e77d7e0354ff4f5a659752f0d18c713a4370df051f3f9eb55b2d5b650e33a0abde975bbf5ab6b807b85ea965d7d8c346180225bffe297b5d4f4c13a60cac3265527ece21adfbc925bfInstaller behaviour, exercised against scratch targets:
linked=3 existing=0, exit 0linked=0 existing=3, exit 0, idempotentscripts/check-harness: 1268 passed, 2 xfailed.One defect found during review
The new
agents/tree matched no CI build filter, so an edit to a subagent definition would have skipped the harness job entirely.test_every_tracked_path_matches_at_least_one_build_filterwas failing. Fixed in8367b545by addingagents/**to the harness filter.Migration note
Because the three files currently exist as unmanaged real files,
install-harnesswill exit 3 on any machine that already has them until they are removed. That is the intended fail-closed behaviour, not a bug, but it needs doing once per machine. The repo copies are byte-identical, so the migration is lossless.https://claude.ai/code/session_01DsDFRG6NVWb2VBNNtVkQ6N