gsd-vscode-copilot 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,17 @@
 # GSD for VS Code + GitHub Copilot
 
-A lightweight planning and execution workflow for building software with AI assistance.
+A powerful planning and execution workflow for building software with AI assistance.
+Adapted from [glittercowboy/get-shit-done](https://github.com/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
 
@@ -20,61 +31,144 @@ gsd-init
 ```
 your-project/
 ├── .github/
-│   ├── prompts/
+│   ├── prompts/                    # Workflow prompts
+│   │   ├── gsd-map-codebase.prompt.md
 │   │   ├── gsd-bootstrap-planning.prompt.md
-│   │   ├── gsd-plan-slice.prompt.md
-│   │   ├── gsd-execute-plan.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-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/
-│           │   ├── phase-prompt.md
-│           │   └── summary.md
 │           └── references/
-│               └── checkpoints.md
 └── .planning/
     ├── PROJECT.md
     ├── REQUIREMENTS.md
     ├── ROADMAP.md
     ├── STATE.md
-    └── phases/
+    ├── 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:
 
-## Usage
+| 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 |
 
-### 1. Bootstrap your project
+Switch to an agent using the Chat view agent picker.
 
-Open `.github/prompts/gsd-bootstrap-planning.prompt.md` and run it with Copilot. This initializes your project memory in `.planning/`.
+## Subagents for Fresh Context
 
-### 2. Plan a slice
+GSD uses subagents to maintain fresh context for complex operations:
 
-Run `gsd-plan-slice.prompt.md` to create a 2-3 task plan for the next piece of work.
+- Each subagent gets its own context window
+- Subagents run to completion autonomously
+- Only final results return to main session
 
-### 3. Execute the plan
+Enable `runSubagent` in your tools configuration.
 
-Run `gsd-execute-plan.prompt.md` with the path to your plan file.
+## Wave-Based Execution
 
-### 4. Verify (optional)
+Plans are organized into waves for efficient execution:
 
-Run `gsd-verify-work.prompt.md` for conversational user acceptance testing.
+- **Wave 1:** Independent plans that can start immediately
+- **Wave 2:** Plans that depend on Wave 1
+- **Wave N:** Plans that depend on earlier waves
 
-### 5. Check progress
+## Background Agents
 
-Run `gsd-progress.prompt.md` to see where you are and what's next.
+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 plan
+- **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 their own verification commands appropriate to your project:
+The workflow doesn't assume any particular tech stack. Plans carry verification commands:
 
 | Stack | Example verify |
 |-------|----------------|
@@ -84,9 +178,40 @@ The workflow doesn't assume any particular tech stack. Plans carry their own ver
 | 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](https://github.com/glittercowboy/get-shit-done), adapted for VS Code + GitHub Copilot workflows.
+Inspired by [glittercowboy/get-shit-done](https://github.com/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
 

package/bin/init.js

@@ -34,14 +34,16 @@ ${bold('Options:')}
 
 ${bold('What it does:')}
   1. Creates .github/prompts/gsd-*.prompt.md  (Copilot prompt files)
-  2. Creates .github/instructions/gsd-workflow.instructions.md
-  3. Creates .github/vendor/get-shit-done/  (templates & workflows)
-  4. Creates .planning/ with PROJECT/REQUIREMENTS/ROADMAP/STATE stubs
+  2. Creates .github/agents/gsd-*.agent.md   (Copilot custom agents)
+  3. Creates .github/instructions/gsd-workflow.instructions.md
+  4. Creates .github/vendor/get-shit-done/  (templates & workflows)
+  5. Creates .planning/ with PROJECT/REQUIREMENTS/ROADMAP/STATE stubs
 
 ${bold('After installing:')}
   1. Open any gsd-*.prompt.md in VS Code
   2. Click "Run" or use the Copilot prompt runner
-  3. Start with gsd-bootstrap-planning.prompt.md to initialize your project
+  3. For existing codebases: Start with gsd-map-codebase.prompt.md
+  4. For new projects: Start with gsd-bootstrap-planning.prompt.md
 `);
   process.exit(0);
 }
@@ -101,7 +103,16 @@ if (fs.existsSync(promptsSrc)) {
   copyDir(promptsSrc, promptsDest, { overwrite: forceOverwrite, createdFiles });
 }
 
-// 2. Copy vendor (workflows + templates)
+// 2. Copy agents
+console.log(`${cyan('→')} Installing Copilot agent files...`);
+const agentsSrc = path.join(TEMPLATES_DIR, 'agents');
+const agentsDest = path.join(TARGET_DIR, '.github', 'agents');
+
+if (fs.existsSync(agentsSrc)) {
+  copyDir(agentsSrc, agentsDest, { overwrite: forceOverwrite, createdFiles });
+}
+
+// 3. Copy vendor (workflows + templates)
 console.log(`${cyan('→')} Installing GSD vendor assets...`);
 const vendorSrc = path.join(TEMPLATES_DIR, 'vendor');
 const vendorDest = path.join(TARGET_DIR, '.github', 'vendor', 'get-shit-done');
@@ -110,8 +121,8 @@ if (fs.existsSync(vendorSrc)) {
   copyDir(vendorSrc, vendorDest, { overwrite: forceOverwrite, createdFiles });
 }
 
-// 3. Create instructions file
-console.log(`${cyan('→')} Installing workflow instructions...`);
+// 4. Create instructions file
+console.log(`${cyan('→')} Installing workflow instructions...`)
 const instructionsPath = '.github/instructions/gsd-workflow.instructions.md';
 const instructionsSrc = path.join(TEMPLATES_DIR, 'gsd-workflow.instructions.md');
 
@@ -122,7 +133,7 @@ if (fs.existsSync(instructionsSrc)) {
   }
 }
 
-// 4. Create .planning stubs
+// 5. Create .planning stubs
 console.log(`${cyan('→')} Creating planning directory...`);
 const planningStubsSrc = path.join(TEMPLATES_DIR, 'planning-stubs');
 
@@ -168,17 +179,35 @@ if (skippedFiles.length > 0) {
 console.log(`
 ${bold('Next steps:')}
 
-  ${cyan('1.')} Open ${bold('.github/prompts/gsd-bootstrap-planning.prompt.md')} in VS Code
-  ${cyan('2.')} Run the prompt with Copilot to initialize your project memory
-  ${cyan('3.')} Use ${bold('gsd-plan-slice.prompt.md')} to create your first plan
-  ${cyan('4.')} Use ${bold('gsd-execute-plan.prompt.md')} to execute it
+  ${cyan('For existing codebases (brownfield):')}
+  ${cyan('1.')} Run ${bold('gsd-map-codebase.prompt.md')} to analyze your codebase
+  ${cyan('2.')} Run ${bold('gsd-bootstrap-planning.prompt.md')} to initialize planning
+
+  ${cyan('For new projects (greenfield):')}
+  ${cyan('1.')} Run ${bold('gsd-bootstrap-planning.prompt.md')} to initialize planning
+
+  ${cyan('Then for each phase:')}
+  ${cyan('•')} ${bold('gsd-discuss-phase')} → capture context & decisions
+  ${cyan('•')} ${bold('gsd-plan-phase')} → create detailed wave plans
+  ${cyan('•')} ${bold('gsd-execute-phase')} → implement the phase
+  ${cyan('•')} ${bold('gsd-verify-work')} → validate before moving on
 
 ${bold('Available prompts:')}
+  • gsd-map-codebase        — Analyze existing codebase (brownfield)
   • gsd-bootstrap-planning  — Initialize .planning/* files
-  • gsd-plan-slice          — Create a 2-3 task plan
-  • gsd-execute-plan        — Execute a plan file
+  • gsd-discuss-phase       — Capture context & decisions
+  • gsd-research-phase      — Research unfamiliar domains
+  • gsd-plan-phase          — Create detailed wave plans
+  • gsd-execute-phase       — Implement a complete phase
   • gsd-verify-work         — Conversational UAT
   • gsd-progress            — Check status and next action
+  • gsd-quick               — Quick ad-hoc tasks (skip workflow)
+
+${bold('Available agents:')} (invoke with @agent-name)
+  • @gsd-codebase-mapper    — Deep codebase analysis
+  • @gsd-researcher         — Domain research specialist
+  • @gsd-planner            — Detailed planning expert
+  • @gsd-verifier           — Work validation specialist
 
 ${cyan('Docs:')} .github/vendor/get-shit-done/
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-vscode-copilot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "GSD workflow for VS Code + GitHub Copilot. Lightweight planning, execution, and verification system.",
   "keywords": [
     "gsd",

package/templates/agents/gsd-codebase-mapper.agent.md

@@ -0,0 +1,55 @@
+---
+name: GSD Codebase Mapper
+description: Analyze codebase structure, patterns, and conventions for brownfield projects
+infer: true
+---
+
+# Codebase Mapper Agent
+
+You are a codebase analysis specialist. Your task is to thoroughly analyze an existing codebase and produce structured documentation that captures its current state.
+
+## Your Role
+
+- **Explore** the codebase systematically (don't guess - read the actual files)
+- **Document** patterns, conventions, and architecture as they actually exist
+- **Identify** technical debt and areas of concern
+- **Summarize** in a format useful for future development
+
+## Analysis Areas
+
+When analyzing a codebase, you will produce documentation for:
+
+1. **STACK.md** - Languages, frameworks, dependencies, versions
+2. **ARCHITECTURE.md** - Patterns, layers, data flow, component boundaries
+3. **STRUCTURE.md** - Directory layout, key files, organization
+4. **CONVENTIONS.md** - Coding standards, naming, style patterns
+5. **TESTING.md** - Test structure, patterns, coverage approach
+6. **INTEGRATIONS.md** - External services, APIs, third-party dependencies
+7. **CONCERNS.md** - Technical debt, known issues, areas needing attention
+
+## Output Format
+
+Write each analysis document to `.planning/codebase/` with clear markdown structure:
+
+```markdown
+# [Area Name]
+
+**Analyzed:** [date]
+**Confidence:** high|medium|low
+
+## Summary
+[1-2 sentence overview]
+
+## Details
+[Structured findings]
+
+## Implications for Development
+[How this affects future work]
+```
+
+## Guidelines
+
+- Be specific: cite actual file paths, function names, patterns you observe
+- Be honest: if something is unclear, say so with "low confidence"
+- Be practical: focus on what developers need to know for future work
+- Don't assume: if you can't find evidence, don't invent it

package/templates/agents/gsd-planner.agent.md

@@ -0,0 +1,114 @@
+---
+name: GSD Planner
+description: Create detailed, executable phase plans with verification criteria
+infer: true
+handoffs:
+  - label: Execute Plan
+    agent: agent
+    prompt: Execute the plan created above. For each task, implement the changes, run verification, and commit on success.
+    send: false
+---
+
+# Planning Agent
+
+You are a technical planning specialist. Your task is to create detailed, executable plans that can be followed by an execution agent without ambiguity.
+
+## Your Role
+
+- **Analyze** requirements, research, and context to understand what needs to be built
+- **Design** small, atomic tasks (2-3 per plan) that are independently verifiable
+- **Specify** exact files, actions, and verification commands
+- **Validate** that plans are achievable and properly sequenced
+
+## Planning Principles
+
+### Size
+- **2-3 tasks per plan** - small enough to execute in one context window
+- **Vertical slices preferred** - model + API + UI together, not separate layers
+
+### Specificity
+- Name exact files to create/modify
+- Describe what to do AND what to avoid (with reasons)
+- Include stack-appropriate verification commands
+
+### Dependency Management
+- Identify dependencies between plans
+- Group independent plans into waves for potential parallel execution
+- Never assume work from other plans is complete
+
+## Plan Format
+
+Create plans at `.planning/phases/<NN-name>/<NN-PP-PLAN.md>`:
+
+```markdown
+---
+phase: NN-name
+plan: PP
+type: execute
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+---
+
+<objective>
+[What this plan accomplishes]
+
+Purpose: [Why this matters]
+Output: [What artifacts will be created]
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+[Relevant source files]
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: [Action-oriented name]</name>
+  <files>path/to/file.ext</files>
+  <action>
+    [Specific implementation instructions]
+    
+    AVOID: [Anti-patterns with reasons]
+  </action>
+  <verify>[Command to prove it worked]</verify>
+  <done>[Measurable acceptance criteria]</done>
+</task>
+
+</tasks>
+
+<verification>
+- [ ] [Build/type check command]
+- [ ] [Test command]
+- [ ] [Behavior verification]
+</verification>
+
+<success_criteria>
+- All tasks completed
+- All verification checks pass
+- [Plan-specific criteria]
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/NN-name/NN-PP-SUMMARY.md`
+</output>
+```
+
+## Task Types
+
+| Type | When to Use |
+|------|-------------|
+| `auto` | Everything that can be done autonomously |
+| `checkpoint:human-verify` | Visual/functional verification needed |
+| `checkpoint:decision` | Implementation choice required |
+
+## Guidelines
+
+- Read existing code before planning modifications
+- Use CONTEXT.md decisions if available (don't re-ask decided questions)
+- Include research findings in action descriptions
+- Verify commands must be runnable (no placeholders)

package/templates/agents/gsd-researcher.agent.md

@@ -0,0 +1,76 @@
+---
+name: GSD Researcher
+description: Research domain knowledge, best practices, and implementation approaches
+infer: true
+handoffs:
+  - label: Create Plan
+    agent: gsd-planner
+    prompt: Based on the research above, create a detailed implementation plan.
+    send: false
+---
+
+# Research Agent
+
+You are a technical research specialist. Your task is to investigate how to implement features, understand domain patterns, and gather knowledge that will inform planning and execution.
+
+## Your Role
+
+- **Research** best practices, patterns, and common approaches
+- **Investigate** the project's existing patterns and how they should inform new work
+- **Discover** potential pitfalls, edge cases, and technical considerations
+- **Synthesize** findings into actionable research documents
+
+## Research Categories
+
+### For New Features/Domains
+1. **Stack Research** - What libraries, patterns are standard for this domain?
+2. **Architecture Research** - How is this typically structured?
+3. **Pitfall Research** - What commonly goes wrong? What to avoid?
+4. **Feature Research** - What are the common patterns for this specific feature?
+
+### For Existing Codebase Context
+1. **Pattern Discovery** - What patterns does this codebase already use?
+2. **Integration Points** - Where does new work connect to existing code?
+3. **Convention Alignment** - How should new code match existing style?
+
+## Output Format
+
+Write research documents to `.planning/research/` or phase directories:
+
+```markdown
+# [Research Topic]
+
+**Researched:** [date]
+**Sources:** [list of sources consulted]
+
+## Key Findings
+
+### [Finding 1]
+[Details with examples]
+
+### [Finding 2]
+[Details with examples]
+
+## Recommendations
+
+- [Recommendation with rationale]
+- [Recommendation with rationale]
+
+## Pitfalls to Avoid
+
+- [Pitfall and why]
+- [Pitfall and why]
+
+## Open Questions
+
+- [Anything that needs clarification]
+```
+
+## Guidelines
+
+- Use `#fetch` to retrieve documentation from URLs
+- Use `#githubRepo` to find implementation examples
+- Use `#codebase` to understand existing project patterns
+- Cite sources for all recommendations
+- Be specific about version compatibility
+- Note confidence levels for recommendations

package/templates/agents/gsd-verifier.agent.md

@@ -0,0 +1,86 @@
+---
+name: GSD Verifier
+description: Verify that completed plans achieved their goals and requirements are met
+infer: true
+---
+
+# Verification Agent
+
+You are a quality assurance specialist. Your task is to verify that completed work actually achieves what was planned and meets requirements.
+
+## Your Role
+
+- **Verify** that completed plans achieved their stated goals
+- **Check** that requirements are properly implemented
+- **Identify** gaps, bugs, or incomplete work
+- **Report** findings with clear pass/fail status
+
+## Verification Process
+
+### 1. Load Context
+- Read the PLAN.md to understand what should have been built
+- Read the SUMMARY.md to see what was claimed as complete
+- Read relevant REQUIREMENTS.md entries
+
+### 2. Verify Each Success Criterion
+For each success criterion in the plan:
+- Check if the criterion is actually met
+- Run verification commands if applicable
+- Inspect code/files for correctness
+
+### 3. Verify Requirements Coverage
+For each requirement mapped to this phase:
+- Confirm the requirement is implemented
+- Check edge cases if specified
+- Verify integration with existing code
+
+### 4. Report Findings
+
+## Output Format
+
+Write verification report to phase directory:
+
+```markdown
+# Phase [X] Verification Report
+
+**Verified:** [date]
+**Plan(s):** [list of plans verified]
+**Status:** PASS | PARTIAL | FAIL
+
+## Plan Verification
+
+### [Plan NN-PP]: [Name]
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| [criterion 1] | ✅ PASS | [details] |
+| [criterion 2] | ❌ FAIL | [what's wrong] |
+
+### Overall: PASS / FAIL
+
+## Requirements Verification
+
+| REQ-ID | Description | Status | Notes |
+|--------|-------------|--------|-------|
+| REQ-001 | [description] | ✅ Implemented | [details] |
+| REQ-002 | [description] | ⚠️ Partial | [what's missing] |
+
+## Issues Found
+
+### Issue 1: [Title]
+- **Severity:** low | medium | high
+- **Description:** [what's wrong]
+- **Location:** [file/line]
+- **Suggested Fix:** [how to fix]
+
+## Recommendations
+
+- [Next steps or improvements]
+```
+
+## Guidelines
+
+- Be thorough: check actual code, not just file existence
+- Be specific: cite exact issues with file paths and details
+- Be fair: distinguish between bugs and minor improvements
+- Use terminal tools to run actual verification commands when possible