SpecOps CLI

Read this in: English | Português (BR)

SpecOps turns GitHub Spec Kit's spec-driven workflow into an enforced, auditable process. It layers an agent-guided atomic development methodology on top of any Speckit repository — a physical state ledger, typed evidence with machine collection, and token-optimized review — without replacing or forking a single Speckit file.

Speckit gives your agents great artifacts (spec → plan → tasks → implement). SpecOps makes sure they actually follow them: state is on disk and Git-verifiable, evidence is collected by tooling instead of claimed by the agent, and review rejects as cheaply as possible.

Why SpecOps?

Spec-driven development with AI agents has three recurring failure modes. SpecOps addresses each one:

What it adds to Speckit

• 📒 Physical state ledger (Repo-as-State). A versioned, structured status.yaml tracks phase, tasks, evidence, and review cycles. Mutated only through specops commands — never hand-edited, never held in agent memory. State changes are atomic and interruption-safe, guarded by optimistic concurrency (a monotonic revision) and a workspace-identity check (feature / branch / baseline); older ledgers migrate losslessly with a backup.
• 🔬 Automated evidence collection. complete-task --auto harvests commits and diffs and records them as typed evidence — mechanically, never agent-narrated. Test verification runs once at the review gate (specops preflight), not per task, so the implement loop stays cheap. A task cannot reach DONE, and no change is approved, without proof.
• 🔁 A phase state machine wired into the prompts. specops init injects directives into the specify, plan, tasks, and implement prompts so the ledger is created and phases advance automatically — the human never runs the bookkeeping by hand.
• ✂️ Token-optimized surgical review. The installed /specops-review command reviews only effective-diff files and stops at the first cheap rejection.
• 📐 Empirical verification & gates. specops consistency and specops reconcile are exit-code gates you can drop into CI or agent prompts.
• ➕ Additive and reversible. Everything is delivered through marker-delimited blocks. Removing those blocks restores the affected Speckit files byte-for-byte.

Install

pip install speckit-specops

Installs the specops command. Requires Python ≥ 3.10 and Git ≥ 2.30. No network I/O after install.

Quick Start

# In a Speckit-initialized repository:
specops init          # inject directives, install /specops-review, create specops.json

That's it. From here you drive Speckit as usual (/speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement) and the injected directives take care of the ledger and phase transitions. Check state anytime:

specops status show

How it works

SpecOps rides the Speckit lifecycle. Once specops init has run, the injected directives drive the ledger at each stage seam:

The phase machine is SPECIFY → PLAN → TASKS → IMPLEMENT → REVIEW → DONE. If SpecOps is not installed, the Speckit prompts still work standalone — the directives degrade to no-ops.

Commands at a glance

The full reference — flags, exit codes, JSON contracts, examples, and the review workflow — lives in docs/commands.md.

Stability & contract freeze

Building automation on SpecOps? docs/stability.md is the contract freeze for 1.0: it classifies every adopter-facing surface — specops.json, status.yaml, lane.yaml, gate-profile files, the --json output envelope, exit codes, the findings-input contract, the context-map file, and SARIF output — as frozen, and states the additive-vs-breaking rule and the post-1.0 versioning/migration obligations for each. Every --json output carries an output_version so you can detect envelope changes.

Recovery operations

Two states an interrupted session leaves behind used to have no legal move, so the only way forward was to hand-edit the very files the ledger exists to make trustworthy. Both are now commands that record the correction rather than hiding it:

• A task closed with wrong evidence. specops status amend-task <id> --evidence … --reason … appends the correction: it becomes the task's current evidence, the prior record is retained as superseded history, and the task is not reopened. An amended task is more informative than a silently-correct one — which is what stops amendment from being a way to launder a bad close.
• The active feature pointer. specops feature use <dir> repoints it explicitly (and status init-spec records the feature it initializes), while specops feature rename <old> <new> carries a renumbering across directory, ledger identity, branch reference and pointer with every recorded fact intact.

SpecOps resolves the active feature with the same precedence Spec Kit uses — SPECIFY_FEATURE_DIRECTORY before .specify/feature.json — so the two tools can never answer about different features from the same repository state.

How SpecOps behaves: a paved road you can leave — on the record

SpecOps is neither a rigid gate that blocks you nor a suggestion you can ignore. It presents a correct path and lets you deviate — as long as the deviation is recorded. What it blocks is silent deviation, not deviation itself:

• A path you changed that the plan didn't predict isn't rejected — you acknowledge it with a reason (specops trace acknowledge).
• A review finding that turns out to be a false positive isn't a dead-end — you dismiss it with a reason (specops handoff finding dismiss).
• A gate that was skipped is recorded as a finding, never silently passed.

SpecOps records the deviation and its reason; it does not judge whether the reason is good — that is the team's call, not the tool's. (A small core of safety-critical gates — persisted-schema changes, secrets, public-contract breaks, destructive actions — is not pierceable; there SpecOps halts and asks a human.)

Configuration — specops.json

Unknown keys are preserved on re-init.

Review round integrity

Each review round records the code scope it covered — an anchor round the full baseline..HEAD, a corrective round the change since the last review — derived from git, never hand-picked (specops handoff record-scope). Approval fails closed unless the recorded scopes together cover the whole feature, so no APPROVED can rest on a partial hunt. If the review keeps cycling past review_round_cap, SpecOps halts and asks a human rather than looping unbounded (raise the cap, approve, or rebaseline to resume). Ledgers that predate this behavior degrade to the prior approval path.

Rounds accumulate coverage; they do not narrow it. A corrective round's delta is where the defects are most likely to be, but it is a priority, not a boundary: record-scope also prints the full baseline..HEAD set with the remainder marked not yet re-verified this round, so a defect an earlier round missed cannot be hidden from later rounds by the tool. If your context budget will not stretch to the whole set, that is a legitimate call — the directive asks you to record it rather than letting the tool make it silently. The command also names any product path that no recorded round has ever reached, and approval fails closed while that set is non-empty. Coverage is derived from commit ranges only, so a round is credited only with what can still be verified: if a rebase or squash orphaned a recorded review HEAD, one specops handoff record-scope on the open round re-anchors over baseline..HEAD — a rewrite costs a re-scope, never a re-review.

Language policy

All SpecOps operational output (CLI messages, injected assets) is in English. Your prose (spec.md, plan.md, task descriptions) may be in any language — SpecOps parses only structural tokens (SC-\d+, T\d+, action suffixes), never content.

Supported Speckit layouts

SpecOps resolves prompt targets at runtime from .specify/integrations/<agent>.manifest.json. Any Speckit integration with a recorded manifest is supported; unknown layouts fail closed. Tested with Speckit ≥ 0.12 (Claude skills mode, separator -).

Uninstall

Remove the appended block from each prompt file, then delete specops.json and the installed review command. No other files are written; the restore is byte-identical.

Contributing

Contributions are welcome — see CONTRIBUTING.md for dev setup, the quality gates, and project principles. SpecOps is at 0.x; the CLI surface and ledger format may still change before 1.0 (see CHANGELOG.md).

License

MIT © Paulo Segundo