{
  "markdown": "<h1 align=\"center\">sdd-flow</h1>\n\n<p align=\"center\">\n  <strong>Spec-Driven Development orchestration for AI coding agents.</strong><br>\n  <em>Turns a feature prompt into a disciplined init → design+tasks → implement → verify pipeline, enforced by cold-context subagents.</em>\n</p>\n\n<p align=\"center\">\n  <code>Agent Skills pack</code> · <a href=\"https://agentskills.io\">agentskills.io</a>-compliant · zero runtime dependency, zero MCP server\n</p>\n\n<p align=\"center\">\n  <a href=\"#overview\">Overview</a> &bull;\n  <a href=\"#install\">Install</a> &bull;\n  <a href=\"#sdd-lifecycle\">SDD Lifecycle</a> &bull;\n  <a href=\"#skills--subagents\">Skills & Subagents</a> &bull;\n  <a href=\"#configuration--rules-sync\">Configuration</a> &bull;\n  <a href=\"#faq\">FAQ</a>\n</p>\n\n---\n\n## Overview\n\n> **spec-driven development** — no code is written until scope, design, and tasks are confirmed\n> on disk. Every phase is a separate subagent, cold-started, reading only the artifact it needs.\n\nAn agent that goes straight from prompt to code skips architecture, invents scope as it goes, and\nproduces a diff nobody reviewed against a plan. sdd-flow fixes this by turning the SDD lifecycle\ninto disk artifacts under `.spec/<feature-slug>/` and a fixed sequence of subagent hand-offs —\neach one starts with **no memory of the conversation**, forcing every decision to be written down\nbefore the next phase can act on it.\n\nsdd-flow is **not** an MCP server and depends on **no external \"skills engine.\"** It ships two\nplain artifact types that any agent harness can read directly off disk:\n\n- **Skills** (`skills/<name>/SKILL.md`) — orchestrator + standards, `agentskills.io`-compliant frontmatter.\n- **Subagent prompts** (`agents/<name>.md`) — the five roles, plain markdown with `name`+`description` frontmatter.\n\n`.mcp.json` ships as `{\"mcpServers\": {}}` — an empty placeholder. There is no process to spawn, no\n`command`/`args`/`env`, nothing running between sessions. The orchestrator, Init, Tech Lead,\nDeveloper, and Verifier are **prompt roles**, not tool calls.\n\n```\nAgent (Claude Code · Gemini CLI · Codex · Cursor · Opencode · Kilo · ...)\n    │ reads skills/*/SKILL.md + agents/*.md directly off disk\n    ▼\nsdd skill (Orchestrator) ──delegates──► sdd-init / sdd-tech-lead / sdd-developer / sdd-verifier\n    │                                        (cold-context subagents, one phase each)\n    ▼\nWorkspace:  .spec/<feature-slug>/{scope,design,tasks/,verify}.md   +   git commits   +   PR\n```\n\n- **Sequential tasks** — one developer at a time, one commit per task.\n- **PR-only** — the Verifier opens a pull request on PASS. Never auto-merges.\n- **Convention-first** — `AGENTS.md` is law; a user-provided precondition, read by every agent, never created or edited by sdd-flow.\n- **Token-friendly** — Orchestrator stays thin, subagents read only what they need, Tech Lead curates per-task context so devs don't grep blindly.\n\n---\n\n## Install\n\n### Claude Code\n\n```\n/plugin marketplace add nushey/sdd-flow\n/plugin install sdd-flow@sdd-flow\n```\n\nRestart Claude Code. The `sdd` skill and five subagents register automatically — \"registration\"\nmeans the plugin loader indexes `skills/` and `agents/` from the installed plugin directory; there\nis no separate config file to edit.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/nushey/sdd-flow\n```\n\n*(Or point to a local checkout: `gemini extensions install ./sdd-flow`)*\n\n### Any other client (Codex, Opencode, Kilo, Cursor, Windsurf/Devin Desktop, Antigravity)\n\nsdd-flow is harness-neutral Agent Skills — any client that reads `.agents/skills/` picks it up\nwith **one command**:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/nushey/sdd-flow/main/scripts/install.sh \\\n  | bash -s -- --client <codex|opencode|kilo|cursor|windsurf|antigravity>\n```\n\nWindows: `scripts/install.ps1 -Client <client>`. Per-client install locations, native\nalternatives, and limitations (Windsurf/Antigravity have no subagent isolation) →\n**[INSTALL.md](./INSTALL.md)**.\n\n### Prerequisites (all clients)\n\n- Your project **must have an `AGENTS.md`** at the root. sdd-flow treats it as law and never\n  creates or scaffolds it — that is on you.\n- **Git + GitHub CLI (`gh`)**, authenticated (`gh auth login`) — the Verifier opens PRs with it.\n\n### Setup FAQ\n\n> **Is sdd-flow an MCP server I need to start or keep running?**\n> No. There is no server, no process, no port. `.mcp.json` is an intentionally empty placeholder.\n> The skills and subagent prompts are read directly off disk by whatever harness you're using.\n\n> **Where does sdd-flow \"register\" itself — is there a config/registry file?**\n> No `.skillsconfig`, no `sdd-flow.json`. Claude Code and Gemini CLI use their own plugin/extension\n> loaders (`.claude-plugin/`, `gemini-extension.json`); every other client just needs the `skills/`\n> and `agents/` folders copied into the directory it already scans (`.agents/skills/`,\n> `.codex/agents/`, etc. — see [INSTALL.md](./INSTALL.md)).\n\n> **Do I need to write my own `AGENTS.md`?**\n> Yes, before running SDD. It's the single source of truth every subagent reads for domain\n> terminology, conventions, and constraints. sdd-flow fails fast (`Status: FAIL — AGENTS.md\n> missing`) rather than inventing or scaffolding one.\n\n---\n\n## SDD Lifecycle\n\n### Full SDD\n\n```\n/sdd Add OAuth login with Google\n```\n\nBest for big features, complex refactors, and changes that need architectural validation and\ncontext isolation between phases.\n\n0. **Triage** (Orchestrator) — asks clarifying questions about scope, PR target branch, and\n   Reference Files (Gold Standards) when the architecture is flexible. Writes `intake.md`.\n1. **Init & Scope** — `sdd-init` verifies `AGENTS.md` is present (precondition, never created),\n   confirms Reference Files exist, and refines `intake.md` into `scope.md` — business intent,\n   observable acceptance criteria, style references.\n2. **Design + Tasks** — `sdd-tech-lead` writes `design.md` (feature-level, no file lists),\n   `tasks.index.md`, and one atomic task file per unit of work, each with its own Reference Files\n   for strict style matching.\n3. **Implement** — `sdd-developer` runs once per task: reads the task + `design.md` + curated\n   context only, implements, commits with conventional commits, fills the Implementation log.\n   One task = one commit.\n4. **Verify** — `sdd-verifier` cross-checks Implementation logs against actual git history, runs\n   tests, reviews architectural fidelity, and opens a PR via `gh pr create` on PASS. Never merges.\n\nAll artifacts live under `.spec/<feature-slug>/`. Re-running `/sdd <slug>` on an existing slug\nresumes where it left off — nothing restarts from zero.\n\n### Mini-SDD\n\n```\n/mini-sdd Fix the typo in the header and update the styles\n```\n\nBest for small fixes/refactors where the full 5-phase flow is overkill. Planning (`mini-sdd-planner`\nskill) runs directly in the Orchestrator; only implementation is delegated — to a single\n`mini-sdd-developer` subagent, cold-started so it loads the Bootstrap (skills + MCP calls) declared\nin `plan.md` before writing any code.\n\n### Failure behavior (both flows)\n\n- Max 3 failure cycles per feature.\n- On failure, the Tech Lead (Full SDD) or the plan (Mini-SDD) produces a **fix task** under\n  `fixes/` — `design.md` stays as-is, the loop doesn't redesign from scratch.\n- A fundamental design gap stops the loop and escalates to the user — sdd-flow does not force a\n  4th cycle on a broken plan.\n- Nothing is pushed until the Verifier passes. On final failure, fix commits stay on the local\n  feature branch; you decide what to do with them.\n\n---\n\n## Skills & Subagents\n\n| Name | Type | Invocation | Purpose |\n|------|------|------------|---------|\n| `sdd` | Skill | `/sdd <feature>` | Orchestrator — triages, writes `.spec/` artifacts, delegates each phase |\n| `mini-sdd` | Skill | `/mini-sdd <change>` | Leaner flow: planning in-orchestrator, one delegated developer subagent |\n| `mini-sdd-planner` | Skill | loaded by `mini-sdd` | Merges Init + Tech Lead into a single `plan.md` for small changes |\n| `pr-creation` | Skill | loaded by the Verifier | PR body standard — value-oriented, minimal technical noise |\n| `writing-skill` | Skill | loaded when a plan/task declares it | Standard for structured technical documentation |\n| `sdd-init` | Subagent | delegated, Phase 1 | Verifies `AGENTS.md`, refines `intake.md` → `scope.md` |\n| `sdd-tech-lead` | Subagent | delegated, Phase 2 + failure recovery | Writes `design.md`, `tasks.index.md`, task files; produces fix tasks on failure |\n| `sdd-developer` | Subagent | delegated once per task | Implements exactly one task, commits, fills Implementation log |\n| `sdd-verifier` | Subagent | delegated, Phase 4 | Runs tests, cross-checks logs vs. git, opens PR on PASS |\n| `mini-sdd-developer` | Subagent | delegated by Mini-SDD | Cold-context implementer for a Mini-SDD `plan.md`; executes all tasks, commits, reports back |\n\nFull prompt bodies live at `skills/<name>/SKILL.md` and `agents/<name>.md` — read them directly,\nthere is no compiled/hidden variant.\n\n### Artifacts (`.spec/<feature-slug>/`)\n\n```\n.spec/<feature-slug>/\n├── intake.md          # Orchestrator's grilling output (Phase 0)\n├── scope.md            # sdd-init's refined contract (Phase 1)\n├── design.md            # sdd-tech-lead's technical design (Phase 2)\n├── tasks.index.md        # ordered task list\n├── tasks/<n>-<slug>.md    # one atomic task per file, incl. Implementation log\n├── fixes/<n>-<slug>.md    # fix tasks emitted on failure recovery\n└── verify.md              # sdd-verifier's PASS/FAIL report (Phase 4)\n```\n\n---\n\n## Configuration & Rules Sync\n\nsdd-flow has **no plugin-specific config file** — no `.skillsconfig`, no `sdd-flow.json`. The only\nconfiguration surface is what your agent harness already reads:\n\n| Surface | Owned by | Role |\n|---------|----------|------|\n| `AGENTS.md` (project root) | You (user-provided precondition) | Domain terminology, conventions, hard architecture rules — every subagent treats it as law |\n| `CLAUDE.md` (optional) | You | Read alongside `AGENTS.md` when present; same authority |\n| `skills/<name>/SKILL.md` | sdd-flow | Orchestrator + standards prompts — edit only if you're forking the flow itself |\n| `agents/<name>.md` | sdd-flow | Canonical subagent prompts — single source of truth; per-client adapters (Codex TOML, Opencode `mode: subagent`, etc.) are generated/copied from these, never hand-edited |\n\nThere is no environment variable and no hook sdd-flow injects into the host — it only reads the\nfiles above and writes to `.spec/<feature-slug>/` and git.\n\n---\n\n## FAQ\n\n> **Does sdd-flow talk to any network service?**\n> No. It never calls an API on its own. The only network action in the whole flow is the\n> Verifier's `gh pr create`, which uses your already-authenticated `gh` CLI.\n\n> **Can I skip a phase, e.g. go straight to Implement?**\n> Not through the intended flow — each phase's subagent expects the prior phase's artifact\n> (`scope.md`, `design.md`, a task file) to exist and refuses to invent one. You can still run a\n> subagent by hand if you already have the artifact it needs.\n\n> **What happens to `.spec/` after Verify passes?**\n> Nothing automatic — the folder stays on disk as the record of what was built and why. It's not\n> gitignored by default in a consuming project unless you choose to.\n\n> **Why five subagents instead of one big prompt?**\n> Context isolation. Each phase starts cold, so a bug in Implement can't leak assumptions the\n> Verifier should be checking independently, and Design can't accidentally see code that doesn't\n> exist yet.\n\n> **Does the Mini-SDD path get the same context isolation?**\n> Partially. Planning runs in the Orchestrator's own context (not isolated); only the developer\n> subagent is cold-started. That's the intended trade-off for small changes — full isolation for\n> every phase is Full SDD's job.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 11910,
  "sha": "80f709a6452fca3230dc6d0f221c65438af75bc6e05275b911e30b25242426f4",
  "repo_slug": "nushey/sdd-flow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nushey_sdd_flow_be246145/readme"
}