specd

specd — Spec-Driven Coding Harness

specd is an agent-agnostic, spec-driven coding harness CLI. It fuses a structured spec workflow (requirements → design → tasks → evidence-gated execution) with a rigid thinking discipline for AI coding agents.

By defining clear phase transitions and validating structural correctness with deterministic gates, specd shifts the burden of process enforcement from the LLM's non-deterministic context to a strict, local, tool-gated pipeline.

The agent reasons. The harness enforces.

Key Features

• 🔄 Strict Planning Ratchet: Enforces human-approved phase gates (Analyze → Plan → Execute → Verify → Reflect).
• 🛡️ Validation Gates: Programmatic checks (specd check) — 7 core gates (EARS syntax, design completeness, task schema, acyclic DAG, evidence, sync, traceability) plus opt-in acceptance, scope, and external custom gates.
• 📉 DAG-Based Task Execution: Computes the concurrent runnable frontier of waves so agents only work on tasks whose dependencies are fully resolved.
• 💾 Evidence-Gated Completion: specd verify runs the task's own verify: command and records the exit code + git HEAD. A task completes only against a passing record — never on a free-text claim alone.
• 🔒 Sandboxed Verify & Rollback: Run verify: under bwrap/container isolation (fail-closed if absent) and optionally stash the working tree on failure (--revert-on-fail).
• 🚦 Frontier Dispatch & Cross-Spec DAG: specd next --dispatch emits ready-to-run packets (role prompt + contract + verify) for parallel subagents; specd status --program resolves which whole specs are runnable across a multi-spec program.
• 🔌 Agent-Agnostic + MCP auto-setup: Teaches any command-running agent via a localized prompt pack, or drives the workflow from any MCP client via stdio (specd mcp) or HTTP/SSE (specd mcp --http). specd init --agent auto detects supported coding agents and installs project-scoped MCP registration for you — managed adapters for claude-code, codex, cursor, antigravity, and vscode (host-native CLI or a safe JSON merge), plus deterministic --config snippets for claude-desktop. .agents/ is intentionally VCS-tracked so Antigravity config stays in repo. specd init --repair verifies the integration end to end.
• 📊 Deterministic Reporting & Live Views: Markdown / self-contained HTML reports, a read-only dashboard (specd report --serve), a frontier event stream (specd report --watch over NDJSON/SSE/webhook), and a network-free PR summary (specd report --pr-summary) — no LLM dependency.
• 🧰 Format, Packs & History: A versioned JSON Schema (specd check --schema / specd check --schema-only), shareable scaffold bundles (specd init --pack), and read-only report history / spec comparison views.

Core Philosophy

specd is built on eight core principles designed to make AI software engineering reliable, structured, and predictable:

1. The Foundational Split: The agent does the creative thinking; the harness enforces process integrity.
2. Specs as the Source of Truth: The active plan lives as versioned Markdown on disk, not floating in the LLM's context window.
3. Evidence Gates Every State Change: Trust is recorded, not assumed. Status changes require verifiable proof.
4. Waves, Not Lines: Work is structured as a Directed Acyclic Graph (DAG) of concurrent batches (waves) rather than flat todo lists.
5. Agent-Agnostic by Design: Standardized command interface integrated via role prompt injection.
6. Human Gates at Phase Boundaries: Semantic transitions require explicit human approval (specd approve).
7. Deterministic Reporting: Reports are generated programmatically from state.json and artifact files.
8. Steering as Constitution: Durable steering files outlive individual chat sessions.

Installation

Quick Install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/0xkhdr/specd/main/scripts/install.sh | bash

With Options

# Force reinstall
curl -fsSL https://raw.githubusercontent.com/0xkhdr/specd/main/scripts/install.sh | bash -s -- --force

# Install specific version
curl -fsSL https://raw.githubusercontent.com/0xkhdr/specd/main/scripts/install.sh | bash -s -- --version 0.1.0

Uninstall

install.sh places a single binary with no separate install directory, so removal is manual:

rm -f ~/.local/bin/specd

If you no longer need ~/.local/bin on your PATH, also remove the # specd-tagged export PATH=... line install.sh added to ~/.bashrc, ~/.zshrc, or ~/.profile (whichever your shell uses).

Update

curl -fsSL https://raw.githubusercontent.com/0xkhdr/specd/main/scripts/install.sh | bash -s -- --force

Requirements

• Linux, macOS, or Windows (amd64 / arm64)
  • Windows note: Windows users should reinstall with the installer command above instead of relying on in-place binary replacement. Task execution verification requires a bash-like environment (like sh or bash from Git for Windows) in the PATH since execution commands are invoked with -c. Brain/Pinky worker orchestration is POSIX-only on Windows and fails fast with: orchestration requires a POSIX shell (sh); not supported on Windows — run under WSL.
• Git (optional — tarball fallback available)

For Agents

specd is designed to be fully drivable by AI agents:

• Set SPECD_JSON=1 to receive structured JSON output for all commands.
• Use specd help --json to discover the full command schema programmatically.
• All state mutations are atomic and versioned — safe for concurrent agent access.
• Exit codes are deterministic: 0=ok, 1=validation, 2=usage, 3=not found.

Quick Start

Golden path: install → init → ask your agent

After installing, the fastest path from a fresh repo to an agent driving specd is one command:

cd <your-project>
specd init --agent auto

specd init --agent auto does four things in order:

1. Scaffolds .specd/ (roles, steering, skills, config.json) and merges AGENTS.md — idempotent and atomic; a rerun on a healthy project changes no bytes.
2. Detects supported coding agents on your machine (executable + project config).
3. Configures project-scoped MCP for the detected agent — preferring the host's own CLI (claude mcp add --scope project) or a safe JSON merge that preserves your other servers. Antigravity writes directly to .agents/mcp_config.json, and .agents/ is intentionally tracked in VCS so host config stays with the repo. Project scope is the default; global config is never touched without --scope global and explicit consent.
4. Verifies the integration with an in-process MCP handshake + tools/list, then prints one next action.

[!NOTE] Restart or reload your coding agent / IDE to pick up MCP configuration.

Then just ask your agent:

"Read specd context and help me create a spec for <feature>."

Explicit / scripted (works non-interactively, no prompts):

specd init --agent claude-code --yes      # configure one named host
specd init --agent all --yes              # configure every detected host
specd init --agent codex --dry-run --json # preview exact mutations, write nothing
specd init --agent none                   # scaffold only, no host config
specd init --agent auto --orchestration session --yes # bootstrap full autonomy from day one

--agent auto configures a host automatically only when exactly one is detected in an interactive terminal. In CI / non-TTY, or when several hosts are detected, auto scaffolds and reports suggested host actions instead of mutating anything.

Check / repair an existing setup:

specd init --repair                  # scaffold + MCP server + host registration health
specd init --repair            # safe, project-scoped, specd-owned repairs only
specd init --repair           # restore missing managed files (keeps your edits)

Air-gapped / manual (no host CLI, or you prefer to paste config yourself):

specd init --agent none
specd mcp --config claude-code   # print a ready-to-merge snippet for the host

See docs/user-guide.md for the full onboarding guide, docs/mcp-guide.md for host details and trust boundaries, and docs/troubleshooting.md for scaffold and MCP remediation.

Creating and Running a Spec

1. Start a new spec:

   specd new my-feature --title "Implement Feature X"
   

2. Author Requirements: Open .specd/specs/my-feature/requirements.md and document requirements in EARS format. Validate and approve:

   specd check my-feature
   specd approve my-feature # Advances spec status from 'requirements' to 'design'
   

3. Create Design: Fill out .specd/specs/my-feature/design.md covering all mandatory sections. Approve:

   specd approve my-feature # Advances spec status from 'design' to 'tasks'
   

4. Decompose into Tasks: Author the task list under .specd/specs/my-feature/tasks.md defining dependency waves. Approve:

   specd approve my-feature # Advances spec status from 'tasks' to 'executing'
   

5. Execute Tasks: Get the next runnable task from the frontier, implement it, then let specd run the task's verify: command itself and record the result. A task can only complete on a passing verify record — not a free-text claim:

   specd next my-feature
   # [Implement the changes...]
   specd verify my-feature T1                  # specd runs the task's verify: command, records exit code + git HEAD
   specd task my-feature T1 --status complete   # allowed only because the verify record passed (exit 0)
   

   Read-only roles (scout/auditor) whose verify is N/A complete with the manual escape hatch: specd task my-feature T1 --status complete --unverified --evidence "<proof>".
6. Final Verification: Once all tasks are complete, run final checks and sign off:

   specd approve my-feature # Closes the spec, promoting learnings and generating final reports
   

Repository & Documentation Map

.
├── README.md               # This overview guide
├── AGENTS.md               # Workflow guide for AI agents working on the specd repo itself
├── TESTING.md              # Deterministic test-harness guide
└── docs/                   # Detailed documentation
    ├── README.md              # Documentation index / navigation
    ├── concepts.md            # Philosophy, the eight principles, architecture
    ├── user-guide.md          # Install, lifecycle, artifacts, execution, troubleshooting
    ├── command-reference.md   # Every command, flag, exit code, env var, config key
    ├── validation-gates.md    # What each gate checks (7 core + acceptance/scope/custom)
    ├── agent-integration.md   # Steering, roles, subagent modes, context, programs
    ├── custom-gates.md        # External custom-gate subprocess contract
    ├── spec-packs.md          # Declarative scaffold bundles (specd init --pack)
    ├── open-spec-format.md    # The versioned open spec format JSON Schema
    ├── github-action.md       # PR gates + deterministic summary comment
    └── contributor-guide.md   # CLI architecture, concurrency model, extension recipes

Quick Links:

• 💡 Concepts — The foundational split, eight principles, architecture overview.
• 📖 User Guide — Getting started, EARS requirements, design headers, task DAG, the verify → complete flow.
• 📑 Command Reference — Commands, flags, exit codes, environment variables, and config.json.
• ✅ Validation Gates — The 7 core gates plus the opt-in acceptance, scope, and custom gates.
• 🤖 Agent Integration Guide — Roles, steering files, subagent modes, context engineering, cross-spec programs.
• 🧩 Custom Gates · 📦 Spec Packs · 📐 Open Spec Format · 🐙 GitHub Action
• 🛠️ Contributor Guide — Codebase architecture, the concurrency model (advisory lock + CAS), parser internals, adding commands/gates.

License

This project is licensed under the MIT License - see the LICENSE file for details.