Agents
The big picture: An agent is a focused helper Claude starts for one job — “review
this diff for permission bugs,” “write the changelog entry.” Blueprint ships 17 of them in
.claude/agents/. Most are gates: they read a change and say what’s wrong with it
before it merges.
Why it matters: One general-purpose session reviewing its own work misses the same things every time. A specialist with a fresh context and one checklist doesn’t get tired, doesn’t skip steps, and doesn’t share the author’s blind spots.
How they get used:
- Claude starts them on its own when a change matches their description (each agent’s
description:line says when). The Fast paths by change class table inCLAUDE.mdmakes that mandatory rather than optional, and it loads with the repository (see Start a project, step 7). - You can always ask for one by name: “run the security-review agent on this branch.”
- Not every agent runs on every change. A typo fix runs almost none; a new full-stack feature runs most. See Development workflow.
Reading the entries: Opus is the stronger, pricier model, used for judgment;
Sonnet is faster and cheaper, used for checklists. “Can delegate” means the agent may
start a few Sonnet sub-agents for parallel scanning. “Read-only” means it can’t edit files.
Four review gates (rbac-check, perf-check, ux-review, accessibility) can’t run
git diff either, so whoever starts one passes the diff in; each of their files says
exactly what, under Brief contract.
Nine read-only gates (regression-check, security-review, rbac-check, perf-check,
ux-review, accessibility, generated-artifact-check, schema-check, spec-review) no
longer see CLAUDE.md or AGENTS.md: each file names the rules it reads instead, so a rule
you add only to those two files will not reach them.
Reading the findings: every review gate grades what it finds the same way:
🔴 blocking, 🟡 should fix, 🟢 note. A 🔴 stops the MR until you decide. That
includes a gate saying it could not confirm something it is responsible for (marked
unconfirmed:). Each report ends with a count line, Findings: 🔴 <n> · 🟡 <n> · 🟢 <n>.
Each agent’s description also says when not to use it.
At a glance
Section titled “At a glance”| When | Agents |
|---|---|
| Before design | threat-model · spec-review |
| Design | architect · ux-design |
| Review the change | regression-check · security-review · rbac-check · perf-check · schema-check · generated-artifact-check · ux-review · accessibility |
| Finish the change | test-scaffold · completeness-check · changelog (optional drafter) · docs |
| On demand | dependency · wave-worker · wave-harness-worker (both spawned by /wave only) |
Before design
Section titled “Before design”threat-model
Section titled “threat-model”What it checks: Where data crosses a trust boundary in a planned feature — login, permissions, sessions or sync, tenancy, file uploads, payments, third-party input — and what an attacker could do at each crossing (the STRIDE method). It also lists each data element the feature stores or emits, including analytics and log events, with its sensitivity class, retention period and how it is deleted.
Why it matters: security-review finds holes in code that exists. This finds them in
the design, before any code is written, when moving a boundary costs a whiteboard instead
of a rewrite.
When: before architect, for any new subsystem that crosses a trust boundary.
Model: Opus · can delegate.
spec-review
Section titled “spec-review”What it checks: What the spec completeness gate cannot judge: acceptance criteria two reviewers could read differently, a feature that delivers something a non-goal rules out, a dependency a feature relies on in prose but does not declare, a persona no feature serves, a feature no persona needs, an NFR with no way to verify it, a decision with a foregone conclusion, and a risk nobody watches.
Why it matters: The gate counts parts; it cannot tell whether a criterion is decidable. A reader that did not write the draft can.
When: on a draft or ready spec under docs/specs/, after scripts/check-spec-completeness.py
passes, before the architect or /spec import. Not called by /wave.
Model: Opus · read-only · report-only (it blocks nothing and is not a CI gate).
Design
Section titled “Design”architect
Section titled “architect”What it checks: The technical approach, before implementation — technical debt, coupling, naming, migration risk, API changes, and whether the change can be undone. It raises blocking questions and recommends an approach.
Why it matters: Changing a plan costs minutes; changing merged code costs days. Do not start implementing until its blocking questions are answered.
When: any new feature, new endpoint, model change, or change to existing behavior. Not for a bug fix with a known cause, docs, dependency bumps, or chores. Model: Opus · can delegate.
ux-design
Section titled “ux-design”What it checks: Proposes the layout, components, interaction flow, and every state (loading, empty, error) for a UI feature — specific enough that whoever builds it makes no design decisions.
Why it matters: When design is left to the implementer, every screen invents its own patterns. One proposal up front keeps the product consistent.
When: after architect, before implementing any UI.
Model: Opus · can delegate.
Review the change
Section titled “Review the change”The first four below are the pre-MR gate batch: independent reads of the same diff, run together in parallel. Running them one after another was the biggest avoidable source of review delay.
regression-check
Section titled “regression-check”What it checks: Whether the change breaks something that used to work. It maps changed files to risk areas, finds stale test mocks and fixtures, runs the affected test suites, and checks every other consumer of any shared rule the change moved.
Why it matters: New code is reviewed carefully; the old code it quietly broke usually isn’t. This is the gate that looks backward.
When: before every MR on a branch that changes source code. Model: Sonnet · can delegate.
security-review
Section titled “security-review”What it checks: The OWASP Top 10, login and session handling, input handling, secrets, plus project-specific risks — for example, a field the API hides from some users but a real-time channel still broadcasts to them.
Why it matters: Security bugs are the ones that cost trust, not just time, and they’re easy to miss in a diff that “just adds an endpoint.”
When: any change to an endpoint, login logic, file upload, invite flow, or
user-controlled input.
Model: Opus (default; /wave runs it on Sonnet) · can delegate.
rbac-check
Section titled “rbac-check”What it checks: Access control on every endpoint: login required, each object scoped to users who may see it, roles enforced per action, every path that grants a role held to the same cap as its siblings, no field or query leaking data across users, and real-time connections closed when access is revoked.
Why it matters: A missing permission check is a security vulnerability, not a style issue — and it’s the single most common way one user sees another’s data.
When: any new or changed endpoint, view, route, serializer, or permission rule. It is
the one gate that checks per-action permissions; security-review and regression-check
don’t repeat it.
Model: Opus, under /wave too (a trial, measured in the gate ledger) · read-only.
perf-check
Section titled “perf-check”What it checks: N+1 queries, missing eager loading, unbounded result sets, missing transaction boundaries — and that every way an endpoint can grow (more rows, more columns, more members) has its own test.
Why it matters: These bugs are invisible with ten test rows and take production down with ten thousand.
When: any new or changed endpoint, query, or data-access path. Model: Sonnet · read-only.
schema-check
Section titled “schema-check”What it checks: Database changes: a migration exists and matches the models; destructive and table-locking operations are called out (and listed in upgrade notes); a new constraint can’t crash-loop a deploy on existing data; the change can be reversed.
Why it matters: A bad migration is the one deploy you can’t simply roll back. It runs on startup against real data.
When: whenever a model, schema file, or migration changes — before you push, not before the MR. Model: Sonnet.
generated-artifact-check
Section titled “generated-artifact-check”What it checks: Files generated from (or hand-copied from) your code — OpenAPI schemas, shared client types, SDKs, GraphQL or protobuf schemas, schema dumps, fixture snapshots — were regenerated from the fully merged code, and their shape matches what the code really returns.
Why it matters: A stale schema passes every check that compares it with itself. The bug shows up in a client, weeks later.
When: any change to an API surface, exported type, or public schema. Model: Sonnet.
ux-review
Section titled “ux-review”What it checks: UI code against your design system — color tokens, component reuse, type sizes, spacing, interactive states, and loading, empty, and error states. It also grades user-facing messages against the UX copy checklist (what happened, why, what to do next, no blame, no jargon).
Why it matters: Small inconsistencies add up to a product that feels unfinished. Some token mistakes look right in light mode and break in dark mode, so it sweeps the whole repo, not just the changed files.
When: after any UI change. Pairs with accessibility, which owns every accessibility
check. Reads .claude/rules/frontend.md
(see /import-design) and .claude/rules/ux-copy.md.
Model: Sonnet · read-only.
accessibility
Section titled “accessibility”What it checks: WCAG 2.1 AA: keyboard operation, screen-reader names, focus management (including focus that stays inside an open dialog), contrast, and touch targets.
Why it matters: An inaccessible screen locks people out. And unlike visual polish, it’s nearly invisible to a sighted mouse user reviewing the diff.
When: after any UI change. Model: Sonnet · read-only.
Finish the change
Section titled “Finish the change”test-scaffold
Section titled “test-scaffold”What it checks: Generates tests in your project’s existing style for code that has none — and requires watching each new test fail on the unfixed code before trusting it.
Why it matters: A test that has never failed might not test anything. Watching it go red first is the cheapest proof it does.
When: a new feature or bug fix with no existing coverage. Model: Sonnet · can delegate · can edit files.
completeness-check
Section titled “completeness-check”What it checks: The whole branch against its issue, by an agent that did not write it:
- every acceptance criterion and test-plan line in the issue and its comments;
- the whole class of bug, not just the reported instance;
- other code that relied on any shared rule the change moved;
- whether the tests can actually fail, and whether the docs are true;
- collisions with what has landed on
mainsince the branch started.
It tags each finding with its cause, and returns the Requirements table the MR carries.
Why it matters: An audit of 20 merged MRs in a sibling project found gaps in 16 — mostly breaking rules that were already written down. What was missing was anyone but the author checking before the push. The author’s context is the worst place to look for what the author didn’t think of.
When: every source or docs branch, before push, after the gate batch. Fixes go in a new commit; then at most one more pass:
- a narrow fix-diff re-check when a fix changed executable code;
- or a full round 2 (fresh agent on round 1’s model, not shown round 1’s findings) when round 1 found a structural problem.
On a branch that touches the rigor floor,
round 2 always runs, on Opus (after a Sonnet round 1 on the strict-light tier). Never a loop.
Model: Opus or Sonnet by risk tier, one audit per branch (see the agent file) · makes no changes (its rules forbid edits, commits, and pushes).
changelog
Section titled “changelog”What it does: Optionally drafts the one-line changelog fragment in changelog.d/
with the right type (added, changed, fixed, security). It is not a gate: the gate
is the changelog-check script (make check-changelog, also the CI job).
Why it matters: changelog-check blocks an MR without a fragment (and rejects a direct
CHANGELOG.md edit outside a release branch), and the release notes are assembled from
these lines — so they’re written while the change is fresh, not the night before release.
When: any branch that touches source, if you want a drafted fragment. Model: Sonnet · can edit files.
What it checks: Writes and updates user-facing documentation — structure, navigation,
version notes, a build check — and sweeps for old claims that the change made false, on
other pages, in README.md, and in changelog.d/.
Why it matters: Docs that describe last month’s behavior are worse than none: readers trust them.
When: any user-facing doc change, especially a new page. Model: Sonnet · can delegate · can edit files.
On demand
Section titled “On demand”dependency
Section titled “dependency”What it checks: A package before you add it: its license (blocks GPL-2.0/3.0), known vulnerabilities, whether your stack already does the job, and how much else it pulls in.
Why it matters: Every dependency is code you didn’t review and must keep patching. A license mistake can be a legal problem, not just a technical one.
When: before adding any new package. Model: Sonnet · can delegate · can search the web.
wave-worker
Section titled “wave-worker”What it does: Implements one /wave issue in its own Claude Code isolated worktree, then
commits and stops. It is not a reviewer.
Why it matters: It is pinned (ADR 0010). It has a fixed tool list with no Agent, and a
hook tier lets it run only listed commands and write only inside its worktree and outside
the harness. It never pushes or opens an MR: the orchestrator runs its gates, pushes the
branch from the worktree, and opens the MR.
When: spawned only by /wave Step 4, for an issue that changes no harness path. A
/wave --harness run uses wave-harness-worker instead.
Model: Sonnet · cannot delegate · no web.
wave-harness-worker
Section titled “wave-harness-worker”What it does: Implements one /wave --harness issue in the worktree the orchestrator made,
then runs its own pre-MR gate batch, commits and stops. It is not a reviewer.
Why it matters: It may change the harness, so nothing pins it. It exists so that
maxTurns, the per-run ceiling on an implementer, can reach the --harness agents too: a
built-in agent has no definition file to set it in.
When: spawned only by /wave Step 4, under --harness.
Model: Sonnet · can spawn its gate batch · has every tool available to subagents.
Go deeper
Section titled “Go deeper”- The model split, the delegation pattern, and writing your own agent: Agent architecture.
- The record each gate leaves in the MR, and how
/kaizenuses it: The gate ledger. - The source of truth: each agent’s own file in
.claude/agents/. Its front matter (model:,tools:,description:) is exactly what Claude Code reads.