Phase 1 — Foundation & Research

Output: a concrete requirement list + a starting point — recorded in PIPELINE_STATUS.md. Nothing gets scaffolded yet. This phase is intentionally fast for the common case — no multi-way comparison ritual, no re-deriving the same decision from scratch every time.

Step 1 — Understand the idea (concretely, not approximately)

Extract, explicitly: what the app is (1 sentence) · who it's for · what it must do (user's words, not assumed) · stated constraints (locale, free-only, integrations).

This is the single biggest lever against features going missing later — a vague requirement here produces a vague Phase 2 blueprint and features silently don't get built. Vague enough that two different builds would satisfy it ("user profiles" — what fields? "search" — by what?) → ask now, even if it feels like slowing down. Don't ask more than 2-3 questions per round. Write answers into PIPELINE_STATUS.md section 1 immediately (create the file, current_phase: research, if it doesn't exist).

Useful questions, skip any already answered: accounts needed at all? · payments, now or later? · single-tenant or multi-tenant? · locale/language? · which business-case shape does this match (marketplace / quiz / booking / content / internal tool / none of these)?

Step 2 — Pick the starting point (fast path is the default)

Read references/boilerplates.md. Default path (most ideas land here): the idea is SaaS/accounts-shaped and doesn't hit any trigger below → nextjs/saas-starter + the matching business-case pattern from that file's "Extending it for common business cases" section. Confirm the pattern fits in one sentence, don't run a comparison against alternatives that don't apply.

Branch only on a specific trigger, per that file's "When to reach for something else" section:

• Idea explicitly needs enterprise SSO/SAML/compliance audit logs → boxyhq/saas-starter-kit.
• User explicitly asks for the most batteries-included option / names Wasp specifically → wasp-lang/open-saas.
• Idea is genuinely zero-backend (vitrine/portfolio/landing, no accounts, no data) → no boilerplate, clone a vetted template.
• Idea is a bare client-side quiz with no accounts/persistence → no boilerplate, scaffold from scratch.

Every boilerplate here (including the default) has a paid-default audit already done in references/boilerplates.md — mention it plainly if relevant, Phase 2 fixes it either way.

Step 3 — Record the decision

PIPELINE_STATUS.md section 2, complete. Two cases:

• Real boilerplate: chosen_boilerplate = name + URL, business_case_pattern = which pattern from boilerplates.md applies (e.g. "marketplace") if using the default, or n/a for the alternative boilerplates.
• No rich boilerplate needed: chosen_boilerplate = the exact literal token none (minimal scaffold) (not a paraphrase — Phase 2 pattern-matches this string). minimal_scaffold_source = a specific vetted template URL (vitrine case) or the literal token from-scratch (bare-quiz case).

Either way: why, freshness date (re-check via scripts/check_github_freshness.py if references/boilerplates.md's last_checked is >30 days old), stack summary, known_stack_gaps_for_this_user (paid defaults + that Phase 2 fixes them automatically — empty for the no-boilerplate case). current_phase: decided.

Step 4 — Hand off

One or two sentences on what happens next. Get a green light before Phase 2 on a decision this consequential — but continue in the same turn if the user confirms immediately.

Reference files

• references/boilerplates.md — default boilerplate + business-case patterns + paid-default audits + alternative-boilerplate triggers
• scripts/check_github_freshness.py — freshness check, see header for usage/fallback