Recipe reference

Shipped recipes, stages, gates, constraints, and project-local recipes

A recipe is data: the ordered stages a bolt runs, what each stage must produce, which stages may wait for approval, and any recipe-level constraints. The execution machinery is recipe-agnostic. It reads the recipe recorded on the bolt and runs those stages.

Recipes live at docs/specsmd/recipes/{id}.yaml. The plugin also ships copies inside the flow. A project file with the same id shadows the shipped recipe at bolt creation. The bolt stores recipe (the id) and an immutable recipe_snapshot. Later edits to the YAML do not change an in-flight bolt.

How a recipe is chosen

You pass a recipe id to bolt-start or bolt-plan.
If you pass nothing, the flow recommends from complexity: low → simple, medium → default, high → ddd.
Empty input applies that recommendation. Your explicit choice always wins.

A recipe never changes after the bolt is created. Complete or abandon, then start another, if the choice was wrong.

Shipped recipes

`default`

Plan, execute, test, review. The recommendation for medium complexity.

Stage	Produces	Gateable
`plan`	`plan.md`	yes
`execute`	—	no
`test`	`test-report.md`	yes
`review`	`review-report.md`, `walkthrough.md`	yes

Completion requires: test-report.md, walkthrough.md

No constraints.

`ddd`

Domain modeling before design and implementation. The recommendation for high complexity.

Stage	Produces	Gateable
`domain-model`	`domain-model.md`	yes
`design`	`design.md`	yes
`decisions`	`decisions.md`	yes
`implement`	—	no
`test`	`test-report.md`	yes

Completion requires: test-report.md

Constraints: no_source_code on domain-model, design, and decisions. Those stages write models and decisions only.

The decisions stage also writes one file per decision under docs/specsmd/decisions/ and a line on the in-force index. Each decision names consult_when — the situation a later bolt should retrieve it for.

Every completed bolt still gets a walkthrough even though this recipe has no walkthrough stage.

`spike`

Time-boxed exploration. Not recommended from complexity — choose it explicitly when the goal is knowledge, not a shipped behavior.

Stage	Produces	Gateable
`explore`	—	no
`findings`	`findings.md`	yes

Completion requires: findings.md

Constraints: time_box of PT8H (eight hours). The clock starts when the bolt becomes active. The next tooling write after expiry writes findings.md if it is missing and completes through the normal complete path. Partial findings are a valid outcome, not a failure.

`simple`

The shortest shipped path. The recommendation for low complexity.

Stage	Produces	Gateable
`plan`	`plan.md`	yes
`implement`	—	no
`walkthrough`	`walkthrough.md`	yes

Completion requires: walkthrough.md

No constraints.

Gates and ceremony

gateable: true means the stage may wait. Whether it actually waits depends on the bolt’s ceremony:

Ceremony	Which gateable stages wait
`autopilot`	none
`confirm`	the first gateable stage in the recipe
`validate`	every gateable stage

A stage with gateable: false never waits.

Autopilot still writes plan.md when the recipe lists it. Implementation happens only on implementation stages (empty produces, or ids execute / implement / explore) after the gate is granted or not-required.

Completion evidence

completion_requires is the list of files that must exist before the bolt can complete. If a recipe omits the field, the contract default is test-report.md and walkthrough.md.

Completion also requires:

every tracked work item has no unchecked - [ ] (gating) line
the walkthrough has a ## Deviations from plan heading (none if nothing diverged)
the walkthrough contains no fenced source listings

A refused completion names what is missing. --force records an override; use it only when you ask for it.

Constraints

Known constraint kinds:

Kind	Effect
`time_box`	Duration (ISO-8601, default `PT8H`) and `on_expiry` (default `complete_with_findings`). Clock starts when the bolt becomes active.
`no_source_code`	Named stages must not write product source.

Unknown constraint kinds are refused when the recipe is loaded.

Add a project-local recipe

Create docs/specsmd/recipes/{id}.yaml. Required fields: id, stages[] with id, produces, gateable. Optional: completion_requires, constraints.

id: two-step
title: Two step
stages:
  - id: plan
    produces:
      - plan.md
    gateable: true
  - id: implement
    produces: []
    gateable: false
completion_requires:
  - plan.md
  - walkthrough.md
constraints: []

The new id is selectable on the next bolt-start or bolt-plan. No skill or script change is required.