/workflow-start

name: workflow-start
description: Primary entry point for the spec-superflow state-machine workflow. Invoke when the user is inside an active spec-superflow change directory (look for .spec-superflow.yaml, changes/<name>/, proposal.md, specs/, design.md, tasks.md, or execution-contract.md) and asks to start, continue, resume, implement, plan, or figure out the next workflow step. Also invoke when the user explicitly asks to start a new spec-superflow change or route through the spec-superflow workflow. Do not invoke for unrelated coding tasks that happen to use words like start, continue, implement, or plan.

Workflow Start

Primary entry point for `spec-superflow`. Jobs: inspect change context, check for updates, confirm DP-0, determine state, route to correct skill, block invalid transitions.

Use This Skill When

Only invoke when spec-superflow context is present: `.spec-superflow.yaml` exists, artifacts like `proposal.md`/`specs/`/`design.md`/`tasks.md`/`execution-contract.md` are present, or user explicitly invokes spec-superflow by name. When in doubt, check for `.spec-superflow.yaml` first.

Do NOT invoke for: general coding tasks outside spec-superflow changes, casual questions, unrelated work.

States

`exploring` → `specifying` → `bridging` → `approved-for-build` → `executing` → `closing`, with `debugging` side-path from `executing`, and `abandoned` as terminal. If a transition is ambiguous, run `ssf runtime asset read docs/state-machine.md`.

Terminal-State Short Circuit

Before update checks or recovery overlays, inspect the persisted state. If it is `closing`, stop immediately: `closing` is a successful terminal state and the next skill is `none`. Report the terminal state and its persisted evidence. Do not run `handoff list`, `checkpoint list`, the execution-control recovery scan, or `release-archivist`; do not resume, hand off, or route any more work.

Initialization

1. **Update check**: Run `ssf runtime check-update`. Exit 0 → continue. Exit 1 → non-blocking upgrade reminder. Exit 2 → skip. 2. **Inspect change folder**: Check for `proposal.md`, `specs/`, `design.md`, `tasks.md`, `execution-contract.md`. Answer: Is the change fuzzy? Artifacts missing/unstable? Contract exist? User approved contract? Execution in progress or blocked? In verification/wrap-up?

Overlay Recovery Scan

3. **Overlay recovery scan**: Run `ssf handoff list <change-dir> --json` and `ssf checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `ssf handoff resolve` before resuming the affected work. An `active` handoff is non-blocking side work. Show a non-stale checkpoint as recovery context; show a stale checkpoint only as historical evidence.

Execution-Control Recovery Scan

4. **Execution-control recovery scan**: For Full or legacy Hotfix in `approved-for-build`, `executing`, or `debugging`, run `ssf execution show <change-dir> --json`. Treat only `current: true` plus `waves[].eligible: true` as permission to start a wave. Do not require this scan for Quick, Tweak, or a valid direct Hotfix receipt.

Direct Short-Path Intake

For a clearly bounded Quick or incident Hotfix request, recommend and accept in the same turn. Do not collect the eight intake facts as a questionnaire: infer them from the request and repository, show the observed facts, recommendation, and qualification reason, then ask the user to choose `tdd`, `new-test`, or `bounded` verification before running:

ssf state init <change-dir>
ssf workflow recommend <change-dir> --task-count <n> --file-count <n> --config-doc-only no --schema-api-change no --new-module no --behavioral-constraint-change <yes|no> --cross-module-change <yes|no> --uncertainty low --request-kind <standard|incident>
ssf workflow accept <change-dir> --source direct-request --verification <tdd|new-test|bounded>

Quick is ≤3 tasks/files of low-risk code. Hotfix is an incident with a reproducible symptom and ≤2 tasks/files. Display `Observed`, `Recommended`, `Why`, and any risk reasons; acceptance is the user's direct request to proceed and their explicit verification choice. Do not create planning artifacts, a contract, an execution plan, wave receipts, or DP approvals. Transition through the receipt-aware guard, execute bounded work, and require `test_result: pass` before closing. A fourth code file, behavioral-constraint change (PRD/spec/design/API/data/permission), cross-module work, a new module, high uncertainty, or failed verification does not auto-escalate: show Quick and Full, then wait for the user's choice. A user selecting Quick must acknowledge the recommendation and choose `tdd`, `new-test`, or `bounded` verification in the receipt. Tweak is only ≤4 config/doc-only tasks/files with no risk signals; it cannot be selected as an override. A legacy Hotfix without a valid direct receipt remains on the Full contract/DP-3/plan/review path.

DP-0: User Confirmation Gate

After Direct Short-Path Intake does not apply, run DP-0 when: change folder doesn't exist, planning artifacts are missing/empty, `dp_0_confirmed` is not `true`, or a legacy change still has an `auto`/empty workflow. Resolve the artifact language first, then complete the workflow path intake. Do not set `dp_0_confirmed=true` while path facts or the user's path choice are still missing.

Artifact Language Resolution

Before the first planning artifact is generated, resolve one concrete artifact language in this priority order:

1. explicit user language 2. the conversation's primary language 3. an explicit non-`auto` `execution.defaultLanguage` 4. the primary language of existing planning artifacts in the current change 5. the primary language of the project templates

Treat `execution.defaultLanguage: auto` as a request to continue resolving, not as a language. Append `artifact_language=<concrete-language>` to `dp_0_decisions`, preserving its existing scope and constraint summary. Never persist `auto` as the r