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::preset;

pub use format::speckit::workflow;

pub use commands::*;

pub use pipeline::*;

Modules

acceptance_at

A person’s decision that a story’s acceptance tests are written at a Setup or Foundational task: the fix for a plan that implements a story’s behaviour before the story. Recorded in the state directory — never an edit of the spec (constitution I) — and changing no order or dependency (IV): only which task’s acceptance author receives the story’s scenarios.

acp

External agents as executors, over the Agent Client Protocol (ACP v1): speccoder is the client, the agent makes one attempt in the worktree, and every permission request, file and terminal call it sends is decided by speccoder’s policy and approvals.

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.

ask

Ask: a read-only conversation beside every view (L0 of the ladder).

attempts

Durable attempt outcomes.

attest

Signed, portable evidence per ticked task.

aws

Where Bedrock’s credentials will come from, named offline: the AWS credential chain’s first source, by kind and name, from environment variable presence and the section headers and key names of the AWS config and credentials files. No value is ever read into a message — only a profile’s region — and nothing here calls AWS.

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.

collection

Which of an attempt’s changed test files the run actually collected: a test that never ran is evidence of nothing.

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.

copy

What went wrong, as one block of plain text to paste into an issue or a chat: the code and the message, each fix line, the docs link, and speccoder’s version, the OS and the run — never a secret. The app copies the same block (its twin in ui/src/lib/copy.ts); the CLI’s --copy puts it on the system clipboard.

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.

explore

spec explore: an idea explored read-only by the format’s own skill (or speccoder’s fallback), ending in approaches the person chooses from; the choice composes the brief that starts the spec. Sessions are files in the project’s state, never in the checkout.

external

External executors: another coding agent 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: what waits for a person across the project’s features — blocked on them (oldest first), ready to review (riskiest evidence first), working, idle. Read-only; every item carries the actions that decide it.

include

[worktree] include and .worktreeinclude (Claude Code’s file, .gitignore syntax): git-ignored files of the person’s checkout — a .env, a local config — copied into each worktree speccoder runs checks in, to the same relative path.

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.

layout

The project’s test layout, detected by code: the runners of the checkout, each runner’s collection rule as configured, where tests live today, the naming habit, and where speccoder puts a task’s acceptance file. A fact handed to the implementer and every test author, never a judge input; undeterminable parts are listed as unknown, never guessed. Same checkout, same bytes.

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.

new_project

A new project from one line of intent: the plan — the stack’s own scaffold, the spec format’s own init, speccoder init --yes and one commit as the person — computed read-only, shown, confirmed, and then run exactly as shown. speccoder writes none of the stack’s or the format’s files itself (constitution VII); speccoder.toml is written only by init.

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.

person

Commands run for a person from an interface that confirmed them.

pipeline

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

plan_lint

Checks of a plan before it runs: where the task list will produce no evidence. Deterministic, text-level, warnings only — they never block, delay or re-order a run, and never edit the plan.

planning_chain

Plan through: one description, planned by the format’s own skills in the order its Planning gives — the creating skill, then toward the task list, then the check — each run unchanged through hosting::run_in. It stops only where a person decides: open questions after the spec is written, the person’s review of the spec before anything is planned, a failure, or the end of what was asked for.

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.

prepare

A run’s worktree gets its dependency folders ([worktree]).

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).

sample

Try the sample: a small project and a run of it recorded with a real model, bundled into release builds, copied into speccoder’s own state directory (never the person’s workspace) and verified by strict replay — no model, no key, no network. A run this build cannot reproduce is reported as such, never shown as if it had worked; a build without the recording says so (SAMPLE-MISSING), never shows an empty playback.

sandbox

The OS sandbox for commands speccoder starts.

secrets

Values copied into a worktree from the person’s secret files (a .env that [worktree] include copies): masked in everything speccoder shows or hands on — command and check output, tool results, messages — as [redacted:NAME], each in the forms it may be printed in (as is, base64, hex, URL-encoded).

seed

A new lane’s build folders, cloned from its feature’s worktree.

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.

session

Ending a started command and everything it started. Through the sandbox helper the command leads a session of its own (procage’s exec_session): what it starts may form process groups (test runners) but never leave the session. A plain command leads a process group.

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.

shape

speccoder shape: a person’s words made into a requirement, a bug line, a quick change or a note. One model call proposes; code decides what the proposal added, dropped and assumed (speccoder_core::shape). Nothing is written: the field’s own sheet or command writes what the person accepts.

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.

welcome

What a host started outside a project shows: the recent projects (speccoder’s own state, written when a project is opened or created) and folder names to choose from — read-only, under the person’s home.

worktree

Isolation and checkpoints.