james.bland
7ec467451b
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.
Agent integration sources
This directory is the client-neutral source of truth for agent behaviour. No
agent client owns the roles, the skills, or the capability policy. Client
directories (.claude/, .codex/) contain only the native files their runtimes
require, and those files are generated.
Layout
| Path | Purpose |
|---|---|
roles/*.md |
Portable role instructions plus reasoning, capability, mutation and reachability metadata. |
skills/** |
Agent Skills-standard content, mirrored verbatim into each client that declares a skills path. |
clients/*.yaml |
Declarative mappings from portable metadata to one client's native syntax. |
Regenerate and verify every registered client:
python3 scripts/sync-agent-integrations.py
python3 scripts/sync-agent-integrations.py --check
--check exits non-zero when a generated adapter has drifted, so it belongs in
CI. Generated files name their source and must never be edited directly — the
next sync reverts the edit.
To add a client, add a manifest under clients/. A client using an existing
native format needs no new role content; a genuinely new format adds one renderer
to the sync script.
Portable metadata
reasoning_tier — deep, balanced, fast, vision, inherit. Describes
intent, never a vendor's model name; each client maps it. Assign by rule rather
than taste:
- work whose output gates something — a merge, a release, a deployment — runs
deep(orvision, which maps to the same frontier model and additionally asserts the client can read images); - roles applying a written standard carefully run
balanced; - mechanical transformation with no judgment to get wrong runs
fast; - prefer not to use
inherit: it resolves to whatever model invoked the role, so the depth of a verdict comes to depend on its caller.
capabilities — read, search, list, shell, write. Mapped to each
client's tool names. Declaring them is not optional: before this layer existed,
four agents here declared no tools and therefore inherited the entire pool,
including the ability to edit files they were only meant to review.
mutation — read-only, workspace-write, external-write. Adapters must
fail safe when translating it. read-only roles are additionally pinned to a
non-editing permission mode where the client has one.
invocation — manual, hook, plan-time, or matrix where a repository
routes reviewers by changed path. Says how a role is actually reached, so a role
nobody can invoke is visible as a defect rather than looking like coverage.
preload_skills (optional) — skills the role should launch with already in
context, for a reviewer that grades against a standard a skill defines. Mapped per
client: a manifest declaring preload_support: false cannot honour it, so the
generated adapter names the skills and states the standard is not in context.
A declaration that silently evaporates between this layer and the client is worse
than one never made, because the repository goes on believing it took effect.
Where a rule belongs
A rule belongs at the highest layer that can hold it:
- formatters, linters and the test suite enforce anything machine-checkable;
CLAUDE.mdholds always-on rules;skills/hold focused procedures that apply those rules;roles/supply the independent judgment tools cannot provide.
A role that restates what a linter already enforces adds tokens and no coverage.