VS Code Installation

VS Code supports Agent Teams Lite through GitHub Copilot’s agent mode and custom instructions. Skills work as context files, and Copilot can read and execute them inline.

Prerequisites

VS Code installed
GitHub Copilot subscription and extension installed
Git installed for cloning the repository
Project directory to work in

Installation Steps

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite

Run the installer

./scripts/install.sh
# Choose option 5: VS Code

./scripts/install.sh --agent vscode

This copies skills to ./.vscode/skills/sdd-*/ in the current directory.

VS Code installation is project-local by default. Skills go in .vscode/skills/ within your project, not in a global directory.

You should see output like:

Installing skills for VS Code (Copilot)...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ./.vscode/skills
  
  Note: Skills installed in current project (.vscode/skills/)

Add orchestrator instructions

VS Code Copilot supports custom instructions through multiple methods. Choose one:

Option 1: User Prompts (Recommended)

Create a prompt file in your VS Code User directory:

mkdir -p ~/Library/Application\ Support/Code/User/prompts
cp examples/vscode/copilot-instructions.md \
   ~/Library/Application\ Support/Code/User/prompts/sdd-orchestrator.instructions.md

mkdir -p ~/.config/Code/User/prompts
cp examples/vscode/copilot-instructions.md \
   ~/.config/Code/User/prompts/sdd-orchestrator.instructions.md

mkdir %APPDATA%\Code\User\prompts
copy examples\vscode\copilot-instructions.md \
     %APPDATA%\Code\User\prompts\sdd-orchestrator.instructions.md

Option 2: Copilot Settings

Open VS Code Settings (Cmd+, / Ctrl+,)
Search for github.copilot.chat.codeGeneration.instructions
Click “Edit in settings.json”
Add the SDD orchestrator instructions

View settings.json format

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "[Paste orchestrator instructions from examples/vscode/copilot-instructions.md]"
    }
  ]
}

Option 3: Project-Level Instructions

Create .github/copilot-instructions.md in your project root:

mkdir -p .github
cp examples/vscode/copilot-instructions.md .github/copilot-instructions.md

Verify installation

Open VS Code in your project:

code .

Open the Chat panel (Ctrl+Cmd+I / Ctrl+Alt+I)Type:

/sdd-init

Expected response:

Reading skill from .vscode/skills/sdd-init/SKILL.md...

✓ Detected stack: [your project's stack]
✓ SDD initialized

Configuration Locations

Project-Local (Recommended)
User-Level
Settings

Skills:

.vscode/skills/sdd-*/

Instructions:

.github/copilot-instructions.md

Benefits:

Skills committed with project
Team members get SDD automatically
Project-specific configuration

User Prompts (macOS):

~/Library/Application Support/Code/User/prompts/

User Prompts (Linux):

~/.config/Code/User/prompts/

User Prompts (Windows):

%APPDATA%\Code\User\prompts\

Benefits:

Available across all projects
User-specific configuration

Copilot Settings:

github.copilot.chat.codeGeneration.instructions

Access via VS Code Settings UI or settings.jsonBenefits:

Centralized configuration
Easy to edit in VS Code

MCP Server Configuration (Optional)

If you want to use Engram or other MCP servers with VS Code:

User-Level MCP Config

// ~/Library/Application Support/Code/User/mcp.json
{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@gentleman-programming/engram"]
    }
  }
}

// ~/.config/Code/User/mcp.json
{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@gentleman-programming/engram"]
    }
  }
}

// %APPDATA%\Code\User\mcp.json
{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@gentleman-programming/engram"]
    }
  }
}

Project-Level MCP Config

// .vscode/mcp.json
{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "@gentleman-programming/engram"]
    }
  }
}

How It Works

VS Code Copilot runs skills inline as context files: Key characteristics:

Skills work as context files (not true sub-agents)
Execution happens inline within Copilot’s context
Agent mode provides tool use capability
Planning phases work well
Implementation guided by skill instructions

Example Usage

Initialize SDD

You: /sdd-init

Copilot: Reading .vscode/skills/sdd-init/SKILL.md...
         
         Analyzing project structure...
         ✓ Detected: React + TypeScript + Vite
         ✓ Package manager: npm
         ✓ Testing: Vitest + React Testing Library
         
         Checking for Engram MCP server...
         ✓ Engram available
         
         SDD initialized for project: my-react-app
         Artifact store: engram

Start a New Feature

You: /sdd-new add-search

Copilot: Exploring codebase for search functionality...
         
         ✓ No existing search implementation
         ✓ Component structure: src/components/
         ✓ API client: src/api/client.ts
         
         Creating proposal...
         
         Proposal Summary:
         - Intent: Add search functionality with filters and sorting
         - Scope: Search component, API integration, URL state sync
         - Approach: Debounced input, query params, server-side search
         - Rollback: Remove SearchBar component, remove /search route
         
         Artifact stored: sdd/add-search/proposal
         
         Ready to continue with specs and design?

Continue Through Planning

You: Yes, continue

Copilot: Creating specifications...
         
         ✓ 4 requirements (SHALL statements)
         ✓ 8 scenarios (Given/When/Then format)
         ✓ Stored: sdd/add-search/spec
         
         Creating technical design...
         
         ✓ Component hierarchy: SearchBar -> SearchResults
         ✓ State management: URL search params + useSearchParams
         ✓ API endpoint: GET /api/search?q=...
         ✓ Debounce: 300ms using useDebouncedValue hook
         ✓ Stored: sdd/add-search/design
         
         Creating task breakdown...
         
         ✓ Phase 1: API integration (2 tasks)
         ✓ Phase 2: Search UI (3 tasks)
         ✓ Phase 3: URL sync (2 tasks)
         ✓ Total: 7 tasks
         ✓ Stored: sdd/add-search/tasks
         
         Ready to implement. Run /sdd-apply to start.

Artifact Storage

engram (Recommended)
openspec
none

If you configure Engram MCP server, artifacts are stored persistently:

title:     sdd/add-search/proposal
topic_key: sdd/add-search/proposal
type:      architecture
project:   my-react-app

Benefits:

Repository stays clean
Persistent across sessions
Searchable via mem_search

File-based artifacts in your project:

openspec/
├── config.yaml
├── specs/
└── changes/
    └── add-search/
        ├── proposal.md
        ├── specs/
        ├── design.md
        └── tasks.md

Verification Checklist

Check skills in project

ls .vscode/skills/sdd-*/

Should show 9 directories:

sdd-apply/  sdd-design/  sdd-init/  sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/

Check shared conventions

ls .vscode/skills/_shared/

Should show:

engram-convention.md
openspec-convention.md
persistence-contract.md

Verify instructions are configured

Check one of:

User prompts directory has sdd-orchestrator.instructions.md
.github/copilot-instructions.md exists in project
github.copilot.chat.codeGeneration.instructions is set in settings

Test in VS Code

code .
# Open Chat (Ctrl+Cmd+I / Ctrl+Alt+I)
# Type: /sdd-init

Should recognize the command and read the skill.

Troubleshooting

Command not recognized

Problem: Copilot doesn’t recognize /sdd-initSolutions:

Verify orchestrator instructions are configured (check one of the three locations)
Restart VS Code to reload configuration
Check Copilot is enabled and logged in
Try alternative phrasing: “Initialize SDD for this project”

Skills not found

Problem: Copilot can’t read skill filesSolutions:

Verify skills are in .vscode/skills/sdd-*/
Ensure you’re in the project directory where you ran the installer
Check file permissions
Open the folder in VS Code (not just individual files)

Instructions not loading

Problem: Orchestrator behavior not activeSolutions:

Check all three instruction locations (User prompts, settings, .github/)
Verify file format (must be valid Markdown)
Restart VS Code after adding instructions
Check Copilot settings are not disabled for workspace

MCP server not connecting

Problem: Engram or other MCP servers not availableSolutions:

Check mcp.json is in correct location (User or workspace)
Verify MCP server is installed: npx -y @gentleman-programming/engram --version
Check VS Code has MCP support enabled
Review VS Code output panel for MCP errors

Team Setup

To share SDD with your team:

Commit skills to repository

git add .vscode/skills/
git add .github/copilot-instructions.md
git commit -m "Add Agent Teams Lite SDD workflow"
git push

Document in README

Add to your project’s README:

## Development Workflow

This project uses Spec-Driven Development (SDD) via Agent Teams Lite.

To start a new feature:
1. Open VS Code Chat (Ctrl+Cmd+I)
2. Run `/sdd-new <feature-name>`
3. Follow the guided workflow

See `.vscode/skills/` for available SDD commands.

Team members pull changes

Team members get SDD automatically when they pull:

git pull
code .
# SDD is now available

Next Steps

Quick Start

Learn the SDD workflow

Commands Reference

Complete command documentation

Engram MCP Setup

Set up persistent storage

Team Workflows

Share SDD with your team

Get Started

Installation

Guides

Commands

Prerequisites

Installation Steps

Option 1: User Prompts (Recommended)

Option 2: Copilot Settings

Option 3: Project-Level Instructions

Configuration Locations

MCP Server Configuration (Optional)

User-Level MCP Config

Project-Level MCP Config

How It Works

Example Usage

Initialize SDD

Start a New Feature

Continue Through Planning

Artifact Storage

Verification Checklist

Troubleshooting

Team Setup

Next Steps

Quick Start

Commands Reference

Engram MCP Setup

Team Workflows

​Prerequisites

​Installation Steps

​Option 1: User Prompts (Recommended)

​Option 2: Copilot Settings

​Option 3: Project-Level Instructions

​Configuration Locations

​MCP Server Configuration (Optional)

​User-Level MCP Config

​Project-Level MCP Config

​How It Works

​Example Usage

​Initialize SDD

​Start a New Feature

​Continue Through Planning

​Artifact Storage

​Verification Checklist

​Troubleshooting

​Team Setup

​Next Steps

Quick Start

Commands Reference

Engram MCP Setup

Team Workflows

Prerequisites

Installation Steps

Option 1: User Prompts (Recommended)

Option 2: Copilot Settings

Option 3: Project-Level Instructions

Configuration Locations

MCP Server Configuration (Optional)

User-Level MCP Config

Project-Level MCP Config

How It Works

Example Usage

Initialize SDD

Start a New Feature

Continue Through Planning

Artifact Storage

Verification Checklist

Troubleshooting

Team Setup

Next Steps