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
- Phase 0: Reconnaissance. Inspect the repository, git state, conventions and the commands that build, test and lint it.
- Phase 1: Discovery. Frame the real problem and users, research where facts matter, compare approaches, recommend one.
- Phase 2: Product definition. Write testable requirements, user journeys and acceptance criteria.
- Phase 3: Architecture. Choose the stack, design components, data and APIs, and record trade-offs; threat-model security-sensitive designs.
- 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.
- 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.
- Phase 6: Independent verification. Run the milestone gate: tests, linters and regression checks, real user flows, then an independent review at meaningful checkpoints.
- 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.
- 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
| Agent | Responsibility | Tools | Can edit files |
|---|---|---|---|
product-manager | Clarifies product goals, target users, user journeys, scope, prioritization and measurable acceptance criteria. Use for discovery and requirements, not coding. | Read, Grep, Glob, WebSearch, WebFetch | No edit tools |
researcher | Researches current libraries, APIs, standards and competitor patterns from primary sources. Use when current external facts materially affect a decision. | Read, Grep, Glob, WebSearch, WebFetch | No edit tools |
architect | Designs or independently critiques system architecture, data models, interfaces, security boundaries and implementation plans. Read-only. | Read, Grep, Glob | No edit tools |
frontend-engineer | Implements and reviews frontend features: components, state, responsive layouts, accessibility and browser interactions. | Read, Edit, Write, Bash, Grep, Glob | Yes (assigned files) |
backend-engineer | Implements backend services, APIs, database schemas, migrations, integrations, validation and data pipelines. | Read, Edit, Write, Bash, Grep, Glob | Yes (assigned files) |
ai-engineer | Designs and implements AI/ML features: LLM integrations, RAG, agents, evaluation, prompts and data/model pipelines. | Read, Edit, Write, Bash, Grep, Glob, WebSearch, WebFetch | Yes (assigned files) |
qa-engineer | Derives tests from acceptance criteria, runs verification, explores edge cases and independently validates behaviour. Read-only auditor: reports findings and proposes tests. | Read, Bash, Grep, Glob | No edit tools |
security-engineer | Independent 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, Glob | No edit tools |
critical-reviewer | Independently reviews plans, diffs and implementations for correctness, security, regressions, maintainability and missed requirements. Read-only. | Read, Grep, Glob, Bash | No 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
- Parallelise only independent work, after shared interfaces are fixed.
- Every implementer gets an explicit list of files it owns. After integration the lead checks
git diff --statagainst it. - Only the lead commits, installs dependencies and edits lockfiles, shared config and state files.
- Worktree isolation is an exception with caveats (needs a git repo; a fresh worktree may lack your unmerged work); see parallel-work.md.
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.