sdd-pilot

SDD Pilot

Enhance your AI coding tool with a structured, spec-driven delivery workflow.

What is SDD Pilot?

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-autopilot remains the explicit unattended exception.

Copilot CLI: The Copilot archive includes .github/skills/sddp-*/SKILL.md command entry points alongside the VS Code prompt files. After installing or updating, run /skills reload, then /skills list to verify discovery. Invoke commands such as /sddp-specify [feature description] directly. The methodology skill is reference material, not the command dispatcher.

Heritage: SDD Pilot evolved from Spec Kit (0.0.90).

How It Works

SDD Pilot has two workflows: an optional project bootstrap to set up shared context, and the feature delivery lifecycle you repeat for each feature.

Project Bootstrap (optional)

Set up reusable product, architecture, and operations context before building features.

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.

Existing codebase? Run /sddp-reverseengineer before or after init. It inspects local source, documentation, configuration, tests, infrastructure, and available history, distinguishing facts, inferences, and unknowns. It stages candidates and asks before canonical publication; it never treats code as product intent or invents future work. Use --resume after interruption and --status for a read-only progress report. Already-implemented scope is imported baseline coverage, not synthetic completed epics or a rebuild backlog. PRD/SAD planning-ready gates still apply, and init remains the governance owner. See the onboarding guide.

Product discovery modes

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.

• --quick runs the focused default path.
• --discover starts or reopens adaptive discovery, moving through framing, evidence, stakeholder, scope, decision, readiness, and synthesis stages as needed.
• --resume continues an active or paused discovery from its durable ledger.
• --skip-research skips 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.

Feature Delivery

The core lifecycle you run for each feature:

Phases marked ⚬ are optional but recommended.

Quality Gates

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.md size 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 without plan.md, and no implementation without tasks.md.
• Unfinished checklists block implementation unless the user explicitly overrides.
• No QC without .completed (set when all tasks pass)
• No release without a .qc-passed marker whose report/evidence SHA-256 digests, Git baseline, and repository-state digest validate
• If QC fails, .completed is removed and [BUG] tasks are injected into tasks.md
• project-instructions.md rules are enforced throughout

Writing quality

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.

Autopilot

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.

Getting Started

Prerequisites

Tip — environment setup: Run /sddp-devsetup to 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

Installation

1. Go to the Releases page.

2. 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

3. 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.

Use the tool-specific release archives, not GitHub’s automatic source archives or a copy of the source checkout. Source root AGENTS.md governs framework development and tells agents to stop /sddp-* execution. Releases install templates/downstream/AGENTS.md as your project’s root AGENTS.md, preserving the pipeline rules. Review local customizations before replacing installed files during upgrades; retain your project-specific project-instructions.md.

Do not copy only Markdown files. The workflows call the archive’s scripts/*.mjs files for structural validation, task parsing, feature resolution, completion state, and QC evidence. A missing node executable or scripts/ directory blocks the affected phase rather than substituting model judgment for those checks.

Quick Start

# 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-qc fails, it injects [BUG] tasks and removes .completed. Run /sddp-implement again, then re-run /sddp-qc. Or use /sddp-implement-qc-loop to automate this cycle (up to 10 iterations).

Interrupted? Re-run /sddp-implement in 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-specify when starting a brand-new feature.

Safe Markdown Compression

Every release archive includes an optional markdown compressor for narrative-heavy docs. It is not required for SDD lifecycle execution:

node scripts/compress-markdown.mjs --check docs/reference.md
node scripts/compress-markdown.mjs docs/reference.md

It 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/sddp/workflows/implement-tasks/WORKFLOW.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.

Feature Workspaces

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.

Repository Validation

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.

Release validation also permits support-tool imports only from explicit node: built-ins and repository-relative modules. Any proposed exception changes the consumer dependency model and requires explicit maintainer review with an updated policy test; do not weaken the existing cases ad hoc.

Run the same validation locally with:

# Full source checkout
node scripts/drift-report.mjs --context source --output .build/drift-report --strict

# Host-specific release installation
node scripts/drift-report.mjs --host opencode --output .build/drift-report --strict

The drift report writes three artifacts under .build/drift-report/:

• drift-report.json — machine-readable inventory, statuses, and findings
• drift-report.md — workflow matrix, agent matrix, findings, and embedded Mermaid diagram
• drift-report.mmd — raw Mermaid source for reuse in other tooling

The source release manifest declares four script inventories: core lifecycle runtime, installed diagnostics (drift-report.mjs, compress-markdown.mjs, and the v0.33 migration helper), release documentation/legal files, and source-only maintainer tooling. Archives contain the first three categories only.

The workflow matrix covers every public command across Copilot, Claude Code, Codex, Antigravity, OpenCode, and Windsurf. Canonical command orchestration lives under .github/sddp/workflows/; reusable support skills remain under .github/skills/. Validation recursively checks canonical delegates and enforces one-to-one wrapper inventories. The agent matrix consumes the immutable registry in scripts/lib/delegated-agents.mjs and shows Copilot, Claude, OpenCode, and Codex availability around canonical .github/agents/ files.

Status meanings:

• in-sync — target, delegate mapping, and surface contract matched expectations
• missing — an expected wrapper file is absent
• stale-reference — a wrapper points at the wrong canonical workflow or delegate target
• normalized-drift — a wrapper still points at the right target but its tool-specific behavior contract drifted
• unsupported-extra — an unexpected wrapper file exists outside the supported inventory

Reference

• 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