Reference Files

Workflow & Process:

• workflow.md — Detailed orchestration and guidance

Core Templates (always use):

• assets/stack.md — STACK.md
• assets/architecture.md — ARCHITECTURE.md
• assets/structure.md — STRUCTURE.md
• assets/conventions.md — CONVENTIONS.md

Optional Templates (use as applicable):

• assets/testing.md — TESTING.md (if tests exist)
• assets/integrations.md — INTEGRATIONS.md (if external services)
• assets/concerns.md — CONCERNS.md (if complex project)

---

Map Codebase

Analyzes existing codebases using parallel Explore agents to produce structured documentation in .planning/codebase/.

Objective

Spawns multiple Explore agents to analyze different aspects of the codebase in parallel, each with fresh context. Results are structured documents in .planning/ that provide a comprehensive map of the codebase state.

Core Output (always generated):

• STACK.md — Languages, frameworks, key dependencies
• ARCHITECTURE.md — System design, patterns, data flow
• STRUCTURE.md — Directory layout, module organization
• CONVENTIONS.md — Code style, naming, patterns

Optional Output (generate as applicable):

• TESTING.md — Test structure, coverage, practices (if tests exist)
• INTEGRATIONS.md — APIs, databases, external services (if external dependencies exist)
• CONCERNS.md — Technical debt, risks, issues (for complex/brownfield projects)

When to Use

Use map-codebase for:

• Brownfield projects before initialization — understand existing code first
• Refreshing codebase map after significant changes
• Onboarding to an unfamiliar codebase
• Before major refactoring — understand current state thoroughly
• When STATE.md references outdated codebase info — refresh understanding

Skip map-codebase for:

• Greenfield projects with no code yet — nothing to map
• Trivial codebases (<5 files) — not worth the overhead

Process

Step 1: Check Existing Documents

Check if codebase documents already exist in .planning/:

• If yes: Offer to refresh (overwrite) or skip
• If no: Proceed with creation

Step 2: Determine Template Set

Ask user which optional templates to generate (or use defaults):

• Always: STACK.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md
• Optional: TESTING.md (if tests exist), INTEGRATIONS.md (if external services), CONCERNS.md (if complex project)

Step 3: Load Project Context

Check for .planning/STATE.md to load existing project context if available. Helps agents understand project-specific terminology and patterns.

Step 4: Process Focus Area Argument

If user provided a focus area (e.g., "api" or "auth"), instruct agents to pay special attention to that subsystem while still providing holistic analysis.

Step 5: Spawn Parallel Explore Agents

Launch 4 Explore agents in parallel, each with "very thorough" exploration level:

Agent 1: Technology Stack & Integrations

• Focus: Languages, frameworks, dependencies, external services
• Outputs: Data for STACK.md and INTEGRATIONS.md

Agent 2: Architecture & Structure

• Focus: System design, patterns, directory organization
• Outputs: Data for ARCHITECTURE.md and STRUCTURE.md

Agent 3: Conventions & Testing

• Focus: Code style, naming patterns, test infrastructure
• Outputs: Data for CONVENTIONS.md and TESTING.md

Agent 4: Concerns & Technical Debt

• Focus: Issues, risks, technical debt, potential improvements
• Outputs: Data for CONCERNS.md

Step 6: Collect Agent Findings

Wait for all agents to complete. Collect and organize findings by document type.

Step 7: Write Core Documents

Write 4 core markdown documents in .planning/:

STACK.md: Languages, versions, frameworks, build tools, key dependencies
ARCHITECTURE.md: System design, patterns, component relationships, data flow
STRUCTURE.md: Directory layout, modules, naming patterns, organization
CONVENTIONS.md: Code style, naming conventions, patterns, documentation

Step 8: Write Optional Documents (if selected)

Generate only selected optional documents:

TESTING.md (if applicable): Test frameworks, structure, coverage, practices
INTEGRATIONS.md (if applicable): External APIs, databases, third-party services, config
CONCERNS.md (if applicable): Tech debt, issues, security, performance, improvements

Step 9: Provide Next Steps

Inform user codebase mapping is complete:

• Review generated documents in .planning/
• Use findings to inform refactoring or development
• Update STATE.md with new insights if needed

Success Criteria

• 4 core documents created in .planning/ (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS)
• Optional documents created based on user selection
• All documents have substantive, actionable content
• Documents follow template structure
• Parallel agents completed without errors
• User informed of completion and next steps

Integration Notes

Command Integration:

• Invoked via /map-codebase [optional: focus-area] command
• Focus area argument is passed to agents for targeted analysis

Project Lifecycle:

• Can run before initial project setup on brownfield codebases
• Can run after initial project setup to refresh as code evolves
• Can run anytime to refresh codebase understanding