13 custom Copilot Chat agents for Spec-Driven Development and a complete UI/UX Design Lifecycle — from idea to production code with quality gates at every step.

SDD VS Code Agents is a plugin for GitHub Copilot Chat in VS Code. It adds 13 specialized AI agents that work together in two pipelines: a Spec-Driven Development (SDD) pipeline that turns vague plans into tested, reviewed code, and a UI/UX Lifecycle pipeline that takes a product idea through research, architecture, wireframes, UX design, visual design, frontend implementation, and UX testing — with a quality gate between every phase.

┌─────────────────────── SDD Pipeline ───────────────────────┐
│                                                             │
│   Plan ──▶ @spec-writer ──▶ @implementer ──▶ @reviewer     │
│              writes spec     codes it         audits it     │
│                                  ▲               │          │
│                                  └── Fix Issues ◀┘          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌──────────────── UI/UX Lifecycle Pipeline ───────────────────┐
│                                                              │
│   @ui-lifecycle-master (orchestrates all 7 phases)           │
│                                                              │
│   Phase 1  @ux-research      ──▶ research-brief.md          │
│       │    ↓ review gate (@design-reviewer)                  │
│   Phase 2  @info-arch        ──▶ information-architecture.md │
│       │    ↓ review gate                                     │
│   Phase 3  @wireframe        ──▶ wireframes/                 │
│       │    ↓ review gate                                     │
│   Phase 4  @ux-design        ──▶ ux-spec.md                  │
│       │    ↓ review gate                                     │
│   Phase 5  @ui-design        ──▶ ui-design/                  │
│       │    ↓ review gate                                     │
│   Phase 6  @frontend-impl    ──▶ src/                        │
│       │    ↓ review gate                                     │
│   Phase 7  @ux-testing       ──▶ ux-test-report.md           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

A Copilot Chat agent (also called a "chat participant") is a custom AI persona that you invoke with @agent-name in the Copilot Chat panel. Each agent has its own system prompt that gives it specialized knowledge and behavior. Agents can use VS Code tools (search files, edit code, run terminal commands) and can hand off to other agents with a single click.

This plugin registers 13 agents via a plugin.json manifest. VS Code loads them when you add the plugin path to your settings.

Windows (PowerShell):

git clone https://github.com/SufficientDaikon/sdd-vscode-agents.git
cd sdd-vscode-agents
./install.ps1

macOS / Linux:

git clone https://github.com/SufficientDaikon/sdd-vscode-agents.git
cd sdd-vscode-agents
chmod +x install.sh
./install.sh

Expected output:

============================================
  SDD VS Code Agents — Installer
============================================

[1/4] Source:  /path/to/sdd-vscode-agents
[1/4] Target:  ~/.copilot/plugins/sdd-vscode-agents

[2/4] Creating target directory...
[3/4] Copying plugin files...
       Copied plugin.json
       Copied agents/design-reviewer.agent.md
       Copied agents/frontend-impl.agent.md
       ... (13 agents total)

[4/4] Verifying installation...

  SUCCESS! All 13 agents installed.

1. Clone this repository anywhere on your machine:

git clone https://github.com/SufficientDaikon/sdd-vscode-agents.git ~/sdd-vscode-agents

2. Open VS Code settings (Ctrl+, / Cmd+,), search for chat.plugins.paths, and add the path:

{
  "chat.plugins.paths": ["~/sdd-vscode-agents"]
}

3. Restart VS Code (or reload the window with Ctrl+Shift+P → "Developer: Reload Window").

4. Open Copilot Chat (Ctrl+Shift+I) and type @spec-writer — you should see it autocomplete.

If you use the Copilot CLI:

copilot plugin install ~/sdd-vscode-agents

Three commands to see it work:

1. Open Copilot Chat in VS Code  →  Ctrl+Shift+I

2. Type:  @spec-writer Create a spec for a task management app where
   users can create projects, add tasks with due dates and priorities,
   assign tasks to team members, and track progress with a dashboard.

3. When the spec is done, click the "Implement the Spec" handoff button.

That's it. The spec-writer produces a specification, then you hand off to the implementer with one click, then hand off to the reviewer. Each agent knows exactly what to do.

The SDD pipeline has three agents that chain together: spec-writer → implementer → reviewer.

The spec-writer takes your rough idea and produces a structured specification with user stories, functional requirements, acceptance criteria, and edge cases.

@spec-writer Create a spec for a REST API that manages a recipe collection.
Users can create, read, update, and delete recipes. Each recipe has a title,
ingredients list, steps, cooking time, and difficulty rating. Users can search
by ingredient and filter by difficulty.

What it produces:

• spec.md in your project directory containing 10 sections:
  1. Project Overview
  2. User Scenarios & Stories (prioritized P1/P2/P3)
  3. Functional Requirements (FR-001, FR-002…)
  4. Non-Functional Requirements
  5. Key Entities & Data Model
  6. Success Criteria (SC-001, SC-002…)
  7. Edge Cases & Error Handling
  8. Assumptions & Dependencies
  9. Out of Scope
  10. Acceptance Checklist

Handoff: Click "Implement the Spec" to pass the spec to the implementer.

The implementer reads the specification and builds it section by section using TDD. It creates a task breakdown, implements in priority order, and tracks progress in tasks.md.

@implementer Implement the specification in spec.md using Node.js with
Express and SQLite. Use Jest for testing.

What it produces:

• Complete project with source code, tests, and configuration
• tasks.md tracking every implementation task
• A completion report with test results and deviation log

Handoff: Click "Review Spec Compliance" to send to the reviewer.

The reviewer compares code against the spec and produces a self-contained HTML compliance report with scores, a traceability matrix, and findings by severity.

@reviewer Review the implementation against spec.md. Check every
functional requirement, user story, and success criterion.

What it produces:

• review-report.html — a styled HTML report with:
  • Executive summary with overall compliance score
  • User story coverage matrix
  • Requirements traceability matrix (FR → Code → Test)
  • Findings categorized as Critical/Major/Minor/Info
  • Verdict: APPROVED / APPROVED WITH CONDITIONS / NEEDS REVISION

Handoff: If issues are found, click "Fix Implementation Issues" to send findings back to the implementer.

The lifecycle pipeline has 7 phases, each handled by a dedicated agent, with a quality gate (@design-reviewer) between every phase. The @ui-lifecycle-master orchestrates the entire flow.

@ui-lifecycle-master I want to build a fitness tracking app. Target audience
is casual gym-goers aged 25-40. Key features: workout logging, progress
charts, exercise library, and social sharing. Constraint: must work offline.

The master agent will:

1. Parse your brief into a structured format
2. Determine the starting phase (usually Phase 1)
3. Invoke each phase agent in sequence
4. Run @design-reviewer between every phase
5. Handle APPROVED / NEEDS REVISION / REJECTED verdicts
6. Report progress after each phase

You can also start at a specific phase:

@ui-lifecycle-master Start at Phase 5 (UI Design). I already have wireframes
in wireframes/ and a UX spec in ux-spec.md.

Each phase agent can be invoked directly if you don't need the full pipeline:

The design reviewer evaluates artifacts against phase-specific criteria. It assigns a score and a verdict:

• ≥95%: APPROVED — proceed to next phase
• 85–94%: APPROVED WITH CONDITIONS — minor fixes, can proceed
• 70–84%: NEEDS REVISION — must fix before proceeding
• <70%: REJECTED — major rework required

@design-reviewer Review the wireframes (Phase 3) for coverage of all IA
screens, grayscale compliance, content hierarchy, and responsive annotations.

The packager turns your agents, skills, or templates into a shareable GitHub repository with documentation.

@packager Package all my custom agents into a shareable GitHub repo
with README, HTML docs site, and install scripts.

Start the SDD pipeline from scratch:

@spec-writer Create a spec for a bookmark manager browser extension. Users can save bookmarks with tags, search by tag or title, organize into folders, and export/import as JSON.

Expected result: A 10-section specification file saved to your project directory.

Run the full UI/UX lifecycle:

@ui-lifecycle-master Build a portfolio website for a freelance photographer. Audience: potential clients and art directors. Features: gallery with filtering, about page, contact form, blog. Constraint: must load fast on mobile.

Expected result: The master agent starts Phase 1 (UX Research) and walks you through all 7 phases.

Quick compliance check:

@reviewer Review the implementation against spec.md. Show me the coverage matrix for all functional requirements.

Expected result: An HTML report at review-report.html with a traceability matrix.

Write a spec, then implement it:

@spec-writer Create a spec for a real-time chat application with rooms, direct messages, typing indicators, and message reactions.

(review the spec, then click "Implement the Spec" handoff button)

Expected result: Spec is written, then implementation begins automatically via handoff.

Design a single page:

@ui-design Create a beautiful landing page design. Style: modern and minimal. Palette: dark theme with blue accents. Include a hero section, features grid, testimonials, and CTA.

Expected result: A ui-design/ directory with design tokens, components, and high-fidelity page HTML/CSS.

Get wireframes for an existing IA:

@wireframe Create grayscale wireframes for all screens in information-architecture.md. Focus on content hierarchy and responsive layout.

Expected result: A wireframes/ directory with one HTML file per screen, plus annotations.

Review a specific phase:

@design-reviewer Review the UX design (Phase 4) for component state completeness, interaction consistency, form UX, and accessibility requirements.

Expected result: A scored review with APPROVED/NEEDS REVISION verdict and specific findings.

Research users for a new product:

@ux-research My product is a meal planning app for busy parents. Target: parents aged 28-45, cooking 4+ meals/week, value health but are time-constrained. Features: weekly meal plans, grocery lists, recipe scaling, family preference profiles.

Expected result: research-brief.md with personas, journey maps, competitive analysis, and insights.

Resume a lifecycle from a specific phase:

@ui-lifecycle-master Resume from Phase 4. The wireframes are approved and in wireframes/. Start UX Design.

Expected result: The master skips Phases 1–3 and begins Phase 4 with existing artifacts.

Chain the full SDD pipeline without stopping:

@spec-writer Create a spec for a URL shortener service with analytics, custom aliases, and link expiration. After writing the spec, immediately hand off to the implementer using Node.js and PostgreSQL.

Expected result: Spec is written, then implementation begins. After implementation, click "Review Spec Compliance" for the final audit.

Use the implementer's deviation protocol:

@implementer Implement spec.md using Python/FastAPI. If any requirement is technically infeasible, document the deviation and propose an alternative instead of skipping it.

Expected result: Implementation with explicit deviation reports for any spec conflicts, logged for the reviewer.

Agent not appearing in Copilot Chat:

Check that chat.plugins.paths in VS Code settings points to the directory containing plugin.json. Restart VS Code after changing settings.

Handoff button not working:

Handoff buttons appear at the bottom of an agent's response. If you don't see them, ensure you're using VS Code 1.96+ and the latest Copilot Chat extension. Try invoking the target agent directly as a workaround: @implementer Implement the spec in spec.md.

Every agent is a standalone Markdown file. To customize behavior:

1. Open the .agent.md file in agents/
2. Edit the YAML frontmatter to change the agent's description or handoffs
3. Edit the Markdown body to change the agent's system prompt
4. Restart VS Code to reload the plugin

Example — changing the spec-writer's output format:

# In agents/spec-writer.agent.md, edit the frontmatter:
---
name: spec-writer
description: My customized spec writer that outputs Gherkin format
tools:
  - search
  - codebase
  - editFiles
  - terminalLastCommand
  - agent
handoffs:
  - label: Implement the Spec
    agent: implementer
    prompt: Implement the specification faithfully.
    send: false
---

1. Create a new file agents/my-agent.agent.md
2. Add YAML frontmatter with name, description, tools, and optional handoffs
3. Write the system prompt in the Markdown body
4. The plugin will pick it up automatically (restart VS Code)

sdd-vscode-agents/
├── plugin.json                          Plugin manifest (name, version, agent path)
├── agents/
│   ├── spec-writer.agent.md             SDD: Spec writing
│   ├── implementer.agent.md             SDD: Code implementation
│   ├── reviewer.agent.md                SDD: Compliance review
│   ├── ui-lifecycle-master.agent.md     Lifecycle: 7-phase orchestrator
│   ├── ux-research.agent.md             Lifecycle Phase 1: User research
│   ├── info-arch.agent.md               Lifecycle Phase 2: Information architecture
│   ├── wireframe.agent.md               Lifecycle Phase 3: Wireframes
│   ├── ux-design.agent.md               Lifecycle Phase 4: UX specification
│   ├── ui-design.agent.md               Lifecycle Phase 5: Visual design
│   ├── frontend-impl.agent.md           Lifecycle Phase 6: Frontend code
│   ├── ux-testing.agent.md              Lifecycle Phase 7: UX validation
│   ├── design-reviewer.agent.md         Lifecycle: Quality gate between phases
│   └── packager.agent.md                Support: Packaging & distribution
├── docs/
│   └── index.html                       Documentation website (open in browser)
├── install.ps1                          Windows/PowerShell installer
├── install.sh                           macOS/Linux installer
├── LICENSE                              MIT License
├── .gitignore                           Git ignore rules
└── README.md                            This file

Developer writes a rough plan
        │
        ▼
┌───────────────┐     Spec file      ┌───────────────┐
│  @spec-writer │ ──────────────────▶ │ @implementer  │
│               │                     │               │
│ • Asks 5      │                     │ • Analyzes    │
│   clarifying  │                     │   spec        │
│   questions   │                     │ • Writes      │
│ • Writes      │                     │   tests first │
│   10-section  │                     │ • Implements  │
│   spec        │                     │   by priority │
│ • Self-       │                     │ • Tracks in   │
│   validates   │                     │   tasks.md    │
└───────────────┘                     └──────┬────────┘
                                             │
                                     Completion report
                                             │
                                             ▼
                                     ┌───────────────┐
                                     │   @reviewer   │
                                     │               │
                                     │ • Checks every│
                                     │   requirement │
                                     │ • Produces    │
                                     │   HTML report │
                                     │ • Scores:     │
                                     │   95%+ = PASS │
                                     │   <80% = REDO │
                                     └──────┬────────┘
                                             │
                                     ┌───────┴───────┐
                                     │               │
                                APPROVED      NEEDS REVISION
                                     │               │
                                     ▼               ▼
                                  Ship it     Back to @implementer

The @ui-lifecycle-master drives a 7-phase pipeline. Between every phase, the @design-reviewer evaluates the artifact against phase-specific criteria. If the score is below 85%, the phase agent must revise before proceeding (max 2 retries, then escalate to developer).

Each phase produces a concrete artifact that the next phase consumes:

Each agent's YAML frontmatter defines handoffs — buttons that appear at the bottom of the agent's response in Copilot Chat. Clicking a handoff button invokes the target agent with a pre-configured prompt. This creates a seamless chain without the developer having to type anything.

Example from spec-writer.agent.md:

handoffs:
  - label: Implement the Spec
    agent: implementer
    prompt: Implement the specification faithfully, section by section.
    send: false

The send: false means VS Code shows the prompt in the chat input but doesn't send it automatically — you can review and edit before sending.

1. Verify plugin.json is in the root of the directory you registered
2. Check your settings.json has the correct path in chat.plugins.paths
3. Restart VS Code (Reload Window is not always sufficient)
4. Ensure you're on VS Code 1.96+ and the latest Copilot Chat extension

• Handoffs require VS Code Copilot Chat with agent mode support
• Ensure the target agent name in handoffs.agent matches the name field of the target agent file
• Try invoking the target agent directly: @implementer Implement spec.md

Each agent declares its tools in the YAML frontmatter (tools: [search, codebase, editFiles, ...]). If an agent can't search files or edit code, check that the tool is listed in its frontmatter.

The agent name you type (@spec-writer) must exactly match the name field in the agent's YAML frontmatter. Names are case-sensitive and use hyphens, not underscores.

1. Fork this repository
2. Edit the .agent.md file in agents/
3. The YAML frontmatter controls metadata; the Markdown body is the system prompt
4. Test by pointing chat.plugins.paths to your fork
5. Submit a pull request with a description of what changed and why

1. Create agents/your-agent.agent.md with valid frontmatter
2. Add handoffs to/from existing agents if it fits into a pipeline
3. Update this README with the new agent's description and usage
4. Test the agent and all its handoffs before submitting

---
name: agent-name # What users type: @agent-name
description: >- # One-line description shown in autocomplete
  Short description of what this agent does.
tools: # VS Code tools this agent can use
  - search
  - codebase
  - editFiles
  - terminalLastCommand
  - agent
handoffs: # Buttons shown after agent response
  - label: Button Text
    agent: target-agent
    prompt: Pre-filled prompt for the target agent.
    send: false # false = review before sending
---
# Agent Title

System prompt content goes here. This is what the AI reads to understand
its role, workflow, and constraints.

MIT — use it, modify it, share it.