map-codebase

<purpose> Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .gsd/codebase/ Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary. Output: .gsd/codebase/ folder with 7 structured documents about the codebase state. </purpose> <philosophy> **Why dedicated mapper agents:** - Fresh context per domain (no token contamination) - Agents write documents directly (no context transfer back to orchestrator) - Orchestrator only summarizes what was created (minimal context usage) - Faster execution (agents run simultaneously) **Document quality over length:** Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. **Always include file paths:** Documents are reference material for Copilot when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`. </philosophy> <process> <step name="resolve_model_profile" priority="first"> Read model profile for agent spawning: ```bash MODEL_PROFILE=$(cat .gsd/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced") ``` Default to "balanced" if not set. **Model lookup table:** | Agent | quality | balanced | budget | | ------------------- | ------- | -------- | ------ | | gsd-codebase-mapper | sonnet | haiku | haiku | Store resolved model for use in Task calls below. </step> <step name="check_existing"> Check if .gsd/codebase/ already exists: ```bash ls -la .gsd/codebase/ 2>/dev/null ``` **If exists:** ``` .gsd/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 .gsd/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 .gsd/codebase/ directory: ```bash mkdir -p .gsd/codebase ``` **Expected output files:** - STACK.md (from tech mapper) - INTEGRATIONS.md (from tech mapper) - ARCHITECTURE.md (from arch mapper) - STRUCTURE.md (from arch mapper) - CONVENTIONS.md (from quality mapper) - TESTING.md (from quality mapper) - CONCERNS.md (from concerns mapper) Continue to spawn_agents. </step> <step name="spawn_agents"> Spawn 4 parallel gsd-codebase-mapper agents. Use Task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution. **CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly. **Agent 1: Tech Focus** Task tool parameters: ``` subagent_type: "gsd-codebase-mapper" model: "{mapper_model}" run_in_background: true description: "Map codebase tech stack" ``` Prompt: ``` Focus: tech Analyze this codebase for technology stack and external integrations. Write these documents to .gsd/codebase/: - STACK.md - Languages, runtime, frameworks, dependencies, configuration - INTEGRATIONS.md - External APIs, databases, auth providers, webhooks Explore thoroughly. Write documents directly using templates. Return confirmation only. ``` **Agent 2: Architecture Focus** Task tool parameters: ``` subagent_type: "gsd-codebase-mapper" model: "{mapper_model}" run_in_background: true description: "Map codebase architecture" ``` Prompt: ``` Focus: arch Analyze this codebase architecture and directory structure. Write these documents to .gsd/codebase/: - ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points - STRUCTURE.md - Directory layout, key locations, naming conventions Explore thoroughly. Write documents directly using templates. Return confirmation only. ``` **Agent 3: Quality Focus** Task tool parameters: ``` subagent_type: "gsd-codebase-mapper" model: "{mapper_model}" run_in_background: true description: "Map codebase conventions" ``` Prompt: ``` Focus: quality Analyze this codebase for coding conventions and testing patterns. Write these documents to .gsd/codebase/: - CONVENTIONS.md - Code style, naming, patterns, error handling - TESTING.md - Framework, structure, mocking, coverage Explore thoroughly. Write documents directly using templates. Return confirmation only. ``` **Agent 4: Concerns Focus** Task tool parameters: ``` subagent_type: "gsd-codebase-mapper" model: "{mapper_model}" run_in_background: true description: "Map codebase concerns" ``` Prompt: ``` Focus: concerns Analyze this codebase for technical debt, known issues, and areas of concern. Write this document to .gsd/codebase/: - CONCERNS.md - Tech debt, bugs, security, performance, fragile areas Explore thoroughly. Write document directly using template. Return confirmation only. ``` Continue to collect_confirmations. </step> <step name="collect_confirmations"> Wait for all 4 agents to complete. Read each agent's output file to collect confirmations. **Expected confirmation format from each agent:** ``` ## Mapping Complete **Focus:** {focus} **Documents written:** - `.gsd/codebase/{DOC1}.md` ({N} lines) - `.gsd/codebase/{DOC2}.md` ({N} lines) Ready for orchestrator summary. ``` **What you receive:** Just file paths and line counts. NOT document contents. If any agent failed, note the failure and continue with successful documents. Continue to verify_output. </step> <step name="verify_output"> Verify all documents created successfully: ```bash ls -la .gsd/codebase/ wc -l .gsd/codebase/*.md ``` **Verification checklist:** - All 7 documents exist - No empty documents (each should have >20 lines) If any documents missing or empty, note which agents may have failed. Continue to commit_codebase_map. </step> <step name="commit_codebase_map"> Commit the codebase map: **Check planning config:** ```bash COMMIT_PLANNING_DOCS=$(cat .gsd/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true") git check-ignore -q .gsd 2>/dev/null && COMMIT_PLANNING_DOCS=false ``` **If `COMMIT_PLANNING_DOCS=false`:** Skip git operations **If `COMMIT_PLANNING_DOCS=true` (default):** ```bash git add .gsd/codebase/*.md git commit -m "$(cat <<'EOF' docs: map existing codebase - STACK.md - Technologies and dependencies - ARCHITECTURE.md - System design and patterns - STRUCTURE.md - Directory layout - CONVENTIONS.md - Code style and patterns - TESTING.md - Test structure - INTEGRATIONS.md - External services - CONCERNS.md - Technical debt and issues EOF )" ``` Continue to offer_next. </step> <step name="offer_next"> Present completion summary and next steps. **Get line counts:** ```bash wc -l .gsd/codebase/*.md ``` **Output format:** ``` Codebase mapping complete. Created .gsd/codebase/: - STACK.md ([N] lines) - Technologies and dependencies - ARCHITECTURE.md ([N] lines) - System design and patterns - STRUCTURE.md ([N] lines) - Directory layout and organization - CONVENTIONS.md ([N] lines) - Code style and patterns - TESTING.md ([N] lines) - Test structure and practices - INTEGRATIONS.md ([N] lines) - External services and APIs - CONCERNS.md ([N] lines) - Technical debt and issues --- ## ▶ Next Up **Initialize project** — use codebase context for planning `/new-project.md` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - Re-run mapping: `/map-codebase.md` - Review specific file: `cat .gsd/codebase/STACK.md` - Edit any document before proceeding --- ``` End workflow. </step> </process> <success_criteria> - .gsd/codebase/ directory created - 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true - Agents write documents directly (orchestrator doesn't receive document contents) - Read agent output files to collect confirmations - All 7 codebase documents exist - Clear completion summary with line counts - User offered clear next steps in GSD style </success_criteria>