for Claude Code
Claude Code plugin
Specstride inside Claude Code. Two skills run a Spec Kit feature through the gated loop and report back in a few lines, so your session keeps its context.
Version 0.1.0. Runs on Linux; macOS is not verified.
Loop engineering LLM-as-a-judge Open source Runs on your machine Your models, your keys
Development governance for coding agents. Every phase reviewed, signed and committed.
An agent that grades its own work says "done" when it isn't. Specstride is a Claude Code plugin that takes a Spec Kit feature to done, phase by phase, unattended: implement, verify, review, commit, resume. A separate reviewer must approve each phase before the run moves on, and every approval leaves a signed record and its own commit.
- implementthe phase's tasks
- verifythe engine runs the tests
- reviewa separate session, no tools
- commita signed record, one commit
- next phaseor resume where it stopped
Install
Claude Code
Install the plugin in Claude Code, then take the ready-made example feature through its first run before pointing it at your own repository.
# in Claude Code /plugin marketplace add mairp/specstride-plugin /plugin install specstride@specstride-marketplace # to try it on a ready-made feature first git clone https://github.com/mairp/specstride-example cd specstride-example claude # then say Run Specstride on the feature in this repo.
On your own repository — any git repo with a specs/NAME/tasks.md and a test script in package.json — say the same sentence. Each approved phase becomes its own commit.
dsh
Build the dsh host from a clone, install it with the engine's CLI from the tarball it pins, then put the three skills into your repository. Nothing is on npm yet.
git clone https://github.com/mairp/specstride-dsh cd specstride-dsh # resolves the pinned engine tarballs; nothing compiles npm install # renders the skills and the shim, runs every build gate npm run build # specstride-host-dsh and the specstride CLI this repository pins npm install -g . vendor/core/specstride-0.1.0.tgz # in your repository; the skills go into .dsh/skills/ specstride-host-dsh install --project # six findings, one line each specstride-host-dsh doctor
Then, in a dsh session in your repository, say "run the specstride-run skill in dry-run on the feature". It plans and validates and launches nothing. Drop "in dry-run" to run the feature for real.
Core (CLI)
Build the engine from a clone and pack its release. Install the specstride CLI on its own, to run it from a shell or to build a host on it. Nothing is on npm yet.
git clone https://github.com/mairp/specstride-core cd specstride-core npm ci # packs the four release tarballs into .build/release/ node scripts/pack-release.mjs npm install -g .build/release/specstride-0.1.0.tgz # prints the CLI protocol, 1 specstride --protocol # in your repository specstride doctor
specstride --help lists every verb. Each verb takes --json, --verbose and -h. To build a host, start from @specstride/host-kit and pass the conformance suite in @specstride/testkit. See the core README.
01 · how it works
How it works
For each phase of a Spec Kit feature, the same gate:
- The implementer works through the phase's tasks.
- The engine runs the tests itself.
- The reviewer — a separate session, with no tools — reads the actual change against the tasks and answers with a one-time nonce.
- Approved: tasks ticked, one commit, signed record. Rejected: back to the implementer with the reasons, up to 3 attempts. A rejection that names new unmet tasks is diagnosed first, and the next attempt is narrowed to them.
===== PHASE 1 — the overlapping work (2026-11-04T03:21:24.358Z) ===== [001-par-overlap] phase 1 attempt 1: proposer started [001-par-overlap] verification: npm test -> passed [001-par-overlap] phase 1 attempt 1: rejected ----- phase 1 REJECTED on attempt 1/3 ----- ----- diagnostician: phase 1 attempt 1 (unmet set changed) ----- [001-par-overlap] phase 1 attempt 2: proposer started ----- accelerator: phase 1 attempt 2/3 (dsh) — acting on the hint for T002,T003 ----- [001-par-overlap] verification: npm test -> passed [001-par-overlap] phase 1 attempt 2: approved ===== PHASE 1 APPROVED (attempt 2) ===== ----- git checkpoint: phase 1 approved -----
The engine's own output, trimmed, from a stored log: the phase's tests passed, the reviewer still said no, the rejection was diagnosed, and the narrowed second attempt was approved.
02 · the reviewer
LLM-as-a-judge, held to evidence
A model judging another model's work is only worth something when the judge is independent, reads the real change, and cannot be imitated. Specstride's reviewer is that judge, and the engine around it is what makes its verdict count.
Independent
The reviewer is a separate session, chosen independently of the implementer, on any provider. A phase is never approved without one.
Evidence, not a summary
It reads the actual change against the phase's tasks, including the contents of new files. The implementer's notebook and repair history are withheld from it.
Facts before opinion
The engine runs the tests itself, before the reviewer sees anything. A phase whose tests fail never reaches review.
Cannot be imitated
The verdict is bound to a one-time nonce for that attempt. Text planted in the evidence cannot pass for it, and an implementer that prints "APPROVED" achieves nothing.
Outside text is data
Everything from outside the runtime enters through one ingress, where it is size-capped, framed as data and stripped of credentials. It fails closed.
A verdict on the record
An approval is a signed record outside the implementer's write scope, read back and verified again on resume. A forged or missing approval stops the run.
Independent
The reviewer is a separate session, chosen independently of the implementer, on any provider. A phase is never approved without one.
Evidence, not a summary
It reads the actual change against the phase's tasks, including the contents of new files. The implementer's notebook and repair history are withheld from it.
Facts before opinion
The engine runs the tests itself, before the reviewer sees anything. A phase whose tests fail never reaches review.
Cannot be imitated
The verdict is bound to a one-time nonce for that attempt. Text planted in the evidence cannot pass for it, and an implementer that prints "APPROVED" achieves nothing.
Outside text is data
Everything from outside the runtime enters through one ingress, where it is size-capped, framed as data and stripped of credentials. It fails closed.
A verdict on the record
An approval is a signed record outside the implementer's write scope, read back and verified again on resume. A forged or missing approval stops the run.
The price is stated too: every attempt makes at least two model calls, on your own subscription or key. The diagnostician that reads a stuck phase gives no verdict; nothing it says approves or rejects.
03 · loop engineering
Loop engineering
A single agent session is one loop with no brakes. Specstride treats the loop itself as the thing to engineer: which loops exist, what ends each of them, what may cross between them, and what happens when one gets stuck.
How it ends
One loop: It can end with "it went quiet".
Engineered: A named stop reason with a fixed exit code.
Who says "done"
One loop: The agent that did the work.
Engineered: The tests first, then a separate reviewer.
What a retry is
One loop: The same attempt again, with the same mistake.
Engineered: A diagnosis first, then an attempt narrowed to the unmet tasks.
Why a decision was made
One loop: No rule to point to.
Engineered: A rule id and a table version on every decision.
What a kill costs
One loop: The loop stops there.
Engineered: No engine process survives, and the next start resumes where it stopped.
01 pipeline stages
ends: Each stage has its preconditions. A run ends only on a named stop reason with a fixed exit code.
02 phases of a run
ends: A phase ends when the reviewer approves it: tasks ticked, one commit, a signed record.
03 phase attempts
ends: Capped at 3 per phase. The third rejection ends the run with exit 2.
04 passes
ends: Watchdogs and breakers end a pass. A long job yields instead of waiting.
05 micro-loop cycles
ends: Inner checks end at a checkpoint: keep, repair or unresolved (the micro layer).
Every loop has an end
Attempts are capped, passes have watchdogs and breakers, and every way a run can stop is a named stop reason with a fixed exit code.
Deterministic checks before any opinion
The verification gate runs the phase's frozen check manifest, with a fixed argument list and no shell. A phase whose tests fail never reaches review.
Stuck phases get unstuck
A rejection that names new unmet tasks is diagnosed first, in a separate session. The next attempt is narrowed to those tasks, and the reviewer judges it like any other.
A router with no I/O
Check order, loop layer and escalation to the next model tier come from a pure function over versioned rule tables. Every decision records its rule id.
Loop layers you can stack
none is the classic loop. micro adds inner checks that end in keep, repair or unresolved. parallel, opt-in, runs tasks with disjoint files at once.
Yields instead of dead waits
Long jobs run detached while the pass yields. A wait that can no longer complete ends early instead of burning its timer.
It learns, with guardrails
The learning layer suggests per-phase settings from the run's own telemetry and reverts any change that makes things worse. Off unless you turn it on.
Every loop has an end
Attempts are capped, passes have watchdogs and breakers, and every way a run can stop is a named stop reason with a fixed exit code.
Deterministic checks before any opinion
The verification gate runs the phase's frozen check manifest, with a fixed argument list and no shell. A phase whose tests fail never reaches review.
Stuck phases get unstuck
A rejection that names new unmet tasks is diagnosed first, in a separate session. The next attempt is narrowed to those tasks, and the reviewer judges it like any other.
A router with no I/O
Check order, loop layer and escalation to the next model tier come from a pure function over versioned rule tables. Every decision records its rule id.
Loop layers you can stack
none is the classic loop. micro adds inner checks that end in keep, repair or unresolved. parallel, opt-in, runs tasks with disjoint files at once.
Yields instead of dead waits
Long jobs run detached while the pass yields. A wait that can no longer complete ends early instead of burning its timer.
It learns, with guardrails
The learning layer suggests per-phase settings from the run's own telemetry and reverts any change that makes things worse. Off unless you turn it on.
04 · what you get
What you get
Each benefit comes from a specific part of how the loop is built. Read every line as: you get this, because the engine does that.
- "Done" that means done
- because Tests run before review, an independent reviewer approves, and the commit happens or the run fails.
- Unattended runs you can walk away from
- because A detached runtime, capped loops, a clean stop, and resume after a crash or a kill.
- Fewer wasted attempts
- because Diagnosis narrows each retry to the unmet tasks, and the router escalates model tiers by rule.
- Your models, your keys
- because The implementer and the reviewer are resolved independently. The engine has Claude, dsh, Codex, pi and prime adapters and a generic descriptor (
cli,openai-chat,anthropic-messages). The hosts ship Claude and dsh today. - An audit trail
- because Approval records, one commit per phase, rule ids on every decision, OTLP and Loki telemetry.
- Safe parallelism
- because Fenced worker trees, audited deltas, and the full gate on the merged tree.
- Extensible without forks
- because 19 versioned extension points (
specstride.<name>/<major>), each with a conformance suite in@specstride/testkit. - Nothing leaves your machine
- because Specstride runs no service of its own, so nothing is sent to its authors.
05 · plugin, dsh, core
Three ways to run it
One engine, and thin hosts on top of it. Pick the one that matches the agent you already use. The loop, the gates, the records and the commits are the same in all three.
for dsh
dsh host
Specstride inside the DeepSeek Harness (dsh). Three skills run a Spec Kit feature through the same gated loop, or plan a reverse specification. A shim is the only path from a skill to the Specstride CLI.
Version 0.1.0, built from a clone: nothing is on npm yet. Linux is verified, macOS is not, and the paid live probe of the skills inside dsh has not run yet.
the engine
Specstride core
The engine behind both hosts. It holds the specstride CLI, the contracts, the loop layers, the runtime, the adapters, and the kits a host is built from. Use it to run the CLI on its own, to build a host for another agent, or to read how the loop and its governance work.
Release 0.1.0, packed from a clone: nothing is on npm yet. Linux is verified, macOS is not.
| Claude Code plugin | dsh host | Specstride core | |
|---|---|---|---|
| Runs in | Claude Code | dsh | Your shell |
| Pick it when | You work in Claude Code. | You work in the DeepSeek Harness. | You run the CLI from a shell, or build a host for another agent. |
| Install | 6 steps, run by hand on 2026-11-05 The steps → | 7 steps, run by hand on 2026-11-08 The steps → | 7 steps, run by hand on 2026-11-08 The steps → |
| You drive it with | 2 skillsspecstride-run specstride-doctor | 3 skillsspecstride-run specstride-reverse specstride-doctor | 5 commandsspecstride launch specstride status · wait · stop · resume specstride doctor specstride learn specstride reverse |
| Status | Version 0.1.0. Runs on Linux; macOS is not verified. | Version 0.1.0, built from a clone: nothing is on npm yet. Linux is verified, macOS is not, and the paid live probe of the skills inside dsh has not run yet. | Release 0.1.0, packed from a clone: nothing is on npm yet. Linux is verified, macOS is not. |
| The loop | The same in all three: same gates, same records, same commits. | ||
06 · unattended
Built for unattended work
For people who leave agents running on real work and need to trust the result when they come back.
Kill the engine mid-run, nothing survives
SIGKILL the engine in the middle of a phase and no engine process is left running. Start it again and the run picks up where it stopped.
Approved means committed
Every approved phase becomes its own commit. If a commit is blocked, the run never reports success: the engine exits 1 and says so.
A clean stop
The stop verb of the specstride CLI that the plugin bundles ends the run at the next safe boundary: the workers finish their pass, the merge check runs, the record closes whole, no survivor.
A reviewer from any provider
The reviewer can come from any provider your DeepSeek Harness (dsh) reaches.
Secrets held back
Credentials are redacted from what the reviewer reads, and a credential in the change blocks the commit.
07 · see it run
See it run
The example repository is a tiny Node project with one Spec Kit feature, in three phases, nothing implemented yet — Specstride does that, one reviewed and committed phase at a time.
[P] tasks ran as a parallel group; the merge check caught a test one worker wrote for a framework the project does not use, so the engine redid both tasks in order before the reviewer saw the phase.08 · governance
Controls an agent can't talk its way past
Autonomy is useful only when you can trust what it reports. These controls are in the engine, so every host gets them.
Separation of roles
The implementer and the reviewer are separate sessions, chosen independently. A phase is never approved without a reviewer.
Verdicts that can't be forged
The verdict is bound to a one-time nonce for that attempt, so an implementer that prints "APPROVED" achieves nothing.
Approval is a record
Approvals live outside the implementer's write scope and are verified again on resume. A forged or missing approval stops the run.
Configuration narrows, never widens
Project configuration can only restrict a run. Anything that widens capability comes from user scope, the environment or flags.
Containment by default
Adapters declare containment levels C0 to C3. The strongest one available is the default, and C0 is an explicit opt-in.
Integrity tripwires
Fingerprints before and after every check, protected paths and pinned toolchains catch an implementer that edits what it must not. A tripwire stops the run until a human clears it.
Everything observable
One primary event writer per run and a read model for status. Every decision carries its rule id, so an audit can follow a run from launch to the last commit.
09 · your models, your keys
Your models, your keys
Choose the implementer and the reviewer independently, on any provider and model your DeepSeek Harness (dsh) reaches. By default both are separate Claude sessions.
Claude
implementer · reviewer
The default. Implementer and reviewer are two separate sessions through your Claude Code login.
dsh
implementer · reviewer
Implementer or reviewer on any provider and model your DeepSeek Harness (
dsh) reaches. Parallel units need dsh as the implementer.
# any provider and model your dsh reaches, either role
SPECSTRIDE_PROPOSER=dsh:<provider>/<model>
SPECSTRIDE_CRITIC=dsh:<provider>/<model>The loop stays the same whichever you choose: same gates, same records, same commits.
10 · parallel units, opt-in
Parallel units, opt-in
Mark tasks [P] in your Spec Kit tasks.md and turn the layer on. Tasks whose files are disjoint run at once, each in its own worker tree, and the project's files are untouched while they run. The engine merges their work and runs the phase's checks before the reviewer sees the phase; tasks whose files overlap are refused, with the reason printed, and run in order.
# your user configuration, read from this file only
loop:
parallel:
units: on
allow_detect: onGroups run only when the implementer runs on dsh, the one harness whose concurrent sessions are tested; with any other harness the layer stays off and the run continues in order.
11 · open source
Where your code goes
Runs on your machine
No service of its own: nothing is sent to Specstride's authors. Run records, approvals and logs stay in ~/.specstride/ on your machine, and telemetry export is off by default.
Your models, your keys
The implementer and the reviewer go through your Claude Code login by default, or through the provider you set with dsh. Each provider's own data policy applies.
12 · faq
Questions
Which one do I want — the plugin, dsh or core?
The one that matches the agent you already use. In Claude Code, the plugin, installed with two /plugin commands. In the DeepSeek Harness, the dsh host. The core is for running the specstride CLI from a shell, or for building a host for another agent. Both hosts bundle or pin the same core, so the loop, the gates, the records and the commits are the same whichever you pick.
What is loop engineering?
An agent session is a loop with no brakes. Loop engineering designs the loops around it instead: pipeline stages, phases, attempts, passes and micro cycles, each with a defined end, deterministic checks before any reviewer opinion, and a rule-driven router that decides what happens when a loop gets stuck. The core page shows the engine layer by layer.
Is this LLM-as-a-judge?
Yes, with the parts the bare pattern leaves out. The reviewer is an LLM that judges another LLM's work, but it is a separate session with no tools, the tests run before it sees anything, it reads the actual change and not a summary, and its verdict is bound to a one-time nonce and written as a signed record. The judge section shows what reaches it and what is held back.
Do I need Spec Kit?
You need the format, not its tooling. A feature is a specs/NAME/ directory with a tasks.md: ## Phase N: Title headings and - [ ] T001 … tasks are what Spec Kit writes, and you can write them by hand. spec.md and plan.md beside the tasks, if you have them, go to the implementer with the tasks.
Which models can it use?
Any you trust. Specstride is an orchestrator and does not rank models. The implementer and the reviewer are chosen independently: by default both are separate Claude sessions through your Claude Code login, and either can instead be any provider and model your DeepSeek Harness (dsh) reaches.
What stops the reviewer waving work through?
The reviewer is a separate session with no tools. It reads the actual change against the phase's tasks — not a summary it is handed — and it must answer with a one-time nonce, so planted text cannot pass for its verdict. The engine runs the tests itself, so the claim it reads was checked against a real run. Credentials are redacted from what it reads.
What happens when a phase keeps failing?
It is not just started again. When the reviewer's rejection names unmet tasks the phase has not been diagnosed for yet, a diagnostician — a fresh session, never the implementer's — reads the phase and writes a hint, and the next attempt is narrowed to those tasks with the hint as its first instruction. Both are on by default (SPECSTRIDE_DIAGNOSTICIAN=false or SPECSTRIDE_ACCELERATOR=false turns one off). A phase gets up to 3 attempts; after the third rejection the run stops with exit 2, the reasons are in the output, and a new run resumes from the phases already approved.
What leaves my machine?
Nothing is sent to Specstride's authors; there is no service of its own. What you choose goes to your model providers — the implementer reads the feature's spec, plan, tasks and the reviewer's feedback; the reviewer reads the tasks, the test output and the change. Each provider's own data policy applies. Run records, approvals and logs stay in ~/.specstride/ on your machine, and telemetry export is off by default.
What does it cost?
Nothing for Specstride itself — it is free and open source under Apache-2.0. Each phase makes at least two model calls on your own subscription or API key, so a run costs more than a single session would.
Does it run on macOS?
macOS is not verified — no Mac has run it. Linux is what it runs on today.
Is it from Anthropic?
No. Specstride is not affiliated with Anthropic.
How do I contribute?
Issues and pull requests on the plugin repository, following CONTRIBUTING.md — add a test with each change, keep the import boundaries, and run the formatter before you push. Good first issues are labelled good first issue. Questions and bugs go to issues.