feat(02-01): /gsd:map-codebase command and workflow skeleton

- commands/gsd/map-codebase.md: slash command entry point - get-shit-done/workflows/map-codebase.md: workflow with 6 process steps - Documents 4 parallel Explore agents and 7 output files - Agent orchestration to be implemented in plan 02-02
2025-12-17 10:04:17 -06:00
parent c2359cdaf3
commit cfde291637
2 changed files with 314 additions and 0 deletions
--- a/commands/gsd/map-codebase.md
+++ b/commands/gsd/map-codebase.md
@@ -0,0 +1,85 @@
+---
+description: Analyze codebase with parallel Explore agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel Explore agents to produce structured codebase documents.
+
+This command spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context. Each agent produces focused documentation under 100 lines.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/map-codebase.md
+@~/.claude/get-shit-done/templates/codebase/stack.md
+@~/.claude/get-shit-done/templates/codebase/architecture.md
+@~/.claude/get-shit-done/templates/codebase/structure.md
+@~/.claude/get-shit-done/templates/codebase/conventions.md
+@~/.claude/get-shit-done/templates/codebase/testing.md
+@~/.claude/get-shit-done/templates/codebase/integrations.md
+@~/.claude/get-shit-done/templates/codebase/concerns.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel Explore agents to analyze codebase:
+   - Agent 1: Stack + Integrations (technology focus)
+   - Agent 2: Architecture + Structure (organization focus)
+   - Agent 3: Conventions + Testing (quality focus)
+   - Agent 4: Concerns (issues focus)
+4. Wait for all agents to complete, collect findings
+5. Write 7 codebase documents using templates:
+   - STACK.md - Languages, frameworks, key dependencies
+   - ARCHITECTURE.md - System design, patterns, data flow
+   - STRUCTURE.md - Directory layout, module organization
+   - CONVENTIONS.md - Code style, naming, patterns
+   - TESTING.md - Test structure, coverage, practices
+   - INTEGRATIONS.md - APIs, databases, external services
+   - CONCERNS.md - Technical debt, risks, issues
+6. Verify each document is under 100 lines (summarize if needed)
+7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written
+- [ ] Each document under 100 lines
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>
--- a/get-shit-done/workflows/map-codebase.md
+++ b/get-shit-done/workflows/map-codebase.md
@@ -0,0 +1,229 @@
+<purpose>
+Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .planning/codebase/
+
+Each agent has fresh context and focuses on specific aspects. Output is concise (under 100 lines per document) and actionable for planning.
+</purpose>
+
+<philosophy>
+**Why parallel agents:**
+- Fresh context per domain (no token contamination)
+- Thorough analysis without context exhaustion
+- Each agent optimized for its domain (tech vs organization vs quality vs issues)
+- Faster execution (agents run simultaneously)
+
+**Why 100-line limit:**
+Codebase maps are reference material loaded frequently. Concise summaries are more useful than exhaustive inventories. If codebase is large, summarize patterns rather than listing every file.
+</philosophy>
+
+<process>
+
+<step name="check_existing" priority="first">
+Check if .planning/codebase/ already exists:
+
+```bash
+ls -la .planning/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.planning/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .planning/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .planning/codebase/ directory:
+
+```bash
+mkdir -p .planning/codebase
+```
+
+**Expected output files:**
+- STACK.md (from stack.md template)
+- ARCHITECTURE.md (from architecture.md template)
+- STRUCTURE.md (from structure.md template)
+- CONVENTIONS.md (from conventions.md template)
+- TESTING.md (from testing.md template)
+- INTEGRATIONS.md (from integrations.md template)
+- CONCERNS.md (from concerns.md template)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel Explore agents to analyze codebase.
+
+<!-- Agent orchestration implemented in plan 02-02 -->
+
+**Agent 1: Stack + Integrations (Technology Focus)**
+Analyze:
+- Languages and their versions
+- Frameworks and libraries (key dependencies)
+- Build tools and package managers
+- External APIs and services
+- Databases and data stores
+- Third-party integrations
+
+Output: STACK.md, INTEGRATIONS.md
+
+**Agent 2: Architecture + Structure (Organization Focus)**
+Analyze:
+- System architecture and design patterns
+- Data flow and component relationships
+- Directory layout and module organization
+- Entry points and routing
+- State management approach
+- File/folder naming conventions
+
+Output: ARCHITECTURE.md, STRUCTURE.md
+
+**Agent 3: Conventions + Testing (Quality Focus)**
+Analyze:
+- Code style and formatting rules
+- Naming conventions (files, functions, variables)
+- Common patterns and idioms
+- Test structure and organization
+- Coverage and test practices
+- Linting and quality tools
+
+Output: CONVENTIONS.md, TESTING.md
+
+**Agent 4: Concerns (Issues Focus)**
+Analyze:
+- Technical debt and code smells
+- Performance issues or bottlenecks
+- Security concerns
+- Outdated dependencies
+- Missing error handling
+- Documentation gaps
+- Hard-coded values or secrets
+
+Output: CONCERNS.md
+
+<!-- End agent orchestration section -->
+
+Continue to collect_results.
+</step>
+
+<step name="collect_results">
+Wait for all 4 agents to complete.
+
+<!-- Result collection implemented in plan 02-02 -->
+
+Aggregate findings from each agent:
+- Agent 1 findings → STACK.md, INTEGRATIONS.md content
+- Agent 2 findings → ARCHITECTURE.md, STRUCTURE.md content
+- Agent 3 findings → CONVENTIONS.md, TESTING.md content
+- Agent 4 findings → CONCERNS.md content
+
+Verify each document will be under 100 lines. If over, summarize patterns instead of listing exhaustively.
+
+Continue to write_documents.
+</step>
+
+<step name="write_documents">
+Write all 7 codebase documents using templates and agent findings.
+
+**For each document:**
+1. Load template from ~/.claude/get-shit-done/templates/codebase/
+2. Populate with relevant agent findings
+3. Ensure under 100 lines (summarize if needed)
+4. Write to .planning/codebase/
+
+**Document order:**
+1. STACK.md
+2. INTEGRATIONS.md
+3. ARCHITECTURE.md
+4. STRUCTURE.md
+5. CONVENTIONS.md
+6. TESTING.md
+7. CONCERNS.md
+
+After all documents written, continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- Each document under 100 lines
+- No empty documents
+- Templates populated with findings
+
+If any checks fail, report issues to user.
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps:
+
+```
+Codebase mapped to .planning/codebase/
+
+Documents created:
+- STACK.md - Technologies and dependencies
+- INTEGRATIONS.md - External services and APIs
+- ARCHITECTURE.md - System design and patterns
+- STRUCTURE.md - Directory layout and organization
+- CONVENTIONS.md - Code style and patterns
+- TESTING.md - Test structure and practices
+- CONCERNS.md - Technical debt and issues
+
+---
+
+## ▶ Next Up
+
+**Typical workflow:**
+
+```
+/gsd:new-project
+```
+
+Use codebase map to inform project initialization (brownfield project).
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review/edit any codebase documents before proceeding
+- `/gsd:plan-phase N` - Plan specific phase using codebase context
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .planning/codebase/ directory created
+- 4 parallel agents spawned and completed
+- All 7 codebase documents written
+- Each document under 100 lines
+- Documents follow template structure
+- User offered clear next steps
+</success_criteria>