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

Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .planning/codebase/

Each agent has fresh context and focuses on specific aspects. Output is concise (under 100 lines per document) and actionable for planning.

**Why parallel agents:** - Fresh context per domain (no token contamination) - Thorough analysis without context exhaustion - Each agent optimized for its domain (tech vs organization vs quality vs issues) - Faster execution (agents run simultaneously)

Why 100-line limit: Codebase maps are reference material loaded frequently. Concise summaries are more useful than exhaustive inventories. If codebase is large, summarize patterns rather than listing every file.

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 stack.md template)
• ARCHITECTURE.md (from architecture.md template)
• STRUCTURE.md (from structure.md template)
• CONVENTIONS.md (from conventions.md template)
• TESTING.md (from testing.md template)
• INTEGRATIONS.md (from integrations.md template)
• CONCERNS.md (from concerns.md template)

Continue to spawn_agents.

Spawn 4 parallel Explore agents to analyze codebase.

Agent 1: Stack + Integrations (Technology Focus) Analyze:

• Languages and their versions
• Frameworks and libraries (key dependencies)
• Build tools and package managers
• External APIs and services
• Databases and data stores
• Third-party integrations

Output: STACK.md, INTEGRATIONS.md

Agent 2: Architecture + Structure (Organization Focus) Analyze:

• System architecture and design patterns
• Data flow and component relationships
• Directory layout and module organization
• Entry points and routing
• State management approach
• File/folder naming conventions

Output: ARCHITECTURE.md, STRUCTURE.md

Agent 3: Conventions + Testing (Quality Focus) Analyze:

• Code style and formatting rules
• Naming conventions (files, functions, variables)
• Common patterns and idioms
• Test structure and organization
• Coverage and test practices
• Linting and quality tools

Output: CONVENTIONS.md, TESTING.md

Agent 4: Concerns (Issues Focus) Analyze:

• Technical debt and code smells
• Performance issues or bottlenecks
• Security concerns
• Outdated dependencies
• Missing error handling
• Documentation gaps
• Hard-coded values or secrets

Output: CONCERNS.md

Continue to collect_results.

Wait for all 4 agents to complete.

Aggregate findings from each agent:

• Agent 1 findings → STACK.md, INTEGRATIONS.md content
• Agent 2 findings → ARCHITECTURE.md, STRUCTURE.md content
• Agent 3 findings → CONVENTIONS.md, TESTING.md content
• Agent 4 findings → CONCERNS.md content

Verify each document will be under 100 lines. If over, summarize patterns instead of listing exhaustively.

Continue to write_documents.

Write all 7 codebase documents using templates and agent findings.

For each document:

1. Load template from ~/.claude/get-shit-done/templates/codebase/
2. Populate with relevant agent findings
3. Ensure under 100 lines (summarize if needed)
4. Write to .planning/codebase/

Document order:

1. STACK.md
2. INTEGRATIONS.md
3. ARCHITECTURE.md
4. STRUCTURE.md
5. CONVENTIONS.md
6. TESTING.md
7. CONCERNS.md

After all documents written, continue to verify_output.

Verify all documents created successfully:

ls -la .planning/codebase/
wc -l .planning/codebase/*.md

Verification checklist:

• All 7 documents exist
• Each document under 100 lines
• No empty documents
• Templates populated with findings

If any checks fail, report issues to user.

Continue to offer_next.

Present completion summary and next steps:

Codebase mapped to .planning/codebase/

Documents created:
- STACK.md - Technologies and dependencies
- INTEGRATIONS.md - External services and APIs
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout and organization
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure and practices
- CONCERNS.md - Technical debt and issues

---

## ▶ Next Up

**Typical workflow:**

/gsd:new-project

Use codebase map to inform project initialization (brownfield project).

<sub>`/clear` first → fresh context window</sub>

---

**Also available:**
- Review/edit any codebase documents before proceeding
- `/gsd:plan-phase N` - Plan specific phase using codebase context

---

End workflow.

<success_criteria>

• .planning/codebase/ directory created
• 4 parallel agents spawned and completed
• All 7 codebase documents written
• Each document under 100 lines
• Documents follow template structure
• User offered clear next steps </success_criteria>