Spec-driven development (SDD) for Claude Code, OpenCode, and Codex CLI — distributed to every repo via one GitHub Action.
You install once with a single preset, then start every session with /sdd. The harness picks a mode, dispatches the right agents in parallel waves, and stops at human gates so you stay in control.
A four-layer distribution that installs into your repo:
- Layer 1 — OpenSpec: the upstream SDD framework
- Layer 2 — Forge baseline: the contract synced everywhere (AGENTS.md sections, 7
forge:*skills, agents, rules, schemas) — undersrc/ - Layer 3 — Repo profiles: optional
frontend/backend-api/brownfield/high-riskoverlays - Layer 4 — Plugins: opt-in extras (memory, live docs, LSP, Playwright, browser, statusline, semantic search, animation skills) — under
plugins/
Same install pipeline runs from the GitHub Action and from a Python CLI on your laptop. No build step, no node, no make.
One picture first — where the harness sits in the full software cycle, and what a /sdd run looks like from "decide the work" to "feedback starts the next cycle". Amber diamonds are human gates the harness cannot skip; blue boxes are work the harness does for you:
Every session starts with /sdd — pick one mode:
| Mode | When | Output |
|---|---|---|
| 1 Simple | tiny change, ≤ 5 tasks | fast path, 2 commits |
| 2 Plan + implement | normal feature | research → plan → 📋 gate → impl waves → tests → ✅ gate → archive |
| 3 Implement existing plan | tasks.md already approved | skip planning |
| 4 Research | answer a question, no code | research.md |
| 5 Bugfix | single-domain fix | minimal scope |
| 6 / 6b Bootstrap | first install | greenfield (PRD) or brownfield (audit) |
| 7 Bugfix-PR | PR has Codacy / Copilot findings | classified + dispatched per finding |
/sdd gc cleans up stale change folders and trace logs.
"/sdd" → mode 2 → "add a /metrics endpoint with prometheus output"
→ researcher checks prom_client docs via context7
→ planner writes proposal.md + design.md + tasks.md
→ 📋 approval gate → you say go
→ backend + tester-back wave runs in parallel (TDD)
→ validator scores 6 criteria × /18 with hard-fail thresholds
→ ✅ approval gate → you confirm manual test passes
→ github-ops commits plan / impl / test / archive
"/sdd" → mode 5 → "the date picker breaks on Safari iOS 17"
→ frontend agent reproduces, isolates regression
→ minimal patch, single commit, no full plan flow
"/sdd" → mode 7 → "PR #482 has 3 Codacy critical issues"
→ bugfix-pr classifies each finding by domain
→ posts a PR comment with the plan
→ dispatches the right specialist (frontend / backend / db)
"/sdd" → mode 4 → "should we use TanStack Query or SWR?"
→ researcher does multi-hop investigation
→ context7 pulls both libraries' current docs
→ outputs research.md with evidence-backed recommendation
Whether you install from CI or from your laptop, the same Python pipeline runs — it wipes and rebuilds the harness-owned trees, merges your instruction files non-destructively, and leaves everything else alone. For coordination hubs it also fans out into the member repos:
gh workflow run sdd-sync-targeted.yml -f repos="my-org/my-repo" -f preset="solo"That's it. Pick the preset that matches the repo:
solo— a single self-contained repo.coordination-hub— an orchestrator over child repos. Locally this also installs into everyrepos:member from the hub'sopenspec/config.yamlthat exists on disk, so one command installs or updates hub + members. (In CI the members aren't checked out, so they're skipped with a warning.)member-repo— a FE/BE child installed on its own; addrepo_role: frontend|backendsince the preset can't infer which one.
Add -f dry_run="true" to preview. Walkthrough: docs/UPGRADE-v2.md.
For when you're offline, on Windows, or just don't want a PR. Pure Python ≥ 3.11.
git clone https://github.com/iNBest-cloud/inbest-sdd-cycle
cd inbest-sdd-cycle
pip install -e .[interactive]
python -m installer install --target-root /path/to/your/repoA 7-step wizard prompts you for tools, role, profile, and optional plugins, then installs. If you pick the coordination role and the repo has a repos: map, it lists the members it found and asks before installing into them too.
The local install does not commit — review with git status and commit yourself when ready.
CI / scripted / containerized install: see docs/INSTALL-CI.md.
Memory backend (Engram) is required for cross-session memory. One-time per-machine install: src/agent_docs/engram-install.md. Wired into target repos via the opt-in
engramplugin.Memory budget (token-optimization, W1-W9): agents follow a tier system — 5 mechanical agents (validator, tester-*, github-ops, agent-sync) are save-only; 8 specialist agents (planner, researcher, frontend, backend, database, agent-prep, devstart, bugfix-pr) are search-capable but bounded by a per-turn budget (max 2
mem_search, max 1 L3 fetch, max 1200 mem-tokens injected). The orchestrator pre-resolves memory cards once per dispatch and passes them asengram_context: [...]in the subagent briefing. Full contract: src/agent_docs/memory-budget.md.
The harness is itself spec-driven. Two ways to contribute:
- Category A — code change (new agent, schema field, installer behavior): edit under
src//installer/, run the full gate suite, open a PR. - Category B — drop-in plugin (new MCP server, skill bundle, settings patch): add
plugins/<your-id>/plugin.json(+ optional fragments). Zero installer code change required.
Full contributor flow, ASCII tree, and a worked example: docs/CONTRIBUTING-CONTENT.md.
Before any merge, run the gates locally:
python -m installer validate # 5-gate src/ + plugins/ consistency
python -m installer generate-manifest --check
python -m pytest installer/tests/ # ~178 tests
bash scripts/check-no-inbest.sh # no stale brand refsThe same gates run in CI on every PR.
The installer ships a default plugin set that installs when --plugins is unset (or passed as an empty string from action.yml). Pass --plugins <explicit,list> to install exactly that list instead.
Default plugin set:
| Plugin | Status | Adds |
|---|---|---|
engram |
ready | Persistent memory MCP |
context7 |
ready | Live library docs MCP |
agent-browser |
ready | Chrome DevTools MCP (lightweight web research) |
rtk |
ready | Tool-I/O compression via advisory Bash PreToolUse hook (60–90% token reduction on covered commands; user installs the rtk binary, then rtk init -g for automatic rewriting) |
Opt-in / community plugins:
| Plugin | Status | Adds |
|---|---|---|
lsp |
ready | LSP bridge MCP + forge:lsp-explore skill |
playwright-bridge |
ready | Official Playwright MCP for E2E tests |
ccstatusline |
ready | Claude Code statusline widget |
gsap |
stub | GSAP animation skill bundle (future) |
Authoring contract: plugins/README.md. Install-ownership matrix: docs/OWNERSHIP.md.
The harness fails closed when you do something risky:
| Gate | What it stops |
|---|---|
| Branch (B1) | Writing code on main or a wrongly-named branch. Forces feat/<change>. |
| Lint scope (B3) | eslint --fix . rewriting 200 unrelated files. |
| Cycle counter (B4) | An agent retrying forever. Hard-stops at 3 attempts per (change, role). |
| Validator hard-fails (C5) | Shipping a 17/21 with code_quality=0. Any of the 7 criteria below threshold → FAIL. Total scorecard is now /21 (was /18 pre-W3 of feat/forge-token-cascade-refactor). |
| Pre-PR Codacy (B5) | Opening a PR with Codacy severity: critical issues unresolved. |
| Validation-cascade cap (D-CASCADE) | A validation step (pnpm test, eslint, prettier --check, …) cascading through pnpm install / symlink probes / full-monorepo re-runs. Hard-blocks the 2nd cascade Bash call after a failed validation OR a banned mid-wave pattern. Worst pre-W3 trace: 50min / 52.6M tokens / depth 5+. |
| Dispatch envelope (A-ENV) | Subagents dispatched without explicit goal: + already_read_files: [...] headers. Honor-system + validator audit; cuts re-Read storms (SWE-Pruner research: 23-54% token reduction). |
| Test proportionality | 12 tests for a /health endpoint. Caps tests to scope. |
Detail in docs/HARNESS-GUIDE.md.
Start here:
- docs/UPGRADE-v2.md — install + verify in plain language
- docs/HARNESS-GUIDE.md — current-state structure, flows, use cases
- docs/INSTALL-CI.md — non-interactive install reference
Migration:
- docs/MIGRATION-v2.md — audit-v2 changes (preset model, mode renumbering)
- docs/MIGRATION-forge.md — re-sync a target repo from the pre-v3 layout
Reference:
- docs/SDD-DEV-SUITE.md — agent team detail
- docs/GOVERNANCE.md — escalation triggers
- docs/OWNERSHIP.md — what the harness owns vs what you own
- docs/CONTRIBUTING-CONTENT.md — adding content (Category A vs B)
- plugins/README.md — plugin authoring contract
- STRUCTURE.md — repo layout contract
MIT