gsd-vscode-copilot 1.0.0 → 1.1.0

package/templates/gsd-workflow.instructions.md

@@ -1,13 +1,25 @@
 ---
-description: "GSD-style workflow for VS Code + GitHub Copilot (planning + execution)"
+description: "GSD-style workflow for VS Code + GitHub Copilot (enhanced with agents and subagents)"
 applyTo: "**"
 ---
 
-# GSD-Style Workflow (VS Code + Copilot)
+# GSD Workflow (VS Code + GitHub Copilot)
 
-This repo uses a lightweight GSD (Get Shit Done) workflow for planning and execution.
+This repo uses an enhanced GSD (Get Shit Done) workflow for planning and execution.
 It provides **context hygiene, atomic plans, explicit verification, and disciplined checkpoints**.
 
+## Quick Start
+
+```
+1. gsd-map-codebase          — Analyze existing code (brownfield projects)
+2. gsd-bootstrap-planning    — Initialize .planning/ files
+3. gsd-discuss-phase [N]     — Capture implementation decisions
+4. gsd-plan-phase [N]        — Create detailed plans
+5. gsd-execute-phase [N]     — Execute plans
+6. gsd-verify-work [N]       — Manual UAT
+7. Repeat for each phase
+```
+
 ## Planning Artifacts (Repository Memory)
 
 Maintain these files under `.planning/`:
@@ -18,51 +30,138 @@ Maintain these files under `.planning/`:
 | `REQUIREMENTS.md` | v1/v2/out-of-scope requirements (checkable) |
 | `ROADMAP.md` | Phases/slices with links to plan IDs |
 | `STATE.md` | Current position, decisions, blockers, next action |
+| `config.json` | Workflow preferences (optional) |
 
-## Execution Rules
+### Additional Artifacts
 
-- Prefer automation: if it can be done via CLI/tooling, do it.
-- Plans must be small: **2–3 tasks max** per plan file.
-- Every task must include:
-  - **Action**: what to do and what to avoid (and why)
-  - **Verify**: exact command(s) / checks to prove it worked
-  - **Done**: measurable acceptance criteria
-- Stop for checkpoints only when unavoidable:
-  - human verification (UI/UX),
-  - human decision (architecture/product choice),
-  - auth gates (login/consent needed).
+| Directory | Purpose |
+|-----------|---------|
+| `codebase/` | Codebase analysis (from gsd-map-codebase) |
+| `research/` | Domain research documents |
+| `phases/` | Phase directories with plans, context, summaries |
 
-## Plan Format
+## Custom Agents
 
-- Location: `.planning/phases/<NN-name>/<NN-NN-PLAN.md>`
-- Structure: YAML frontmatter + XML tasks (see vendor templates)
-- Reference: `.github/vendor/get-shit-done/templates/phase-prompt.md`
+GSD includes specialized agents for different tasks. Install to `.github/agents/`:
 
-## Workflow Prompts
+| Agent | Purpose |
+|-------|---------|
+| `gsd-codebase-mapper` | Analyze existing codebase structure |
+| `gsd-researcher` | Research domain knowledge and best practices |
+| `gsd-planner` | Create detailed execution plans |
+| `gsd-verifier` | Verify completed work meets goals |
+
+### Using Agents
+
+Switch to an agent in the Chat view agent picker, or reference via prompts.
+
+## Subagents for Fresh Context
 
-Use the prompt files in `.github/prompts/`:
+GSD prompts use subagents for operations that need fresh context:
+
+```
+Use a subagent to [task description].
+Return: [what to report back]
+```
+
+Enable `runSubagent` in your tools. Subagents:
+- Get their own context window (no pollution)
+- Run to completion autonomously
+- Return only final results to main session
+
+## Workflow Prompts
 
 | Prompt | When to use |
 |--------|-------------|
+| `gsd-map-codebase.prompt.md` | Analyze existing codebase (brownfield) |
 | `gsd-bootstrap-planning.prompt.md` | Initialize `.planning/*` for a new project |
-| `gsd-plan-slice.prompt.md` | Create a 2–3 task plan for the next slice |
-| `gsd-execute-plan.prompt.md` | Execute a plan file |
+| `gsd-discuss-phase.prompt.md` | Capture implementation decisions before planning |
+| `gsd-research-phase.prompt.md` | Research complex domains or approaches |
+| `gsd-plan-phase.prompt.md` | Create detailed execution plans for a phase |
+| `gsd-execute-phase.prompt.md` | Execute all plans in a phase |
 | `gsd-verify-work.prompt.md` | Conversational UAT after execution |
 | `gsd-progress.prompt.md` | Check current status and next action |
 
+### Legacy Prompts (still available)
+
+| Prompt | Notes |
+|--------|-------|
+| `gsd-plan-slice.prompt.md` | Simpler planning (2-3 tasks) |
+| `gsd-execute-plan.prompt.md` | Execute single plan file |
+
+## Execution Rules
+
+- **Prefer automation:** if it can be done via CLI/tooling, do it
+- **Plans must be small:** 2–3 tasks max per plan file
+- **Fresh context per major task:** use subagents for complex operations
+- **One commit per task:** atomic, reversible commits
+
+### Task Requirements
+
+Every task must include:
+- **Action:** what to do and what to avoid (and why)
+- **Verify:** exact command(s) / checks to prove it worked
+- **Done:** measurable acceptance criteria
+
+### Checkpoint Types
+
+Stop for checkpoints only when unavoidable:
+- `checkpoint:human-verify` — UI/UX verification
+- `checkpoint:decision` — architecture/product choice
+- `checkpoint:human-action` — truly unavoidable manual steps
+
+## Wave-Based Execution
+
+Plans are organized into waves:
+- **Wave 1:** Independent plans that can start immediately
+- **Wave 2:** Plans that depend on Wave 1
+- **Wave N:** Plans that depend on earlier waves
+
+Within a wave, plans can potentially run in parallel using background agents.
+
+## Background Agents
+
+For long-running or parallel work, use Copilot CLI background agents:
+
+```
+@cli [task description]
+```
+
+Background agents:
+- Run in isolated Git worktrees
+- Can work while you continue other tasks
+- Merge results when complete
+
 ## STATE.md Discipline
 
-Whenever you:
-- make a decision,
-- discover a constraint,
-- hit a blocker,
-- finish a slice,
+Record in `.planning/STATE.md` whenever you:
+- Make a decision
+- Discover a constraint
+- Hit a blocker
+- Finish a slice
+
+Always include the **next action**.
+
+## Plan Format
+
+- Location: `.planning/phases/<NN-name>/<NN-PP-PLAN.md>`
+- Structure: YAML frontmatter + XML tasks
+- Reference: `.github/vendor/get-shit-done/templates/phase-prompt.md`
+
+## Git Commit Conventions
 
-…record it in `.planning/STATE.md` with the next action.
+```bash
+# One commit per task
+feat(NN-PP): [task description]
+fix(NN-PP): [fix description]
+test(NN-PP): [test description]
+docs(NN-PP): [docs description]
+refactor(NN-PP): [refactor description]
+```
 
-## Verification Conventions
+Commit immediately after verification passes.
 
-Adapt verification commands to your stack:
+## Verification Commands by Stack
 
 | Stack | Example verify commands |
 |-------|------------------------|
@@ -72,4 +171,34 @@ Adapt verification commands to your stack:
 | Go | `go build ./...`, `go test ./...` |
 | Rust | `cargo build`, `cargo test` |
 
-Plans carry the specific verify commands — the workflow is stack-agnostic.
+Plans carry specific verify commands — the workflow is stack-agnostic.
+
+## File Structure
+
+```
+.planning/
+├── PROJECT.md
+├── REQUIREMENTS.md
+├── ROADMAP.md
+├── STATE.md
+├── config.json
+├── codebase/           # From gsd-map-codebase
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── CONVENTIONS.md
+│   ├── CONCERNS.md
+│   └── SUMMARY.md
+├── research/           # Domain research
+│   └── [TOPIC]-RESEARCH.md
+└── phases/
+    ├── 01-foundation/
+    │   ├── 01-CONTEXT.md
+    │   ├── 01-RESEARCH.md
+    │   ├── 01-01-PLAN.md
+    │   ├── 01-01-SUMMARY.md
+    │   └── 01-VERIFICATION.md
+    └── 02-core-features/
+        ├── 02-CONTEXT.md
+        ├── 02-01-PLAN.md
+        └── 02-01-SUMMARY.md
+```

package/templates/prompts/gsd-discuss-phase.prompt.md

@@ -0,0 +1,178 @@
+````prompt
+---
+description: "GSD: Discuss phase details before planning (capture implementation decisions)"
+argument-hint: "Phase number or name (e.g., '2' or 'authentication')"
+agent: ask
+---
+
+Gather context and capture implementation decisions for a phase before planning begins.
+
+## Purpose
+
+Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned.
+
+The output — `CONTEXT.md` — feeds directly into:
+1. **Researcher** — knows what patterns to investigate
+2. **Planner** — knows what decisions are locked
+
+## Process
+
+### Step 1: Load Phase Context
+
+Read the planning files:
+
+```bash
+cat .planning/ROADMAP.md
+cat .planning/STATE.md
+```
+
+If no phase specified, ask which phase to discuss.
+
+### Step 2: Analyze Phase for Gray Areas
+
+Based on what's being built, identify decision points. Different feature types have different gray areas:
+
+**Visual/UI Features:**
+- Layout and density (cards vs lists, compact vs spacious)
+- Interactions (hover states, animations, transitions)
+- Empty states and loading states
+- Responsive behavior
+- Accessibility considerations
+
+**APIs/Backend:**
+- Response format and structure
+- Error handling approach
+- Authentication/authorization patterns
+- Rate limiting, pagination
+- Logging and observability
+
+**Data/Content Systems:**
+- Content structure and organization
+- Naming conventions
+- Validation rules
+- Migration approach for existing data
+
+**Infrastructure/DevOps:**
+- Deployment strategy
+- Environment configuration
+- Monitoring and alerting
+- Rollback procedures
+
+### Step 3: Present Gray Areas
+
+Present the identified gray areas and ask which to discuss:
+
+```
+I've identified these decision points for Phase [X]: [Name]
+
+**Must Decide:**
+1. [Gray area 1] — affects [what downstream]
+2. [Gray area 2] — affects [what downstream]
+
+**Optional/Nice to Clarify:**
+3. [Gray area 3]
+4. [Gray area 4]
+
+Which would you like to discuss? (comma-separated numbers, or "all")
+```
+
+### Step 4: Deep-Dive Each Selected Area
+
+For each selected gray area, have a focused conversation:
+
+1. **Ask** about preferences and constraints
+2. **Probe** for specifics ("What should happen when...?")
+3. **Confirm** understanding
+4. **Move on** when satisfied or user says "that's enough"
+
+Example dialogue:
+```
+User: Let's discuss layout
+Assistant: For the [feature], I see a few layout approaches:
+- Cards in a grid (visual, scannable)
+- Table rows (dense, sortable)
+- List with previews (balanced)
+
+What feels right for your use case? Any references to point me at?
+```
+
+### Step 5: Create CONTEXT.md
+
+After discussion, create the context file in the phase directory:
+
+```bash
+mkdir -p ".planning/phases/[NN-name]"
+```
+
+Write `.planning/phases/[NN-name]/[NN]-CONTEXT.md`:
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor]
+
+## Implementation Decisions
+
+### [Category 1 that was discussed]
+- [Decision or preference captured]
+- [Another decision if applicable]
+
+### [Category 2 that was discussed]
+- [Decision or preference captured]
+
+### Claude's Discretion
+[Anything explicitly left as "your choice" during discussion]
+
+## Open Questions
+[Anything that still needs clarification, if any]
+
+## References
+[Any examples, links, or inspirations mentioned]
+```
+
+### Step 6: Update STATE.md
+
+Add a note about context gathering:
+```
+**Context Gathered:** Phase [X] - [summary of key decisions]
+```
+
+### Step 7: Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE [X] CONTEXT CAPTURED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Decisions captured:** [count]
+**Ready for:** Planning
+
+▶ Next: Run gsd-plan-phase to create execution plans
+   Or: Run gsd-research-phase if domain research needed first
+
+───────────────────────────────────────────────────────────────
+```
+
+## Output
+
+Creates `.planning/phases/[NN-name]/[NN]-CONTEXT.md` with:
+- Phase boundary (scope)
+- Implementation decisions by category
+- Areas left to Claude's discretion
+- Open questions
+- References
+
+## Tips
+
+- This is conversational — no code is written
+- Be specific: "card layout" not "whatever looks good"
+- Mention anti-patterns: "definitely NOT a modal"
+- Share references: "like how GitHub does it"
+- It's OK to say "your choice" for things you don't care about
+
+````

package/templates/prompts/gsd-execute-phase.prompt.md

@@ -0,0 +1,253 @@
+````prompt
+---
+description: "GSD: Execute all plans in a phase with wave-based execution"
+argument-hint: "Phase number (e.g., '2')"
+agent: agent
+---
+
+Execute all plans in a phase using wave-based execution.
+
+## Process Overview
+
+1. Discover all plans for the phase
+2. Group plans by wave (from frontmatter)
+3. Execute waves sequentially
+4. Within each wave, execute plans (can use subagents for isolation)
+5. Verify phase completion
+6. Update state and create summaries
+
+## Step 1: Load Phase Context
+
+```bash
+# Get phase details
+cat .planning/ROADMAP.md
+cat .planning/STATE.md
+
+# Find the phase directory
+ls .planning/phases/ | grep "^0*[PHASE]-"
+```
+
+## Step 2: Discover Plans
+
+```bash
+# List all plans for this phase
+ls .planning/phases/[NN-name]/*-PLAN.md
+```
+
+Parse frontmatter from each plan to extract:
+- `wave` — execution order
+- `depends_on` — dependencies
+- `autonomous` — whether checkpoints exist
+
+Group plans by wave number.
+
+## Step 3: Execute Wave by Wave
+
+For each wave (starting with wave 1):
+
+### Present Wave
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WAVE [N] — [count] plan(s)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Plans in this wave:
+- [NN-01]: [objective]
+- [NN-02]: [objective]
+```
+
+### Execute Plans in Wave
+
+**Option A: Sequential (default)**
+Execute each plan in order, providing fresh context for complex plans:
+
+```
+For plan [NN-PP]:
+Use a subagent to execute this plan. The subagent should:
+1. Read the full plan file
+2. Execute each task sequentially
+3. Run verification after each task
+4. Stop on checkpoint tasks and report back
+5. Create SUMMARY.md when complete
+```
+
+**Option B: Parallel with Background Agents**
+For truly independent plans, suggest using background agents:
+
+```
+These plans are independent. You can:
+1. Execute sequentially here (default)
+2. Run in parallel using @cli for isolated execution
+
+Choose approach:
+```
+
+### Per-Task Execution
+
+For each task in a plan:
+
+**`type="auto"` tasks:**
+1. Implement the changes described in `<action>`
+2. Run the `<verify>` command(s)
+3. If verification fails: stop and report with proposed fixes
+4. If verification passes: confirm `<done>` criteria met
+5. Commit changes:
+   ```bash
+   git add [files]
+   git commit -m "[type]([phase]-[plan]): [task-name]"
+   ```
+
+**`type="checkpoint:*"` tasks:**
+1. STOP immediately
+2. Display checkpoint message with what's needed
+3. Wait for user response before continuing
+
+### After Each Plan
+
+Create summary file `.planning/phases/[NN-name]/[NN-PP-SUMMARY.md]`:
+
+```markdown
+# Phase [X] Plan [Y]: [Name] Summary
+
+**Completed:** [timestamp]
+**Duration:** [time]
+
+## Accomplishments
+- [What was built]
+
+## Files Created/Modified
+- `path/to/file` - What it does
+
+## Decisions Made
+[Key decisions, or "None - followed plan as specified"]
+
+## Issues Encountered
+[Problems and resolutions, or "None"]
+
+## Verification Results
+- [x] [Verification check 1]
+- [x] [Verification check 2]
+```
+
+## Step 4: Wave Transition
+
+After completing a wave:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WAVE [N] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Completed: [list plans completed]
+Commits: [count]
+
+Next: Wave [N+1] with [count] plans
+```
+
+Continue to next wave.
+
+## Step 5: Phase Verification
+
+After all waves complete, verify phase goals:
+
+```
+Use a subagent with the gsd-verifier agent to verify Phase [X]:
+
+Check all success criteria from ROADMAP.md.
+Report PASS/FAIL with details.
+```
+
+Create `.planning/phases/[NN-name]/[NN]-VERIFICATION.md` with results.
+
+## Step 6: Update State
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: [X] - COMPLETE
+- Plans executed: [list]
+- Next: Phase [X+1]
+
+## Recent Decisions
+[Any decisions made during execution]
+```
+
+Update `.planning/ROADMAP.md`:
+- Mark phase as complete
+- Update progress indicators
+
+## Step 7: Present Completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE [X] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase [X]: [Name]**
+
+| Metric | Value |
+|--------|-------|
+| Plans | [N] executed |
+| Waves | [M] completed |
+| Commits | [K] created |
+| Verification | PASS / PARTIAL / FAIL |
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase [X+1]: [Name]** — [goal]
+
+Options:
+- Run gsd-discuss-phase [X+1] — gather context first
+- Run gsd-plan-phase [X+1] — plan directly
+- Run gsd-verify-work [X] — manual UAT for this phase
+
+───────────────────────────────────────────────────────────────
+```
+
+## Git Commit Strategy
+
+**One commit per task:**
+```bash
+# Type based on what changed
+feat([phase]-[plan]): [task description]
+fix([phase]-[plan]): [fix description]
+test([phase]-[plan]): [test description]
+docs([phase]-[plan]): [docs description]
+refactor([phase]-[plan]): [refactor description]
+```
+
+**Commit immediately after verification passes** — don't batch.
+
+## Error Handling
+
+**If a task fails verification:**
+1. Report the failure with error details
+2. Propose fixes
+3. Ask: "Retry with fix, or stop for manual intervention?"
+
+**If a plan fails completely:**
+1. Mark plan as failed
+2. Save partial progress
+3. Report what succeeded and what failed
+4. Ask whether to continue with next plan or stop
+
+## Background Agent Integration
+
+For long-running or parallelizable phases, suggest:
+
+```
+This phase has [N] independent plans in wave 1.
+
+You can use @cli to run them as background agents:
+- Each gets isolated worktree
+- All run in parallel
+- Merge results when complete
+
+Use background agents? (yes/no)
+```
+
+If yes, hand off to background agent sessions.
+
+````