--- name: magebyte-zero/workflow-start source: https://app.decimal.ai/s/magebyte-zero-workflow-start@1/SKILL.md source_sha256: b3fe9890b28d --- # 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 --json` and `ssf checkpoint list --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 --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: ```bash ssf state init ssf workflow recommend --task-count --file-count --config-doc-only no --schema-api-change no --new-module no --behavioral-constraint-change --cross-module-change --uncertainty low --request-kind ssf workflow accept --source direct-request --verification ``` 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=` to `dp_0_decisions`, preserving its existing scope and constraint summary. Never persist `auto` as the resolved artifact language. If DP-0 was already confirmed but this field is absent, resolve and append it before routing to `spec-writer`. All later planning skills reuse this field so one change does not switch languages without an explicit user request. ### Workflow Path Intake (Mode Detection, Full/Legacy) Workflow path selection is a DP-0 intake decision. It selects the planning path (`full`, `hotfix`, `tweak`, or `quick`); it is separate from DP-4, which later selects the execution mode (`Inline`, `Batch Inline`, or `SDD`). It does not add a state or cause a phase transition. 1. Obtain the change name and one-sentence intent before any state-dependent command. Validate the change name as one non-empty relative path segment (not `.` or `..`, with no `/` or `\\`), resolve the change dir as `/changes/`, and reject any normalized path that escapes the project's `changes/` directory. 2. If the state file is absent or `dp_0_confirmed` is `false`/null, run `ssf state init ` before `show`; initialization must leave DP-0 unconfirmed. 3. Read `state.workflow`. An explicit `full` workflow wins and skips automatic recommendation. For an explicit `hotfix`/`tweak`/`quick`, report the active path; if scope, risk, or verification now exceeds its boundary, refresh the recommendation with observed facts and route it to Full instead of continuing. 4. For `auto`/`null`/unset, run `ssf workflow show --json` before collecting or changing any facts. A missing receipt is represented as `needs-input` with all eight fixed facts in `missing_facts`. 5. If the response is `needs-input`, ask only for `missing_facts`; do not ask for any fact not listed by the receipt. Do not invent facts from missing artifacts and do not default the path to `full`. 6. Run `ssf workflow recommend ...` once with one complete fact snapshot. 7. Show the user `Observed`, `Available`, `Recommended`, and `Why`. A recommendation is advice only: never persist it as the workflow selection. 8. A recommended low-risk Quick or incident Hotfix is accepted only with `ssf workflow accept --source direct-request --verification `. For Full, legacy Hotfix, or Tweak, obtain the user's explicit choice and run `ssf workflow select --mode --confirm --reason ""`. For a risk-signalled Quick choice, run `workflow select --mode quick --confirm --acknowledge-recommendation --verification `. 9. Add `--acknowledge-recommendation` only after the user chooses a non-recommended selectable path. Report the persisted receipt and DP-0 audit summary. 10. To escalate a selected Quick, direct Hotfix, or Tweak, refresh `workflow recommend` with observed risk facts, then select `full` with `--confirm` (and `--acknowledge-recommendation` only if required). Do not overwrite an explicit mode without this persisted recommendation. 11. Keep `ssf runtime infer ` only for legacy artifact inference and validation compatibility; it cannot replace user selection at intake. ### Confirm DP-0 Only after an explicit workflow path is available, ask for the remaining DP-0 decisions: change name and one-sentence intent, known constraints, related optimizations (include or stay focused?), and communication preference (ask per decision or draft for review). Confirm one combined summary containing those decisions, the resolved `artifact_language`, and the persisted workflow path plus recommendation-alignment summary. Preserve existing scope, constraints, and language entries; never replace them with the path summary alone. After that combined confirmation: ```bash ssf state set dp_0_decisions "" ssf state set dp_0_result confirmed ssf state set dp_0_confirmed true ssf state set dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ) ``` Config-aware routing: check `artifacts.order`, `artifacts.skip`, and `execution.defaultLanguage` from project config. ## Routing Rules ### Route to need-explorer Change is fuzzy, scope unclear, comparing options, no stable change name. ### Route to spec-writer (Full only) Guard: `ssf runtime guard check exploring specifying --json` → fail = BLOCK. User knows what they want, artifacts missing/incomplete. ### Route to contract-builder Only for Full or legacy Hotfix. Guard: `... check specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`. ### Route to build-executor For Full or legacy Hotfix: contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `ssf execution recommend [--wave ...]`, then run `ssf execution plan --mode --confirm ...` and `execution show`. For Quick, Tweak, or direct Hotfix: use the receipt-aware guard and bounded verification; do not require DP-4, a contract, plan, or review receipt. ### Route to bug-investigator Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor. ### Route to code-reviewer (Full/legacy Hotfix only) The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `ssf execution review --wave --base --head --report --verdict ` receipt before any dependent wave or closing transition. Quick, Tweak, and direct Hotfix use their verification summary instead. ### Route to release-archivist Only while the current state is `executing`: implementation is complete and verification is ready. For Full/legacy Hotfix, run the guard and complete verification, audit, delta merge, and DP-7. For Quick, Tweak, and direct Hotfix, run the receipt-aware guard, persist `test_result: pass`, and produce the verification summary without audit or DP-7. ### Route to spec-merger Only while the current state is `executing`, before the final `executing → closing` transition: delta specs need merging with ADDED/MODIFIED/REMOVED/RENAMED specs. Never route a change already in `closing` to `spec-merger`. ### Route to abandoned User explicitly requests, bug-investigator escalates after 3+ failures AND user chooses, scope change makes change no longer worthwhile AND user confirms. Block from `closing` or `abandoned`. ### Optional Prototype Handoff When the user's brief explicitly contains UI, screen, interaction, layout, UX, or product-experience uncertainty, ask once whether a prototype would reduce uncertainty. Do not create a prototype handoff or enter a prototype worktree until the user confirms. After confirmation: ```bash ssf handoff create \ --type prototype --objective "" \ --expected-output "" --acceptance "" ssf isolate prototype- ``` Never suggest or enter this route automatically for backend, CLI, configuration, or internal-refactor work. Never pass `--force` to `ssf isolate` for prototype work. ### Fast-Path Routing - **Legacy Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). It may skip planning artifacts but still requires a minimal contract, DP-3, and a current execution plan. A direct Hotfix instead follows Direct Short-Path Intake. - **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight) Post-transition: 💡 `ssf inject ` to update phase-guard artifacts. ## Staleness Detection Use content inspection, not timestamps. **Stale contract**: proposal scope expanded beyond contract scope fence, or contract references capabilities no longer in proposal → route back to `contract-builder`. **Stale planning artifacts**: capability in proposal has no spec file, or spec exists for capability not in proposal → drift detected. **Stale tasks**: requirement in specs has no corresponding task → stale tasks. ## Guardrails - Full/legacy Hotfix: no implementation before planning artifacts or contract exist - No implementation for Full or legacy Hotfix without a current `ssf execution plan`; no state transition based on an unverified DP-4 string - No "continue" without state inspection - Full/legacy Hotfix: no implementation past stale contract - No implementation past bug without investigation - Full/legacy Hotfix: no closure without all planned wave review receipts recorded as `pass` or with unsynced delta specs - `closing` is a successful terminal state: next skill is none and recovery overlays do not run - No transitions from `abandoned` (terminal) - No transition to `abandoned` from `closing` or `abandoned` - No auto-abandon without user confirmation - No merging delta specs from abandoned change ## Output Standard Always state: (1) current detected state, (2) why (cite file/content/condition), (3) which skill should run next. If blocking, explain missing artifact/approval. Decision point references when routing: - contract-builder → DP-3, build-executor → DP-4, bug-investigator (escalation) → DP-5, release-archivist (verification failure) → DP-6, release-archivist → DP-7 ## Exception Handling - **Parse failures**: Fall back to content-level detection if `.spec-superflow.yaml` is malformed - **Missing files**: Route to the skill that generates the missing files - **User interruption**: Re-inspect change directory content (not cached state) on resume ## Standard User-Facing Handoff End every user-facing phase report with this concise handoff. Only a successfully persisted `closing` state and `abandoned` are terminal. ### Normal report - Current stage: ``. - Completed / blocker: ``. - Next stage: ``. - Entry condition: ``. ### Blocked report - Current stage: ``. - Completed / blocker: ``. - Next stage: ``. - Entry condition: ``. ### Approval-wait report - Current stage: ``. - Completed / blocker: ``. - Next stage: ``. - Entry condition: ``. ### Successful terminal report - Current stage: successfully persisted `closing` or `abandoned`. - Completed / blocker: ``. - Next stage: `none`. - Entry condition: no further transition exists.