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 |
Creates or refines the canonical PRD through quick or adaptive, resumable product discovery |
/sddp-systemdesign |
Adaptively designs and validates the SAD, architecture views, major data flows, and standalone MADR records |
/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.
With no mode flag, /sddp-prd uses --quick: at most two focused question batches, useful research only when needed, then validator-backed creation or refinement of the canonical PRD. The default path is specs/prd.md; an already registered custom Product Document remains the sole write target. The validated path is registered in .github/sddp-config.md.
--quickruns the focused default path.--discoverstarts or reopens adaptive discovery, moving through framing, evidence, stakeholder, scope, decision, readiness, and synthesis stages as needed.--resumecontinues an active or paused discovery from its durable ledger.--skip-researchskips external research and can modify quick, discover, or resume mode.
Quick mode creates neither discovery artifact. Discover/resume maintains specs/prd-discovery.md; if external research runs, it also writes specs/prd-research.md. Interactive questions always require an explicit answer. Recommendations are guidance only, and free-form answers remain available where permitted.
The workflow validates both a temporary candidate and the live PRD with scripts/validate-prd.mjs before registration. prd_maturity: draft records a structurally valid but incomplete product definition. /sddp-projectplan and /sddp-autopilot require the validator's planning-ready profile, completed matching discovery, and canonical registration; project planning also requires the Technical Context Document.
See the /sddp-prd user guide for theoretical examples covering simple products, research-free runs, multi-sided discovery, regulated products, resumed sessions, and safe PRD refinement.
See the /sddp-systemdesign user guide for theoretical examples covering simple applications, compound SaaS platforms, regulated systems, streaming architectures, and brownfield refinement.
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. Three handoffs also run mandatory structural validators:
- Spec → Plan: the Spec Validator requires complete frontmatter, concrete P1 acceptance criteria, no more than three unresolved clarification markers, and no unresolved CRITICAL/HIGH stress-test finding.
- Plan → Tasks: the Plan Validator requires complete P1 coverage in the Requirement Coverage Map, no orphaned architecture decisions, and installable declared dependencies.
- Tasks → Implement: the Tasks Validator requires valid phased tasks, at most 40 tasks, P1 task coverage, no circular dependencies, and a
tasks.mdsize of at most 6 KB. - A failed validator blocks the next phase. Interactive runs may explicitly choose “Proceed anyway”; autopilot stops.
- No planning without
spec.md, no tasks withoutplan.md, and no implementation withouttasks.md. - Unfinished checklists block implementation unless the user explicitly overrides.
- No QC without
.completed(set when all tasks pass) - No release without a
.qc-passedmarker whose report/evidence SHA-256 digests, Git baseline, and repository-state digest validate - If QC fails,
.completedis removed and[BUG]tasks are injected intotasks.md project-instructions.mdrules are enforced throughout
Every phase applies the writing-quality contract in AGENTS.md while composing user-facing text and artifact prose. The pass removes stock AI phrasing, filler, and vague claims before structural validation. It edits only prose created or changed by the current task and preserves artifact structure, IDs, commands, evidence, quoted text, and machine-readable content.
The expanded rules live in .github/skills/writing-quality/SKILL.md. They are ambient workflow guidance, not a public command or a separate lifecycle phase.
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. The setting authorizes /sddp-autopilot; it does not make standalone commands unattended. If either document 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 directly to your project root. Hidden discovery directories such as
.github/,.opencode/, or.claude/are already at the archive root; no wrapper directory needs to be moved or renamed.
# 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. Governance files are admitted only through the exact manifest in scripts/lib/markdown-compression.mjs; the first gated target is .github/skills/implement-tasks/SKILL.md, where only <rules> and <workflow> prose can change. All other workflow, instruction, and parser-sensitive files remain blocked. The validator preserves frontmatter, headings, fenced code, inline code, links, IDs, tables, checkbox lines, list structure, and lines outside gated blocks exactly. Use --idempotent to make CI fail when an allowlisted file can still be compressed; in-place writes retain a one-time .original.md backup.
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 and ambient governance hoists as checkable contracts. CI runs scripts/drift-report.mjs and fails if any supported wrapper surface is missing, points at the wrong canonical target, diverges from its expected tool-specific behavior, or reloads a hoisted runtime contract.
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 every public command across Copilot, Claude Code, Codex, Antigravity, OpenCode, and Windsurf. Validation recursively checks canonical delegates and enforces one-to-one wrapper inventories. 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
- Glossary — definitions of SDD Pilot workflow, artifact, validation, and traceability terms
- Lifecycle and governance rules
- Shared project context
- Specs file conventions