spec-superflow: a spec-first workflow plugin that picks a lightweight or full path by change risk

What spec-superflow adds on top of a plain AI coding agent

An agent given a prompt will usually start editing files. spec-superflow inserts a planning stage before that, and it does so by fusing two existing ideas: the OpenSpec planning engine for proposals and contracts, and Superpowers execution discipline for how the work is carried out. The package description states the integration happens "via bridge contract". The README's own framing is that the plugin selects a lightweight or full path according to change risk, so a one-line fix and a multi-file refactor do not go through the same ceremony. That routing decision is the product. Everything else, the nine skills and the 19 platform installers, exists to make the routing available inside whichever agent you already use.

How the routing works: content-level state detection, not timestamps

The mechanism the README describes is a content-level check. The agent inspects the current artifact directory and compares the scope of the proposal against the intent lock in the contract, rather than looking at file modification times. From that comparison it decides which phase you are in and routes to the correct next skill. This matters because timestamp-based detection breaks the moment you edit an old file or check out a branch. The README gives three entry phrases: starting a new change, resuming an old one, and asking what to do when you are unsure. State is persisted in a `.spec-superflow.yaml` file, which the `ssf state` subcommand manages. The CLI exposes the same information from the terminal through `ssf list`, which lists all changes and their status, and `ssf validate <dir>`, which checks artifact completeness. The design choice here is that the plugin owns a directory of artifacts rather than reading your git history. That keeps it tool-agnostic, and it also means an artifact directory that drifts from the repository is invisible to the router.

Installing spec-superflow and running a first change

Claude Code users install through the plugin marketplace. The README shows three commands: add the marketplace, install the plugin, and update it later. Marketplace installation loads hooks automatically and injects context at the start of each new session.

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

For Cursor, the README gives a CLI path and a script path. Both deploy the skills, scripts and docs that the runtime needs, because Cursor discovers skills from directories such as `.cursor/skills/` and `~/.cursor/skills/`.

npx spec-superflow@latest install-cursor

If you only want the command line tooling, install it globally with npm. Node 20 or newer is required, according to the `engines` field in package.json.

npm install -g spec-superflow
ssf doctor

The `ssf doctor` command runs a health check over the version, hooks, skills and documentation consistency. On a fresh install you should see it confirm those four areas rather than report mismatches. After that, `ssf list` shows the changes it can see, and the first real use is to tell your agent "用 workflow-start 开始" (start with workflow-start) so the router inspects the artifact directory and picks the next skill.

git isolation and the finish step are where spec-superflow gets opinionated

Two commands show the plugin's stance most clearly. `ssf isolate <dir>` enforces git isolation before implementation: if you are on main or master it creates a worktree, including recursive submodule initialization, or a branch, and writes a warning into the progress ledger that the working directory is not persistent. `ssf finish <dir>` then merges back with `--no-ff`, verifies synchronization, and runs a verification command on the trunk. The default command is `npm test` with a ten-minute timeout, and you can override it with `--test-cmd`. Only if verification passes does it delete the worktree and the isolation branch. On failure it keeps the worktree so you can go back and fix things. This is a real constraint on how you work, and it is the part most likely to conflict with an existing branch policy. The trade-off is deliberate: the plugin assumes an agent can leave the repository in a state you would not merge, and it makes that state recoverable rather than trusting the agent to clean up.

Where spec-superflow is the wrong tool

The plugin assumes there is a spec to route on. If your workflow is a single prompt that produces a patch, there is nothing for the content-level comparison to compare, and the planning stage becomes overhead you pay on every change. The README also documents a platform-specific gap: Codex loads the skills declared by the plugin, but the plugin does not enable SessionStart hooks there, so you must call `workflow-start` explicitly in a new session. The same README notes that after installing or upgrading through the Codex CLI you must restart the Codex App and open a new session, because old sessions do not hot-load skills. That is a sharp edge for anyone who expects the context injection they get in Claude Code to carry over. Finally, Trae is listed as manual or import only, through `.trae/skills/`, `~/.trae/skills/` or an uploaded zip, so it does not get the same installer treatment as the other platforms. The README does not document rollback for a finished change, and it does not describe what happens if `ssf finish` is interrupted mid-merge.

How it compares with using OpenSpec or Superpowers alone

The two upstream projects solve different halves. OpenSpec supplies the planning engine: proposals, contracts, and the artifact structure that a spec-first process needs. Superpowers supplies execution discipline: the rules an agent follows while implementing. Using OpenSpec alone leaves the execution side to whatever the agent decides, and using Superpowers alone leaves the planning side to the prompt. spec-superflow's contribution is the bridge contract between them plus the router that decides which path a change takes. If you already run OpenSpec and are happy wiring your own execution rules, the added value here is mostly the nine skills and the installer coverage across 19 platforms. If you run neither, spec-superflow is a larger commitment than either one, because you inherit both artifact conventions at once.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-15. Releases are frequent enough to suggest the project is moving: v0.12.1 on 2026-07-27, v1.0.0 on 2026-08-04, and v1.2.0 on 2026-09-02. The licence is MIT, which permits commercial use and modification; the repository ships a LICENSE file and a SECURITY.md. This article is not legal advice, so read the licence text yourself if you plan to redistribute. The upgrade cost is concentrated in version synchronization. The package.json `version` script runs `ssf version` to push a new semver into every manifest, then `check-version-consistency.mjs`, then stages the result. That implies several manifests can drift out of sync, and the `ssf doctor` health check includes a documentation consistency check for the same reason. Budget for re-running `ssf doctor` after every upgrade, and note that the README tells Codex users to restart the App and open a new session rather than expecting a live reload.

Editorial conclusion

Adopt spec-superflow if your team already writes proposals and contracts before implementation and you want a CLI that refuses to let an agent skip that order. Do not adopt it if you want an agent to start editing files from a one-line prompt, or if your tool is not on the platform matrix, because the plugin only routes work it can see in its own artifact directories. Before you commit, run ssf doctor in a scratch repository, then run ssf list to confirm it reads your existing changes, and verify that ssf isolate creates the worktree or branch you expect on your default branch.

Frequently asked questions

Official sources

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