# 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:

```bash
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`** (or `vision`, 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:

1. formatters, linters and the test suite enforce anything machine-checkable;
2. `CLAUDE.md` holds always-on rules;
3. `skills/` hold focused procedures that apply those rules;
4. `roles/` supply the independent judgment tools cannot provide.

A role that restates what a linter already enforces adds tokens and no coverage.