Layer 2: Agent Definitions
Roles, access boundaries, and retry policy for every agent in CAF.
Layer 2 defines who does what. Every role in the pipeline has its own definition
file in .claude/agents/ — generated by caf-init scaffold agents, already informed
by context from Layer 1: Project Knowledge Base.
The roster
CAF's final roster is five agents, called by filename:
| File | Role | Tools |
|---|---|---|
caf-planner.md | Writes the spec from the ticket: requirements.md, tasks.md, and design.md or breakdown.md when the request needs one | Read, Write, Glob, Grep — artifacts only, no code |
caf-frontend.md / caf-backend.md | Writes code per the spec, inside its own scope, then self-verifies | Read, Write, Edit, Bash |
caf-validator.md | Checks every acceptance criterion by running its evidence itself; does not change code | Read, Write for validate-report.md, Bash |
caf-reviewer.md | Reviews the diff against the spec and writes a verdict | Read, Write for review-notes.md, Bash |
caf-reviewer.md does not replace a human. Its verdict makes it easier for a
human to decide — the merge decision always stays with a human.
In a monorepo, scaffold agents assigns Frontend and Backend per app. In a
single-package repo it writes two whole-repo agents, caf-frontend.md and
caf-backend.md; --role frontend or --role backend generates just one of them.
Replaced and dropped roles
These are no longer scaffolded, and a new repo does not get them. A repo scaffolded
earlier keeps its files, and curate still recognizes them:
caf-qa— replaced bycaf-validator. CAF Orchestrator runscaf-validatorwhen the repo has that file and falls back tocaf-qaotherwise.caf-architect— folded into the Planner, which writesdesign.mdthrough thecaf-designskill.caf-implementer— replaced bycaf-frontend+caf-backend.caf-documentation,caf-devops,caf-pm,caf-ux-designer,caf-auditor. The Orchestrator runscaf-documentationonly if that file exists.
An agent file whose name is neither a known kind nor an app slug is skipped by
curate and reported as unknown-kind.
What's inside a definition file
- Role and Scope — the boundaries of that role's responsibility
- Allowed Tools — which tools the agent may use (see the table above)
- Input / Output — the artifacts it reads and must write (see
Layer 3: Artifact Handoff). The spec-driven rules of
each agent live in
Output - Working Pattern (PIV) and Verify Checklist. The Validator and the Reviewer have a pattern of their own, since they read and report rather than plan and implement
- Retry Logic and, for the Validator, Reviewer and QA, Report Format — the exact status lines CAF Orchestrator parses
- Skills — optional pointers to the CAF skills (below)
- Constraints
Skills
caf-init scaffold skills writes nine skills into .claude/skills/<name>/SKILL.md:
caf-self-verify, caf-scope-discipline, caf-no-guess, caf-escalate, caf-piv,
and the spec skills caf-spec, caf-traceability, caf-design and caf-breakdown.
An agent reaches them through Read pointers in its ## Skills section; a manual
Claude Code session picks them up by their description. A skill that still has a
DRAFT banner is ignored by agents (caf-traceability is born that way). Skills are
guidance — enforcement stays with the Validator and Reviewer stages. See
CAF Initiator.
Customization
These files aren't locked-down configuration. Role, Scope, Verify Checklist,
Constraints and Skills hold per-project data and are yours to edit — for
example, adding a rule to caf-backend.md like "always write a test for every new
function."
The other sections are tracked: caf-init curate compares them with the current
template so a template fix can reach agents generated earlier. A tracked section you
edited by hand is reported, never overwritten. If you run through CAF Orchestrator,
leave Retry Logic and Report Format as generated — the Orchestrator parses their
status lines word for word.
Relationship to other layers
Layer 2 consumes context from Layer 1 and determines the artifact format that gets written to Layer 3: Artifact Handoff at the end of every phase.