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, micro and the opt-in parallel layer.

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)

install.sh
curl -fsSL https://specstride.ai/install.sh | bash -s -- core

Or step by step

Core (CLI, for host builders)
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

Useful? A star on mairp/specstride-core helps others find Specstride.