feat(agents): rescue long advisors via -deep suffix, unify source of truth#4500
Merged
Conversation
bokelley
added a commit
that referenced
this pull request
May 13, 2026
…truth
`.agents/roles/` is now the single source for all subagent prompts, with
two forms per role:
- `{name}.md` — short triage checker (terse, PR-bound, used by triage
routine)
- `{name}-deep.md` — long-form design advisor (full reasoning) for
open-ended work like MCP tool surface review or threat modeling
Nine `-deep` counterparts are now reachable that had been silently
shadowed by the short `.claude/agents/` versions for ~7 months: MCP
agentic-API design review, context-window efficiency lens, threat
modeling depth, curriculum architecture, etc.
`.claude/agents/` and `.codex/agents/` are fully generated by
`scripts/import-claude-agents.mjs`. The script gained a
filename-matches-frontmatter-name check and a duplicate-name guard.
Addie's expert-panel system-prompt section filters out `-deep` variants
so each persona appears once (server/src/addie/rules/index.ts), with a
regression test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Info callout added to dist/docs/3.0.7/building/validate-your-agent.mdx in #3826 linked to /docs/building/validate-with-mock-fixtures, but the page actually lives at /docs/building/verification/validate-with-mock-fixtures (the IA Phase 2 path that #3826 itself migrated to in the live docs/ copy). The link in dist/ was missed during that migration, fails CI's broken-links check on every PR that touches docs/ or addie source code, and is currently red on origin/main. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The legacy adcp_version alias in static/schemas/source/index.json had drifted to 3.0.12 (a non-existent release tag) while published_version and package.json are at 3.0.3. The pre-push verify-version-sync hook caught this; origin/main is in the same state but CI doesn't run the check, so it went unnoticed. Regenerated via `node scripts/build-schemas.cjs`; the only change is the one-line legacy alias. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
bokelley
force-pushed
the
bokelley/claude-agents-sync-strategy
branch
from
93f4d93 to
0450747
Compare
The previous fix(docs) commit tried to correct the link path. But the target page (validate-with-mock-fixtures) doesn't exist in the dist/docs/3.0.7/ snapshot at all — it was added to the live docs/ tree after 3.0.7 was cut. Either spelling of the link breaks one of two checks: broken-links (target missing) or check-dist-links (unversioned link in a versioned snapshot). The 3.0.7 snapshot should be immutable; PR #3826 violated that by adding the Info callout pointing at content that didn't exist when 3.0.7 shipped. Restore the snapshot to its pre-3826 state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 13, 2026
Merged
Closed
Merged
Merged
Merged
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
1 participant
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.
Summary
.agents/roles/becomes the single source of truth for all subagent prompts, with short triage checkers ({name}.md) and long design advisors ({name}-deep.md) co-locatedcode-reviewer-deep(agentic API design + context-window efficiency),security-reviewer-deep(deeper threat modeling),prompt-engineer-deep,docs-expert-deep, etc..claude/agents/and.codex/agents/are now fully generated byscripts/import-claude-agents.mjs(don't hand-edit)What was going on
.agents/roles/held 18 long-form expert personas (the original Codex-shared roles)..claude/agents/held 10 short triage checkers added in #2944 for the v2 expert-consultation step.The two directories shared 9 names. Claude Code's agent loader resolved the collision by picking
.claude/agents/, which meant the long advisor versions of those 9 names were silently unreachable — the "agentic API design", "context window efficiency", "MCP tool surface design", deep threat modeling content sat dormant.What changed
.agents/roles/(long) and.claude/agents/(short).agents/roles/directory.claude/agents/code-reviewer.md.agents/roles/code-reviewer.md.agents/roles/code-reviewer.md(shadowed).agents/roles/code-reviewer-deep.md(reachable).claude/agents/import-claude-agents.mjs.codex/agents/scripts/import-claude-agents.mjsnow also writes.claude/agents/*.md(verbatim copies of source), gained a frontmatter-name-matches-filename check, and a duplicate-name guard.Addie's expert-panel system-prompt section (
server/src/addie/rules/index.ts) filters out-deepvariants so each persona appears once in her lens reference. Regression test added..agents/routines/triage-prompt.mdupdated: triage uses short (non--deep) variants..agents/playbook.mdCross-Agent Integration section rewritten to describe the new layout.Test plan
node scripts/import-claude-agents.mjsproduces 28 files in each of.claude/agents/and.codex/agents/, byte-identical mirroring of sourcediff -rq .agents/roles/ .claude/agents/clean after syncexpert panel excludes -deep design-advisor variantsregression test)-deeppersonasFollow-up (separate PRs)
adcp-client,adcp-client-python,adcp-go,adcp-sdk-java🤖 Generated with Claude Code