GSD for VS Code + GitHub Copilot

A powerful planning and execution workflow for building software with AI assistance. Adapted from glittercowboy/get-shit-done for VS Code + GitHub Copilot.

What is GSD?

GSD (Get Shit Done) is a context engineering and spec-driven development system that makes AI-assisted coding reliable. It solves context rot — the quality degradation that happens as the AI fills its context window.

Key principles:

• Small, atomic plans (2-3 tasks max)
• Fresh context for each major task (using subagents)
• Explicit verification for every task
• Disciplined state management

Installation

npx gsd-vscode-copilot

This runs the installer in your current directory (the project you want to set up).

Or install globally (makes the CLI available everywhere):

npm install -g gsd-vscode-copilot

# then, inside each project you want to use GSD in:
cd /path/to/your-project
gsd-init

Notes:

• Global install does not automatically add prompt files to every repo — you still run gsd-init per project.
• If you prefer not to install globally, npx gsd-vscode-copilot is the per-project alternative.

What it installs

your-project/
├── .github/
│   ├── prompts/                    # Workflow prompts
│   │   ├── gsd-map-codebase.prompt.md
│   │   ├── gsd-bootstrap-planning.prompt.md
│   │   ├── gsd-discuss-phase.prompt.md
│   │   ├── gsd-research-phase.prompt.md
│   │   ├── gsd-plan-phase.prompt.md
│   │   ├── gsd-execute-phase.prompt.md
│   │   ├── gsd-verify-work.prompt.md
│   │   ├── gsd-progress.prompt.md
│   │   └── gsd-quick.prompt.md
│   ├── agents/                     # Custom agents
│   │   ├── gsd-codebase-mapper.agent.md
│   │   ├── gsd-researcher.agent.md
│   │   ├── gsd-planner.agent.md
│   │   └── gsd-verifier.agent.md
│   ├── instructions/
│   │   └── gsd-workflow.instructions.md
│   └── vendor/
│       └── get-shit-done/
│           ├── templates/
│           └── references/
└── .planning/
    ├── PROJECT.md
    ├── REQUIREMENTS.md
    ├── ROADMAP.md
    ├── STATE.md
    ├── config.json             # Workflow preferences
    ├── codebase/               # From gsd-map-codebase
    ├── research/               # Domain research
    └── phases/                 # Plans and summaries

Workflow

GSD supports three workflows depending on your situation:

1. Quick Mode (Ad-hoc Tasks)

For small, self-contained tasks that don't need planning:

/gsd-quick Fix the login button styling

Use for: bug fixes, config changes, small refactors, adding tests.

2. Brownfield (Existing Codebase)

For projects with existing code:

1. /gsd-map-codebase         → Analyze existing code
2. /gsd-bootstrap-planning   → Initialize project planning
3. /gsd-discuss-phase 1      → Capture implementation decisions
4. /gsd-plan-phase 1         → Create detailed plans
5. /gsd-execute-phase 1      → Execute with verification
6. /gsd-verify-work 1        → Manual UAT (optional)
7. Repeat for each phase

3. Greenfield (New Project)

For brand new projects:

1. /gsd-bootstrap-planning   → Initialize project planning
2. /gsd-discuss-phase 1      → Capture implementation decisions
3. /gsd-plan-phase 1         → Create detailed plans
4. /gsd-execute-phase 1      → Execute with verification
5. Repeat for each phase

Commands Reference

Core Workflow

| Command | Purpose | |---------|---------| | /gsd-map-codebase | Analyze existing codebase (brownfield) | | /gsd-bootstrap-planning | Initialize .planning/ files | | /gsd-discuss-phase [N] | Capture implementation decisions before planning | | /gsd-research-phase [N] | Research complex domains or approaches | | /gsd-plan-phase [N] | Create detailed execution plans | | /gsd-execute-phase [N] | Execute all plans in a phase | | /gsd-verify-work [N] | Conversational user acceptance testing | | /gsd-progress | Check status and next action | | /gsd-quick [task] | Quick ad-hoc tasks (skip full workflow) |

Custom Agents

GSD includes specialized agents for different tasks:

| Agent | Purpose | |-------|---------| | gsd-codebase-mapper | Analyze codebase structure, patterns, conventions | | gsd-researcher | Research domain knowledge and best practices | | gsd-planner | Create detailed, executable plans | | gsd-verifier | Verify completed work meets goals |

Switch to an agent using the Chat view agent picker.

Subagents for Fresh Context

GSD uses subagents to maintain fresh context for complex operations:

• Each subagent gets its own context window
• Subagents run to completion autonomously
• Only final results return to main session

Enable runSubagent in your tools configuration.

Wave-Based Execution

Plans are organized into waves for efficient execution:

• Wave 1: Independent plans that can start immediately
• Wave 2: Plans that depend on Wave 1
• Wave N: Plans that depend on earlier waves

Background Agents

For long-running or parallel work, use Copilot CLI background agents:

@cli [task description]

Background agents run in isolated Git worktrees while you continue other work.

Core Principles

• Small plans: 2-3 tasks max per plan
• Explicit verification: Every task has a verify command
• Context hygiene: Fresh context for each plan execution
• Atomic commits: One logical commit per task

Stack-Agnostic

The workflow doesn't assume any particular tech stack. Plans carry verification commands:

| Stack | Example verify | |-------|----------------| | Node | npm test | | Python | pytest | | .NET | dotnet test | | Go | go test ./... | | Rust | cargo test |

File Structure

.planning/
├── PROJECT.md              # Vision, constraints, non-goals
├── REQUIREMENTS.md         # v1/v2/out-of-scope requirements
├── ROADMAP.md              # Phases with status
├── STATE.md                # Current position, decisions, blockers
├── config.json             # Workflow preferences
├── codebase/               # From gsd-map-codebase
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   └── CONCERNS.md
├── research/               # Domain research
│   └── [TOPIC]-RESEARCH.md
└── phases/
    ├── 01-foundation/
    │   ├── 01-CONTEXT.md   # Implementation decisions
    │   ├── 01-RESEARCH.md  # Phase-specific research
    │   ├── 01-01-PLAN.md   # First plan
    │   ├── 01-01-SUMMARY.md
    │   └── 01-VERIFICATION.md
    └── 02-core-features/
        └── ...

Credits

Inspired by glittercowboy/get-shit-done, adapted for VS Code + GitHub Copilot workflows with full support for:

• Custom agents (.agent.md)
• Subagents (runSubagent)
• Background agents (@cli)
• Agent handoffs

License

MIT