The Scaffold Pipeline

The mental model

Scaffold is a prompt pipeline: a curated, ordered sequence of structured meta-prompts that turn an idea into a fully-specified, build-ready project. Each meta-prompt is a markdown file under content/pipeline/; the CLI assembles one into a full prompt at runtime (injecting upstream artifacts, knowledge entries, and depth instructions) and hands it to Claude Code or another AI tool.

The pipeline divides cleanly into two regimes:

• Planning (phases 0–14) — stateful, sequential steps. Each produces a durable artifact (a vision doc, a PRD, a tech-stack doc, an implementation plan…). The CLI tracks completion in .scaffold/state.json, enforces dependencies, and detects when you re-run a step (UPDATE mode). You run each step roughly once, in dependency order, working toward a frozen spec.
• Build (phase 15) — stateless, on-demand steps. These are the execution loops (single-agent, multi-agent), the resume commands, quick-task, and new-enhancement. They carry no completion state and can be run repeatedly (stateless: true in frontmatter — src/types/frontmatter.ts:126). You run these over and over while actually writing code.

The 16 phases are the single source of truth in code: the PHASES constant (src/types/frontmatter.ts:6) defines every slug, number, and display name. Everything in this guide is anchored to it.

The 16 phases at a glance

Phase numbers and display names below are quoted verbatim from the PHASES constant (src/types/frontmatter.ts:6). Phases 0–14 are planning; phase 15 is the stateless build phase.

Each step's order is phase-aligned: phase N occupies the N00–N99 band (tech-stack is 220, coding-standards is 230, single-agent-start is 1510). The order field is the primary tiebreaker in the topological sort, so within a phase steps run in order sequence.

The arrows show the phase progression, not the exact step-level dependency graph — a single step usually depends on one upstream step, not its whole phase. See Why a step is blocked for how dependencies actually gate execution.

Methodology & depth

Two orthogonal knobs control how much of the pipeline runs and how thoroughly:

1. Preset — which steps are enabled. Three presets ship (content/methodology/): mvp, custom (balanced, depth 3), and deep (the schema default).
2. Depth — how thorough each enabled step's output is, on a 1–5 scale.

Depth (1–5)

Every depth level dials the same step from a sketch to an exhaustive document. Each step's ## Methodology Scaling section spells out its behavior per level — coding-standards at depth 1 is "core naming conventions, commit format, import ordering, 1–2 pages"; at depth 5 it's "full suite with all sections, custom linter rules, and code review checklist, 15–20 pages."

External-model / multi-model dispatch at depth 4–5 is step-specific — it applies to the prompts whose ## Methodology Scaling section declares it (chiefly the review-* / innovate-* / validation steps). For most authoring steps, higher depth just means a more thorough single-model output.

Depth 3 is the inflection point where steps start adding structure, cross-references, and validation beyond the basics. Override depth per run with scaffold run <step> --depth N.

The three presets

Project-type playbooks

Overlays (content/methodology/*-overlay.yml) layer onto a preset. Most overlays only inject domain knowledge into existing steps (so a web-app build pulls in web-app-auth-patterns during tech-stack, security, etc.); a few also enable whole step families.

Other shipped overlays include backend, data-pipeline, data-science, ML, web3, browser-extension, and several research presets — all under content/methodology/.

Navigating the pipeline

The CLI is your driver. Every command lives in src/cli/commands/.

A typical loop: scaffold next to see what's unblocked → scaffold run <step> → repeat. next is a pure read — it derives eligibility live from the graph + state and deliberately does not mutate state.json, so running it after an upgrade won't churn committed state.

rework is phase-scoped: scaffold rework --through 5 re-runs phases 1–5, --phases 2,7 re-runs just those, --exclude 3 drops a phase, --depth 5 bumps depth for the batch. It batch-resets the selected steps to pending and creates a rework session the runner skill walks through.

For build-phase work you don't touch next/complete — the stateless steps (single-agent-start, multi-agent-start, the resume commands, quick-task, new-enhancement) are run on demand and never tracked. See the concepts guide{mode=advisory} and the CLI reference{mode=advisory} for the full command surface.

Why a step is blocked

A step becomes eligible only when its dependencies are satisfied. The frontmatter distinguishes two relationships, and they behave very differently:

• dependencies (src/types/frontmatter.ts:114) — hard gates. scaffold run refuses a step whose deps aren't completed or skipped, exiting with DEP_UNMET (src/cli/commands/run.ts:262-281). coding-standards declares dependencies: [tech-stack], so you can't write standards before you pick a stack.
• reads (src/types/frontmatter.ts:122) — soft references. A step reads an upstream artifact if it's available, but a missing/incomplete read never blocks execution — the assembler silently skips it (src/cli/commands/run.ts:413-421). coding-standards reads create-prd so the domain informs which patterns matter, but a missing PRD won't stop it.

Conditional ("if-needed") steps

A step with conditional: 'if-needed' (src/types/frontmatter.ts:118) is enabled but only applies to certain project shapes. database-schema is conditional: "if-needed" (content/pipeline/specification/database-schema.md:10) — it runs only if your project has a database layer. The spec steps (database-schema, api-contracts, ux-spec), add-e2e-testing, design-system, beads, and platform-parity-review are all conditional in the default presets.

A representative dependency slice

The phase-2 foundation steps show the gating in miniature: tech-stack has no dependencies (it kicks off the foundation), and coding-standards depends on it.

Solid arrows are hard dependencies (block until done); dashed arrows are soft reads (used if present, never block).

CREATE vs UPDATE mode

Running a planning step a second time doesn't blindly overwrite its artifact. Every document-creating prompt carries a Mode Detection block: if the output file already exists, the step runs in UPDATE mode instead of CREATE mode.

scaffold run detects this and (unless --force) confirms before re-running a completed step, and warns on a depth downgrade (re-running at a lower depth than last time). In UPDATE mode the prompt is instructed to preserve human/team customizations and only change what genuinely needs to change. From coding-standards's Mode Detection block (content/pipeline/foundation/coding-standards.md:57):

Update mode if docs/coding-standards.md exists. In update mode: preserve naming conventions, lint rule customizations, commit message format, and project-specific patterns.

So re-running coding-standards after you've hand-tuned its linter config keeps your overrides; it doesn't reset them. This is what makes the planning phases safe to iterate — you can rework a phase at higher depth and get richer output without losing the decisions you've already made.

Phase-boundary audits

Completing certain planning docs automatically triggers a non-gating cross-document audit. Six steps are phase boundaries (src/observability/engine/phase-subsets.ts:1-8): user-stories, tech-stack, coding-standards, design-system, implementation-plan, and implementation-playbook. When you complete one of these, the state manager fires an H-cross-doc audit and prints a one-line summary — catching doc drift the moment a planning phase closes, without ever blocking the transition. See the build observability guide{mode=advisory} for how that audit works and what the nine lenses check.

Where it all lives

The phase list, ordering, and slugs are defined exactly once, in PHASES (src/types/frontmatter.ts:6); every doc, skill, and command resolves against it.