Phase 2 — Scaffold ("it's a lego, not a monolith")

Goal: chosen boilerplate → this specific app. Only what the idea needs, kept or built; everything else removed or disabled. Real git history. Every must_have_feature verified actually working before this phase ends — not just "the app boots."

Read PIPELINE_STATUS.md first (sections 1-2: the idea, the boilerplate, known stack gaps). Don't re-ask what's already answered there.

Check chosen_boilerplate now. If it's the literal token none (minimal scaffold), several steps below are lighter or don't apply — each says so inline. Don't force a keep/remove pass or a paid-default audit onto a project that never had either.

Step 0 — Environment check

Follow shared/references/environment-check.md. Run check_environment.sh with the right flags for this boilerplate (Docker flags only if boxyhq/saas-starter-kit). Fix gaps via install_environment.sh (with user consent) before proceeding — don't discover a missing tool halfway through cloning.

Step 1 — Read the boilerplate's own docs first

Real boilerplate: look for AGENTS.md, CLAUDE.md, llms.txt, CONTRIBUTING.md before touching code. wasp-lang/open-saas ships AGENTS.md specifically for this. Follow its conventions. No-boilerplate case: skip — there's no upstream repo with its own conventions to read.

Step 2 — Get a working baseline

Real boilerplate: clone, follow its own README to get local dev running unmodified. Before the first commit — verify .env/.env.local is actually in .gitignore (per shared/references/git-hygiene.md); getting local dev running usually means creating a real .env file, and committing before checking this is exactly how a secret ends up in git history. Fix .gitignore first, in its own commit, if it's missing this. Then commit as first commit (or note the upstream SHA branched from). No-boilerplate, vitrine template (minimal_scaffold_source is a URL): same as above — clone that specific template, run its README. No-boilerplate, from-scratch (minimal_scaffold_source is from-scratch): run create-next-app (or the harness's equivalent) fresh, confirm it boots, first commit.

Either way: PIPELINE_STATUS.md → current_phase: scaffolding, repo_path_local, last_scaffold_commit.

Step 2b — Set up CI and (if Claude Code) the redesign hook — once, now

A real dev sets this up before writing feature code, not after. Both are one-time, inexpensive, and protect everything built from here on:

1. CI: copy references/ci-workflow-template.yml to .github/workflows/ci.yml, adjust for the actual package manager (see shared/references/ci-and-branching.md), commit. PIPELINE_STATUS.md → ci_configured: yes.
2. Redesign scope hook (Tier 1 — real blocking, not advice): run node shared/scripts/install_scope_hook.cjs --apply, which installs the PreToolUse guard and mounts the hook bridge in the harness profile. It applies at the next dsh web start (restarting ends the running session, so do it when convenient; the git-diff script covers until then). PIPELINE_STATUS.md → redesign_hook_configured: yes (or pending-restart). Detail: 02b-redesign/references/enforcement.md.

No-boilerplate case: still do this — CI matters just as much for a minimal scaffold, and costs nothing extra to set up now.

Step 3 — Build (or resume) the Feature Blueprint

Resuming? Check feature_blueprint_path in PIPELINE_STATUS.md first — if FEATURE_BLUEPRINT.md already exists, read it, don't rebuild from scratch. Its missing/needs-modification/unknown rows are the actual to-do list for this session; don't waste a turn re-deriving what's already been mapped. Also git pull first if there's any chance another session/harness touched this repo since — a stale local read of a file that's supposed to be the source of truth defeats the point of having it.

Fresh build: follow references/feature-blueprint-guide.md in full — this is the fix for features going missing to Phase 3 undetected, and what keeps this phase token-light: map structure first (directory tree + README + package.json + the boilerplate's AI doc), infer where each must_have_feature should live, only THEN read those specific files to confirm real status. Never read the whole codebase to "get oriented" — the blueprint's structural pass replaces that. For the no-boilerplate case this is much lighter (few features, e.g. "quiz timer," "results page") but still worth doing — it's still the acceptance gate in Step 8.

Output: FEATURE_BLUEPRINT.md at project root, one row per must_have_feature, Status column honestly filled from actually opening the relevant files (not guessed). PIPELINE_STATUS.md section 3 → feature_blueprint_path.

Step 4 — Keep / disable / remove pass

No-boilerplate case: skip entirely — nothing to prune on a from-scratch or bare-template scaffold. Go to Step 6.

Real boilerplate: for each of its features (from README/docs, cross-check against explicitly_not_needed):

• Keep: maps directly to a must_have_feature.
• Disable, don't delete: plausible later value, not needed now (e.g. payments with no monetization yet). Comment out / feature-flag. Note in PIPELINE_STATUS.md so Phase 4 knows it's there.
• Remove: conflicts with the idea or adds maintenance/security surface for zero value (e.g. SSO in a solo consumer app). Actually delete — don't leave dead enterprise auth code sitting around as attack surface.

For any paid-by-default piece (S3, email, Svix, Retraced — per the chosen boilerplate's audit in 01-foundation-research/references/boilerplates.md), consult shared/references/free-stack-swaps.md's own "disable instead when" guidance for that specific piece as part of this keep/remove decision — e.g. it already says most solo apps should just remove Svix rather than standing up a self-hosted replacement for a feature nothing consumes. Don't re-decide this independently in Step 4 and then again in Step 5; Step 5 only swaps what Step 4 decided to keep.

Show the plan to the user before executing — one short list, let them object before anything gets deleted.

Record in PIPELINE_STATUS.md section 3 (modules_kept, modules_removed_or_disabled).

Step 5 — Apply the free-stack swaps

No-boilerplate case: skip entirely — a zero-backend site has no paid-by-default piece to swap. Go to Step 6.

Real boilerplate: read shared/references/free-stack-swaps.md. For every paid-by-default piece this boilerplate ships (per 01-foundation-research/references/boilerplates.md's audit for the chosen boilerplate) that's staying in scope per Step 4: apply the documented swap. Most are env-var-only changes (S3→Garage, SendGrid→Brevo) — verify, don't assume, but don't over-engineer a code rewrite where a config change suffices. Update known_stack_gaps_for_this_user in PIPELINE_STATUS.md to reflect what's now fixed vs. still pending user action (e.g. "needs a free Brevo account — see shared/references/user-setup-guides.md").

Step 6 — Execute in small, committed steps

Per shared/references/git-hygiene.md — one logical change per commit:

1. Remove/disable unused modules.
2. Apply stack swaps (Step 5).
3. Build whatever FEATURE_BLUEPRINT.md shows as missing or needs-modification.
4. Content/copy specific to the idea — match the boilerplate's existing patterns.
5. Run existing tests after each meaningful change, not just at the end.

More than a handful of changes? Run it as a ledgered loop — the discipline is written out in 00-orchestrator/SKILL.md → Delegation discipline. In practice, per task:

• take one missing/needs-modification row at a time, and quote the blueprint row verbatim in the dispatch instead of summarising it;
• name the model on the dispatch (deepseek-flash for mechanical work, the session model for anything that needs judgement) — an omitted model silently inherits the expensive one;
• after a task that touches more than one file, dispatch a separate reviewer with fresh context and two verdicts: does it match that blueprint row, and is the code any good;
• one fix dispatch per review wave with the whole findings list, then re-check only the fix;
• append Task N: complete (commits a1b2c3d..d4e5f6a) to docs/pipeline/LEDGER.md as each task lands. Compaction erases memory; the ledger and git log are what survive it.

Step 7 — Cross-boilerplate skill references

No-boilerplate case: skip — nothing upstream to reference.

If the boilerplate documents its own official skill/plugin integration (e.g. Wasp's Claude Code plugin), use that instead of reinventing equivalent logic — check during Step 1, not after duplicating the work.

Step 8 — Verify against the blueprint, then hand off

Acceptance gate — replaces "app runs with no console errors" as sufficient:

• Every row in FEATURE_BLUEPRINT.md is exists-and-works. Not exists-but-incomplete, not missing, not unknown. This is the check that was being skipped.
• CI (ci_configured: yes from Step 2b) is green on the final push — lint, typecheck, production build, tests. A production build succeeding is a different, stronger claim than "the dev server has no console errors" — don't substitute one for the other.
• .env.example lists every env var actually needed now (no leftovers from removed features, nothing missing for added ones).
• PIPELINE_STATUS.md section 3 complete, env_vars_needed by name only (see shared/references/secrets-handling.md), current_phase: ready_to_deploy.
• Pushed to GitHub (create the repo with the user if needed — GitHub account/token steps are in shared/references/user-setup-guides.md, don't re-explain from scratch).

Ask about a design pass before deploy. The app still looks like the boilerplate's default styling. Run node shared/scripts/setup_harness.cjs --check first (it reports whether vision and screenshots actually work — the redesign phase depends on them), then offer 02b-redesign/SKILL.md now or "deploy as-is, revisit later" — let the user choose, don't silently skip it. Record redesign_ran: yes | no | deferred in §3b either way.

Hand off to 02b-redesign/SKILL.md (if chosen) or 03-deploy-vps/SKILL.md.