9. Multi-Agent Claude Code Architecture with Role-Specialized Agents

Status

Accepted — 2026-02-20, hardened through 2026-04

Context

The repository is maintained by one developer working with Claude Code. A single general-purpose agent is forced to juggle unrelated concerns on every request — tone, security, code hygiene, spec compliance, test coverage, visual design — and does none of them with depth. Prompts bloat to cover every concern at once, context windows fill with unrelated instructions, and reviews miss things that a specialist would catch. The work has enough distinct dimensions (satirical voice, Firebase security surface, Angular hygiene, shared/ architecture) that a partitioned roster pays off.

Decision

The project runs a roster of role-specialized agents under .claude/agents/, each with a narrow charter, a documented invocation pattern, and no overlap with its neighbors.

Current roster, grouped by domain:

  • Content and editorial. ash (trim and pacing), ernest (deadpan voice guardian), lyle (structural comedy), vera-redline (AI-tell detection), bryce-fontaine (visual design direction).
  • Code hygiene and architecture. scout (in-file hygiene, no cross-file lookups), cartographer (shared/ and spec drift), inspector (project-wide spec compliance sweep), prospector (magic values, env vs. Remote Config vs. constant).
  • Security and boundaries. bastion (HTTP headers and CSP in firebase.json), dispatch (Cloud Functions audit), hex (Firestore rules audit), sentry (frontend/backend boundary).
  • Testing. garrison (coverage assessment and test authoring, frontend and functions).
  • Research. research-gemini (external information gathering).

Each agent’s description includes explicit delineations against adjacent agents (“Not a general hygiene pass — that’s scout”; “Not an architecture check — that’s cartographer”) so invocation is unambiguous. Slash commands (/pre-check, /hygiene, /security-audit, /content-review) invoke curated panels of agents for common workflows.

Consequences

  • Each agent loads only the files and spec sections relevant to its charter. Reviews are deeper and context usage is tighter than a single general agent would achieve on the same task.
  • Invocation has cognitive cost: the developer must know which agent to call. The explicit “not X, that’s Y” delineations in each agent’s description exist to manage this.
  • The roster is the architecture. Adding a concern (e.g., accessibility auditing) means adding an agent with a clear charter and delineation, not expanding an existing agent’s scope.
  • Agents can only run when invoked. Coverage depends on the developer remembering to call them or on the relevant slash command running them as a panel.
  • Keeping agent descriptions accurate is ongoing maintenance. A stale charter produces the wrong reviews.
  • Consolidating back to a single general agent is possible but would collapse the depth advantage. The partitioning is the point.