spec-superflow

# spec-superflow

spec-superflow is a self-contained, zero-runtime-dependency workflow plugin for AI coding tools.

Current version: v2.0.1.

## Default v2 flow

- New work has two paths: direct or planned.
- Direct records the requested scope and requires final verification.
- Planned requires proposal.md and tasks.md, one approval, an authoritative schema-2 execution plan, one final review, and final verification.
- specs/ and design.md are created only when the change needs them.
- Current-session inline execution is the default. SDD/subagents and wave reviews are opt-in.
- A feature branch in the current checkout is the default isolation. Worktrees are opt-in.
- Ordinary diagnosis stays in executing. Failed evidence is never rewritten as success.
- Existing v1 changes retain their legacy workflow, approvals, contracts, and recovery rules.

## Primary commands

- `ssf workflow start <dir> --path direct --scope <request>`
- `ssf workflow start <dir> --path planned --confirm --reason <approval> [--mode sdd]`
- `ssf workflow complete <dir> --verification-command <command>`
- `ssf workflow complete <dir> --accept-risk --confirm --reason <decision>`
- `ssf isolate <dir> [--worktree]`
- `ssf resume [dir]`
- `ssf validate <dir>`
- `ssf sync <dir>`
- `ssf finish <dir>`

## Key documents

- README.md: Chinese v2 overview and usage
- docs/README_en.md: English v2 overview and usage
- INSTALL.md: installation for 19 supported platforms
- docs/state-machine.md: full legacy and recovery state reference
- docs/artifact-contract.md: artifact roles and compatibility contracts
- CHANGELOG.md: version history
- CONTRIBUTING.md: contribution guide

## Activation

Use the workflow only when the user explicitly requests spec-superflow or when the active change contains `.spec-superflow.yaml`. Codex manifests suppress SessionStart hooks, so ordinary Codex sessions receive no automatic workflow injection.