| name | map-codebase |
| description | Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .gsd/codebase/ with 7 structured documents. |
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.
**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.
Read model profile for agent spawning:
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.
Check if .gsd/codebase/ already exists:
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.
Create .gsd/codebase/ directory:
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.
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.
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.
Verify all documents created successfully:
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.
Commit the codebase map:
Check planning config:
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):
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.
Present completion summary and next steps.
Get line counts:
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.
<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>
