<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:

code

.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:

code

subagent_type: "gsd-codebase-mapper"
model: "{mapper_model}"
run_in_background: true
description: "Map codebase tech stack"

Prompt:

code

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:

code

subagent_type: "gsd-codebase-mapper"
model: "{mapper_model}"
run_in_background: true
description: "Map codebase architecture"

Prompt:

code

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:

code

subagent_type: "gsd-codebase-mapper"
model: "{mapper_model}"
run_in_background: true
description: "Map codebase conventions"

Prompt:

code

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:

code

subagent_type: "gsd-codebase-mapper"
model: "{mapper_model}"
run_in_background: true
description: "Map codebase concerns"

Prompt:

code

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:

code

## 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:

code

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>