flow

Decision 0022 · Accepted

Start runs explore alongside
the bootstrap

start produces a verified repository but forbids product discovery and must be invoked by name.

Status
Accepted
Built from:
da88c48

Status: Accepted (2026-10-28). Amended by 0066 (the first spec need not test the riskiest assumption or ship instrumentation). Amended by 0067 (explore runs beside start only when the request describes a product). Amends 0010 (no discovery during initialization) and 0019 (start explicit-only). Related: 0020, 0023. Spec: 011. Amended by 0024 (start explores at Lite depth). Amended by 0039. Amended by 0044 (start confirms only what the request leaves unclear).

Context

start produces a verified repository but forbids product discovery and must be invoked by name. Founders describe their idea in the same breath as "start a Next.js project", and that context is lost while the bootstrap runs. Dogfooding explore showed that the first slice changes later plans, so specifying every slice up front is waste.

Decision

  • start is speakable. Plain requests such as "let's start a Next.js project" load it. Before writing anything it states the template, name, and destination and waits for an explicit yes.
  • After the yes, a worker runs the bootstrap while the main session runs explore at Full depth on the user's description. Hosts without workers run them in sequence.
  • Explore writes only after the bootstrap's initial commit. Its brief replaces the product sections of the baseline PRODUCT.md.
  • Explore writes spec 001 (the first vertical slice) in full, and later slices as candidate stubs. Slice 1 must test the riskiest assumption and ship the main metric's instrumentation.

Rationale

The bootstrap is mechanical and slow; the conversation is the valuable part and can run beside it. The pre-write confirmation preserves the safety reason 0019 kept start explicit. One full slice plus stubs follows the lean practice of keeping one slice ready and the rest as bets.

Alternatives

  • Keep start silent on discovery (0010 as written). Rejected: loses the founder's context at the moment it is richest.
  • Explore first, then bootstrap. Rejected as the default: it delays a working repository until the conversation ends. The fallback runs the bootstrap first instead, so the repository exists when explore writes.
  • Full specs for every slice. Rejected: specs after slice 1 go stale.

Consequences

  • start, explore, and to-spec change; start's safety rules and bootstrap library are unchanged.
  • The validator's explicit-only set no longer includes start.
  • docs/agent-compatibility.md and the catalog describe the new behavior.

Jump to, or try a question