spec-superflow retires five execution modes for two, and keeps the old state machine alive for anyone mid-change

Five execution paths became two, and existing changes keep their old state

Version 2 removed the mode questionnaire and the hand-written execution contract document for new tasks. Two paths remain.

| Old default | v2 default | | --- | --- | | Five path choices | `direct` or `planned` | | Four planning documents plus a handwritten contract | `proposal.md` plus `tasks.md`; spec and design only as needed | | Confirmation at each stage | planned confirms once, on a concrete plan | | Spec-driven development, subagents and per-task review | Current-session execution plus a final review | | Automatic worktree | Feature branch in the current directory; worktree opt-in | | Debugging switches to a separate state | Ordinary diagnosis stays inside `executing` | | Several caches that could block a plan | An approved schema v2 execution plan is the only basis for judgement |

The migration story is the part worth reading twice. Changes that already exist keep recovering on their original state, approval records and review results, and are explicitly not migrated or reset. So the eight-state routing and the legacy contract rules are not dead code, they are the recovery path for anything started under v1.

Direct fits a change whose intent is clear, whose blast radius you can judge and whose verification is reproducible. It generates no planning package, no recommendation receipt and no contract, only the requested scope and the final verification result. If scope grows mid-execution you add the two documents and upgrade to planned with one approval, without reopening the state machine.

Completion is a stored exit code, and failure is never written as a pass

The definition of done is deliberately narrow. Completing means recording which verification command ran, what exit code it returned, which stretch of Git changes the review covered, and whether the checks passed. It is not the model writing a sentence claiming the bug is fixed.

Two states are reachable at the end. A passing verification records `verified`. Delivering with a known problem records `accepted-risk`, and only when the user explicitly agrees:

ssf workflow complete changes/example \
  --accept-risk \
  --confirm \
  --reason "接受已记录的兼容性限制，后续单独处理"

The outcome keeps the original failing result on record and does not merge the branch automatically. So accepted-risk is a decision with a reason attached, not an overwrite.

Three things cannot count as completion at all: a failed verification, an empty Git review range, and corrupt records. Recovery is explicit too, through `ssf resume <dir>` and `ssf checkpoint list <dir>`, and missing or damaged authorisation records, review results or range information produce errors rather than defaults. The stated principle is that the tool will not fabricate a pass.

On the planned path, completion additionally checks the task list, the final review and the sync state of any delta specs.

The platform count is 17 in one place, 19 in another, and 5 are documented

Three numbers, and they do not reconcile.

The repository description says 17 platforms supported. The front page says the project supports 19 AI coding platforms. The install section then gives five concrete commands:

/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow

for Claude Code; `codex plugin marketplace add MageByte-Zero/spec-superflow --ref v2.0.1` followed by `codex plugin add spec-superflow@spec-superflow` for Codex; `npx spec-superflow@latest install-cursor` for Cursor; `copilot plugin marketplace add` and `copilot plugin install` for the GitHub Copilot CLI; and `gemini extensions install https://github.com/MageByte-Zero/spec-superflow` for the Gemini CLI. The rest are deferred to an install document with a separate platform matrix for capability differences.

Three of those five do not share a mechanism. Claude Code, Codex and Copilot use a marketplace and plugin pair, Cursor uses an npx subcommand, and Gemini installs straight from the repository URL. Codex is also the only one with a version ref on the marketplace add, which means it is the only documented install that pins.

One behavioural difference is called out on the page: Codex does not enable session-start auto-injection, so you invoke `workflow-start` yourself or resume an existing change. The repository also physically carries six platform-specific directories, which is a different count again from either claim.

The executable is a checked-in script, and the compiled output is committed as well

The package exposes two binary names, `ssf` and `spec-superflow`, and both point at the same file, `./scripts/spec-superflow.mjs`.

That path is the interesting one. The library entry point in the manifest is `dist/index.js` with types at `dist/index.d.ts`, and the build script is a plain `tsc` invocation, so there is a compiled TypeScript artifact. The command you actually run is a raw ES module script sitting in the repository, not the compiled output.

Two consequences follow. Installing the CLI does not require a build step, which is what makes a zero-dependency, zero-runtime-install experience possible. And a stale copy of that script elsewhere on your PATH is a real hazard, which the front page addresses directly by having marketplaces and per-platform installers upgrade the skill and the same-version runtime together, so the skill only calls the runtime inside its own installed package rather than another older `ssf` it happens to find.

The repository also commits its build output, since a `dist/` directory sits at the root alongside `src/`. And the published package contents are decided by a `.npmignore` file rather than by an explicit allowlist, so there is no list on the page telling you what ships.

The release script stages your whole working tree as a side effect

The version script is one line and it is worth reading before your next release.

npm run check-versions

runs a version consistency check, and the npm lifecycle hook that runs on a version bump is `node scripts/spec-superflow.mjs version $npm_new_version && node scripts/check-version-consistency.mjs && git add -A`. The staging step is the third clause.

So publishing a version stages whatever is in the working tree at that moment, not just the files the release touched. That is convenient and it is also the kind of automation that surprises people who keep notes in a scratch file, and it means the commit that a release produces is shaped by whatever happened to be uncommitted.

The rest of the developer surface is small. Build is `tsc`, tests run through a script, artifact validation is a separate script, and there is a dedicated raw-mode smoke test that runs the Node test runner directly against one file. Git hooks are installed by their own command rather than assumed.

On dependencies, the claim of zero runtime dependencies holds and is easy to verify: the manifest carries no runtime dependency list at all and a single development dependency, TypeScript, on a caret range. The CLI uses the Node standard library, which is also why the stated floor is Node.js 20 or newer.

Nine skills exist and the shortest default chain touches three

The nine skills are described as on-demand responsibility modules, not nine stages to walk through every time. The call chains are given explicitly:

Direct:  workflow-start → build-executor → release-archivist
Planned: need-explorer? → spec-writer → workflow-start → build-executor
         → code-reviewer → spec-merger? → release-archivist
Bug:     build-executor → bug-investigator → build-executor

A question mark means the skill runs only when its conditions are met. So a direct change involves three skills, and a planned one between six and seven, with the explorer skipped when the requirements are already clear and the merger skipped when there are no delta specs to sync.

Two entries exist purely for the previous version. `contract-builder` maintains the old execution contract document and its approval obligations, and is described as legacy-change-only and not called by the new direct or planned paths. The front page also notes that the workflow recommend, select and accept commands, the old execution plan format and the eight-state routing are all reserved for recovering v1 changes.

The other deliberate omission is worth stating: the default chain creates no subagents, performs no per-task review and does not create a worktree automatically. Each is opt-in, and the reason given is that ordinary coding sessions should not have a full workflow force-injected into them by a session-start hook or a global rule.

Debugging stopped being its own state, which is the quietest change in v2

One row of the old-to-new table says that debugging used to switch into a separate state and now ordinary diagnosis stays inside `executing`. Everything else in the table is about removing ceremony, and this one is about removing a mode transition.

The bug skill shows the consequence. It is invoked when execution hits a defect or a failing test, its job is to reproduce, trace the root cause and verify a minimal fix, and the chain then returns to the executor. No new workflow is started, no approval is requested and no separate artifact is produced.

The same restraint shows up in review. On the native path there is exactly one final review covering the full Git range, and wave-by-wave review is only available when explicitly selected. Failed reviews must carry a stable issue identifier, and escalation to human arbitration happens only after the same issue survives three consecutive attempts, with unrelated issues deliberately not accumulated into a loop.

That last rule is a design opinion rather than a feature list item. Most review loops fail by conflating every new finding with the previous one, so requiring a stable identifier and a fixed attempt count is a way of keeping an automated reviewer from stalling a change forever.

Two files in the repository have no explanation on the front page

The root holds the usual set of agent-facing files, including an agents file, a Claude plugin directory, a Codex plugin directory, a Cursor plugin directory, an OpenCode directory, a security policy and a contributing guide, alongside the source, the skills directory, the commands directory, templates and tests. Two entries are not explained anywhere on the front page.

The first is `token-baseline.json` at the root. Its name implies a recorded budget for context consumption, and the repository is otherwise unusually explicit about keeping ordinary sessions light, so whatever it tracks is probably part of that effort. Nothing on the page says what consumes it, how it is checked, or whether the build fails when it regresses.

The second is `llms.txt`, the plain-text convention for giving a language model a map of a repository. Its presence in a plugin that already ships nine skills and a command surface is a small signal about who the documentation is written for.

Two other details belong in the same list of things the page does not resolve. The Gemini extension declares its manifest as a single file at the root rather than in a directory like the other platforms, and the version floor, Node.js 20, is stated in the requirements section rather than enforced visibly at install time.

Editorial conclusion

spec-superflow is a good fit for teams whose failure mode is an agent declaring a fix and nobody checking, because its completion contract is the interesting part. It refuses to record a pass without a verification command and an exit code, refuses an empty or truncated Git range, and forces a stable issue identifier plus three consecutive failures before anything is escalated to a human. Accepting a known problem is allowed but leaves a reason and keeps the original failure on record. That is a better shape than most workflow plugins have. Who should use it: developers on one of the platforms with a documented installer, working on changes small enough that a two-document plan is proportionate. Who should not: anyone expecting the v1 command surface, since the recommend, select and accept workflow commands and the eight-state routing exist only to recover v1 changes, and anyone who wants the full nine-skill chain on a small edit. Three things to check before you install. Settle the platform count, because the repository description says 17, the front page says 19, and only five have install commands written out with the rest deferred to a separate file. Note that the executable you run is a checked-in script rather than built output, which is why the install is small and why a stale copy on your PATH is the failure mode the page warns about. And decide how you feel about the release script staging your entire working tree, since the version hook ends with an add-all command rather than leaving that to you. What it is not is a spec-driven development framework in the OpenSpec sense. It borrows OpenSpec's organisation and Superpowers' discipline and depends on neither at runtime.

Frequently asked questions

Official sources

1. License: MIT
2. MageByte-Zero/spec-superflow on GitHub
3. Project website
4. README
5. Releases