---

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 "<plugin-root>/scripts/spec-superflow.mjs"; <plugin-root> 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 <change-dir> --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 <dir> --path direct --scope "<requested outcome and bounds>". 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 <dir> --path planned --confirm --reason "<existing approval>". 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 <dir> --verification-command "<required check 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 "<decision and remaining issues>"; 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 <change-dir> 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.