--- name: workflow-start description: Primary entry point for the spec-superflow state-machine workflow. Invoke only when the user explicitly requests spec-superflow or an active change contains .spec-superflow.yaml and the user asks to continue that change. Generic proposal, specs, design, task, or contract files are not activation signals. --- # Workflow Start ## Bundled runtime Before executing a CLI line below, replace its leading `SSF` with `node "/scripts/spec-superflow.mjs"`; `` is the absolute directory two levels above this file. Never run `SSF` literally or call an `ssf` from `PATH`. Use only for an explicit spec-superflow request or an existing change. Ordinary coding does not require a spec workflow. ## Resume Run `SSF resume --json` once. It combines state, handoffs, checkpoints and current-plan inspection. Use the returned absolute `change.path` for all subsequent operations: recovery may redirect a stale source copy into its recorded worktree. Follow `next_action`; do not repeat all component commands unless diagnosing that result. A blocked continuation is not a retry instruction; resolve its named cause before running it again. Read only the artifacts relevant to the next action. - `debugging`: diagnose first, even if a plan is stale. Never dispatch an eligible wave during diagnosis. - `closing`: logical completion. If a recorded isolation still has physical finish pending, route to release-archivist for that remaining action, subject to existing merge authorization. Otherwise stop. - `abandoned`: stop. - A ready handoff needs review through `SSF handoff resolve`; an active handoff is non-blocking. Stale checkpoints are history, not current evidence. - Missing/stale Full plans block implementation, not investigation. Valid short paths and Tweak do not require plans. Update checks are optional (`SSF runtime check-update`), cached and non-blocking. Never make network access a recovery prerequisite. ## New request Infer scope and risks from the request and repository; do not turn CLI fields into a questionnaire. Validate the change name as a single safe relative path segment under `changes/` and create only that directory. Reuse authorization already given. Never infer approval from artifact existence. Offer only two paths, without a mode-selection interview: - **Direct**: clear requested change with a bounded proof. In the same turn run `SSF workflow start --path direct --scope ""`. No planning pack, recommendation receipt or execution plan is needed. Use affected tests or checks; `--verification` can record tdd/new-test/bounded when relevant. Task/file counts are advisory, not hard limits. - **Planned**: uncertain behavior, architecture or a user-requested plan. Draft proposal.md (scope, acceptance, risks) and tasks.md (ordered tasks and proof) together. Add specs/design only when their information is needed. Check shared interfaces against actual code once. Present one concrete plan for approval, reusing approval already covering it. Then run `SSF workflow start --path planned --confirm --reason ""`. The CLI derives the execution plan and enters executing; no contract-builder, handwritten contract, DP-0..DP-4 sequence or execution recommend is required. Native + final is the default; add `--mode sdd` only for explicit delegation. Continue to build-executor without another question. Ordinary debugging stays in executing. Scope changes update the affected planning sections and repeat planned start once with actual reapproval; do not traverse intermediate states. Nonsemantic corrections can use execution resync with a recorded reason, retaining review history. Completion uses `SSF workflow complete --verification-command ""`. It runs the check once and preserves failures. Planned work also requires its current review and completed tasks; existing delta specs require synchronization. A user can explicitly accept known risks with `workflow complete --accept-risk --confirm --reason ""`; this records accepted-risk, never pass, and does not authorize integration. ## Legacy changes Do not convert an active legacy change or discard its receipts automatically. Resume its recorded obligations: Full/legacy Hotfix may still need contract-builder and old approval/review gates; old Quick/Tweak/Lightweight/direct Hotfix use their existing receipts. Read docs/decision-points.md only for the applicable old decision, not for every task. Use `SSF runtime asset read docs/state-machine.md` only when a legacy transition is unclear. Legacy `SSF state init` precedes `SSF workflow recommend`; a nonrecommended choice requires acknowledgment. Legacy Quick/direct Hotfix use `workflow accept --verification` and persist `test_result: pass` before closing; use `SSF state set dp_0_timestamp now` for portable timestamps. Continue authorized internal work without phase-by-phase handoff questions. For all paths, read only the current task's source and evidence. Progress updates use one short paragraph; ask only for a new material decision, never “continue?” for authorized work.