refactor: agents and skills move to a client-neutral source that renders per client

`.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.
This commit is contained in:
2026-09-19 17:27:26 -04:00
parent e111e61832
commit 3f0786f1e7
53 changed files with 13801 additions and 2 deletions
+23
View File
@@ -0,0 +1,23 @@
# Native adapter manifest for Codex. `.agents/skills/` is already Codex's
# project skill-discovery path, so no generated skill destination is needed.
#
# tier_policy is `unsupported` and that is a DECLARATION, not an omission. No
# per-agent model key is confirmed for this client's generated agent TOML, and
# emitting one it ignores would be worse than the gap — the repository would
# treat the tier as enforced while nothing read it. Every generated adapter
# therefore carries a notice saying the tier is not enforced here, and
# `reasoning_tiers` must stay empty while this says `unsupported`.
#
# To close it: confirm the agent-level model key this Codex version reads, switch
# to "mapped" and fill `reasoning_tiers`. The sync then refuses any role whose
# tier has no mapping, and the notice disappears on its own.
{
"name": "codex",
"agent_format": "codex-toml",
"agents_path": ".codex/agents",
"skills_path": null,
"tier_policy": "unsupported",
"preload_support": false,
"reasoning_tiers": {},
"capabilities": {}
}