Agent architecture
The big picture: Blueprint splits AI work two ways. Skills are workflows
started with /name (some only by you); agents are specialists Claude starts when a change needs them.
And each job goes to the cheapest model that can do it well — Opus for judgment,
Sonnet for checklists.
Why it matters: The right split keeps quality high where it counts and cost low everywhere else. Most of the bill in agent-heavy work is re-reading context, not writing code, so how many agents run — and on which model — decides what a feature costs.
How it works:
- Opus agents (architecture, security, permissions, design, the completeness audit) make the judgment calls. They hand mechanical scanning to a few parallel Sonnet sub-agents, then synthesize.
- Sonnet agents (regressions, performance, UX, tests, changelog) follow a checklist.
- Delegation stops at one level. A sub-agent starts no more agents beyond the fan-out ceiling’s exceptions — see Fan-out ceiling.
- Every agent’s
tools:line limits what it can do. A reviewer with onlyRead, Grep, Globcan’t edit anything.
The full roster is on the Agents and Skills pages. This page is how they’re built, and how to add your own.
Model selection guide
Section titled “Model selection guide”| Use opus when the agent needs to… | Use sonnet when the agent needs to… |
|---|---|
| Synthesize findings across multiple files | Scan for patterns in code |
| Make judgment calls or trade-off decisions | Follow a checklist or ruleset |
| Reason about attack scenarios or edge cases | Generate code from templates |
| Inhabit a persona or produce empathetic analysis | Execute mechanical transformations |
Skills vs agents
Section titled “Skills vs agents”The template uses two extension points:
- Skills (
.claude/skills/<name>/SKILL.md) — user-invocable workflows triggered by/name. Used for multi-step operations like opening MRs, running releases, or importing specs. Skills withdisable-model-invocation: truecan only be triggered by the user (not auto-invoked by Claude) — use this for actions with external side effects. - Agents (
.claude/agents/<name>.md) — proactively invoked by Claude when their trigger conditions are met. Used for review, analysis, and generation tasks that should run automatically as part of the development workflow.
| Feature | Skills | Agents |
|---|---|---|
| Invocation | You type /name; Claude may also start one unless it’s marked ⛔ |
Claude invokes proactively, or you ask by name |
| Side effects | Can have external effects (GitLab, git push) | Typically read/analyze/generate |
disable-model-invocation |
Supported | N/A (agents are always model-invokable) |
| Frontmatter | Full schema (model, effort, argument-hint, etc.) | Limited (name, model, description, tools) |
| Supporting files | Can include templates/scripts in the skill directory | Single file only |
Skills marked ⛔ on the Skills page have
disable-model-invocation: true.
Adding a project-specific agent
Section titled “Adding a project-specific agent”Create a file in .claude/agents/:
---name: my-agentmodel: opus # or sonnet — see model selection abovedescription: When to use this agent (be specific so Claude invokes it proactively).tools: Read, Grep, Glob, Bash, Agent---
# My Agent
[instructions — include sub-agent delegation if the agent does Phase 1 scanning]If the agent delegates scanning work to sub-agents, include Agent in the tools list
and structure the instructions with parallel sub-agent launches. Cap the launch at a
handful (2–3 is typical; /wave’s own wave default is 5) and never give the sonnet
sub-agent Agent in its tools — one level of delegation is the pattern, not a
precedent for the sub-agent to delegate again. See Fan-out ceiling
below for the project-wide default this pattern has to fit inside.
### Step 1 — Gather context (parallel sub-agents)
Launch **2 sub-agents in parallel** (both with `model: "sonnet"`). Wait for both.
**Sub-agent 1 — [scanning task]:**> [instructions]
**Sub-agent 2 — [scanning task]:**> [instructions]
### Step 2 — Synthesize (you do this — do NOT delegate)
[synthesis instructions using sub-agent results]Fan-out ceiling
Section titled “Fan-out ceiling”.claude/settings.json’s deny list guards what agent work does — force-push,
auto-merge, reading secrets. It has no per-task wave-size lever (nesting depth and
concurrent-subagent count are bounded by the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS env keys; see
the subagents reference, checked: 2026-10-15),
and runaway fan-out (agents spawning agents spawning agents on a task that didn’t need it) is
its own failure mode: upstream, a wave of delegated agents ran ~122M tokens per merged
MR, 95.9% of it cache reads rather than generation, and spend was concentrated — the
top 10 of 169 subagents were 44% of the total, one subagent alone at 166M against a 6M
median.
The project’s own CLAUDE.md documents the default this pattern has to respect (see
Subagent fan-out ceiling in its Agent workflow section, and the cost rules
section of .claude/skills/wave/SKILL.md): cap concurrent delegated agents at 5 per
task unless the user asks for more, never let a delegated agent re-delegate beyond the
one Phase-1 level shown above (or a /wave --harness implementer’s pre-MR gate batch; a pinned
wave-worker spawns nothing, and the orchestrator runs its gates), default read-only gates to the cheaper model, and state
an explicit reason when a task needs to exceed the default.
This is enforced by two things, not one: the tools: restriction on each agent
definition (a real, load-bearing cap — an agent with no Agent in its tools: cannot
spawn sub-agents at all), and review discipline for everything tools: can’t reach —
verifying what a delegated agent actually committed rather than trusting its summary. A
settings.json hook was considered for the harder cap (blocking a spawn outright, or
counting fan-out across a wave) and rejected: the lifecycle events for a subagent spawn
(SubagentStart/SubagentStop) can’t refuse a spawn (SubagentStart has no decision
control; SubagentStop can only keep a subagent from stopping), and a PreToolUse hook
would have to match the spawn tool by name, which has changed across Claude Code versions
(Task vs. Agent; see the hooks reference, checked: 2026-10-15).
Adding a project-specific skill
Section titled “Adding a project-specific skill”Create a directory in .claude/skills/:
---name: my-skilldescription: What this does and when to use it.disable-model-invocation: true # only if it has external side effectsargument-hint: "[arg description]"---
# My Skill
[instructions — same format as agents, with $ARGUMENTS for user input]Enforcing the agent workflow
Section titled “Enforcing the agent workflow”The workflow is mandatory rather than suggested because its rules are in the repository:
the Fast paths by change class table and the Pre-MR gate batch in CLAUDE.md, plus
the Gate reference table and cross-cutting rules in .claude/operating-rules.md
(imported by CLAUDE.md). They load whenever Claude Code opens the project, and only
then, so they do not leak into your other repositories.
The Gate reference table says when each gate applies and when it doesn’t, so
backend-only changes skip the UX agents and bug fixes skip the design phases. It records
only what each agent’s own description: does not already say, because the harness
injects those descriptions anyway.
global-claude-md.example remains as an optional template for personal preferences
that apply across projects. Nothing in it is needed for the harness to run. See
Start a project, step 7.
Package-level rules for monorepos
Section titled “Package-level rules for monorepos”For monorepos with distinct frontend/backend/worker packages, give agents stack-specific context in one of two ways:
my-project/├── AGENTS.md # Project contract any coding agent reads├── CLAUDE.md # Claude Code workflow; imports AGENTS.md├── worker/CLAUDE.md # nested: loads when files under worker/ are read└── .claude/rules/ ├── frontend.md # paths: ["frontend/**"] React patterns, design tokens └── backend.md # paths: ["backend/**"] Django patterns, API rulesA nested CLAUDE.md loads when Claude reads a file in its directory. A
.claude/rules/*.md file with paths: globs loads when Claude works with a matching
file, and can match a file class rather than one directory. Both keep package rules out
of the always-loaded root file. Use /import-design to generate
.claude/rules/frontend.md from a design guide.
Optional sandbox for Bash commands
Section titled “Optional sandbox for Bash commands”The permission deny list is not a security boundary; the sandbox is the layer that
limits what an allowed Bash command can touch. The template ships an opt-in profile,
.claude/settings.sandbox.example.jsonc, that restricts filesystem writes and network
hosts; make doctor reports whether it is active. It is off by default.
There is no per-agent sandbox: subagents share the parent session’s sandbox, and it
covers Bash only (see Sandboxing, checked: 2026-10-17).
Gates limited to Read, Grep and Glob are unaffected. Every agent with the Bash tool is constrained:
the read-only gates completeness-check, schema-check, generated-artifact-check,
regression-check, security-review and architect, plus dependency, docs, test-scaffold,
threat-model, ux-design and voc.