{"id":"1f56b94d-0826-4d01-8b29-24a3c8020bfe","slug":"sdd-harness","kind":"mcp","name":"sdd-harness","summary":"A spec-driven development harness for coding agents: instruction layering, a documentation model, risk-matched review, and the gates that keep them honest.","owner":"sebas8824","repoUrl":"https://github.com/sebas8824/sdd-harness","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-24T04:34:44.000Z","addedAt":"2026-10-21T09:34:03.356Z","logoUrl":"https://avatars.githubusercontent.com/u/3869490?u=1618c8cc6d8a50246ec274e01c5f4db017fdb149&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing","developer-tools"],"tags":["adr","ai-agents","claude-code","developer-tools","documentation","spec-driven-development"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T00:31:07.899Z","sample":false,"url":"https://conduits.dev/tools/sdd-harness","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# sdd-harness\n\nA **spec-driven development harness for coding agents** — the instruction layering, documentation\nmodel, review orchestration, and enforcement gates that let an agent work on a real codebase over\nmonths without re-deriving the project every session.\n\nIt is not a framework and it is not tied to a language or a stack. It is a **repository shape**: a\nset of files an agent reads, a set of documents it writes, and a set of gates that fail the build\nwhen either drifts.\n\n> **Why it exists.** Agents forget. Sessions end, context windows compact, and the reasoning behind\n> a decision leaves with them. Every piece of this harness exists to move something out of a session\n> and into a file that outlives it — a decision into an ADR, a punt into a targeted row, a repeated\n> correction into a rule, a half-finished feature into a handoff.\n\n---\n\n## The shape in one diagram\n\n```mermaid\nflowchart TD\n    subgraph always[\"Always loaded — every session, every agent\"]\n        agents[\"AGENTS.md<br/>thin index: invariants, gates,<br/>working agreements\"]\n        claude[\"CLAUDE.md → @AGENTS.md\"]\n    end\n\n    subgraph ondemand[\"Loaded on demand\"]\n        skills[\".claude/skills/<br/>craft + project rules\"]\n        roles[\".claude/agents/<br/>reviewer role prompts\"]\n        docs[\"docs/**<br/>specs · ADRs · roadmap · architecture\"]\n        tasks[\"tasks/**<br/>plan · todo · handoff\"]\n    end\n\n    subgraph gates[\"Enforcement — fails the build, not the reviewer's patience\"]\n        hooks[\".githooks/ + .github/workflows/<br/>sensitive-paths · skills-sync\"]\n    end\n\n    agents --> skills\n    agents --> docs\n    claude --> agents\n    docs --> tasks\n    skills --> roles\n    hooks -. governs .-> agents\n    hooks -. governs .-> skills\n```\n\nThe rule that keeps it cheap: **`AGENTS.md` holds only what no gate can catch** — rules whose failure\nis silent and corrupting. Everything a gate already enforces, plus all examples and rationale, lives\nin a skill loaded on demand. A redundant always-loaded reminder costs tokens on every single turn.\n\n---\n\n## What is in here\n\n| Path | What it is |\n|------|-----------|\n| [`AGENTS.md`](AGENTS.md) | The always-loaded instruction file, as a fill-in template. Canonical for **every** harness. |\n| [`CLAUDE.md`](CLAUDE.md) | A one-line pointer to `AGENTS.md`. Never a second source of truth. |\n| [`docs/HARNESS.md`](docs/HARNESS.md) | The harness structure, file by file, and why each layer exists. |\n| [`docs/DOCUMENTATION-MODEL.md`](docs/DOCUMENTATION-MODEL.md) | Where each kind of documentation lives and the exact format of each. |\n| [`docs/WORKFLOW.md`](docs/WORKFLOW.md) | The `/spec → /plan → /build → /test → /review → /ship` lifecycle and the review orchestration around it. |\n| [`docs/TOOLS.md`](docs/TOOLS.md) | The tools this harness runs on: Agent Skills, code-review-graph, rtk, MCP servers, hooks. |\n| [`docs/ADOPTING.md`](docs/ADOPTING.md) | Installing the harness into an existing repository, in order. |\n| [`templates/`](templates/) | Copy-ready templates: spec, ADR, plan, todo, handoff, roadmap, deferred, lessons, project, session start. |\n| [`.claude/skills/`](.claude/skills/) | Portable skills authored here, plus the two project-owned stubs every adopter fills in. |\n| [`.claude/agents/`](.claude/agents/) | Reviewer role prompts, written to be readable by any harness — not just Claude Code. |\n| [`.githooks/`](.githooks/) + [`.github/workflows/`](.github/workflows/) | The gates: sensitive-paths ADR policy and cross-harness skill sync. |\n\n---\n\n## Quick start\n\n```bash\ngit clone https://github.com/<you>/sdd-harness\ncd your-project\n\n# 1. The instruction layer\ncp ../sdd-harness/AGENTS.md ../sdd-harness/CLAUDE.md .\n$EDITOR AGENTS.md              # fill in the invariants and gates for YOUR project\n\n# 2. The documentation model\nmkdir -p docs/architecture/adr docs/specs docs/session tasks\ncp ../sdd-harness/templates/adr-0000-template.md docs/architecture/adr/0000-template.md\ncp ../sdd-harness/templates/{ROADMAP,DEFERRED,LESSONS,PROJECT}.md docs/\ncp ../sdd-harness/templates/SENSITIVE-PATHS.md docs/architecture/adr/\n\n# 3. The gates\ncp -R ../sdd-harness/.githooks .\ncp ../sdd-harness/.github/workflows/config-policy.yml .github/workflows/\ngit config core.hooksPath .githooks\n\n# 4. The agent layer\ncp -R ../sdd-harness/.claude .\n```\n\nThen read [`docs/ADOPTING.md`](docs/ADOPTING.md) — it walks the same four steps with the decisions\neach one asks of you.\n\n---\n\n## The five ideas this harness is made of\n\n**1. One canonical instruction file, read by every agent.**\n`AGENTS.md` is canonical; `CLAUDE.md` (and any other harness's file) is a pointer to it. Two\ninstruction files means two agents enforcing two versions of the same rule, with nothing reporting\nthe divergence.\n\n**2. Documentation is layered by lifetime, not by topic.**\nA decision that must outlive the code goes in an **ADR**. A feature's intent goes in a **spec**. The\nsequencing goes in a **plan** and a **todo**. What a cold agent needs to resume goes in a **handoff**.\nWhat was punted goes in **DEFERRED.md** *with a target*. What went procedurally wrong goes in\n**LESSONS.md**. Nothing lives in two places, and everything cross-links by id.\n\n**3. Rules earn their place by what a gate cannot catch.**\nFormatting is a gate, so it is not a rule in the prompt. \"Never read back what you just wrote\" is not\nmechanically checkable, so it is. This is the only thing keeping an always-loaded file from growing\ninto a context tax.\n\n**4. Review is risk-matched and independent, never a rubber stamp.**\nOne writer at a time, then an independent reviewer selected by a risk matrix. Findings are verified\nagainst source before they are acted on; a fix owes the same red-green proof as any other change.\n\n**5. Verification is a run, not a claim.**\n\"Tests pass\" means the command was executed and its output read. An incremental build is not a\nverification. A green suite is not evidence that a new test bites — remove the behaviour, watch it\nfail, restore it.\n\n---\n\n## Author\n\n**Sebastián Benítez** ([@sebas8824](https://github.com/sebas8824)) — author and maintainer.\n\nBuilt from a real multi-service codebase, then stripped of everything specific to it.\n\n## Credits\n\nThe SDD lifecycle commands and the general engineering craft skills come from\n**[Addy Osmani's Agent Skills](https://github.com/addyosmani/agent-skills)** (MIT), adopted as an\n**installed dependency** rather than vendored. This harness is the layer *around* it: the repository\ncontract, the documentation model, the review orchestration, and the gates. See\n[`docs/TOOLS.md`](docs/TOOLS.md) for installation.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n"}