Spec-Driven Development pipeline for GitHub Copilot CLI

SDD Copilot Agents is a 4-agent pipeline that turns rough feature plans into tested, reviewed code — entirely inside GitHub Copilot CLI. It's built for developers who want structured, repeatable software delivery without leaving the terminal. The system enforces a spec-first workflow where code is always traceable back to a written requirement, and every implementation gets audited against its spec with a scored compliance report.

  ┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │             │     │              │     │              │     │              │
  │  Your Plan  │────▶│  Spec Writer │────▶│ Implementer  │────▶│   Reviewer   │
  │  (rough)    │     │              │     │              │     │              │
  └─────────────┘     └──────┬───────┘     └──────┬───────┘     └──────┬───────┘
                             │                    │                    │
                             ▼                    ▼                    ▼
                        spec.md              Working Code        HTML Report
                     (10 sections)         (tests first)        (scored %)

• What's Included
• Key Concepts
• Prerequisites
• Installation
• Quick Start
• The Four Agents
  • Spec Writer
  • Implementer
  • Reviewer
  • Packager
• Pipeline Flow
• Prompts Guide
• Architecture
• Documentation Website
• Customization
• Troubleshooting
• Contributing
• License

Before using this system, you need to understand two Copilot CLI concepts:

An agent is a custom persona for GitHub Copilot CLI defined in a .agent.md file inside ~/.copilot/agents/. When you type @agent-name in the Copilot CLI chat, Copilot loads that file as system instructions. It controls the agent's identity, rules, and behavior. Think of it as a role definition — "you are a spec writer, here's how you work."

A skill is a knowledge module defined in a SKILL.md file inside ~/.copilot/skills/. Skills contain procedures, templates, and reference material that agents can invoke. When an agent needs to produce a spec, it reads the spec-writer skill to know the exact template and rules to follow. Skills are the "how-to manuals" that agents consult.

Together: Agents define who does the work. Skills define how the work gets done. Templates define what the output looks like.

Clone the repo and run the installer for your platform:

Windows (PowerShell):

git clone https://github.com/YOUR_USERNAME/sdd-copilot-agents.git
cd sdd-copilot-agents
.\install.ps1

macOS / Linux (Bash):

git clone https://github.com/YOUR_USERNAME/sdd-copilot-agents.git
cd sdd-copilot-agents
chmod +x install.sh && ./install.sh

The installer copies agents to ~/.copilot/agents/, skills to ~/.copilot/skills/, prompts to ~/.copilot/sdd/prompts/, and templates to ~/.copilot/sdd/templates/. Existing files are backed up before overwriting.

Use --dry-run to preview what would be installed without making changes:

.\install.ps1 -DryRun

Copy each component to the correct Copilot directory:

# Create directories
mkdir -p ~/.copilot/agents
mkdir -p ~/.copilot/skills
mkdir -p ~/.copilot/sdd/prompts
mkdir -p ~/.copilot/sdd/templates

# Copy agents
cp agents/*.agent.md ~/.copilot/agents/

# Copy skills (each skill is a directory)
cp -r skills/spec-writer ~/.copilot/skills/
cp -r skills/implementer ~/.copilot/skills/
cp -r skills/reviewer ~/.copilot/skills/
cp -r skills/packager ~/.copilot/skills/

# Copy prompts
cp prompts/*.md ~/.copilot/sdd/prompts/

# Copy templates
cp templates/* ~/.copilot/sdd/templates/

Open VS Code, start a Copilot Chat session in the terminal, and run:

/skills

You should see spec-writer, implementer, reviewer, and packager listed as available skills. You can also test agent availability:

@spec-writer Are you available?

Expected response: The agent identifies itself as the Specification Architect and confirms it's ready.

Three prompts to see the full pipeline in action:

Step 1 — Write a spec:

@spec-writer Turn this plan into a spec: Users can search products by name,
filter by category, and sort by price. Admin can add/edit/delete products.

Step 2 — Implement the spec:

@implementer Implement the spec at .specify/specs/product-search/spec.md

Step 3 — Review the implementation:

@reviewer Review the implementation against the spec at .specify/specs/product-search/spec.md

The reviewer generates an HTML compliance report with a percentage score and opens it in your browser.

Role: Specification Architect — transforms vague plans into comprehensive, implementable specifications.

Invocation: @spec-writer

What it does:

1. Asks 5 clarifying questions about your plan before writing anything
2. Produces a 10-section specification covering: Project Overview, User Stories (prioritized P1/P2/P3), Functional Requirements, Non-Functional Requirements, Data Model, API Contracts, Success Criteria, Edge Cases, Assumptions, and Out of Scope
3. Uses Given/When/Then format for all acceptance scenarios
4. Marks ambiguities with [NEEDS CLARIFICATION] instead of guessing
5. Saves the spec to .specify/specs/{feature}/spec.md and a global copy to ~/.copilot/sdd/specs/

Example prompt:

@spec-writer I need a spec for a real-time notification system.
Users should receive push notifications, email digests, and in-app alerts.
They should be able to configure which channels they want per notification type.

Expected output: A structured markdown spec file with 5+ user stories, acceptance scenarios, a data model for notification preferences, and API contracts for the notification endpoints.

Role: Disciplined Builder — takes approved specs and translates them into working, tested code.

Invocation: @implementer

What it does:

1. Reads the entire spec and breaks it into phased tasks (Setup → Foundation → User Stories → Polish)
2. Creates a tasks.md tracking file with task IDs (T001, T002, etc.) mapped to user stories
3. Writes tests first from acceptance criteria, then implements code to pass them
4. Follows spec literally — never improvises or adds unrequested features
5. Implements in priority order: all P1 stories first, then P2, then P3
6. Documents any deviations with justification when the spec conflicts with reality
7. Generates a completion report with pass/fail status per task

Example prompt:

@implementer Implement the spec at .specify/specs/product-search/spec.md

Expected output: Working code with tests, a tasks.md file tracking progress, and a completion report saved to ~/.copilot/sdd/reports/{project}/.

Role: Specification Compliance Auditor — compares implemented code against the spec and generates a scored HTML report.

Invocation: @reviewer

What it does:

1. Reads the spec and the implemented code systematically
2. Audits every user story, functional requirement, non-functional requirement, success criterion, and edge case
3. Provides evidence-based findings with file paths, line numbers, and code snippets
4. Scores each requirement: ✅ Implemented (1.0), ⚠️ Partial (0.5), ❌ Missing (0.0), ⬜ Not Applicable (0.0)
5. Calculates an overall compliance percentage and issues a verdict:
   • 95–100%: ✅ APPROVED
   • 80–94%: ⚠️ APPROVED WITH CONDITIONS
   • 60–79%: 🔶 NEEDS REVISION
   • Below 60%: ❌ REJECTED
6. Generates a self-contained HTML report with executive summary, requirements traceability matrix, and prioritized findings

Example prompt:

@reviewer Review the implementation against the spec at .specify/specs/product-search/spec.md

Expected output: A review-report.html file with a compliance score, color-coded requirement matrix, and actionable findings sorted by severity.

Role: Package Publisher — converts local Copilot artifacts into shareable GitHub repos with documentation and install scripts.

Invocation: @packager

What it does:

1. Discovers and inventories all agents, skills, prompts, and templates in your ~/.copilot/ directory
2. Creates a clean repo structure with everything needed to share
3. Generates a professional README with installation commands and prompt guides
4. Creates cross-platform install scripts (install.ps1 + install.sh)
5. Builds a self-contained HTML documentation website
6. Sanitizes paths and removes user-specific data before packaging
7. Optionally pushes to GitHub and enables GitHub Pages

Example prompt:

@packager Package the SDD system into a GitHub repo with documentation and install scripts

Expected output: A complete repo at ~/.copilot/packages/{repo-name}/ with README, install scripts, HTML docs site, and all artifacts organized for sharing.

Here's how a feature moves through the SDD pipeline from idea to reviewed code:

 1. PLAN                    You describe what you want to build (plain English)
    │
    ▼
 2. SPEC (Spec Writer)      Agent asks clarifying questions, then produces spec.md
    │                        • 10 structured sections
    │                        • User stories with P1/P2/P3 priority
    │                        • Given/When/Then acceptance scenarios
    │                        • Data models and API contracts
    │
    ▼
 3. IMPLEMENT (Implementer)  Agent reads spec, creates tasks.md, builds code
    │                        • Tests written first (from acceptance criteria)
    │                        • Implementation follows test → code → verify loop
    │                        • P1 stories first, then P2, then P3
    │                        • Deviations documented with justification
    │
    ▼
 4. REVIEW (Reviewer)        Agent audits code against spec, generates report
    │                        • Every requirement checked with evidence
    │                        • Scored compliance percentage
    │                        • HTML report with findings and recommendations
    │
    ▼
 5. VERDICT                  APPROVED / APPROVED WITH CONDITIONS / NEEDS REVISION / REJECTED
    │
    ▼
 6. ITERATE (if needed)      Fix issues flagged in report → re-run reviewer

These prompts get you from zero to a reviewed implementation.

Write a specification from a plain-English plan:

@spec-writer Turn this plan into a spec: Users can search products by name,
filter by category, and sort by price. Admin can add/edit/delete products.

What happens: The spec writer asks 5 clarifying questions (e.g., "Should search be fuzzy or exact match?"), then generates a full spec with user stories, requirements, data models, and acceptance scenarios. The spec is saved to .specify/specs/product-search/spec.md.

Build the code from an approved spec:

@implementer Implement the spec at .specify/specs/product-search/spec.md

What happens: The implementer reads the spec, creates a tasks.md breakdown, writes tests from acceptance criteria, implements code to pass those tests, and generates a completion report.

Audit the implementation against the spec:

@reviewer Review the implementation against the spec at .specify/specs/product-search/spec.md

What happens: The reviewer systematically checks every requirement, scores compliance, and generates an HTML report you can open in a browser. You'll see a percentage score and a color-coded matrix of what passed, what's partial, and what's missing.

Run all three phases automatically with a single prompt:

Read and execute ~/.copilot/sdd/prompts/sdd-full-pipeline-prompt.md against this codebase

What happens: Copilot reads the orchestration prompt and executes Phase 1 (spec), Phase 2 (implement), and Phase 3 (review) sequentially. All artifacts are saved to the standard locations.

Ask the spec writer to interview you before writing:

@spec-writer I need a spec for a real-time chat system. Ask me clarifying
questions first, then write the spec.

What happens: The agent asks targeted questions about your chat system (message persistence, user presence, typing indicators, file sharing, etc.), then writes the spec incorporating your answers.

Implement only one user story instead of the entire spec:

@implementer Implement only User Story 3 (P2) from the spec at .specify/specs/chat/spec.md

What happens: The implementer reads the full spec for context but only implements the tasks related to User Story 3. Tests are written for that story's acceptance criteria only.

Get a fast compliance summary without the full HTML report:

@reviewer Give me a quick compliance score for the spec at
.specify/specs/chat/spec.md — just the percentage and top 3 issues

What happens: The reviewer scans the implementation and returns a short summary: overall percentage, verdict, and the three highest-priority findings.

Bundle your agents and skills into a shareable repo:

@packager Package the SDD system into a GitHub repo with documentation

What happens: The packager inventories your ~/.copilot/ artifacts, creates a clean repo with README, install scripts, and an HTML docs site, then optionally pushes to GitHub.

Set up the SDD pipeline in a different workspace or machine:

Read ~/.copilot/sdd/prompts/bootstrap-stress-test.md and execute the full
pipeline against this workspace

What happens: The bootstrap prompt instructs the agent to read all global SDD system files (agent profiles, skills, rules, templates), explore the current codebase, and run the full 3-phase pipeline. Artifacts are saved both locally and to the global ~/.copilot/sdd/ directory.

Reverse-engineer a specification from an existing codebase:

@spec-writer Reverse-engineer a specification from the existing codebase in
src/. Document what it currently does as a formal spec.

What happens: The spec writer reads your source code, identifies features, user flows, and data models, then produces a spec documenting the current behavior. This is useful for brownfield projects that need a spec baseline before refactoring.

Review code against two versions of a spec to track changes:

@reviewer Compare the implementation against TWO specs: the original at
specs/v1/spec.md and the updated at specs/v2/spec.md. Show what changed
and whether the code matches v2.

What happens: The reviewer audits the code against both specs, highlights which requirements changed between v1 and v2, and reports whether the implementation conforms to the updated spec. The report includes a delta section showing added, removed, and modified requirements.

~/.copilot/
├── agents/                          # Agent definitions (loaded via @agent-name)
│   ├── spec-writer.agent.md         #   "Specification Architect"
│   ├── implementer.agent.md         #   "Disciplined Builder"
│   ├── reviewer.agent.md            #   "Specification Compliance Auditor"
│   └── packager.agent.md            #   "Package Publisher"
│
├── skills/                          # Skill modules (loaded via /skills)
│   ├── spec-writer/
│   │   ├── SKILL.md                 #   Procedures for writing specs
│   │   ├── templates/
│   │   │   ├── spec-template.md     #   10-section spec structure
│   │   │   └── constitution-template.md
│   │   └── examples/
│   │       └── sample-spec.md       #   Example completed spec
│   ├── implementer/
│   │   ├── SKILL.md                 #   Procedures for implementing specs
│   │   └── templates/
│   │       └── tasks-template.md    #   Task breakdown format
│   ├── reviewer/
│   │   ├── SKILL.md                 #   Procedures for reviewing code
│   │   └── templates/
│   │       └── report-template.html #   24KB self-contained HTML report
│   └── packager/
│       ├── SKILL.md                 #   Procedures for packaging repos
│       └── templates/
│           ├── website-template.html
│           ├── readme-template.md
│           ├── install-template.ps1
│           └── install-template.sh
│
└── sdd/                             # Global SDD artifacts
    ├── prompts/                     #   Orchestration prompts
    │   ├── sdd-full-pipeline-prompt.md
    │   ├── sdd-stress-test-prompt.md
    │   └── bootstrap-stress-test.md
    ├── templates/                   #   Standalone template copies
    ├── specs/                       #   Generated specs (by project)
    └── reports/                     #   Generated reports (by project)

┌──────────────────────────────────────────────────────────┐
│                    AGENT LAYER                           │
│  @spec-writer  @implementer  @reviewer  @packager        │
│  (identity, rules, workflow per agent)                   │
├──────────────────────────────────────────────────────────┤
│                    SKILL LAYER                           │
│  Each agent reads its matching skill for procedures      │
│  and templates. Skills are the "how-to manuals."         │
├──────────────────────────────────────────────────────────┤
│                   TEMPLATE LAYER                         │
│  spec-template.md  tasks-template.md  report-template.html│
│  (structured output formats that agents fill in)         │
├──────────────────────────────────────────────────────────┤
│                   ARTIFACT LAYER                         │
│  specs/  reports/  prompts/                              │
│  (generated files saved globally and per-project)        │
└──────────────────────────────────────────────────────────┘

This repo includes an HTML documentation site that can be deployed to GitHub Pages or viewed locally.

Open the docs site directly in your browser:

# From the repo root
open docs/index.html        # macOS
start docs/index.html       # Windows
xdg-open docs/index.html    # Linux

1. Push the repo to GitHub
2. Go to Settings → Pages
3. Set source to Deploy from a branch, select main, folder /docs
4. The site will be live at https://YOUR_USERNAME.github.io/sdd-copilot-agents/

Agent files are plain markdown. Edit them to change the agent's personality, rules, or workflow:

# Open the spec writer agent for editing
code ~/.copilot/agents/spec-writer.agent.md

Common modifications:

• Change the number of clarifying questions the spec writer asks
• Adjust the implementer's priority ordering (e.g., implement P2 stories first for a specific project)
• Modify the reviewer's scoring thresholds
• Add domain-specific rules (e.g., "always use PostgreSQL" or "follow our API naming conventions")

Create a new template in the skill's templates/ directory:

# Add a custom spec template for API-only projects
code ~/.copilot/skills/spec-writer/templates/api-spec-template.md

Then reference it in the skill's SKILL.md so the agent knows to use it.

Create a new skill directory with a SKILL.md:

mkdir ~/.copilot/skills/my-custom-skill
code ~/.copilot/skills/my-custom-skill/SKILL.md

The SKILL.md file should define: when the skill triggers, what procedures it follows, and what templates it uses. See any existing skill's SKILL.md for the format.

This is a personal productivity system packaged for sharing. To adapt it for your own use:

1. Fork this repository
2. Clone your fork locally
3. Modify agents, skills, and templates to match your workflow
4. Test by running the installer and invoking each agent
5. Push your changes and share

# Clone your fork
git clone https://github.com/YOUR_USERNAME/sdd-copilot-agents.git
cd sdd-copilot-agents

# Make changes to agents or skills
code agents/spec-writer.agent.md

# Test locally by installing
./install.sh --force

# Verify
# Open Copilot CLI → @spec-writer Are you available?

# Commit and push
git add -A
git commit -m "Customize spec writer for my workflow"
git push origin main

sdd-copilot-agents/
├── README.md              ← You are here
├── agents/                ← Agent definitions (edit these to change behavior)
├── skills/                ← Skill modules (edit these to change procedures/templates)
├── prompts/               ← Pipeline prompts (edit these to change orchestration)
├── templates/             ← Standalone template copies
├── guide/                 ← SDD-GUIDE.md (comprehensive reference)
└── docs/                  ← Documentation website

MIT License. See LICENSE for details.

Use it, modify it, share it. Attribution appreciated but not required.