Enhance your AI coding tool with a structured, spec-driven delivery workflow.
Most AI coding tools jump straight to code. SDD Pilot adds a spec-driven development layer on top — so you specify what to build before how to build it.
- Phase-by-phase process — each feature moves through Specify → Plan → Tasks → Implement → QC
- Quality gates — you cannot skip ahead; each phase requires the previous phase's artifacts
- Structured artifacts — specs, plans, tasks, and QC reports live under
specs/<feature-folder>/ - Specialized agents — a dedicated role (Product Manager, Architect, Engineer, QC) handles each phase
- Autopilot mode — run the full pipeline unattended with a single command
Runtime output: Workflow and sub-agent communication is compact by default. Milestone updates prefer
done / issues / next, while safety warnings, destructive actions, and parser-sensitive artifacts stay explicit.
Compatibility: Works with GitHub Copilot, Antigravity, Windsurf, OpenCode, Claude Code, and OpenAI Codex.
Codex behavior: Codex wrappers explicitly stop for user answers at interactive decision points instead of inferring the recommended option.
/sddp-autopilotremains the explicit unattended exception.
SDD Pilot has two workflows: an optional project bootstrap to set up shared context, and the feature delivery lifecycle you repeat for each feature.
Set up reusable product, architecture, and operations context before building features.
flowchart TB
B((Start)) --> PRD["/sddp-prd · Product Discovery"]
B -.-> SA
PRD --> SA["/sddp-systemdesign · Architecture"]
SA --> DO["/sddp-devops · Operations"]
SA --> PP["/sddp-projectplan · Epic Planning"]
DO -.-> PP
PP --> Init["/sddp-init · Governance"]
PP -.-> Amend["/sddp-amend · Cross-Artifact Amend"]
Init -.-> Amend
B --> Init
style B fill:#455A64,stroke:#263238,color:#fff
style PRD fill:#6D4C41,stroke:#3E2723,color:#fff
style SA fill:#5D4037,stroke:#3E2723,color:#fff
style DO fill:#00796B,stroke:#004D40,color:#fff
style PP fill:#283593,stroke:#1A237E,color:#fff
style Amend fill:#00838F,stroke:#006064,color:#fff
style Init fill:#512DA8,stroke:#311B92,color:#fff
| Command | What it does |
|---|---|
/sddp-prd |
Turns a rough product idea into a canonical PRD (specs/prd.md) |
/sddp-systemdesign |
Creates the Software Architecture Document (specs/sad.md) and standalone MADR decision records (specs/adrs/) |
/sddp-devops |
Defines deployment & operations context (specs/dod.md) |
/sddp-projectplan |
Decomposes the project into prioritized epics (specs/project-plan.md) |
/sddp-amend |
Propagates a new project-level change across existing bootstrap artifacts and the project plan |
/sddp-init |
Sets up project governance rules (project-instructions.md) |
/sddp-regen |
Archives a completed prototype and regenerates all canonical bootstrap artifacts from scratch, informed by learnings |
All bootstrap steps except /sddp-init are optional. Once bootstrap artifacts exist, use /sddp-amend to keep them aligned when scope or strategy changes. You can still jump straight to /sddp-init and start delivering features.
The core lifecycle you run for each feature:
flowchart TB
S["/sddp-specify · Specify"] --> C["/sddp-clarify · Clarify"]
S --> P["/sddp-plan · Plan"]
C --> P
P --> CH["/sddp-checklist · Checklist ⚬"]
P --> T["/sddp-tasks · Tasks"]
CH --> T
T --> A["/sddp-analyze · Analyze ⚬"]
T --> I["/sddp-implement · Implement"]
A --> I
I --> QC["/sddp-qc · QC"]
QC -->|PASS| R["Release Ready ✓"]
QC -->|FAIL| I
Auto["/sddp-autopilot"] -.-> S
Loop["/sddp-implement-qc-loop"] -.-> I
style S fill:#1976D2,stroke:#0D47A1,color:#fff
style C fill:#F57C00,stroke:#E65100,color:#fff
style P fill:#00796B,stroke:#004D40,color:#fff
style CH fill:#7B1FA2,stroke:#4A148C,color:#fff
style T fill:#D32F2F,stroke:#B71C1C,color:#fff
style A fill:#0288D1,stroke:#01579B,color:#fff
style I fill:#37474F,stroke:#263238,color:#fff
style QC fill:#C62828,stroke:#B71C1C,color:#fff
style R fill:#2E7D32,stroke:#1B5E20,color:#fff
style Auto fill:#00695C,stroke:#004D40,color:#fff
style Loop fill:#6A1B9A,stroke:#4A148C,color:#fff
Phases marked ⚬ are optional but recommended.
| Phase | Command | What it produces |
|---|---|---|
| Specify | /sddp-specify |
spec.md — user stories, requirements, success criteria |
| Clarify | /sddp-clarify |
Updated spec.md with resolved ambiguities |
| Plan | /sddp-plan |
plan.md — architecture decisions, tech context |
| Checklist | /sddp-checklist |
checklists/*.md — requirements quality checks |
| Tasks | /sddp-tasks |
tasks.md — phased, dependency-ordered task list |
| Analyze | /sddp-analyze |
Consistency report (no files modified) |
| Implement | /sddp-implement |
Source code with tasks marked complete |
| QC | /sddp-qc |
qc-report.md — tests, lint, security, traceability |
Each phase requires the previous phase's output:
- No planning without
spec.md - No tasks without
plan.md - No implementation without
tasks.md - No QC without
.completed(set when all tasks pass) - No release without
.qc-passed - If QC fails,
.completedis removed and[BUG]tasks are injected intotasks.md project-instructions.mdrules are enforced throughout
Run the entire feature-delivery pipeline unattended:
/sddp-autopilot Build user authentication with email/password
Requires: Autopilot enabled in .github/sddp-config.md, plus a registered Product Document and Technical Context Document. If either is missing, run /sddp-prd and/or /sddp-systemdesign first.
For OpenAI Codex, this unattended behavior is specific to /sddp-autopilot. The other Codex commands ask and wait at workflow decision points.
Autopilot is provided through the repository's tool-specific workflow wrappers; there is no separate standalone orchestrator/ package.
| Tool | Requirements |
|---|---|
| GitHub Copilot | VS Code ≥ 1.109, Copilot Chat extension, active Copilot access |
| Antigravity | Antigravity installed |
| Windsurf | Windsurf IDE installed |
| OpenCode | OpenCode IDE or CLI installed |
| OpenAI Codex | Codex CLI installed (npm i -g @openai/codex), active ChatGPT plan or OpenAI API key |
| Claude Code | Claude Code CLI, active Anthropic API key or Claude Max subscription |
Tip — environment setup: Run
/sddp-devsetupto analyze your repo and get a guided setup walkthrough.
Tip — model choice: You do not need the most expensive tiers. Recommended GPT-5.4 or Claude Sonnet 4.6
-
Go to the Releases page.
-
Download the archive for your tool:
- GitHub Copilot →
sdd-pilot-copilot-vX.Y.Z.zip - Antigravity →
sdd-pilot-antigravity-vX.Y.Z.zip - Windsurf →
sdd-pilot-windsurf-vX.Y.Z.zip - OpenCode →
sdd-pilot-opencode-vX.Y.Z.zip - OpenAI Codex →
sdd-pilot-codex-vX.Y.Z.zip - Claude Code →
sdd-pilot-claude-code-vX.Y.Z.zip
- GitHub Copilot →
-
Extract the archive contents to your project root.
# 1. Initialize project governance
# (optionally run /sddp-prd and /sddp-systemdesign first for richer context)/sddp-init My project is a Node.js monorepo using TypeScript.
# 2. Create a feature branch and deliver a feature
git checkout -b 00001-user-auth/sddp-specify Build user authentication with email/password
/sddp-clarify
/sddp-plan
/sddp-tasks
/sddp-implement
/sddp-qc
Or replace the feature commands with a single autopilot run:
/sddp-autopilot Build user authentication with email/password
QC feedback loop: If
/sddp-qcfails, it injects[BUG]tasks and removes.completed. Run/sddp-implementagain, then re-run/sddp-qc. Or use/sddp-implement-qc-loopto automate this cycle (up to 10 iterations).
Interrupted? Re-run
/sddp-implementin a new chat. Completed tasks (marked[X]) are automatically skipped.
Same chat or new chat? Both work. Each command resets its context. A new chat is only recommended for
/sddp-specifywhen starting a brand-new feature.
This repo also includes an internal markdown compressor for narrative-heavy docs:
node scripts/compress-markdown.mjs --check docs/reference.md
node scripts/compress-markdown.mjs docs/reference.mdIt is intentionally narrow. Allowed targets are README.md, docs/**/*.md, and feature-level research.md, analysis-report.md, and manual-test.md. It blocks parser-sensitive artifacts such as spec.md, plan.md, tasks.md, qc-report.md, checklist files, ADRs, and workflow/instruction files. The script preserves headings, fenced code, inline code, links, IDs, tables, and checkbox lines exactly, and writes a one-time .original.md backup before overwriting.
Each feature gets its own workspace under specs/. The workspace name is derived from your git branch:
Branch: 00001-user-auth → specs/00001-user-auth/
New workspaces must use the #####-feature-name format (e.g. 00001-user-auth). If your branch doesn't match this pattern, /sddp-specify will prompt you for a name.
The repository now treats wrapper propagation as a checkable contract. CI runs scripts/drift-report.mjs and fails if any supported wrapper surface is missing, points at the wrong canonical target, or diverges from its expected tool-specific behavior.
Run the same validation locally with:
node scripts/drift-report.mjs --output .build/drift-report --strictThe drift report writes three artifacts under .build/drift-report/:
drift-report.json— machine-readable inventory, statuses, and findingsdrift-report.md— workflow matrix, agent matrix, findings, and embedded Mermaid diagramdrift-report.mmd— raw Mermaid source for reuse in other tooling
The workflow matrix covers command-level wrappers across Claude, Agents skills, Agents workflows, OpenCode commands, and Windsurf. The agent matrix covers tool-specific wrappers around canonical .github/agents/ files, including OpenCode and Codex.
Status meanings:
in-sync— target, delegate mapping, and surface contract matched expectationsmissing— an expected wrapper file is absentstale-reference— a wrapper points at the wrong canonical skill or delegate targetnormalized-drift— a wrapper still points at the right target but its tool-specific behavior contract driftedunsupported-extra— an unexpected wrapper file exists outside the supported inventory
- Full reference documentation — agent role mapping, artifact taxonomy, sddp-config internals, workspace conventions
- Lifecycle and governance rules
- Shared project context
- Specs file conventions