SDD Pilot — Spec-Driven Development Framework

Built for Structured Delivery

Projects can optionally bootstrap shared product vision and technical context first. Then every feature moves through enforced phases with dedicated agents, structured artifacts, and quality gates.

Project Bootstrap + Gates

Define your product vision with /sddp-prd, establish a reusable technical baseline with /sddp-systemdesign, then enter a strict gated lifecycle. You still can't plan without a spec or implement without tasks.

Specialized AI Agents

Each phase has a dedicated persona — Product Strategist, Solution Architect, Product Manager, Software Architect, QA Engineer, QC Agent, Project Manager — plus sub-agents for delegation.

Requirement Traceability

Tasks link to functional requirements ({FR-###}) and user stories ([US#]). Nothing gets lost between spec and code.

Ambiguity Detection

Five pattern-based strategies (Adverb Trap, Passive Voice, Unspecified Scale, Missing Failure Mode, Scope Creep Detector) catch vagueness before it becomes bugs.

Quality Checklists

"Unit Tests for English" — checklists that test requirements quality, not code behavior. Auto-evaluated with PASS / RESOLVE / ASK outcomes.

Resumable Implementation

Interrupted? Re-run /sddp-implement — completed tasks are automatically skipped. Pick up where you left off.

Multi-Tool Architecture

Shared, tool-agnostic skill files power GitHub Copilot, Claude Code, Windsurf, Antigravity, OpenCode, OpenAI Codex, and Gemini CLI through thin wrapper layers.

Compliance Analysis

Cross-artifact consistency checks: spec vs. plan alignment, plan vs. tasks alignment, project instructions compliance — up to 50 findings with severity levels.

Online Research

A dedicated Technical Researcher agent fetches best practices, official docs, and industry standards from the web — then distills findings into a concise research.md so your plan is evidence-backed.

Autopilot Mode

Run the entire feature-delivery pipeline with /sddp-autopilot. Bootstrap stays explicit, while downstream phases auto-resolve decisions and record every choice.

How It Works

Projects can optionally bootstrap shared product and architecture context before the strict feature-delivery lifecycle begins. Each feature phase still produces structured artifacts and must pass quality gates.

B0 · PRD B1 · System Design B2 · DevOps B3 · Project Plan B4 · Init B5 · Amend Feature Delivery 1 · Specify 2 · Clarify 3 · Plan 4 · Checklist 5 · Tasks 6 · Analyze 7 · Implement 8 · QC 🔄 Implement-QC Loop

Project Bootstrap

Dashed lines = optional phases

Feature Delivery

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#BB86FC', 'primaryTextColor': '#121212', 'primaryBorderColor': '#985EFF', 'lineColor': '#6A6A6A', 'secondaryColor': '#1E1E1E', 'tertiaryColor': '#03DAC6', 'background': '#1E1E1E', 'mainBkg': '#1E1E1E', 'nodeBorder': '#333', 'clusterBkg': '#121212', 'titleColor': '#E0E0E0', 'edgeLabelBackground': '#1E1E1E' }}}%% graph TD S["/sddp-specify
Product Manager"] --> C["/sddp-clarify
Business Analyst"] S --> P["/sddp-plan
Software Architect"] C --> P P --> K["/sddp-checklist
QA Engineer"] P --> T["/sddp-tasks
Project Manager"] K --> T T --> A["/sddp-analyze
Compliance Auditor"] A --> I["/sddp-implement
Software Engineer"] I --> QC["/sddp-qc
QC Agent"] QC -->|PASS| Release["Release Ready"] QC -->|FAIL| I T -.->|optional| Loop["/sddp-implement-qc-loop"] Loop --> Release S -.->|unattended| AP["/sddp-autopilot"] AP --> Release style S fill:#448AFF,stroke:#82B1FF,color:#fff style C fill:#FF6E40,stroke:#FFAB91,color:#fff style P fill:#00897B,stroke:#03DAC6,color:#fff style K fill:#8E24AA,stroke:#CE93D8,color:#fff style T fill:#E53935,stroke:#CF6679,color:#fff style A fill:#0288D1,stroke:#80D8FF,color:#fff style I fill:#37474F,stroke:#B0BEC5,color:#fff style QC fill:#2E7D32,stroke:#69F0AE,color:#fff style Release fill:#00C853,stroke:#69F0AE,color:#121212 style Loop fill:#5C6BC0,stroke:#7986CB,color:#fff style AP fill:#00695C,stroke:#03DAC6,color:#fff

Dashed lines = optional / alternative paths

PRD

Product Strategist creates or refines specs/prd.md as the canonical Product Requirements Document and registers it in .github/sddp-config.md.

System Design

Solution Architect creates or refines specs/sad.md as the canonical technical context and registers it in .github/sddp-config.md.

DevOps

DevOps Strategist creates or refines specs/dod.md as the canonical Deployment & Operations Document and registers it in .github/sddp-config.md.

Project Plan

Project Planner creates or refines specs/project-plan.md as the canonical Project Implementation Plan and registers it in .github/sddp-config.md.

Init

Project Initializer establishes project-instructions.md and preserves or adopts the registered Product Document, Technical Context Document, Deployment & Operations Document, and Project Plan in .github/sddp-config.md.

Amend

Project Amender propagates a project-level change across project-instructions.md, the canonical PRD, SAD, DOD, and project plan by analyzing impact and inline-executing the owning bootstrap workflows.

Specify

Product Manager agent captures WHAT users need and WHY. Produces spec.md with prioritized user stories and functional requirements.

Clarify

Business Analyst agent detects ambiguity using 5 pattern-based strategies. Asks targeted questions and encodes answers directly into the spec.

Plan

Software Architect agent designs the technical approach. Produces plan.md, research.md, data models, and API contracts while reusing the registered technical context when present.

Checklist

QA Engineer agent generates domain-specific quality checklists in checklists/*.md. Covers testing, security, accessibility, and more.

Tasks

Project Manager agent decomposes spec + plan into dependency-ordered tasks.md. Each task is atomic, testable, and traceable to requirements.

Analyze

Compliance Auditor agent runs cross-artifact traceability analysis. Detects gaps, contradictions, and missing coverage between spec, plan, and tasks.

Implement

Software Engineer agent executes tasks phase-by-phase. Completed tasks marked [X] are skipped on re-run. Fully resumable.

QC Agent runs tests, static analysis, security audits, and story verification. Failures loop back as [BUG] tasks. Pass creates a .qc-passed marker.

Structured Artifacts,
Full Traceability

Project bootstrap writes shared artifacts outside feature folders. Feature delivery then produces a complete set of traceable documents per feature, from requirements through QC.

specs/prd.md — Canonical product requirements document
specs/sad.md — Canonical software architecture and technical context
specs/dod.md — Canonical deployment & operations and infrastructure context
specs/project-plan.md — Canonical project implementation plan and epic decomposition
project-instructions.md — Project governance enforced by downstream agents
.github/sddp-config.md — Product and technical context registration plus autopilot settings
spec.md — User stories, functional requirements, success criteria
plan.md — Architecture decisions, data models, API contracts
tasks.md — Phased task list with FR links and parallelism flags
checklists/ — "Unit Tests for English" quality verification

specs/
├── prd.md              # Canonical product requirements
├── sad.md              # Canonical technical context
├── dod.md              # Canonical deployment & operations
└── project-plan.md     # Canonical project implementation plan
project-instructions.md # Project governance
.github/
└── sddp-config.md      # Shared document registration + autopilot settings

specs/00001-user-auth/
├── spec.md             # Feature specification
├── plan.md             # Implementation plan
├── tasks.md            # Phased task list
├── research.md         # Technology research
├── data-model.md       # Entity definitions
├── quickstart.md       # Integration guide
├── contracts/          # API contracts
│   └── auth-api.md
├── checklists/         # Quality checklists
│   ├── spec-quality.md
│   └── plan-quality.md
├── .completed          # Implementation done marker
├── autopilot-log.md    # Autopilot audit log
└── .qc-passed          # QC gate passed marker

Getting Started

Up and running in under 5 minutes. Bootstrap shared technical context when you need it, then start feature delivery with the same command sequence across supported tools.

Install the framework

Download the release archive for your AI tool and extract it into your project.

# Download a tool-specific release
gh release download --repo attilaszasz/sdd-pilot \
  --pattern "sdd-pilot-copilot-*.zip" --dir .
unzip sdd-pilot-copilot-*.zip -d my-project

Optional: create canonical product document

Transform product ideas into a structured specs/prd.md that provides downstream phases with product vision, user personas, and domain context.

# Create or refine specs/prd.md and register it
/sddp-prd Here are my product ideas, target audience,
  and key features I want to build

Optional: create canonical technical context

Generate or refine specs/sad.md when you want a reusable architecture baseline before feature work.

# Create or refine specs/sad.md and register it
/sddp-systemdesign Use the attached PRD, architecture notes,
  and deployment constraints to create the canonical specs/sad.md

Optional: define DevOps strategy

New

Creates or refines the Deployment & Operations Document (specs/dod.md). Uses shared architecture and product context to define environments, CI/CD, and operational requirements.

# Define production environment requirements
/sddp-devops Define production environment requirements,
             deployment topology, and CI/CD pipelines.

Optional: create project plan

New

Creates or refines the Project Implementation Plan (specs/project-plan.md). Decomposes the product features into prioritized, dependency-ordered epics guiding the delivery schedule.

# Create an implementation plan
/sddp-projectplan Create an implementation plan based on the
                  system design and product requirements.

Initialize project governance

Define the non-negotiable principles that all downstream agents will enforce while preserving the registered technical context.

# Establish project-instructions.md and preserve shared context
/sddp-init Initialize project governance using attached PRD

Create a feature branch and specify

Start feature delivery with a natural-language description, then remove ambiguity before planning.

# Create a feature branch
git checkout -b 00001-user-auth

# Specify what you want to build
/sddp-specify Build user authentication with email/password,
  including registration, login, and password reset.

# Clarify any ambiguity
/sddp-clarify

Plan, task, and implement

Walk through the remaining phases. Each command produces structured artifacts and enforces quality gates.

# Design the technical approach
/sddp-plan

# Generate quality checklists (optional but recommended)
/sddp-checklist

# Decompose into dependency-ordered tasks
/sddp-tasks

# Run compliance analysis (optional but recommended)
/sddp-analyze

# Execute implementation — fully resumable
/sddp-implement

# Run quality control — tests, security, story verification
/sddp-qc

# Or loop implement + QC automatically (max 10 cycles)
/sddp-implement-qc-loop

Autopilot alternative: Run /sddp-autopilot Build user auth to execute the feature-delivery pipeline unattended. Bootstrap remains explicit.

Commands at a Glance

Seventeen commands across project bootstrap and feature delivery. Every command maps to a specialized AI agent.

Command	Agent	Produces	Requires
/sddp-prd	Product Strategist	specs/prd.md	Product ideas / attached docs
/sddp-systemdesign	Solution Architect	specs/sad.md	specs/prd.md
/sddp-devops	DevOps Strategist	specs/dod.md	specs/prd.md + specs/sad.md
/sddp-projectplan	Project Planner	specs/project-plan.md	specs/prd.md + specs/sad.md (dod optional)
/sddp-amend	Project Amender	Updated bootstrap artifacts	project-instructions.md + PRD + SAD + project plan
/sddp-init	Project Initializer	project-instructions.md	Governance principles
/sddp-devsetup	Environment Setup Analyst	Local dev environment	Repository context
/sddp-specify	Product Manager	spec.md	Feature description
/sddp-clarify	Business Analyst	Updated spec.md	spec.md
/sddp-plan	Software Architect	plan.md, research.md	spec.md
/sddp-checklist	QA Engineer	checklists/*.md	spec.md + plan.md
/sddp-tasks	Project Manager	tasks.md	spec.md + plan.md
/sddp-analyze	Compliance Auditor	Markdown report	spec + plan + tasks
/sddp-implement	Software Engineer	Source code	spec + plan + tasks
/sddp-qc	QC Agent	.qc-passed / [BUG] tasks	.completed + spec + tasks
/sddp-implement-qc-loop	Software Engineer (looping)	Source code + .qc-passed	spec + plan + tasks
/sddp-autopilot	Pipeline Orchestrator	All artifacts + autopilot-log.md	Autopilot enabled + Product Document + Technical Context Document

Multi-Tool Wrapper Architecture

One set of shared skills powers every supported AI tool. Each tool gets a thin wrapper layer that translates its native format into the shared skill engine.

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#BB86FC', 'primaryTextColor': '#121212', 'primaryBorderColor': '#985EFF', 'lineColor': '#6A6A6A', 'secondaryColor': '#1E1E1E', 'tertiaryColor': '#03DAC6', 'background': '#1E1E1E', 'mainBkg': '#1E1E1E', 'nodeBorder': '#333', 'clusterBkg': '#1A1A1A', 'titleColor': '#E0E0E0', 'edgeLabelBackground': '#1E1E1E' }}}%% graph TB subgraph Tools["AI Coding Tools"] CP["GitHub Copilot
.github/prompts/"] CC["Claude Code
.claude/agents/ + skills/"] WS["Windsurf
.windsurf/workflows/"] AG["Antigravity
.agents/workflows/"] OC["OpenCode
.opencode/commands/"] CX["OpenAI Codex
.agents/skills/"] GC["Gemini CLI
gemini-extension/"] end subgraph Core["Shared Skill Engine"] SK[".github/skills/
System Design • Methodology
Spec Authoring • Plan Authoring
Task Generation • Quality Control"] AG2[".github/agents/
Sub-agent definitions"] IN[".github/instructions/
Governance rules"] end CP --> SK CC --> SK WS --> SK AG --> SK OC --> SK CX --> SK GC --> SK SK --> AG2 SK --> IN style CP fill:#7C4DFF,stroke:#BB86FC,color:#fff style CC fill:#D4A054,stroke:#FFD180,color:#121212 style WS fill:#0288D1,stroke:#80D8FF,color:#fff style AG fill:#E53935,stroke:#CF6679,color:#fff style OC fill:#00897B,stroke:#03DAC6,color:#fff style CX fill:#412991,stroke:#BB86FC,color:#fff style GC fill:#4285F4,stroke:#80D8FF,color:#fff style SK fill:#2E7D32,stroke:#69F0AE,color:#fff style AG2 fill:#37474F,stroke:#B0BEC5,color:#fff style IN fill:#37474F,stroke:#B0BEC5,color:#fff

Shared Skill Engine

All methodology logic lives in .github/skills/ — tool-agnostic Markdown files that define how each SDD phase works. Write once, run everywhere.

Thin Wrapper Layers

Each AI tool gets a minimal wrapper in its native format — Copilot prompts, Antigravity workflows, Claude agents, Windsurf workflows, OpenCode commands, Codex skills, and Gemini extensions — that delegates to the shared skills.

Tool-Agnostic Sub-Agents

Sub-agents like the QC Auditor, Story Verifier, and Technical Researcher are defined in .github/agents/ and invoked identically by every tool.

Per-Tool Release Archives

Every release builds seven separate zip archives — one per tool. Each contains only the files that tool needs: its wrappers plus the shared core.

Consistent Behavior

Because every tool reads the same skill files, you get identical phase gates, artifact formats, and quality standards — regardless of which AI tool you choose.

Easy to Extend

Adding a new AI tool means writing a thin wrapper layer. The skill engine, sub-agents, and governance rules are already there and ready to use.

Repository Layout

sdd-pilot/
      ├── .github/                    # Shared core (all tools read from here)
      │   ├── skills/                 # Shared skills, including system-design
      │   ├── agents/                 # Sub-agent definitions + Copilot agents
      │   ├── instructions/           # Governance rules
      │   ├── prompts/                # Copilot prompt wrappers
      │   └── sddp-config.md          # Product / technical context registration
      │
      ├── specs/
      │   ├── prd.md                  # Canonical product requirements document
      │   ├── sad.md                  # Canonical technical context document
      │   ├── dod.md                  # Canonical deployment & operations
      │   └── project-plan.md         # Canonical project implementation plan
      ├── .agents/workflows/          # Antigravity workflow wrappers
      ├── .windsurf/workflows/        # Windsurf workflow wrappers
      ├── .claude/agents/ + skills/   # Claude Code agent + skill wrappers
      ├── .opencode/agents/ + cmds/   # OpenCode agent + command wrappers
      ├── .codex/agents/               # Codex custom agent definitions
      ├── .agents/skills/              # Codex skill entry points
      │
      ├── project-instructions.md     # Project governance (shared)
      └── AGENTS.md                   # Agent conventions (shared)

A framework for Spec-Driven Development.