Eleven agents lived only in `~/.claude/agents/`, which is not a git repository —
they would have gone with the laptop. Eight of those were product-specific
reviewers already defined in the projects that need them, and they are removed from
the user level rather than duplicated here. Two were genuinely generic and already
product-neutral (zero references to any product, customer or employer), so they
belong in the shared scaffold: `mr-reviewer` reviews open MRs/PRs on a non-primary
remote in a multi-remote repository, and `solution-reviewer` does a whole-codebase
health review.
`irs-validator` is deliberately NOT brought in. It is personal tooling rather than
a development capability, and per the user CLAUDE.md personal tooling must not be
referenced inside a project repository because those are mirrored to other remotes.
The client manifest gains `fetch` and `websearch` capability mappings, which
`solution-reviewer` needs. Worth noting how that surfaced: the sync REFUSED to
render rather than dropping the two tools silently, which is the fail-safe
behaviour the capability mapping exists to provide — an unmapped capability that
rendered as absent would have quietly removed the agent's web access.
`~/.claude/agents/README.md` now records that ten of the eleven agents there are
installed output from this repository, how to regenerate and reinstall them, and
which one is deliberately personal.
`.claude/agents/` was the source of truth, which made every role Claude-Code
shaped. Adding a second client meant rewriting each role in that client's syntax
and maintaining both copies — the drift this scaffold exists to prevent, one layer
up.
Roles and skills now live under `.agents/` and render into each registered
client. `.claude/agents/`, `.claude/skills/` and `.codex/agents/` are generated;
`scripts/sync-agent-integrations.py --check` fails on drift and belongs in CI.
The role metadata is portable rather than vendor-named: `reasoning_tier`
(deep/balanced/fast/vision), `capabilities`, `mutation`, `invocation`, and an
optional `preload_skills`. A client manifest maps those to native syntax and must
declare what it cannot express — `codex.yaml` declares `tier_policy: unsupported`
and its adapters say so in the file, rather than the tier silently evaporating and
leaving the repository to believe it was enforced.
The port is behaviour-preserving where it should be and a fix where it should not.
Every instruction body is byte-identical — the whole diff to `.claude/agents/` is
18 added lines and zero deletions. What changed is frontmatter that was missing:
- four agents (`code-reviewer`, `tdd-guardian`, `dependency-audit`, `pr-creator`)
declared no `tools:` and therefore inherited the ENTIRE tool pool, so three
review-only agents could edit and write the code they were reviewing. All eight
now declare capabilities explicitly.
- the six read-only roles gain a non-editing permission mode, so the constraint is
enforced by the client rather than by the prompt asking nicely.
- `mutation` is now explicit, which records the two roles that genuinely need to
write: `pr-creator` (external-write — it pushes a branch and opens a PR) and
`dependency-audit` (workspace-write — package managers rewrite lockfiles).
`pr-creator` keeps `shell` because opening a PR needs it, but it is now the only
agent here with a write mutation and a declared reason for it, instead of one of
four with unlimited access by omission.
james.bland