Architecture: one lead agent, nine Claude Code subagents

Your main Claude Code session is the lead. It owns planning, integration, git and the final report. Subagents do bounded, independent work and report back.

Flow

  1. Phase 0: Reconnaissance. Inspect the repository, git state, conventions and the commands that build, test and lint it.
  2. Phase 1: Discovery. Frame the real problem and users, research where facts matter, compare approaches, recommend one.
  3. Phase 2: Product definition. Write testable requirements, user journeys and acceptance criteria.
  4. Phase 3: Architecture. Choose the stack, design components, data and APIs, and record trade-offs; threat-model security-sensitive designs.
  5. Phase 4: Execution planning. Define measurable acceptance criteria and milestones with verification gates in a persistent task file, with a per-milestone iteration budget; add security controls where risk warrants.
  6. Phase 5: Implementation. Build one milestone at a time as vertical slices on a work branch; the lead commits only after the milestone passes its gate.
  7. Phase 6: Independent verification. Run the milestone gate: tests, linters and regression checks, real user flows, then an independent review at meaningful checkpoints.
  8. Phase 7: Iterate. Repeat plan, build, test, review, fix per milestone, with root-cause analysis of failures, until the completion standard is met or a blocker needs you.
  9. Phase 8: Delivery. Report what was built and, per criterion, what is verified, partially verified or untested, whether review was independent, the security status, and what you must do next.

After phase 4 an optional Checkpoint A asks for your approval when a consequential choice is involved. Phases 5 to 7 repeat per milestone: each milestone must pass a verification gate before the next starts. The loop ends when the completion standard is met, a bound is hit, or a blocker needs you. The security gate runs alongside: a Critical finding blocks completion and a High finding needs a fix or your explicit acceptance.

Agents and permissions

The nine AUTO-BUILDER subagents (generated from .claude/agents/)
AgentResponsibilityToolsCan edit files
product-managerClarifies product goals, target users, user journeys, scope, prioritization and measurable acceptance criteria. Use for discovery and requirements, not coding.Read, Grep, Glob, WebSearch, WebFetchNo edit tools
researcherResearches current libraries, APIs, standards and competitor patterns from primary sources. Use when current external facts materially affect a decision.Read, Grep, Glob, WebSearch, WebFetchNo edit tools
architectDesigns or independently critiques system architecture, data models, interfaces, security boundaries and implementation plans. Read-only.Read, Grep, GlobNo edit tools
frontend-engineerImplements and reviews frontend features: components, state, responsive layouts, accessibility and browser interactions.Read, Edit, Write, Bash, Grep, GlobYes (assigned files)
backend-engineerImplements backend services, APIs, database schemas, migrations, integrations, validation and data pipelines.Read, Edit, Write, Bash, Grep, GlobYes (assigned files)
ai-engineerDesigns and implements AI/ML features: LLM integrations, RAG, agents, evaluation, prompts and data/model pipelines.Read, Edit, Write, Bash, Grep, Glob, WebSearch, WebFetchYes (assigned files)
qa-engineerDerives tests from acceptance criteria, runs verification, explores edge cases and independently validates behaviour. Read-only auditor: reports findings and proposes tests.Read, Bash, Grep, GlobNo edit tools
security-engineerIndependent application-security reviewer: threat modeling, attack surface, OWASP Top 10, authn/authz, injection, XSS/CSRF/SSRF, secrets, dependencies, data privacy, AI/LLM security. Read-only; reports evidence-based findings.Read, Bash, Grep, GlobNo edit tools
critical-reviewerIndependently reviews plans, diffs and implementations for correctness, security, regressions, maintainability and missed requirements. Read-only.Read, Grep, Glob, BashNo edit tools

Routing: product-manager for scope, researcher for current external facts, architect for design critique (and for flagging security-sensitive decisions), the three engineers for implementation, security-engineer for threat modeling and security review where the project warrants it, and qa-engineer plus critical-reviewer for independent verification. Security findings are owned by security-engineer; QA validates behavior and security regression tests; the critical reviewer judges overall quality. The lead spawns only what a task needs.

State files

Project memory lives in files, not in the conversation: docs/auto-builder/ holds PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, TASKS.md, TESTING.md, DECISIONS.md, PROGRESS.md (a running log) and, where they apply, SECURITY-REVIEW.md (threat model, findings register and gate status) BROWSER-QA.md (browser test evidence) and LESSONS.md (project lessons, plus proposals that only you can apply), created from templates only as the project warrants and never overwritten. TASKS.md also holds the milestone gate table and the Verified / Partially verified / Untested state of every acceptance criterion. Stable facts such as build commands may be proposed for your project's CLAUDE.md.

Parallel work rules

Repository layout

.claude/
  agents/                 9 subagent definitions
  skills/auto-builder/
    SKILL.md              the /auto-builder skill
    workflows/            discovery, planning, implementation, verification, delivery
    references/           project categories, parallel work, Claude Code features
    templates/            state-file templates
    scripts/              init-artifacts.sh, hooks/ (opt-in)
install.sh  install.ps1   installers
tests/                    validate.py, test-install.sh
site/  docs/              this website (generator and output)

Supporting documents are loaded on demand (progressive disclosure); SKILL.md stays short. Next: install it.