Scaffold
A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 11 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
By the end, you'll have a fully planned, standards-documented, implementation-ready project with working code.
What is Scaffold?
Scaffold is a composable meta-prompt pipeline built for Claude Code and other supported AI coding tools. If you have an idea for a software project but don't know where to start — or you want to make sure your project is set up with solid architecture, standards, and tests from day one — Scaffold guides you through every step.
Here's how it works:
Initialize — run
scaffold initin your project directory. The init wizard detects whether you're starting fresh (greenfield) or working with an existing codebase (brownfield), and lets you pick a methodology preset (deep, mvp, or custom). Every question shows inline descriptions and friendly labels — type?at any choice prompt for detailed help.Run steps — each step is a composable meta-prompt (a short intent declaration in
content/pipeline/) that gets assembled at runtime into a full 7-section prompt. The assembly engine injects relevant knowledge base entries, project context from prior steps, methodology settings, and depth-appropriate instructions.Follow the dependency graph — Scaffold tracks which steps are complete, which are eligible, and which are blocked. Run
scaffold nextto see what's unblocked, orscaffold statusfor the full picture. Each step produces a specific artifact — a planning document, architecture decision, specification, or actual code.
You can run steps two ways:
- CLI:
scaffold run create-prd— the assembly engine builds a full prompt from the meta-prompt, knowledge base entries, and project context. Best for the structured pipeline with dependency tracking. - Runner skill: In Claude Code (or another agent host), the scaffold-runner skill provides an interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting the AI pick defaults silently.
Either way, Scaffold constructs the prompt and the target AI tool does the work. The CLI tracks pipeline state and dependencies; the runner skill adds interactive decision surfacing on top.
Key Concepts
Meta-prompts — Each pipeline step is defined as a short .md file in content/pipeline/ with YAML frontmatter (dependencies, outputs, knowledge entries) and a markdown body describing the step's intent. These are not the prompts Claude sees — they're assembled into full prompts at runtime.
Assembly engine — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
Knowledge base — 278 domain expertise entries in content/knowledge/ organized in twenty categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3, mcp-server) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, smart-contract security and audit workflow, MCP protocol fundamentals, tool and resource design, transport patterns, and more. These get injected into prompts based on each step's knowledge-base frontmatter field. Knowledge files with a ## Deep Guidance section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in .scaffold/knowledge/ that layer on top of the global entries.
A daily cron audits entries against their declared authoritative sources and opens refresh PRs when they drift — see docs/knowledge-freshness/operations.md for the operator guide (provider selection across Z.ai, DeepSeek, and Anthropic, the Z.ai→DeepSeek fallback, secret setup, manual overrides).
Reference guides — Human- and agent-readable reference guides live under content/guides/<topic>/ (markdown source + generated HTML). Run scaffold guides to open the index or scaffold guides <topic> to open a specific guide in your browser; agents read the source via scaffold guides <topic> --markdown and discover topics with scaffold guides --list --format json.
Methodology presets — Three built-in presets control which steps run and how deep the analysis goes:
- deep (depth 5) — all steps enabled, exhaustive analysis
- mvp (depth 1) — 7 critical steps, get to code fast
- custom (depth 1-5) — you choose which steps to enable and how deep each one goes
Depth scale (1-5) — Controls how thorough each step's output is, from "focus on the core deliverable" (1) to "explore all angles, tradeoffs, and edge cases" (5). Depth resolves with 4-level precedence: CLI flag > step override > custom default > preset default.
Multi-model validation — At depth 4-5, review and validation steps can dispatch independent reviews to the three MMR CLI channels (Codex, Antigravity, Claude) via the mmr CLI, plus the Superpowers code-reviewer agent as a complementary 4th channel on wrapper invocations (scaffold run review-pr, scaffold run review-code). The MMR-backed wrappers are the preferred path; some older depth-5 validation steps still dispatch Codex/Antigravity directly via the multi-model-dispatch skill (migration in progress). Multiple independent models catch more blind spots than one. Findings are reconciled by confidence level (multiple channels agree = high confidence, single channel P0 = still actionable). When Codex or Antigravity is unavailable, a compensating Claude self-review pass runs in its place (labeled [compensating: Codex-equivalent] or [compensating: Antigravity-equivalent], single-source confidence); there is no compensating pass when Claude itself is unavailable — the review simply proceeds with the remaining channels. CLI commands must always run in the foreground — background execution produces empty output. mmr review also supports non-PR targets (staged changes, branch diff, specific files) — see the Multi-Model Review section.
State management — Pipeline progress is tracked in .scaffold/state.json with atomic file writes and crash recovery. An advisory lock prevents concurrent runs. Decisions are logged to an append-only decisions.jsonl. Pressing Ctrl+C during any command exits cleanly with an informative message — no stack traces, no orphaned locks, no corrupted state.
Dependency graph — Steps declare their prerequisites in frontmatter. Scaffold builds a DAG, runs topological sort (Kahn's algorithm), detects cycles, and computes which steps are eligible at any point.
Prerequisites
Required
Node.js (v18.17 or later)
- Install: https://nodejs.org or
brew install node - Verify:
node --version
Git
- Install: https://git-scm.com or
brew install git - Verify:
git --version
Claude Code The AI coding assistant that runs the assembled prompts. Claude Code is a command-line tool from Anthropic.
- Install:
npm install -g @anthropic-ai/claude-code - Verify:
claude --version - Docs: https://docs.anthropic.com/en/docs/claude-code
Optional
Codex CLI (for multi-model review) Independent code review from a different AI model. Used at depth 4-5 by all review steps.
- Install:
npm install -g @openai/codex - Requires: ChatGPT subscription (Plus/Pro/Team)
- Verify:
codex --version
Antigravity CLI (for multi-model review) Independent review from Google's current agent CLI. Can run alongside or instead of Codex.
- Install and sign in through Google's Antigravity distribution
- Requires: Google account
- Verify:
agy --version
mmr (multi-model review CLI) Automates dispatching, monitoring, and reconciling code reviews across multiple AI model CLIs. Works standalone or with Scaffold.
- Install:
npm install -g @zigrivers/mmr - Verify:
mmr --help - Setup:
mmr config init(auto-detects installed CLIs) - See: mmr — Multi-Model Review CLI
Playwright MCP (web apps only) Lets Claude control a real browser for visual testing and screenshots.
- Install:
claude mcp add playwright npx @playwright/mcp@latest
Installation
Scaffold has two parts that install separately:
- CLI (
scaffold) — the core tool. Install via npm or Homebrew. Use it from your terminal or from Claude Code with! scaffold run <step>. - Plugin — optional Claude Code plugin that auto-activates the scaffold runner and pipeline reference skills for interactive guidance.
Step 1: Install the CLI
Pick one:
npm (recommended)
npm install -g @zigrivers/scaffoldHomebrew
brew tap zigrivers/scaffold
brew install scaffoldVerify: scaffold version
Step 2: Add the plugin (recommended)
Install the Scaffold plugin inside Claude Code for auto-activated skills:
/plugin marketplace add zigrivers/scaffold
/plugin install scaffold@zigrivers-scaffoldThis gives you:
- Scaffold Runner skill — intelligent interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting Claude pick defaults silently
- Pipeline reference skill — shows pipeline ordering, dependencies, and phase structure
- Multi-model dispatch skill — correct invocation patterns for Codex and Antigravity CLIs
Usage — just tell Claude Code what you want in natural language:
"Run the next scaffold step" → previews prompt, asks decisions, executes
"Run scaffold create-prd" → same for a specific step
"Where am I in the pipeline?" → shows progress and next eligible steps
"What's left?" → compact view of remaining steps only
"Skip design-system and add-e2e-testing" → batch skip with reason
"Is add-e2e-testing applicable?" → checks platform detection without running
"Use depth 3 for everything" → remembers preference for the sessionThe plugin is optional — everything it does can also be done with scaffold run <step> from the CLI. But you lose the interactive decision surfacing without the Scaffold Runner skill.
CLI-only users: If you prefer not to install the plugin, skills are installed automatically —
scaffold initsets them up, and any subsequent CLI command keeps them current after upgrades. No manualscaffold skill installneeded.
Other agent CLIs: the auto-install covers Claude Code (
.claude/skills/) and shared/OpenCode hosts (.agents/skills/). To install the scaffold skills in another CLI's native form, runscaffold skill install --platform <codex|antigravity|cursor|opencode>— it writes a managedAGENTS.mdblock (Codex/Antigravity),.cursor/rules/*.mdc(Cursor), or.opencode/skills/(OpenCode).
Updating
npm
npm update -g @zigrivers/scaffoldHomebrew
brew upgrade scaffoldmmr
npm update -g @zigrivers/mmrPlugin
/plugin marketplace update zigrivers-scaffoldExisting projects
After upgrading the CLI, existing projects still get automatic state migrations. Run scaffold status in your project directory — the state manager detects and renames old step keys, removes retired steps, normalizes artifact paths, and persists the changes atomically. No manual editing of .scaffold/state.json is needed.
Step migrations handled automatically:
add-playwright/add-maestro→add-e2e-testingmulti-model-review→automated-pr-reviewuser-stories-multi-model-review→ removed (folded intoreview-user-stories)claude-code-permissions→ removed (folded intogit-workflow+tech-stack)multi-model-review-tasks→ removed (folded intoimplementation-plan-review)testing-strategy→tdd,implementation-tasks→implementation-plan,review-tasks→implementation-plan-review
The PRD is always created as docs/plan.md. If you have a legacy docs/prd.md from an older version, the context gatherer resolves aliased paths so downstream steps find your PRD regardless.
Generated output layout
Fresh scaffold init now creates committed project state under .scaffold/ and auto-runs scaffold build, which writes inspectable adapter artifacts under .scaffold/generated/. Scaffold also manages a dedicated block in .gitignore so generated output, .scaffold/lock.json, and Scaffold temp files stay out of version control by default.
The canonical execution entrypoints are still scaffold run <step> and the installed Scaffold plugin. Files under .scaffold/generated/ are internal build artifacts, not root-level project files.
Migration for older projects
This release is a clean breaking change for generated adapter output. To migrate an existing project:
- Upgrade Scaffold.
- Remove old root-level generated Scaffold output if present:
prompts/,codex-prompts/,commands/, and rootAGENTS.mdonly if it was Scaffold-generated. Runscaffold status— it warns about any legacy output. - Run
scaffold build. - Review the Scaffold-managed block in
.gitignore. - Commit
.gitignoreplus the intended committed.scaffold/state files (config.yml,state.json,decisions.jsonl,instructions/). - Do not commit
.scaffold/generated/or.scaffold/lock.json.
Quick Start
The fastest way to use Scaffold is through natural language inside Claude Code. The Scaffold Runner skill handles pipeline navigation, surfaces decision points before Claude picks defaults, and tracks your progress automatically. The examples below show what you'd type in a Claude Code session.
Starting a Brand New Project
Let's say you want to build a neighborhood tool lending library — an app where neighbors can list tools they own and borrow from each other. Here's how that looks end to end.
Set up the project (one-time, in your terminal):
mkdir tool-library && cd tool-library
git init
scaffold initThe init wizard detects that this is a brand new project and walks you through setup with friendly labels and inline descriptions for every option. Type ? at any choice prompt for detailed guidance. Choose mvp if you want to get to working code fast — it runs only 7 critical steps instead of the full 60. You can always switch to deep or custom later.
Open Claude Code in your project directory, then start talking:
"I want to build a neighborhood tool lending library where neighbors can
list tools they own, browse what's available nearby, and request to borrow
items. Run the first scaffold step."The runner picks up create-vision (the first eligible step), asks you a few strategic questions about your idea — who's the audience, what makes this different from existing apps, what does success look like — and produces docs/vision.md. This becomes the foundation everything else builds on.
"Run the next scaffold step"Now it runs create-prd. Claude translates your vision into a detailed product requirements document with features, user personas, success criteria, and scope boundaries. The output lands in docs/plan.md.
"Next step"review-prd — Claude reviews the PRD for gaps, ambiguity, and completeness, then suggests improvements. You decide which suggestions to accept.
"Keep going"user-stories — Claude breaks the PRD into detailed user stories with acceptance criteria. Each story maps back to a specific requirement so nothing falls through the cracks.
"What's left?"The runner shows your remaining steps and which ones are unblocked. With the mvp preset, you're almost there — just review-user-stories, tdd, implementation-plan, and implementation-playbook remain.
"Finish the remaining steps"The runner executes each remaining step in order, pausing to surface decisions that need your input (testing framework preferences, depth level for reviews, etc.) rather than letting Claude guess silently.
Once the pipeline is complete:
"Start building"Claude picks up the first implementation task and begins writing code using TDD — tests first, then implementation. Your project now has architecture docs, coding standards, a test strategy, and a task graph, all produced from your original idea.
CLI equivalent: Everything above can also be done with
scaffold run create-vision,scaffold run create-prd,scaffold next, etc. The runner skill adds interactive decision surfacing on top of these commands.
Adding Scaffold to an Existing Project
Say you have a Next.js app with a handful of features built, but no documentation, formal test strategy, or architecture docs. Scaffold can backfill all of that.
In your project root:
cd ~/projects/my-nextjs-app
scaffold initScaffold detects that you already have code (package.json, source files, git history) and classifies the project as brownfield. It suggests the deep methodology since existing projects benefit from thorough documentation, but you can choose any preset.
If you already have docs that match Scaffold's expected outputs (a PRD, architecture doc, etc.), bootstrap your state:
scaffold adoptThis scans your project for existing artifacts and marks those pipeline steps as complete so you don't redo work.
Now open Claude Code and skip what doesn't apply:
"Skip create-vision and create-prd — I already know what I'm building"The runner marks those steps as skipped with your reason logged.
"Run tech-stack"Claude scans your existing dependencies, framework choices, and configuration, then documents everything in docs/tech-stack.md — formalizing decisions you've already made so future contributors (and AI agents) understand the rationale.
"Run tdd"Claude sets up a testing strategy tailored to your existing stack — test runner config, coverage targets, TDD workflow conventions. If you already have some tests, it builds around them.
"Run coding-standards"Claude analyzes your existing code patterns and creates docs/coding-standards.md with linter and formatter configs that match how you're already writing code.
Continue through whatever steps make sense — git-workflow, security, implementation-plan — and skip the rest.
Later, when you want to add a new feature with full Scaffold rigor:
"Run new-enhancement"Claude walks you through adding a feature the right way — updating the PRD, creating new user stories, setting up tasks with dependencies, and kicking off implementation. All the planning docs stay in sync.
Checking Your Progress
Scaffold persists your pipeline state in .scaffold/state.json, so you can close Claude Code, take a break, and pick up right where you left off.
In Claude Code (natural language):
"Where am I in the pipeline?" → full progress view with phase breakdown
"What's next?" → shows the next unblocked step(s)
"What's left?" → compact view of remaining steps onlyFrom the terminal (CLI):
scaffold status # full pipeline progress
scaffold status --compact # remaining work only
scaffold next # next eligible step(s)
scaffold dashboard # open a visual progress dashboard in your browserTips for New Users
- You don't need every step. The
mvppreset runs just 7 steps and gets you building fast. Start there and switch todeeporcustomif you want more rigor. - "I'm not sure" is a valid answer. When Claude asks a question you can't answer yet, say so — it'll suggest reasonable defaults and explain the trade-offs. You can revisit any decision later.
- You can re-run any step. If your thinking evolves, use
scaffold reset <step>to reset it, then run it again. Scaffold uses update mode — it improves the existing artifact rather than starting from scratch. - Every step produces a real document. Vision docs, PRDs, architecture decisions, test strategies — these all land in your project's
docs/folder as markdown files. They're not throwaway; they're the source of truth your code is built from. - The pipeline is a guide, not a cage. Skip steps that don't apply (
scaffold skip <step> --reason "..."). Run them out of order if you know what you're doing. Scaffold tracks dependencies so it'll tell you if you're missing a prerequisite. - Depth controls thoroughness. Each step runs at a depth from 1 (focused, fast) to 5 (exhaustive). The mvp preset defaults to depth 1; deep defaults to 5. You can override per step or per session:
"Use depth 3 for everything".
Non-Interactive / CI Usage
Every scaffold init wizard question can be answered via CLI flags, making scaffold fully scriptable for CI pipelines, automation, and reproducible project setup.
General Flags
| Flag | Type | Description |
|---|---|---|
--methodology |
deep/mvp/custom | Methodology preset |
--depth |
1-5 | Custom methodology depth (requires --methodology custom) |
--adapters |
comma-sep | AI adapters: claude-code, codex |
--traits |
comma-sep | Project traits: web, mobile, desktop |
--project-type |
string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension, research, data-science, web3, mcp-server, macos-native |
--auto |
boolean | Non-interactive mode (uses Zod defaults for unset flags) |
Web-App Config Flags (require --project-type web-app or auto-set it)
| Flag | Type | Values |
|---|---|---|
--web-rendering |
string | spa, ssr, ssg, hybrid |
--web-deploy-target |
string | static, serverless, container, edge, long-running |
--web-realtime |
string | none, websocket, sse |
--web-auth-flow |
string | none, session, oauth, passkey |
Backend Config Flags (require --project-type backend or auto-set it)
| Flag | Type | Values |
|---|---|---|
--backend-api-style |
string | rest, graphql, grpc, trpc, none |
--backend-data-store |
comma-sep | relational, document, key-value |
--backend-auth |
string | none, jwt, session, oauth, apikey |
--backend-messaging |
string | none, queue, event-driven |
--backend-deploy-target |
string | serverless, container, long-running |
--backend-domain |
string | none, fintech |
The wizard and
--backend-domainflag remain single-select in v1; multi-domain stacking requires hand-editing.scaffold/config.ymlto use an array (e.g.domain: ['fintech']).
CLI Config Flags (require --project-type cli or auto-set it)
| Flag | Type | Values |
|---|---|---|
--cli-interactivity |
string | args-only, interactive, hybrid |
--cli-distribution |
comma-sep | package-manager, system-package-manager, standalone-binary, container |
--cli-structured-output |
boolean | --cli-structured-output / --no-cli-structured-output |
Library Config Flags (require --project-type library or auto-set it)
| Flag | Type | Values |
|---|---|---|
--lib-visibility |
string | public, internal |
--lib-runtime-target |
string | node, browser, isomorphic, edge |
--lib-bundle-format |
string | esm, cjs, dual, unbundled |
--lib-type-definitions |
boolean | --lib-type-definitions / --no-lib-type-definitions |
--lib-doc-level |
string | none, readme, api-docs, full-site |
Mobile-App Config Flags (require --project-type mobile-app or auto-set it)
| Flag | Type | Values |
|---|---|---|
--mobile-platform |
string | ios, android, cross-platform |
--mobile-distribution |
string | public, private, mixed |
--mobile-offline |
string | none, cache, offline-first |
--mobile-push-notifications |
boolean | --mobile-push-notifications / --no-mobile-push-notifications |
Data Pipeline Config Flags (require --project-type data-pipeline or auto-set it)
| Flag | Type | Values |
|---|---|---|
--pipeline-processing |
string | batch, streaming, hybrid |
--pipeline-orchestration |
string | none, dag-based, event-driven, scheduled |
--pipeline-quality |
string | none, validation, testing, observability |
--pipeline-schema |
string | none, schema-registry, contracts |
--pipeline-catalog |
boolean | --pipeline-catalog / --no-pipeline-catalog |
ML Config Flags (require --project-type ml or auto-set it)
| Flag | Type | Values |
|---|---|---|
--ml-phase |
string | training, inference, both |
--ml-model-type |
string | classical, deep-learning, llm |
--ml-serving |
string | none, batch, realtime, edge |
--ml-experiment-tracking |
boolean | --ml-experiment-tracking / --no-ml-experiment-tracking |
Browser Extension Config Flags (require --project-type browser-extension or auto-set it)
| Flag | Type | Values |
|---|---|---|
--ext-manifest |
string | 2, 3 |
--ext-ui-surfaces |
comma-sep | popup, options, newtab, devtools, sidepanel |
--ext-content-script |
boolean | --ext-content-script / --no-ext-content-script |
--ext-background-worker |
boolean | --ext-background-worker / --no-ext-background-worker |
Research Config Flags (require --project-type research or auto-set it)
| Flag | Type | Values |
|---|---|---|
--research-driver |
string | code-driven, config-driven, api-driven, notebook-driven |
--research-interaction |
string | autonomous, checkpoint-gated, human-guided |
--research-domain |
string | none, quant-finance, ml-research, simulation |
--research-tracking |
boolean | --research-tracking / --no-research-tracking |
MCP Server Config Flags (require --project-type mcp-server or auto-set it)
| Flag | Type | Values |
|---|---|---|
--mcp-language |
string | typescript, python |
--mcp-transport |
string | stdio, streamable-http, sse |
--mcp-primitives |
comma-sep | tools, resources, prompts |
--mcp-auth |
string | none, oauth, apikey |
--mcp-deployment |
string | local, hosted |
--mcp-stateful |
boolean | --mcp-stateful / --no-mcp-stateful |
macOS-Native Config Flags (require --project-type macos-native or auto-set it)
| Flag | Type | Values |
|---|---|---|
--macos-ui-framework |
string | swiftui, appkit, hybrid |
--macos-app-style |
string | standard, menu-bar, agent |
--macos-min-version |
string | e.g. 14.0, 15.0 |
--macos-distribution |
string | developer-id, mac-app-store, both |
--macos-sandboxed |
boolean | --macos-sandboxed / --no-macos-sandboxed |
--macos-persistence |
string | none, sqlite, core-data, swiftdata |
--macos-auto-update |
string | none, sparkle |
The full macosNativeConfig object written to .scaffold/config.yml:
| Config field | Default | Notes |
|---|---|---|
macosNativeConfig.uiFramework |
swiftui |
UI toolkit: swiftui, appkit, or hybrid |
macosNativeConfig.appStyle |
standard |
App style: standard, menu-bar, or agent |
macosNativeConfig.minMacosVersion |
15.0 |
Minimum macOS deployment target (string, e.g. "15.0") |
macosNativeConfig.distribution |
developer-id |
Distribution channel: developer-id, mac-app-store, or both |
macosNativeConfig.sandboxed |
false |
Whether the App Sandbox is enabled |
macosNativeConfig.persistence |
none |
Local persistence: none, sqlite, core-data, or swiftdata |
macosNativeConfig.autoUpdate |
none |
Auto-update mechanism: none or sparkle |
Coupling constraints:
distribution: mac-app-storeorboth→sandboxedis forced totrue(Mac App Store requirement).distribution: mac-app-store→autoUpdateis forced tonone(App Store builds cannot bundle Sparkle).persistence: swiftdatarequiresminMacosVersion≥ 14.0 (SwiftData requires macOS 14+). The init wizard auto-bumpsminMacosVersionto14.0when you pick swiftdata with a lower version;adopt/ direct config validation rejects a swiftdata +<14combination (fail-closed).
Data Science Config (--project-type data-science)
Data science has one forward-compatible config field in the schema, defaulted automatically — no CLI flags are needed in v1:
| Config field | Values | Notes |
|---|---|---|
dataScienceConfig.audience |
solo |
Default (applied by the wizard and --auto). Covers the DS-1 audience (solo / small-team, local-first, prototyping). A future DS-2 release will extend the enum with 'platform' (platform-engineered / larger-team DS) additively, without breaking existing configs. |
Web3 Config (--project-type web3)
Web3 has one forward-compatible config field in the schema, defaulted automatically — no CLI flags are needed in v1:
| Config field | Values | Notes |
|---|---|---|
web3Config.scope |
contracts |
Default (applied by the wizard and --auto). Covers the W3-1 audience (smart-contract / protocol projects on EVM chains — Foundry / Hardhat). A future W3-2 release will extend the enum with 'dapp' (web3 application / dApp) additively, without breaking existing configs. |
Game Config Flags (require --project-type game or auto-set it)
| Flag | Type | Values |
|---|---|---|
--engine |
string | unity, unreal, godot, custom |
--multiplayer |
string | none, local, online, hybrid |
--target-platforms |
comma-sep | pc, web, ios, android, ps5, xbox, switch, vr, ar |
--online-services |
comma-sep | leaderboards, accounts, matchmaking, live-ops |
--content-structure |
string | discrete, open-world, procedural, endless, mission-based |
--economy |
string | none, progression, monetized, both |
--narrative |
string | none, light, heavy |
--locales |
comma-sep | Locale codes: en, ja, fr-FR |
--npc-ai |
string | none, simple, complex |
--modding |
boolean | --modding / --no-modding |
--persistence |
string | none, settings-only, profile, progression, cloud |
Flag aliases: Game flags have
--game-*aliases for consistency with other project types (e.g.,--game-engineis equivalent to--engine). Bare flags like--enginestill work.
Declarative init from a YAML manifest (--from)
For multi-service projects, use scaffold init --from <file> to provide a
full ScaffoldConfig as YAML instead of running the interactive wizard:
scaffold init --from services.yml --forceThe file must be a complete ScaffoldConfig (with version, methodology,
platforms, and project.services[]). Pass - to read from stdin.
--from is exclusive with config-setting flags (--methodology, all
--backend-*, --web-*, etc.); combining them is an error. Operational
flags (--root, --force, --auto, --verbose, --format) still work.
Multi-service execution (v3.17.0+): Multi-service projects are
fully executable. Every stateful command (run, next, status,
skip, complete, info, dashboard, decisions, reset,
rework) accepts --service <name> to target one service's pipeline.
State is sharded under .scaffold/services/<name>/state.json with a
merged global+service view; per-service locks are independent.
Services can expose artifacts for cross-service consumption via the
exports allowlist in config, and pipeline steps can declare
cross-reads: in their frontmatter to consume foreign artifacts
during assembly.
How Flags Interact
- Flag > auto > interactive: Flags always take highest precedence.
--auto --engine unrealuses defaults for everything except engine. - Partial flags + interactive: Provide some flags and the wizard asks only the remaining questions.
scaffold init --project-type game --engine unrealprompts interactively for multiplayer, platforms, etc. - Type-specific flags auto-set project type:
--engine unityautomatically sets--project-type game,--web-rendering ssrsets--project-type web-app,--backend-api-style restsets--project-type backend,--cli-interactivity hybridsets--project-type cli,--lib-visibility publicsets--project-type library,--mobile-platform iossets--project-type mobile-app,--pipeline-processing batchsets--project-type data-pipeline,--ml-phase trainingsets--project-type ml,--ext-manifest 3sets--project-type browser-extension,--research-driver code-drivensets--project-type research,--mcp-language typescriptsets--project-type mcp-server. Error if conflicting type. (Data science and web3 currently have no dedicated CLI flags — pass--project-type data-scienceor--project-type web3directly.) - Cannot mix flag families:
--web-rendering ssr --backend-api-style restis an error. Each flag family (--web-*,--backend-*,--cli-*,--lib-*,--mobile-*,--pipeline-*,--ml-*,--research-*,--ext-*,--mcp-*, game) is exclusive. - Validation:
--depthrequires--methodology custom.--online-servicesrequires--multiplayer onlineorhybrid. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static). ML inference projects must specify a serving pattern. Browser extensions must declare at least one capability (UI surface, content script, or background worker). Notebook-driven research cannot be fully autonomous.stdiotransport cannot use network auth (--mcp-authmust benonewith--mcp-transport stdio).stdiotransport runs locally and cannot use hosted deployment (--mcp-deploymentmust belocalwith--mcp-transport stdio).
CI Examples
# Web-app project (SSR with serverless deploy)
scaffold init --auto --methodology deep --project-type web-app \
--web-rendering ssr --web-deploy-target serverless
# Web-app with real-time features and OAuth
scaffold init --auto --methodology deep --project-type web-app \
--web-rendering ssr --web-deploy-target container \
--web-realtime websocket --web-auth-flow oauth
# Backend project (GraphQL with relational + key-value stores)
scaffold init --auto --methodology deep --project-type backend \
--backend-api-style graphql --backend-data-store relational,key-value
# Backend with event-driven messaging and JWT auth
scaffold init --auto --methodology deep --project-type backend \
--backend-api-style rest --backend-data-store relational \
--backend-auth jwt --backend-messaging event-driven \
--backend-deploy-target container
# CLI project (interactive with multiple distribution channels)
scaffold init --auto --methodology mvp --project-type cli \
--cli-interactivity hybrid --cli-distribution package-manager,standalone-binary
# CLI with structured JSON output
scaffold init --auto --methodology deep --project-type cli \
--cli-interactivity args-only --cli-distribution package-manager \
--cli-structured-output
# Public library with full API docs and ESM bundle
scaffold init --auto --methodology deep --project-type library \
--lib-visibility public --lib-runtime-target isomorphic \
--lib-bundle-format esm --lib-doc-level api-docs
# Internal library (Node-only, no docs)
scaffold init --auto --methodology mvp --project-type library \
--lib-visibility internal --lib-runtime-target node \
--lib-bundle-format cjs --lib-doc-level none
# Cross-platform mobile app with offline support
scaffold init --auto --methodology deep --project-type mobile-app \
--mobile-platform cross-platform --mobile-offline offline-first \
--mobile-push-notifications
# iOS app with private distribution
scaffold init --auto --methodology mvp --project-type mobile-app \
--mobile-platform ios --mobile-distribution private
# Streaming data pipeline with event-driven orchestration
scaffold init --auto --methodology deep --project-type data-pipeline \
--pipeline-processing streaming --pipeline-orchestration event-driven \
--pipeline-quality observability --pipeline-schema schema-registry
# Batch ETL pipeline with DAG orchestration
scaffold init --auto --methodology mvp --project-type data-pipeline \
--pipeline-processing batch --pipeline-orchestration dag-based \
--pipeline-quality validation
# LLM inference service with realtime serving
scaffold init --auto --methodology deep --project-type ml \
--ml-phase inference --ml-model-type llm --ml-serving realtime
# Classical ML training pipeline (no serving)
scaffold init --auto --methodology mvp --project-type ml \
--ml-phase training --ml-model-type classical \
--no-ml-experiment-tracking
# MV3 browser extension with popup and content script
scaffold init --auto --methodology deep --project-type browser-extension \
--ext-manifest 3 --ext-ui-surfaces popup,options \
--ext-content-script --ext-background-worker
# Devtools-only browser extension
scaffold init --auto --methodology mvp --project-type browser-extension \
--ext-manifest 3 --ext-ui-surfaces devtools \
--no-ext-content-script
# Autonomous quant-finance research (trading strategy optimization)
scaffold init --auto --methodology deep --project-type research \
--research-driver code-driven --research-interaction autonomous \
--research-domain quant-finance
# Checkpoint-gated ML architecture search
scaffold init --auto --methodology deep --project-type research \
--research-driver config-driven --research-interaction checkpoint-gated \
--research-domain ml-research
# Solo / small-team data science project (reproducibility-first)
scaffold init --auto --methodology deep --project-type data-science
# Web3 smart-contract / protocol project (Foundry / Hardhat on EVM)
scaffold init --auto --methodology deep --project-type web3
# MCP server — TypeScript, streamable-http transport, tools + resources
scaffold init --auto --methodology deep --project-type mcp-server \
--mcp-language typescript --mcp-transport streamable-http \
--mcp-primitives tools,resources --mcp-auth oauth --mcp-deployment hosted
# MCP server — Python, stdio transport (local tooling, no auth)
scaffold init --auto --methodology mvp --project-type mcp-server \
--mcp-language python --mcp-transport stdio --mcp-auth none
# Multiplayer mobile game with Unity
scaffold init --project-type game --methodology deep --auto \
--engine unity --multiplayer online --target-platforms ios,android \
--economy monetized --online-services matchmaking,leaderboards
# Simple puzzle game
scaffold init --project-type game --auto --engine godot
# Custom methodology at depth 3
scaffold init --methodology custom --depth 3 --auto
# AAA console game with full configuration
scaffold init --project-type game --methodology deep --auto \
--engine unreal --multiplayer online --target-platforms ps5,xbox,pc \
--economy both --online-services matchmaking,leaderboards,accounts,live-ops \
--narrative heavy --locales en,ja,ko,zh-CN,fr,de,es \
--npc-ai complex --modding --persistence cloud \
--content-structure open-worldProject-Type Overlays
Scaffold supports project-type overlays — domain-specific knowledge and pipeline customizations that activate based on your project type. When you set a project type during scaffold init, the corresponding overlay layers on top of your chosen methodology (mvp, deep, or custom):
- Injects domain knowledge into existing pipeline steps (e.g., SSR caching strategies into
tech-stack, API pagination patterns intocoding-standards)
The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). Like the game overlay, the mcp-server overlay also adjusts step enablement — it disables the UI-focused steps (design-system, ux-spec, review-ux) since an MCP server has no UI, and marks database-schema/review-database as if-needed. The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, browser-extension, research, data-science, and web3 overlays are knowledge-only — they inject domain expertise into existing steps without changing which steps run or how they depend on each other. The research type additionally supports domain sub-overlays (quant-finance, ml-research, simulation) that layer domain-specific knowledge on top of the core research overlay, and the backend type supports a fintech sub-overlay. Both research and backend accept domain as either a single string or an array (e.g. domain: ['quant-finance', 'simulation']) for stacking multiple sub-overlays; the wizard and CLI flags remain single-select in v1, so multi-domain stacking requires hand-editing .scaffold/config.yml.
Overlays are composable with methodology presets. An MVP web-app gets fewer steps at lower depth; a deep backend project gets exhaustive analysis of every architectural decision.
| Project Type | Overlay | Knowledge Entries | Config Options |
|---|---|---|---|
web-app |
web-app-overlay.yml |
17 entries (rendering, state management, auth, SSR, deploy targets, real-time, PWA, testing) | Rendering strategy, deploy target, real-time, auth flow |
backend |
backend-overlay.yml |
22 entries (API design, data stores, auth, messaging, observability, deploy, caching, rate limiting) | API style, data store(s), auth, messaging, deploy target |
cli |
cli-overlay.yml |
10 entries (argument parsing, config management, output formatting, distribution, testing, error handling) | Interactivity model, distribution channels, structured output |
library |
library-overlay.yml |
12 entries (API design, bundling, type definitions, versioning, documentation, testing, security) | Visibility, runtime target, bundle format, type definitions, documentation level |
mobile-app |
mobile-app-overlay.yml |
12 entries (architecture, offline patterns, push notifications, deployment, distribution, testing, security) | Platform, distribution model, offline support, push notifications |
data-pipeline |
data-pipeline-overlay.yml |
12 entries (architecture, batch and streaming patterns, orchestration, schema management, quality, testing, security) | Processing model, orchestration, data quality strategy, schema management, data catalog |
ml |
ml-overlay.yml |
12 entries (architecture, training and serving patterns, experiment tracking, model evaluation, observability, testing, security) | Project phase, model type, serving pattern, experiment tracking |
browser-extension |
browser-extension-overlay.yml |
12 entries (architecture, manifest configuration, service workers, content scripts, cross-browser, store submission, testing, security) | Manifest version, UI surfaces, content script, background worker |
research |
research-overlay.yml + domain sub-overlays |
25 entries (experiment loop, tracking, overfitting prevention, backtesting, risk metrics, architecture search, simulation) | Experiment driver, interaction mode, domain, experiment tracking |
data-science |
data-science-overlay.yml |
13 entries (reproducibility, experiment tracking, notebook discipline, model evaluation, data versioning, dev environment, observability, project structure, conventions, requirements, security, testing, architecture) | Audience (solo default; platform reserved for DS-2) |
web3 |
web3-overlay.yml |
14 entries (Foundry tooling, smart-contract security, upgradeability, gas optimization, oracles, audit workflow, deployment, testing patterns, EVM fundamentals, ABI/interface design, event/log indexing, supply-chain) | Scope (contracts default; dapp reserved for W3-2) |
game |
game-overlay.yml |
25 entries (engines, networking, audio, VR/AR, economy, save systems, certification) | Engine, multiplayer, platforms, economy, narrative, and 6 more |
mcp-server |
mcp-server-overlay.yml |
12 entries (protocol fundamentals, tool design, resource design, transport patterns, SDK selection, auth, error handling, testing, observability, deployment, versioning, prompt primitives) | Language, transport, primitives, auth, deployment, stateful |
macos-native |
macos-native-overlay.yml |
20 entries (architecture, SwiftUI/AppKit patterns, accessibility, distribution, entitlements, sandboxing, testing, observability, security, conventions) | UI framework |
Game Development
Scaffold fully supports game development projects. When you select game as your project type, a project-type overlay activates 24 game-specific pipeline steps and injects game domain expertise into existing steps — all while keeping the standard pipeline workflow (status, next, rework, multi-model review) fully functional.
Getting Started
# Interactive — the wizard asks about your engine, multiplayer, platforms, etc.
scaffold init
# Non-interactive with defaults (engine: custom, single-player, PC)
scaffold init --project-type game --auto
# Non-interactive with specific configuration
scaffold init --project-type game --methodology deep --auto \
--engine unity --multiplayer online --target-platforms ios,android \
--economy monetized --online-services matchmaking,leaderboards
# Adopt an existing game project (auto-detects Unity/Unreal/Godot)
scaffold adoptHow It Works
Game support uses a project-type overlay architecture. You choose your methodology normally (mvp, deep, or custom), then projectType: game layers on top:
- Enables 24 game steps — GDD, performance budgets, art bible, audio design, etc.
- Disables 3 web-centric steps —
design-system,ux-spec,review-ux(replaced bygame-ui-spec) - Injects 29 game knowledge entries into existing steps (e.g., game engine evaluation into
tech-stack, game testing patterns intotdd) - Remaps artifact references so downstream steps read game-specific docs instead of web ones
A game jam project uses mvp + game overlay (fewer steps, lower depth). An AAA project uses deep + game overlay (all steps, max depth).
Game Configuration
During scaffold init, the wizard asks game-specific questions with progressive disclosure:
| Category | Questions |
|---|---|
| Core (always asked) | Game engine (Unity/Unreal/Godot/custom), multiplayer mode (none/local/online/hybrid), target platforms (PC/console/mobile/VR/AR) |
| Conditional | Online services (if multiplayer), content structure (levels/open-world/procedural/endless), economy type (none/progression/monetized) |
| Advanced (opt-in) | Narrative depth, supported locales, NPC AI complexity, mod support, persistence model |
These answers control which conditional steps activate. A single-player puzzle game gets a different pipeline than a multiplayer live-service RPG.
Game Pipeline Steps
Always enabled (12 steps):
| Step | Phase | What It Produces |
|---|---|---|
game-design-document |
Pre | Game pillars, core loop, mechanics catalog, progression systems |
review-gdd |
Pre | Multi-pass review of GDD for pillar coherence, scope feasibility |
performance-budgets |
Foundation | Frame budgets, memory budgets, GPU limits, loading targets per platform |
game-accessibility |
Specification | XAG-aligned accessibility plan (visual, motor, cognitive, auditory) |
input-controls-spec |
Specification | Input bindings, rebinding, haptics, dead zones, cross-play fairness |
game-ui-spec |
Specification | HUD, menus, controller navigation, settings, FTUE/tutorial, UI states |
review-game-ui |
Specification | Multi-pass review of game UI for completeness and accessibility |
content-structure-design |
Specification | Level layouts, world regions, procedural rulesets, or mission templates |
art-bible |
Specification | Art style, asset specs, naming conventions, DCC pipeline, LOD strategy |
audio-design |
Specification | Audio direction, adaptive music, spatial audio, middleware config, VO |
playtest-plan |
Quality | Playtest types, schedule, feedback templates, balance testing |
analytics-telemetry |
Quality | Event taxonomy, crash telemetry, data pipeline, privacy compliance |
Conditional (12 steps — activated by your game configuration):
| Step | Activates When | What It Produces |
|---|---|---|
narrative-bible |
Narrative is light/heavy | World lore, characters, dialogue systems, branching narrative |
netcode-spec |
Multiplayer is online/hybrid | Network topology, tick rate, prediction, lag compensation, anti-cheat |
review-netcode |
Netcode spec enabled | Latency tolerance, bandwidth, cheat resistance review |
ai-behavior-design |
NPC AI is simple/complex | Behavior trees, pathfinding, perception, difficulty scaling |
economy-design |
Economy is not none | Currencies, loot tables, monetization, legal compliance |
review-economy |
Economy design enabled | Inflation analysis, exploit detection, ethical monetization review |
online-services-spec |
Online services selected | Identity, leaderboards, matchmaking, moderation, cloud save |
modding-ugc-spec |
Mod support enabled | Mod API, sandboxing, distribution, content moderation |
save-system-spec |
Persistence is not none | Save format, cloud sync, corruption recovery, migration |
localization-plan |
Multiple locales | String management, fonts (CJK/RTL), VO localization, LQA |
live-ops-plan |
Live-ops selected | Content cadence, events, hotfix deployment, maintenance |
platform-cert-prep |
Console/mobile/VR targets | Sony TRC, Xbox XR, Nintendo Lotcheck, store compliance checklists |
Multi-type Detection
scaffold adopt detects 14 project types from manifest files and directory layouts:
| Type | Key Signals |
|---|---|
web-app |
next.config.*, nuxt.config.*, app/ router dirs, SPA frameworks |
backend |
routes/ or controllers/, ORM schemas, server deps |
cli |
bin field in manifest, commander/yargs/clap deps |
library |
main/types fields, peer dependencies, no bin |
mobile-app |
app.json (Expo), ios//android/ dirs, React Native deps |
game |
Assets/*.meta (Unity), *.uproject (Unreal), project.godot (Godot) |
data-pipeline |
dags/ dir, Airflow/Prefect/Dagster deps, Spark configs |
ml |
training//models/ dirs, PyTorch/TensorFlow deps, MLflow configs |
browser-extension |
manifest.json with manifest_version field |
research |
program.md + results.tsv, backtest/strategy files with trading deps, optimization deps + experiment dirs, simulation framework deps |
data-science |
Marimo signals required (marimo dep or .marimo.toml); DVC (dvc.yaml, .dvc/config, dvc py dep) is supplementary evidence only. Low-tier; defers to ml / research / data-pipeline when those match at medium/high tier |
web3 |
foundry.toml or hardhat.config.{ts,js,cjs,mjs} (medium-tier); remappings.txt, lib/forge-std are supplementary low-tier signals. EVM-only scope. Library-collision boundary pinned by tiebreak (high-tier library wins over medium-tier web3 for published-library Hardhat projects) |
mcp-server |
@modelcontextprotocol/sdk / mcp / fastmcp dep = low (MCP clients share these deps — avoids mis-adopting a client as a server); dep + entrypoint registering tools/resources = high |
macos-native |
*.xcodeproj / *.xcworkspace + .swift sources = medium; Package.swift + import AppKit/import SwiftUI without mobile targets = high |
Each detector returns a confidence tier (high/medium/low) with evidence trails. Override detection with --project-type <type>.
Multi-type Disambiguation
When scaffold adopt finds signals matching multiple project types, you'll
see a radio prompt:
? Which best describes this project? (Use arrow keys)
> web-app [high] next-config (next.config.mjs), app-router-dir (app/page.tsx), public-dir (public/), react-dep
backend [high] routes-dir (app/api), prisma-schema (prisma/schema.prisma), pg-dep
library [medium] pkg-main-field (package.json), pkg-types-field (package.json), peer-deps (react)
None of these — continue without a project typeThe default selection is the highest-confidence match with the most evidence. Press Enter to accept, or use arrow keys to pick a different option.
For non-interactive use (CI, scripts), pass --project-type <type> explicitly:
scaffold adopt --auto --project-type web-appIf you run scaffold adopt --auto and detection is ambiguous, the command
exits with code 6 (ExitCode.Ambiguous) and lists the candidate types in the
error message.
The Pipeline
Phase 0 — Product Vision (vision)
You describe your idea and Claude turns it into a strategic vision document covering who it's for, what makes it different, and what success looks like. The review step stress-tests the vision for gaps, and the innovate step explores market positioning opportunities. Without this, later steps lack a clear North Star and features drift.
| Step | What It Does |
|---|---|
create-vision |
Claude asks about your idea — who it's for, what problem it solves, what makes it different — and produces a vision document with elevator pitch, target audience, competitive positioning, guiding principles, and success criteria. |
review-vision |
Claude stress-tests the vision across five dimensions — clarity, audience precision, competitive rigor, strategic coherence, and whether the PRD can be written from it without ambiguity — and fixes what it finds. |
innovate-vision |
Claude explores untapped opportunities — adjacent markets, AI-native capabilities, ecosystem partnerships, and contrarian positioning — and proposes innovations for your approval. (optional) |
Phase 1 — Product Definition (pre)
Claude translates your vision into a detailed product requirements document (PRD) with features, user personas, constraints, and success criteria. Then it breaks the PRD into user stories — specific things users can do, each with testable acceptance criteria in Given/When/Then format. Review and innovation steps audit for gaps and suggest enhancements. Without this, you're building without a spec.
| Step | What It Does |
|---|---|
create-prd |
Claude translates your vision (or idea, if no vision exists) into a product requirements document with problem statement, user personas, prioritized feature list, constraints, non-functional requirements, and measurable success criteria. |
innovate-prd |
Claude analyzes the PRD for feature-level gaps — competitive blind spots, UX enhancements, AI-native possibilities — and proposes additions for your approval. (optional) |
review-prd |
Claude reviews the PRD across eight passes — problem rigor, persona coverage, feature scoping, success criteria, internal consistency, constraints, non-functional requirements — and fixes blocking issues. |
user-stories |
Claude breaks every PRD feature into user stories ("As a [persona], I want [action], so that [outcome]") organized by epic, each with testable acceptance criteria in Given/When/Then format. |
innovate-user-stories |
Claude identifies UX enhancement opportunities — progressive disclosure, smart defaults, accessibility improvements — and integrates approved changes into existing stories. (optional) |
review-user-stories |
Claude verifies every PRD feature maps to at least one story, checks that acceptance criteria are specific enough to test, validates story independence, and builds a requirements traceability index at higher depths. |
Phase 2 — Project Foundation (foundation)
Claude researches and documents your technology choices (language, framework, database) with rationale, creates coding standards tailored to your stack with actual linter configs, defines your testing strategy and test pyramid, and designs a directory layout optimized for parallel AI agent work. Without this, agents guess at conventions and produce inconsistent code.
| Step | What It Does |
|---|---|
beads |
Sets up optional Beads task tracking for downstream projects Scaffold generates, with a lessons-learned file for cross-session learning, and creates the initial CLAUDE.md skeleton with core principles and workflow conventions. (This is not Scaffold's own issue-tracking workflow.) |
tech-stack |
Claude researches technology options for your project — language, framework, database, hosting, auth — evaluates each against your requirements, and documents every choice with rationale and alternatives considered. |
coding-standards |
Claude creates coding standards tailored to your tech stack — naming conventions, error handling patterns, import organization, AI-specific rules — and generates working linter and formatter config files. |
tdd |
Claude defines your testing approach — which types of tests to write at each layer, coverage targets, what to mock and what not to, test data patterns — so agents write the right tests from the start. |
project-structure |
Claude designs a directory layout optimized for parallel AI agent work (minimizing file conflicts), documents where each type of file belongs, and creates the actual directories in your project. |
Phase 3 — Development Environment (environment)
Claude sets up your local dev environment with one-command startup and live reload, creates a design system with color palette, typography, and component patterns (web apps only), configures your git branching strategy with CI pipeline and worktree scripts for parallel agents, optionally sets up automated PR review with multi-model validation, and configures AI memory so conventions persist across sessions. Without this, you're manually configuring tooling instead of building.
| Step | What It Does |
|---|---|
dev-env-setup |
Claude configures your project so make dev (or equivalent) starts everything — dev server with live reload, local database, environment variables — and documents the setup in a getting-started guide. |
design-system |
Claude creates a visual language — color palette (WCAG-compliant), typography scale, spacing system, component patterns — and generates working theme config files for your frontend framework. (web apps only) |
git-workflow |
Claude sets up your branching strategy, commit message format, PR workflow, CI pipeline with lint and test jobs, and worktree scripts so multiple AI agents can work in parallel without conflicts. |
automated-pr-review |
Claude configures automated code review — three-CLI MMR dispatch (Codex, Antigravity, Claude) plus Superpowers code-reviewer as a complementary 4th channel via the scaffold wrappers, with severity definitions and review criteria tailored to your project. Covers PRs and non-PR targets (local code, diffs, files). (optional) |
ai-memory-setup |
Claude extracts conventions from your docs into path-scoped rule files that load automatically, optimizes CLAUDE.md with a pointer pattern, and optionally sets up persistent cross-session memory. |
Phase 4 — Testing Integration (integration)
Claude auto-detects your platform (web or mobile) and configures end-to-end testing — Playwright for web apps, Maestro for mobile/Expo. Skips automatically for backend-only projects. Without this, your test pyramid has no top level.
| Step | What It Does |
|---|---|
add-e2e-testing |
Claude detects whether your project is web or mobile, then configures Playwright (web) or Maestro (mobile) with a working smoke test, baseline screenshots, and guidance on when to use E2E vs. unit tests. (optional) |
Phase 5 — Domain Modeling (modeling)
Claude analyzes your user stories to identify all the core concepts in your project — the entities (things like Users, Orders, Tools), their relationships, the rules that must always be true, and the events that happen when state changes. This becomes the shared language between all your docs and code. Without this, different docs use different names for the same concept and agents create duplicate logic.
| Step | What It Does |
|---|---|
domain-modeling |
Claude analyzes your user stories to identify the core concepts in your project (entities, their relationships, the rules that must always hold true), and establishes a shared vocabulary that all docs and code will use. |
review-domain-modeling |
Claude verifies every PRD feature maps to a domain entity, checks that business rules are enforceable, and ensures the shared vocabulary is consistent across all project files. |
Phase 6 — Architecture Decisions (decisions)
Claude documents every significant technology and design decision as an Architecture Decision Record (ADR) — what was decided, what alternatives were considered, and why. The review catches contradictions and missing decisions. Without this, future contributors (human or AI) don't know why things are the way they are.
| Step | What It Does |
|---|---|
adrs |
Claude documents every significant design decision — what was chosen, what alternatives were considered with pros and cons, and what consequences follow — so future contributors understand why, not just what. |
review-adrs |
Claude checks for contradictions between decisions, missing decisions implied by the architecture, and whether every choice has honest trade-off analysis. |
Phase 7 — System Architecture (architecture)
Claude designs the system blueprint — which components exist, how data flows between them, where each piece of code lives, and how the system can be extended. This translates your domain model and decisions into a concrete structure that implementation will follow. Without this, agents make conflicting structural assumptions.
| Step | What It Does |
|---|---|
system-architecture |
Claude designs the system blueprint — which components exist, how data flows between them, where each module lives in the directory tree, and where extension points allow custom behavior. |
review-architecture |
Claude verifies every domain concept lands in a component, every decision constraint is respected, no components are orphaned from data flows, and the module structure minimizes merge conflicts. |
Phase 8 — Specifications (specification)
Claude creates detailed interface specifications for each layer of your system. Database schema translates domain entities into tables with constraints that enforce business rules. API contracts define every endpoint with request/response shapes, error codes, and auth requirements. UX spec maps out user flows, interaction states, accessibility requirements, and responsive behavior. Each is conditional — only generated if your project has that layer. Without these, agents guess at interfaces and implementations don't align.
| Step | What It Does |
|---|---|
database-schema |
Claude translates your domain model into database tables with constraints that enforce business rules, indexes optimized for your API's query patterns, and a reversible migration strategy. (if applicable) |
review-database |
Claude verifies every domain entity has a table, constraints enforce business rules at the database level, and indexes cover all query patterns from the API contracts. (if applicable) |
api-contracts |
Claude specifies every API endpoint — request/response shapes, error codes with human-readable messages, auth requirements, pagination, and example payloads — so frontend and backend can be built in parallel. (if applicable) |
review-api |
Claude checks that every domain operation has an endpoint, error responses include domain-specific codes, and auth requirements are specified for every route. (if applicable) |
ux-spec |
Claude maps out every user flow with all interaction states (loading, error, empty, populated), defines accessibility requirements (WCAG level, keyboard nav), and specifies responsive behavior at each breakpoint. (if applicable) |
review-ux |
Claude verifies every user story has a flow, accessibility requirements are met, all error states are documented, and the design system is used consistently. (if applicable) |
Phase 9 — Quality (quality)
Claude reviews your testing strategy for coverage gaps, generates test skeleton files from your user story acceptance criteria (one test per criterion, ready for TDD), creates automated eval checks that verify code meets your documented standards, designs your deployment pipeline with monitoring and incident