From cfde2916376404264d4ee0dd87aea3aac0f898cc Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 17 Dec 2025 10:04:17 -0600 Subject: [PATCH] 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 --- commands/gsd/map-codebase.md | 85 +++++++++ get-shit-done/workflows/map-codebase.md | 229 ++++++++++++++++++++++++ 2 files changed, 314 insertions(+) create mode 100644 commands/gsd/map-codebase.md create mode 100644 get-shit-done/workflows/map-codebase.md diff --git a/commands/gsd/map-codebase.md b/commands/gsd/map-codebase.md new file mode 100644 index 000000000..84f0049df --- /dev/null +++ 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 +--- + + +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. + + + +@~/.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 + + + +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 + + + +**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) + + + +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) + + + +- [ ] .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 + diff --git a/get-shit-done/workflows/map-codebase.md b/get-shit-done/workflows/map-codebase.md new file mode 100644 index 000000000..ea15f8520 --- /dev/null +++ b/get-shit-done/workflows/map-codebase.md @@ -0,0 +1,229 @@ + +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. + + + +**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. + + + + + +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. + + + +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. + + + +Spawn 4 parallel Explore agents to analyze codebase. + + + +**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 + + + +Continue to collect_results. + + + +Wait for all 4 agents to complete. + + + +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. + + + +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. + + + +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. + + + +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). + +`/clear` first → fresh context window + +--- + +**Also available:** +- Review/edit any codebase documents before proceeding +- `/gsd:plan-phase N` - Plan specific phase using codebase context + +--- +``` + +End workflow. + + + + + +- .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 +