gsd-vscode-copilot 1.0.0 → 1.1.0

package/templates/prompts/gsd-map-codebase.prompt.md

@@ -0,0 +1,150 @@
+````prompt
+---
+description: "GSD: Map existing codebase for brownfield projects"
+argument-hint: "Optional: focus area (e.g., 'api', 'auth', 'frontend')"
+agent: gsd-codebase-mapper
+---
+
+Analyze the existing codebase and create structured documentation in `.planning/codebase/`.
+
+## When to Use
+
+- **Before starting work** on an existing codebase you're unfamiliar with
+- **Before `/gsd-bootstrap-planning`** to inform project planning with codebase context
+- **After major changes** to refresh understanding of current state
+- **When onboarding** to understand how things work
+
+## Process
+
+### Step 1: Check Existing Map
+
+```bash
+ls -la .planning/codebase/ 2>/dev/null
+```
+
+If `.planning/codebase/` exists with recent files, ask:
+- "Codebase map exists from [date]. Refresh it, or work with existing?"
+
+### Step 2: Create Directory Structure
+
+```bash
+mkdir -p .planning/codebase
+```
+
+### Step 3: Analyze Codebase
+
+Use subagents to analyze different aspects of the codebase. For each area, spawn a focused analysis:
+
+**Stack Analysis:**
+```
+Use a subagent to analyze the technology stack:
+- Languages and versions
+- Frameworks and libraries
+- Package managers and dependencies
+- Build tools and scripts
+
+Write findings to .planning/codebase/STACK.md
+```
+
+**Architecture Analysis:**
+```
+Use a subagent to analyze the architecture:
+- Directory structure and organization
+- Design patterns in use
+- Data flow between components
+- Entry points and boundaries
+
+Write findings to .planning/codebase/ARCHITECTURE.md
+```
+
+**Conventions Analysis:**
+```
+Use a subagent to analyze coding conventions:
+- Naming patterns (files, functions, variables)
+- Code style and formatting
+- Error handling patterns
+- Documentation style
+
+Write findings to .planning/codebase/CONVENTIONS.md
+```
+
+**Concerns Analysis:**
+```
+Use a subagent to identify concerns:
+- Technical debt
+- Known issues or TODOs
+- Areas needing refactoring
+- Missing tests or documentation
+
+Write findings to .planning/codebase/CONCERNS.md
+```
+
+### Step 4: Create Summary
+
+After all analyses complete, create `.planning/codebase/SUMMARY.md`:
+
+```markdown
+# Codebase Summary
+
+**Mapped:** [date]
+**Focus:** [all | specific area]
+
+## Quick Reference
+
+| Aspect | Key Points |
+|--------|------------|
+| Stack | [primary language, framework] |
+| Architecture | [pattern, e.g., "MVC", "microservices"] |
+| Entry Points | [main files/endpoints] |
+| Test Coverage | [exists/missing, approach] |
+
+## Key Files
+
+- `[path]` - [purpose]
+- `[path]` - [purpose]
+
+## Development Notes
+
+[Critical things to know before making changes]
+
+## Concerns
+
+[Top 3 issues to be aware of]
+```
+
+### Step 5: Next Steps
+
+Report what was created and suggest:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► CODEBASE MAPPED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created:
+- .planning/codebase/STACK.md
+- .planning/codebase/ARCHITECTURE.md
+- .planning/codebase/CONVENTIONS.md
+- .planning/codebase/CONCERNS.md
+- .planning/codebase/SUMMARY.md
+
+▶ Next: Run gsd-bootstrap-planning to initialize project planning
+```
+
+## Output
+
+Creates `.planning/codebase/` with:
+- `STACK.md` - Languages, frameworks, dependencies
+- `ARCHITECTURE.md` - Patterns, layers, data flow
+- `CONVENTIONS.md` - Coding standards, naming patterns
+- `CONCERNS.md` - Technical debt, issues
+- `SUMMARY.md` - Quick reference overview
+
+## Notes
+
+- This prompt uses the `gsd-codebase-mapper` agent for specialized analysis
+- Subagents get fresh context for each analysis area
+- If analyzing a specific area (e.g., "api"), focus documents on that subsystem
+- The codebase map informs subsequent planning prompts
+
+````

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

@@ -0,0 +1,179 @@
+````prompt
+---
+description: "GSD: Plan a phase with research and verification (enhanced)"
+argument-hint: "Phase number (e.g., '2') [--skip-research] [--skip-verify]"
+agent: gsd-planner
+---
+
+Create detailed execution plans for a roadmap phase with integrated research and verification.
+
+## Process Overview
+
+**Default flow:** Research (if needed) → Plan → Verify → Done
+**With flags:** Can skip research or verification steps
+
+## Step 1: Parse Arguments and Load Context
+
+```bash
+cat .planning/ROADMAP.md
+cat .planning/STATE.md
+cat .planning/config.json 2>/dev/null || echo "{}"
+```
+
+Parse the phase number from arguments. Extract phase details from ROADMAP.md.
+
+## Step 2: Check for Existing Context
+
+Look for existing artifacts:
+
+```bash
+# Check for discuss-phase output
+ls .planning/phases/*/[phase]-CONTEXT.md 2>/dev/null
+
+# Check for existing research
+ls .planning/phases/*/[phase]-RESEARCH.md 2>/dev/null
+ls .planning/research/*.md 2>/dev/null
+
+# Check for codebase map
+ls .planning/codebase/SUMMARY.md 2>/dev/null
+```
+
+Load any existing context:
+- **CONTEXT.md** — implementation decisions from `/gsd-discuss-phase`
+- **RESEARCH.md** — domain knowledge from `/gsd-research-phase`
+- **Codebase map** — existing patterns from `/gsd-map-codebase`
+
+## Step 3: Research (if needed)
+
+**Skip if:** `--skip-research` flag OR research already exists
+
+If research is needed, spawn a research subagent:
+
+```
+Use a subagent to research how to implement Phase [X]: [Name].
+
+Focus on:
+- Best practices for [domain]
+- Integration with existing codebase patterns (see .planning/codebase/)
+- Potential pitfalls
+
+Write findings to .planning/phases/[NN-name]/[NN]-RESEARCH.md
+```
+
+## Step 4: Create Phase Directory
+
+```bash
+# Get phase name from ROADMAP.md
+PHASE_NAME=$(grep "Phase [N]:" .planning/ROADMAP.md | head -1 | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+mkdir -p ".planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
+```
+
+## Step 5: Analyze and Plan
+
+Based on phase requirements, break into 2-3 task plans per execution unit.
+
+**Key decisions:**
+- How many plans are needed? (2-3 tasks each)
+- What dependencies exist between plans?
+- Which plans can run in parallel (same wave)?
+
+For each plan, create `.planning/phases/[NN-name]/[NN-PP-PLAN.md]`:
+
+Use the format from `.github/vendor/get-shit-done/templates/phase-prompt.md`
+
+**Frontmatter:**
+```yaml
+---
+phase: NN-name
+plan: PP
+type: execute
+wave: N              # Plans in same wave can run in parallel
+depends_on: []       # Plan IDs this depends on
+files_modified: []   # Files this plan will touch
+autonomous: true     # false if has checkpoints
+---
+```
+
+**Incorporate context:**
+- Reference CONTEXT.md decisions (don't re-ask decided questions)
+- Apply research findings to action descriptions
+- Follow existing codebase conventions
+
+## Step 6: Verify Plans (if not skipped)
+
+**Skip if:** `--skip-verify` flag
+
+After creating plans, verify coverage:
+
+```
+Use a subagent to verify the plans for Phase [X]:
+
+Check:
+1. All phase success criteria from ROADMAP.md are covered
+2. All relevant requirements are addressed
+3. Plans are properly sequenced (dependencies correct)
+4. Verification commands are executable
+5. No gaps or overlaps between plans
+
+Report: PASS with notes, or FAIL with issues to fix
+```
+
+If verification fails, iterate:
+1. Review issues
+2. Update plans
+3. Re-verify
+
+Max 3 iterations, then present for human review.
+
+## Step 7: Present Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PHASE [X] PLANNED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase [X]: [Name]** — [N] plan(s) in [M] wave(s)
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1    | 01, 02 | [objectives] |
+| 2    | 03     | [objective]  |
+
+Research: [Completed | Used existing | Skipped]
+Verification: [Passed | Passed with notes | Skipped]
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Execute Phase [X]**
+
+Run gsd-execute-phase [X]
+
+───────────────────────────────────────────────────────────────
+```
+
+## Output
+
+Creates in `.planning/phases/[NN-name]/`:
+- `[NN]-RESEARCH.md` — domain research (if conducted)
+- `[NN]-01-PLAN.md` — first execution plan
+- `[NN]-02-PLAN.md` — second execution plan (if needed)
+- etc.
+
+## Wave Planning
+
+**Wave 1:** Independent plans that can start immediately
+**Wave 2:** Plans that depend on Wave 1 completion
+**Wave N:** Plans that depend on earlier waves
+
+Within a wave, plans could theoretically run in parallel (if using background agents).
+
+## Tips
+
+- Keep plans small (2-3 tasks, ~50% context usage max)
+- Prefer vertical slices over horizontal layers
+- Include specific verification commands for your stack
+- Reference existing code patterns when modifying existing files
+
+````

package/templates/prompts/gsd-progress.prompt.md

@@ -10,23 +10,23 @@ Read `.planning/STATE.md` and `.planning/ROADMAP.md` and give me a quick status
 
 Tell me (concisely):
 
-1. **Where we are now** (1–2 sentences)
-   - Current phase and plan
+1. **Where we are now** (1-2 sentences)
+   - Current phase and wave
    - What was last completed
+   - Any context files that exist (CONTEXT.md, RESEARCH.md)
 
 2. **What's blocked** (if anything)
-   - Pending decisions
+   - Pending decisions or questions
    - External dependencies
-   - Technical blockers
+   - Technical blockers or concerns
 
 3. **The next best action**
-   - Which prompt to run next
-   - What specific slice to work on
+   - Which prompt or agent to run next
+   - Specific phase/wave to work on
 
 ## If `.planning/` files are missing
 
-Propose the minimal bootstrap steps:
-
+### For New Projects
 ```
 .planning/ not initialized.
 
@@ -39,12 +39,50 @@ This will create:
   - STATE.md
 ```
 
+### For Existing Codebases (Brownfield)
+```
+.planning/ not initialized but codebase exists.
+
+Run: gsd-map-codebase.prompt.md first
+
+This will analyze the codebase and create:
+  - .planning/codebase/STACK.md
+  - .planning/codebase/ARCHITECTURE.md
+  - .planning/codebase/CONVENTIONS.md
+  - .planning/codebase/CONCERNS.md
+
+Then run: gsd-bootstrap-planning.prompt.md
+```
+
+## Workflow Navigation
+
+Based on phase state, suggest the appropriate next step:
+
+| State | Next Action |
+|-------|-------------|
+| Phase not started | `gsd-discuss-phase.prompt.md` to capture context |
+| Context captured | `gsd-research-phase.prompt.md` if complex domain |
+| Ready to plan | `gsd-plan-phase.prompt.md` to create detailed plans |
+| Plans ready | `gsd-execute-phase.prompt.md` to implement |
+| Implementation done | `gsd-verify-work.prompt.md` to validate |
+| Phase complete | Update STATE.md, move to next phase |
+
 ## Format
 
 Keep it short — this is a quick status check, not a full report.
 
 ```
-📍 Status: Phase 2 / Plan 1 complete
-📋 Last: User auth endpoints implemented
-⏭️ Next: Run gsd-plan-slice for "Phase 2 Plan 2: Protected routes"
+📍 Status: Phase 2 / Wave 1 in progress
+📋 Last: User auth endpoints implemented  
+📁 Context: CONTEXT.md ✓ | RESEARCH.md ✗
+⚠️ Blocked: None
+⏭️ Next: Run gsd-execute-phase for "Phase 2 Wave 2: Protected routes"
 ```
+
+## Agent Hints
+
+If the user seems stuck, suggest using specialized agents:
+- **@gsd-codebase-mapper** — Re-analyze codebase after major changes
+- **@gsd-researcher** — Deep dive into unfamiliar technology
+- **@gsd-planner** — Rework a problematic plan
+- **@gsd-verifier** — Validate completed work before proceeding

package/templates/prompts/gsd-quick.prompt.md

@@ -0,0 +1,69 @@
+---
+description: "GSD: Quick task (skip full workflow for small changes)"
+argument-hint: "Describe the quick task or fix"
+agent: ask
+---
+
+# Quick Task Mode
+
+This is for **small, self-contained tasks** that don't warrant the full GSD workflow.
+
+## Examples of appropriate quick tasks:
+- Fix a specific bug
+- Add a small utility function
+- Update configuration
+- Refactor a single file
+- Add a missing test
+
+## NOT appropriate for quick mode:
+- New features spanning multiple files
+- Architectural changes
+- Anything requiring research or discussion
+
+---
+
+## Your Task:
+
+{{input}}
+
+## Instructions:
+
+1. **Analyze** — Understand what's being asked
+2. **Plan briefly** — Mental model, no need for plan files
+3. **Implement** — Make the changes
+4. **Verify** — Run tests/checks if applicable
+5. **Report** — Brief summary of what was done
+
+## Constraints:
+
+- **Keep changes minimal** — Don't refactor unrelated code
+- **Follow existing patterns** — Match the codebase conventions
+- **Test if possible** — Run existing tests to verify
+- **Don't create planning files** — This bypasses the full workflow
+
+## Output Format:
+
+```
+✅ Quick Task Complete
+
+Changed:
+  - path/to/file.ts: [description]
+  - path/to/other.ts: [description]
+
+Verified:
+  - [x] Tests pass / [x] Linter clean / [ ] N/A
+
+Notes:
+  [Any important observations]
+```
+
+## If the task is too big:
+
+Stop and suggest using the full workflow instead:
+
+```
+⚠️ This task is too complex for quick mode.
+
+Recommended: Run gsd-discuss-phase.prompt.md to capture context,
+then gsd-plan-phase.prompt.md to create a proper plan.
+```

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

@@ -0,0 +1,184 @@
+````prompt
+---
+description: "GSD: Research domain/implementation before planning"
+argument-hint: "Phase number or specific topic (e.g., '3' or 'OAuth implementation')"
+agent: gsd-researcher
+---
+
+Research how to implement a phase or topic before creating plans.
+
+## When to Use
+
+- **Complex/unfamiliar domains** — 3D, audio, ML, specialized protocols
+- **Architecture decisions** — need to understand patterns before committing
+- **Integration work** — connecting to new APIs or services
+- **Before planning** — when you need to understand the landscape first
+
+## Process
+
+### Step 1: Load Context
+
+```bash
+cat .planning/PROJECT.md
+cat .planning/ROADMAP.md
+cat .planning/STATE.md
+```
+
+If a phase number is provided, extract the phase details from ROADMAP.md.
+If a topic is provided, focus research on that topic.
+
+### Step 2: Identify Research Questions
+
+Based on the phase/topic, identify what needs to be researched:
+
+```
+Researching: [Phase X: Name] or [Topic]
+
+Key questions to investigate:
+1. [Question about technology/approach]
+2. [Question about patterns/best practices]
+3. [Question about potential pitfalls]
+4. [Question about integration points]
+
+Shall I proceed, or add/modify questions?
+```
+
+### Step 3: Conduct Research
+
+For each question, use available tools:
+
+- `#fetch` — retrieve documentation from URLs
+- `#githubRepo` — find implementation examples
+- `#codebase` — understand existing project patterns
+- `#search` — general web search for approaches
+
+Use subagents for parallel research when investigating multiple areas:
+
+```
+Use a subagent to research [specific question]. Return:
+- Key findings with sources
+- Recommended approach
+- Pitfalls to avoid
+```
+
+### Step 4: Create Research Document
+
+Write `.planning/research/[TOPIC]-RESEARCH.md` or `.planning/phases/[NN-name]/[NN]-RESEARCH.md`:
+
+```markdown
+# [Topic/Phase] Research
+
+**Researched:** [date]
+**Status:** Complete
+**Confidence:** high | medium | low
+
+## Overview
+
+[1-2 paragraph summary of findings]
+
+## Key Findings
+
+### [Finding 1: Topic]
+
+[Details with examples and sources]
+
+**Source:** [URL or reference]
+
+### [Finding 2: Topic]
+
+[Details with examples and sources]
+
+**Source:** [URL or reference]
+
+## Recommended Approach
+
+Based on research, the recommended approach is:
+
+1. [Step/decision with rationale]
+2. [Step/decision with rationale]
+3. [Step/decision with rationale]
+
+**Why this approach:**
+- [Reason]
+- [Reason]
+
+## Alternatives Considered
+
+| Approach | Pros | Cons | Why Not |
+|----------|------|------|---------|
+| [Alt 1] | [pros] | [cons] | [reason] |
+| [Alt 2] | [pros] | [cons] | [reason] |
+
+## Pitfalls to Avoid
+
+- **[Pitfall 1]:** [What to avoid and why]
+- **[Pitfall 2]:** [What to avoid and why]
+
+## Integration with Existing Code
+
+[How this connects to existing patterns in the codebase]
+
+## Open Questions
+
+- [Anything that couldn't be resolved through research]
+
+## Sources
+
+- [URL 1] — [description]
+- [URL 2] — [description]
+```
+
+### Step 5: Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Topic:** [topic/phase]
+**Confidence:** [high/medium/low]
+**Key Recommendation:** [1-liner]
+
+Created: .planning/[path]/[NAME]-RESEARCH.md
+
+▶ Next: Run gsd-plan-phase to create execution plans
+
+───────────────────────────────────────────────────────────────
+```
+
+## Output
+
+Creates research document with:
+- Key findings with sources
+- Recommended approach with rationale
+- Alternatives considered
+- Pitfalls to avoid
+- Integration notes
+
+## Special Research Prompts
+
+### For Project Research (like original GSD)
+
+When researching before a new project, investigate:
+
+**Stack:** "What's the standard stack for [domain]?"
+**Features:** "What are typical features of [product type]?"
+**Architecture:** "How is [domain] typically structured?"
+**Pitfalls:** "What commonly goes wrong in [domain] projects?"
+
+### For Library/API Research
+
+Focus on:
+- Official documentation
+- Version compatibility
+- Common usage patterns
+- Known issues/limitations
+
+### For Pattern Research
+
+Focus on:
+- Established patterns (not novel approaches)
+- Real-world examples
+- Trade-offs between approaches
+
+````