Band Roles and Agents

Band Roles and Agents

During orchestrated runs, five role agents handle specific phases. Each is defined in .claude/agents/ with a fixed tool mask, success condition, and scope constraint.

Role Matrix

Agent	Role	Band	Tool Kind	Shell	Can Write
spec.md	spec	define	RW	No (Guard 7)	Spec files only
plan.md	plan	define	RW	No (Guard 7)	Plan files only
code.md	code	build	RW	Test command only	Task scope from envelope
audit.md	audit	verify	R	No (Guard 7)	Nothing
qa.md	qa	verify	X	Test command only	Nothing (Guard 5)

A sixth agent, define-review.md, is a non-band advisory reviewer for the review loop.

Agent Constraints

Each agent's frontmatter declares:

• tools: — The role's tool mask (what tools it can call)
• Success condition — What constitutes a completed task
• Stop-on-denial — If a guard denies, the agent stops
• One hand-back — Claims only the role's own gate
• No dispatch — Agents cannot dispatch other agents (Guard 6: ORCH_NESTED_DISPATCH)
• Scope copy — Verbatim scope from the SNAP envelope

All prompts fit in 999 tokens or fewer.

The Hand-back

When a role completes, it returns exactly one SNAP_HANDBACK line. The orchestrator validates this before the next dispatch. A wall of prose never reaches the orchestrator's context.

Guard Enforcement

Every role is a separate container dispatched by the orchestrator. The hook (Guards 5–7) sits between each role and the repository, so a role can only do what its band envelope allows.

flowchart TB
  orch["<b>Orchestrator</b><br/><i>[Claude Code session running /cc-orchestrate]</i><br/>Only caller allowed to dispatch — Guard 6"]

  subgraph defineb["Define band"]
    spec["<b>spec</b><br/><i>[Agent · RW]</i><br/>No shell · writes spec files only"]
    plan["<b>plan</b><br/><i>[Agent · RW]</i><br/>No shell · writes plan files only"]
    rev["<b>define-review</b><br/><i>[Agent · R, advisory]</i><br/>Checklist review, no writes"]
  end
  subgraph buildb["Build band"]
    code["<b>code</b><br/><i>[Agent · RW]</i><br/>Test command only · task scope"]
  end
  subgraph verifyb["Verify band"]
    audit["<b>audit</b><br/><i>[Agent · R]</i><br/>No shell · no writes"]
    qa["<b>qa</b><br/><i>[Agent · X]</i><br/>Test command only · no writes"]
  end

  hook["<b>pre-tool-use.mjs</b><br/><i>[Hook · Node.js]</i><br/>G5 write scope · G6 no nested dispatch · G7 shell"]
  env[("<b>band-envelope.json</b><br/>role, tool kind, scope globs")]
  repo[("<b>Repository</b>")]

  orch <-- "Dispatch with SNAP envelope ⇄<br/>one-line SNAP_HANDBACK" --> defineb & buildb & verifyb
  defineb & buildb & verifyb -- "Every write<br/>and shell call" --> hook
  hook -- "Reads" --> env
  hook -- "Allowed calls only" --> repo

  classDef system fill:#1168bd,stroke:#0b4884,color:#fff
  classDef container fill:#438dd5,stroke:#2e6295,color:#fff
  classDef component fill:#85bbf0,stroke:#5d82a8,color:#000
  class orch system
  class spec,plan,rev,code,audit,qa container
  class hook,env,repo component
  style defineb fill:none,stroke:#1168bd,stroke-dasharray:5 5
  style buildb fill:none,stroke:#1168bd,stroke-dasharray:5 5
  style verifyb fill:none,stroke:#1168bd,stroke-dasharray:5 5

Loading

The Review Loop

Before each define approval:

1. define-review agent checks the spec/plan against a declared checklist
2. Open rows go back to the generating role via SendMessage
3. Up to 3 reviewer passes, 2 revisions
4. ORCH_REVIEW_CAP refuses a fourth round (no halt)
5. Advisory only — your approval is always required

How roles are dispatched

1. Orchestrator builds a SNAP v3 envelope with the role's scope
2. Validates: snap-validate --to <role>
3. Installs envelope at .claude/memory/band-envelope.json
4. Dispatches via Agent tool with agent_type matching the role name
5. Waits for completion
6. Validates the SNAP_HANDBACK response
7. Proceeds to next role or phase