specrails-core

The agent workflow engine behind Specrails Desktop. Core does two things:

1. Installs the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: the implement and retry entry points (implement runs one ticket or several tickets as one aggregate run), provider settings and the official OpenSpec skills. The architect, developer and reviewer roles are defined by the runtime itself; no role file is installed.
2. Executes Desktop-owned workflow definitions through the programmatic agent runtime: independent agent and implementation operations, per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models. Desktop owns workflow composition and editable loop agents; Core retains the old builtin for saved runs.

Desktop bundles a pinned Core package and owns everything around it: worktrees, commits, pull requests, backlog and the user interface. Core never ships code on its own; it prepares a reviewed candidate for the host.

Commands

specrails-core init                Install specrails into a repository
specrails-core install-framework   Materialize the versioned framework (offline)
specrails-core swap-current        Point framework/current at a version (offline)
specrails-core assemble            Link the framework into a project workspace (offline)
specrails-core pipeline            Inspect and verify durable implementation phases
specrails-core runtime             Run, inspect and resume programmatic agents

Desktop calls init and the offline framework lifecycle, then launches dist/agent-runtime/cli.js directly. The machine-readable contract between both lives in integration-contract.json; the runtime configuration schema is schemas/agent-runtime.schema.json.

Layout

bin/specrails-core.mjs     npm bin shim → dist/installer/cli.js
src/installer/             CLI, framework lifecycle, provider rendering
src/pipeline/              pipeline journal, gates and verification receipts
src/agent-runtime/         programmatic runtime: graph, executors, compact loop, recovery
templates/                 workflow commands, provider settings, Kimi runner
schemas/                   runtime configuration schema and fixtures
integration-contract.json  Desktop ⇄ Core contract

Develop

Requires Node.js 20.19.0+ and Git.

npm ci
npm test               # build + typecheck + vitest
npm run ci             # full local CI: typecheck, script tests, coverage, package check

See CONTRIBUTING.md and CI and publishing.

License

MIT