msd-core/get-shit-done/workflows/map-codebase.md

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:

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:

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:

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:

Check planning config:

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations

If COMMIT_PLANNING_DOCS=true (default):

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:

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.

<success_criteria>

• .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 </success_criteria>