Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/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: .planning/codebase/ folder with 7 structured documents about the codebase state. **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 Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`. 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 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. Spawn 4 parallel gsd-codebase-mapper agents. Use Task tool with `subagent_type="gsd-codebase-mapper"` 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" 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 .planning/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" run_in_background: true description: "Map codebase architecture" ``` Prompt: ``` Focus: arch Analyze this codebase architecture and directory structure. Write these documents to .planning/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" run_in_background: true description: "Map codebase conventions" ``` Prompt: ``` Focus: quality Analyze this codebase for coding conventions and testing patterns. Write these documents to .planning/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" 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 .planning/codebase/: - CONCERNS.md - Tech debt, bugs, security, performance, fragile areas Explore thoroughly. Write document directly using template. Return confirmation only. ``` Continue to 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:** - `.planning/codebase/{DOC1}.md` ({N} lines) - `.planning/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. Verify all documents created successfully: ```bash ls -la .planning/codebase/ wc -l .planning/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. Commit the codebase map: ```bash git add .planning/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. Present completion summary and next steps. **Get line counts:** ```bash wc -l .planning/codebase/*.md ``` **Output format:** ``` Codebase mapping complete. Created .planning/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 `/gsd:new-project` <sub>`/clear` first → fresh context window</sub> --- **Also available:** - Re-run mapping: `/gsd:map-codebase` - Review specific file: `cat .planning/codebase/STACK.md` - Edit any document before proceeding --- ``` End workflow. - .planning/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