Specstride core
The engine every host is built on. 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.
Loop engineering
A single agent session is one loop with no brakes. The core treats the loop itself as the thing to engineer: which loops exist, what ends each of them, and what happens when one gets stuck. From the outside in, the loops are pipeline stages, the phases of a run, phase attempts, passes and micro-loop cycles.
- 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, before the critic sees anything.
- 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. Each decision records its rule id.
- Loop layers you can stack:
none,microand the opt-inparallellayer.
Governance
- Separation of roles. The implementer and the reviewer are separate sessions, chosen independently.
- Verdicts that can’t be forged. A verdict is bound to a one-time nonce for that attempt.
- Approval is a record. Approvals live outside the implementer’s write scope and are verified again on resume.
- Configuration narrows, never widens. Project configuration can only restrict a run. Anything that widens capability comes from user scope, the environment or flags.
- Layering enforced in CI. A layer imports only from layers below it and from the contracts package.
Layers
L7 HOSTS Claude Code plugin · dsh · Hermes · plain shell
L6 CLI derive · validate · launch · status · wait · stop · resume · doctor · learn
L5 RUNTIME detached runtime root · lock and lease · run-state owner
L4 ENGINE run → phase → attempt · verification gate → critic → approval record
L3 PASS LOOP passes · watchdogs · breakers · yields · loop layers · router
L2 PORTS harness · spec format · check runner · event sink · secret resolver
L1 EDGES adapters · stream readers · sinks · resolvers
L0 STATE user state · per-workspace control plane
A release is four packages with one version: specstride (the CLI as one ESM file with no runtime dependencies), @specstride/contracts, @specstride/host-kit and @specstride/testkit. A host takes a release by pinning the tarballs and their sha256.
Hosts built on it
- Claude Code plugin — Its skills run the core 0.1.0 CLI from your PATH.
- dsh host — Pins the core 0.1.0 release tarballs by sha256.
- Hermes host — Pins the core 0.1.0 release tarballs by sha256.
Commands
specstride launch- Runs the launch checks, writes the launch record, starts the detached runtime root and waits for the handshake.
specstride status · wait · stop · resume- Read the state of a run, block until it changes, end it at the next safe boundary, or continue it from the records on disk.
specstride doctor- Checks this machine and workspace — Node, git, the agents on the search path, a
specs/directory. specstride learn- Suggests per-phase settings from the run's own telemetry, evaluates each change against a baseline and reverts the ones that make things worse. Off unless you turn it on.
specstride reverse- Reverse specification of existing sources — plan, lint, guard, inventory.
Install
Core (CLI, for host builders)
The dsh and Hermes hosts pin the core, and the Claude Code path above installs its CLI. Install it on its own only to run the specstride CLI from a shell or to build a host on it. Build the engine from a clone and pack its release. Nothing is on npm yet.
Needs
- Linux. macOS is not verified.
- Node 22+ and git
In one command — runs the steps below, in order (read the script)
curl -fsSL https://specstride.ai/install.sh | bash -s -- core
Or step by step
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.
Commands last run as shown: 2026-11-08
RepositoryStar mairp/specstride-core on GitHubPublishing
Useful? A star on mairp/specstride-core helps others find Specstride.