specd-cli

specd

A spec-driven coding harness. It moves process enforcement out of an AI agent's context window into a deterministic, local, tool-gated pipeline: plan a change in Markdown, get it approved by a human, then execute it one task at a time against recorded evidence.

The agent reasons. The harness enforces.

Go, standard library only, zero runtime dependencies, one static binary.

Status

Released and young. 0.x is not a formality: the public surface may break on any minor bump.

The base loop is implemented and proven end to end by fourteen replayed journeys and by one real change through the whole loop — one change, in one root. It is not proven at scale, across concurrent callers, or over long-lived changes. Read release/release-decision.md for exactly what has been proven and what has not; it is the boundary this project stands behind.

Install

Go 1.26 or newer:

go install github.com/0xkhdr/specd-cli/cmd/specd@v0.1.0
specd --version

Or build from source:

git clone https://github.com/0xkhdr/specd-cli
cd specd-cli
go build -o specd ./cmd/specd

Each tagged release also publishes binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64, with SHA256SUMS and a build provenance attestation. Verify a download before running it:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify specd_linux_amd64 --repo 0xkhdr/specd-cli

The test suite runs on Linux, macOS, and Windows before any of those artifacts is published — see release/release-decision.md for what that does and does not establish. There is no installer script and no package.

The loop

init → new → author proposal/delta/design/tasks → check → human approve
→ next → context → start → edit declared files → verify → complete
→ human sync → sync → archive

Two of those steps are human, not agent: approve authorizes the plan, and sync authorizes accepted truth. The harness derives the human route from a controlling terminal, so an agent cannot pass either gate. There is no bypass flag.

Getting started, on an empty project:

specd init                       # create or adopt the managed .specd root
specd new add-dark-mode          # create the change and its planning artifacts
# author proposal.md, the delta spec, design.md, and tasks.md
specd check add-dark-mode        # run the planning gates
specd approve add-dark-mode --approver you --reason "plan reviewed"
specd next add-dark-mode         # the ready frontier
specd context add-dark-mode T1   # the bounded read context for one task
specd start add-dark-mode T1 --revision 2      # bind a baseline, open the attempt
# edit only the files that task declares
specd verify add-dark-mode T1 <attempt>        # record evidence at current HEAD
specd complete add-dark-mode T1 --revision 3   # consume the evidence, close the task
specd sync add-dark-mode --approver you --reason "behavior accepted"
specd archive add-dark-mode

start and complete take the revision you observed from status: if the change moved underneath you, they refuse instead of acting on stale state. verify takes the attempt id start returned.

Commands

Every flag, exit code, and allowed lifecycle lives in docs/operations.md, which is generated from the operation registry and byte-checked against it by the release gate. It is the source of truth; nothing else restates a flag.

Add --json to any operation for the stable machine-readable envelope an agent reads.

specd --help prints this palette from the same registry, and specd --version reports the build. Neither is an operation: they resolve no root and write nothing.

Documentation

Start at docs/.

What it guarantees

• Evidence is not completion. verify records an observation pinned to current HEAD. complete is a separate harness-owned transition that consumes applicable passing evidence. No free-text claim closes a task.
• An agent cannot approve its own plan. Approval is a human act, and editing an approved artifact makes the approval stale.
• Declared scope is enforced. A task names the files it may touch; a diff outside them is refused. Git-ignored files count, deliberately.
• State is harness-owned. .specd/ state, history, evidence, and task markers are written atomically with revision guards and are never hand-edited.
• Refusals are actionable. Every refusal fails closed and carries exactly one legal next action.
• No LLM and no network in any validation, state, graph, evidence, or report path.

Repository layout

Contributing

go test ./... -race -count=1
go vet ./...
gofmt -l .

Standard library only — go.mod having an empty require set is a release gate. Full guide: docs/contributing.md and CONTRIBUTING.md. Read AGENTS.md before changing anything, and release/surface-inventory.md before adding a surface: every exported symbol maps to one journey or one invariant, and unowned surface fails the build.

License

MIT. See LICENSE.