Stage: init-check

Runtime config (canonical): workflow.json → stages.init-check

Purpose: read the worktree's project brain (docs/STATE.md + docs/), present the current snapshot to the user, and let them choose what this run should do — start fresh, work on the next task, or revise any of the upstream design docs. Output artifact: write to the absolute path provided in your I/O context Valid results this stage writes: pending (snapshot drafted, awaiting user choice), fresh, next-task, revise-product, revise-ui, revise-tech, revise-test, revise-roadmap

This is an interruptible inline stage — the main agent executes it directly and pauses naturally for the user's choice.

Protocol — main agent

Step 1 — Read the epoch and write a pending artifact immediately

Open state.md in the run directory to read epoch:. Then immediately write the output artifact at the path shown in your I/O context with:

This guarantees the stop hook sees a pending artifact even if the user pauses mid-conversation.

Step 2 — Read the worktree state

Look at <project-root>/docs/STATE.md and <project-root>/docs/ (and <project-root>/CLAUDE.md if present).

• No docs/STATE.md → this is a fresh project. Skip Step 3, present the user with the offer to start research, but still let them ask questions.
• STATE.md exists → parse it. Read the At a Glance, Design Docs, Tasks, and Open Iteration Items sections so you can summarise.

Step 3 — Present the snapshot

Surface to the user, in plain prose:

• Current stage / next-step pointer (from At a Glance)
• MVP status (which P0 tasks remain, % complete)
• Latest design-doc revisions (date + which docs)
• Open iteration items (failing tests, unresolved verify rounds, side-effect warnings)

Step 4 — Ask one clear multi-choice question

Offer these options (skip those that don't apply — e.g. no next-task if no roadmap, no revise-* if that doc doesn't exist yet):

• A — Start fresh (kick off research). Only sensible if there is no docs/STATE.md, or the user explicitly wants to restart.
• B — Work on the next task (jump to pick-task).
• C — Revise the product design.
• D — Revise the UI design.
• E — Revise the tech design.
• F — Revise the test plan.
• G — Revise the roadmap.

Wait for the user's choice. Allow follow-up questions — keep result: pending while iterating.

Step 5 — Finalise

Once the user has chosen, overwrite the output artifact:

That is the only action needed here. The main loop reads the artifact's result: and calls update-status.sh to advance — do NOT call it yourself.

Side-effect rules (apply to all stages in this workflow)

1. Artifact first, worktree second — write the stage artifact (with the final result:) before touching docs/. The state machine only reads the artifact.
2. Side-effect failure is fail-soft — if you can't write docs/ or STATE.md, leave the artifact result: correct and record the warning under STATE.md → Open Iteration Items next time. Never abort or git commit.
3. STATE.md / CLAUDE.md use sentinel blocks — wrap each section with <!-- section:<name> -->...<!-- /section --> and read-modify-write the whole file. Never >> append. CLAUDE.md edits stay inside <!-- product-cycle:BEGIN -->...<!-- /product-cycle -->.

Rules

• Do NOT run update-status.sh yourself.
• Do NOT modify any file outside the run directory's artifact during this stage. (No worktree writes here — init-check is read-only on docs/.)
• If the worktree has no docs/STATE.md AND the user picks anything other than fresh, push back: nothing exists to revise yet.