Crate speccoder_runtime 

Application services of speccoder.

The only crate that executes anything: every side effect (file writes, processes, model calls) goes through here, and model calls and tool calls through the embedded agentplane runtime (see substrate). The CLI only parses arguments, calls a service and renders its result.

Re-exports

pub use format::speckit::hooks;

pub use format::speckit::workflow;

pub use commands::*;

pub use pipeline::*;

Modules

actions

What a person can do now, and taking it. The list comes from the project as it stands: the report, what waits for a decision, the planning files not yet committed and the installed planning skills. Interfaces render the list; perform is the one place an action’s Runnable becomes runtime calls, for every interface.

approvals

A person’s approvals and rejections.

attempts

Durable attempt outcomes.

attest

Signed, portable evidence per ticked task.

bench

Public benchmarks as evaluation cases.

bug

speccoder bug: the L2 rung. The person’s triad is recorded where the format keeps bugs (its own bug structure first, else its standing bug-fix unit), reproduced by a test-blind author — one test per stated behaviour, red on the untouched code by an assertion — confirmed by the person once, frozen, and fixed as an ordinary task whose verdict also needs the revert rejected. Nothing here is a second pipeline: the stages run inside speccoder run (pipeline::bug).

code

A feature’s code as a person reads it: what its branch changed since it forked — by commit, by file — and its files. The revision is never the caller’s: it is the feature’s branch, or HEAD before speccoder worked on it; a file is read only when the tree lists it.

commands

Read-side and single-shot services: inspect, worktree, propose, replay and eval.

comments

Anchored review comments: the person comments on a passage of a feature document, a line of the spec’s changes, a line of a shown visible test or a finding; the drafts collect in a tray in the state directory (<state>/comments/<unit>.json, never browser storage, never the worktree) and go out together as one revision turn of the format’s revising skill, scoped to the sections they touch. Before the turn the feature’s documents are snapshot; after it the change is shown per section, sections no comment touched flagged; Undo Revision restores the snapshot byte for byte, on the person’s command only (constitution 2.3.0, principle I). Code-view line comments become one nudge for a task’s next attempt.

context

The context bundle for one task.

controls

A person’s controls over single tasks: accept, skip, nudge — and cost, what the work used.

convergence

speccoder converge: assess a finished feature against its artifacts and append what remains.

current

The current feature: which unit a command works on when none is named, shown and switched by speccoder feature.

doctor

speccoder doctor: everything a run depends on, checked without writing anything — git, the repository, the spec project and its tool, the configuration, the model key, the sandbox, the state directory, the attestation signing key and the repository’s instructions. A failure is a run that would fail or judge wrongly; a warning is less than it could be (unsigned evidence, no spec tool).

documents

A feature’s planning documents, rendered for an interface: the spec, the plan and the task list as HTML. Raw HTML in them is shown as text, never passed through: the documents are the repository’s, and an interface that holds a token must not run what they contain.

eval

speccoder eval: judge attempts with held-out oracles.

evidence

A task’s evidence as rows: its verdict and what established it, read from the signed statements on its commit and the report — never re-derived, so what an interface shows is what a reviewer can verify with attest verify. Every interface renders these rows; none computes its own.

external

External executors: another coding agent — Claude Code (claude -p), Codex (codex exec) or any command — makes the attempt; speccoder keeps everything around it.

format

The spec-format seam: everything the runtime knows about a spec format comes from an Adapter — where the intent lives, what a planning skill may write, what the model is told, how a task is ticked. The judge (verification, evidence, commits) is the same for every format.

git

A thin wrapper over the git CLI — the user’s git, with the user’s configuration, for anything that writes.

github

GitHub, built in: its REST and GraphQL APIs, over TLS, as the person — a token from the environment or the one speccoder auth login kept in the credential store. No gh needed. Reading is free (issues, a branch’s pull request); writing is pr, which a person confirms. github.com and Enterprise hosts alike: the host is the remote’s.

handoff

speccoder pr: hands a feature’s work to review as a draft pull request whose body is the evidence behind every tick.

held_out

Held-out acceptance tests: written by a second author call after the visible ones, kept in the state directory — never in the worktree, never in an implementer’s input — red-checked on the checkpoint, and run over the final tree after an attempt that passed visibly. Only the scenario IDs of a failure reach a retry.

hosting

speccoder spec: list the installed Agent Skills, or run one.

in_place

In-place runs: speccoder run --in-place works on speccoder/<feature> in the person’s own checkout instead of a separate worktree — the way to run features whose spec git ignores (a worktree holds only commits).

inbox

speccoder inbox: every decision that waits for a person, across the project’s features, the most urgent first. When agents write the code, this is the person’s work: approve or refuse a call, rule on tests, look at a suspected shortcut, settle a changed spec, decide what to do with a task that did not pass, commit a plan, hand off a branch. Read-only; every item carries the actions that decide it.

init

speccoder init: detect a project’s checks and write speccoder.toml.

instructions

The repository’s instructions for agents: the committed AGENTS.md files that apply to a task, as agents.md defines them — “the closest AGENTS.md to the edited file wins”.

integrity

The integrity audit of an attempt’s diff.

ladder

Where work came from, written once: <project state>/ladder/origins.json, one record per subject (a unit, or <unit>/<requirement>). Only record_origin writes it; a second write for a subject is refused.

mcp

MCP servers’ tools, under speccoder’s policy.

mutation

Mutation testing as evidence: after a passing verdict, the attempt’s changed code is mutated and the tests run against each mutant. A mutant the tests do not catch (“survivor”) is code the tests do not really check — the shape of a test written to pass rather than to verify.

next

What to do next, from a command’s result: its status and payload classified into an Outcome, whose steps every renderer shows — the human Next: block, data.next, the TUI footer.

oracle

The oracle at review: per requirement, the visible acceptance tests the run would use, written on the person’s request — two independent author calls whose stated expectations are compared for ambiguity, the first one’s citing tests red-checked on the checkout’s HEAD in a scratch worktree, a held-out set sealed beside them — shaped by the person (reject, ask again, edit, choose a reading), and frozen with the approval (freeze). A task whose requirement has a frozen, current oracle reuses it instead of calling the author.

pipeline

The run pipeline: one task (task), a feature (feature), and the pieces they share.

pre_frozen

The store of acceptance tests decided before the run (PreFrozenAcceptance): <project state>/pre-frozen/<unit>/<requirement>/ holds the record and the files it names. Written only by the producer’s person-commanded step; every load checks each file’s hash.

progress

Live progress: what a run is doing while it does it.

quick

speccoder do "…": a small change without a planning ceremony, and without skipping the evidence. The request becomes a story, a requirement (approved: the person wrote it) and a task in the format’s standing unit for quick changes; those planning files are committed; then the task runs like any other — worktree, failing acceptance tests first, checks, a verdict, a commit with its evidence.

resume

Resuming an attempt a killed process left behind.

review

speccoder review: the person’s review of the spec, one requirement at a time. A decision — approved, or changes requested with a comment — is bound to the exact line it was made on, and names who made it; when the line changes, the decision lapses. It is recorded in review.json beside the spec, to commit and share like the spec itself. The model never writes it (crate::tools::paths::REVIEW_FILE).

sandbox

The OS sandbox for commands speccoder starts.

service

The web host’s one way into the runtime: every entry point it uses, re-exported or delegated without changing a result. A write the host serves goes through actions::perform, like every interface’s; a later feature adds read views here as delegates, never a second write path. The layering test holds the host to this module.

settings

speccoder.toml as settings: a catalogue of every key — its type, default and meaning — the values a project sets, and edits that keep the file’s comments and are checked by every parser before they are written. speccoder reads committed configuration only, so a change is offered as a commit of exactly this file.

skills

Installed Agent Skills: SKILL.md files under .claude/skills/ and .agents/skills/, as spec formats install their commands.

status

speccoder report: a feature’s tasks and the evidence behind each tick, read from what is durable and reviewable — tasks.md at the tip of speccoder/<feature> and the trailers of its commits. Read-only: no model, no worktree, no state directory.

strength

Measuring the acceptance set’s strength: wrong and permitted candidates of a verified task’s change, run against its acceptance tests.

substrate

The execution substrate: agentplane, embedded.

tools

speccoder’s tools: what an attempt may do to its worktree, served to agentplane as tool servers fs, proc and git.

tour

The evidence tour of one task, built from the signed statements on its commit and the commit itself — nothing else, so it never says more than attest verify can check. Six steps in a fixed order; a step without evidence says so in the verdict’s own words instead of being left out.

user_config

The person’s own settings, ~/.config/speccoder/config.toml: how speccoder gets their attention. Never read from the committed speccoder.toml, which is the project’s policy.

verify

speccoder verify: run the project’s declared checks and judge the result.

worktree

Isolation and checkpoints.