The scaffold system orchestrates software delivery end-to-end — from raw requirement to validated, production-ready code — using specialist subagents for each phase.
Scaffold breaks delivery into sequential stages:
product → stack → architecture → implementation → validation
Each stage is executed by specialist subagents. The root conversation stays lean — it tracks stage, decisions, and gaps, never raw code or logs. State persists across sessions in .claude/state/.
/scaffold <your requirement>
Examples:
/scaffold build a task management API with auth and PostgreSQL
/scaffold add Stripe payment flow to the existing checkout service
/scaffold fix the broken onboarding flow — users can't complete step 3
Scaffold automatically detects the execution mode from context:
| Mode | When used |
|---|---|
greenfield |
No existing codebase — building from scratch |
brownfield |
Existing codebase — adding or modifying features |
repair |
Existing codebase — fixing broken behavior |
Shapes the requirement into actors, flows, scope, MVP cuts, and acceptance criteria.
Run manually if you want to shape requirements first:
/plan-product <raw requirement>
Chooses the technology stack with rationale and records an ADR.
Run manually to force a stack decision:
/decide-stack <constraints or preferences>
Defines system shape, module boundaries, contracts, and design decisions.
Dispatches frontend, backend, platform, and other engineers based on what the architecture requires.
Runs the delivery validator to check definition-of-done coverage, requirement traceability, and release readiness.
Validation runs automatically after each stage. Run manually at any time:
/validate
Scaffold state persists. When you return to a conversation:
/resume-scaffold
This loads current stage, open gaps, and last validator result — then continues from the checkpoint rather than restarting.
When /validate finds issues, it writes them to the gap queue. Fix them with:
/fix-gap <gap-id>
/fix-gap all-blockers
This routes each gap to the correct specialist subagent, runs remediation, and re-validates automatically.
If a stage was interrupted mid-execution:
/continue-stage
Picks up from the last checkpoint without re-running prior stages.
| Command | Purpose |
|---|---|
/scaffold <requirement> |
Start a new run |
/resume-scaffold |
Resume from saved state |
/continue-stage |
Continue the active stage from checkpoint |
/validate |
Run delivery validation |
/fix-gap <id or "all-blockers"> |
Route a gap to its owner and re-validate |
/plan-product <requirement> |
Shape requirements into a product spec |
/decide-stack <constraints> |
Choose stack with tech-strategist |
All state lives in .claude/state/:
| File | Contents |
|---|---|
scaffold-state.json |
Current mode, stage, open gap IDs, next action |
project-summary.md |
Human-readable summary of the project |
artifact-index.json |
Pointers to all produced artifacts (specs, ADRs, schemas, etc.) |
gap-queue.json |
Open gaps with severity and owner assignments |
validator-status.json |
Latest validation result and timestamp |
stage-checkpoints/ |
Per-stage snapshots for resume |
Scaffold dispatches these agents automatically. You can also reference them by name if needed:
| Agent | Handles |
|---|---|
product-designer |
Requirements shaping, acceptance criteria |
tech-strategist |
Stack selection, ADRs |
solution-architect |
System design, contracts, module boundaries |
frontend-engineer |
UI, components, state, routing |
backend-engineer |
APIs, schema, jobs, auth |
platform-engineer |
CI/CD, Docker, deployment, secrets |
test-architect |
Test strategy, coverage, test scaffolding |
security-reviewer |
Auth, authz, secrets, data exposure |
ux-optimizer |
Flow friction, error states, task efficiency |
design-system |
Tokens, typography, component consistency |
delivery-validator |
Read-only — validates readiness, never patches |
bug-fixer |
Root cause diagnosis and targeted fixes |
- Start with a clear requirement. The more specific, the better the product spec. Vague requirements produce vague acceptance criteria.
- Don't skip validation.
/validateis the gate between stages. A passing validator means the next stage starts with a clean baseline. - Use
/fix-gap all-blockerswhen you have multiple failures. It routes and remediates in one pass. - Resume, don't restart.
/resume-scaffoldrecovers full context. Starting a new/scaffoldrun discards prior decisions and artifacts. - SEO stage is optional. For internal tools and APIs, scaffold skips the SEO stage automatically. For public-facing web products, it runs between product and stack.