# Multi-Agent Codebase Map

> Inspired by [GSD's map-codebase](https://github.com/gsd-build/get-shit-done) (MIT, Copyright (c) 2025 Lex Christopherson). Adapted with distinct output format and rewritten agent prompts. Full attribution: [NOTICES.md](../../../NOTICES.md).

## Purpose

Analyze an existing codebase across 5 dimensions in parallel. Produces structured, evidence-based reports with exact file path citations, optimized for consumption by BMAD planning agents.

## Output Location

All outputs go to `{project-root}/{output_folder}/codebase-analysis/`.

## Relationship to bmad-document-project

Complementary, not a replacement. `bmad-document-project` generates comprehensive human-readable docs. This skill generates structured analysis optimized for downstream LLM consumption. Run this first, then `bmad-document-project` for full documentation.

---

## Step 1 — Prepare

<action>Create output directory `{output_folder}/codebase-analysis` (use your native file-create tool; it will create parent directories as needed). The first `Write` tool call targeting a file inside this directory will auto-create it, so no explicit mkdir is required in practice.</action>
<action>Determine project root absolute path: `{{project_root}}`</action>

<action>Note: each agent reads `{{project_root}}/.gitignore` and `{{project_root}}/.aiexclude` (if present) and treats every listed file/directory as off-limits. The `scan.js` helper applies these patterns automatically; agents apply them to their Glob/Grep operations as well. This prevents inclusion of build artifacts, vendored code, secrets, and explicitly AI-excluded paths in the analysis.</action>

---

## Step 2 — Launch 5 Analysis Agents in Parallel

Launch ALL FIVE agents in a **single message** using the Agent tool.

<critical>
All 5 Agent calls MUST be in the same message to run in parallel.
Each agent writes its output file directly.
Each agent must cite exact file paths for every finding.
Each agent has specific exploration commands to run — they are self-sufficient.
</critical>

### Agent 1: Stack Analyzer

```
Agent(
  description: "Technology stack analysis",
  prompt: <read from ./agents/stack-analyzer.md, set project_root={{project_root}}, output_file={{project_root}}/{output_folder}/codebase-analysis/stack-analysis.md>
)
```

### Agent 2: Architecture Mapper

```
Agent(
  description: "Architecture pattern analysis",
  prompt: <read from ./agents/architecture-mapper.md, set project_root and output_file=architecture-analysis.md>
)
```

### Agent 3: Quality Assessor

```
Agent(
  description: "Code quality assessment",
  prompt: <read from ./agents/quality-assessor.md, set project_root and output_file=quality-analysis.md>
)
```

### Agent 4: Concerns Hunter

```
Agent(
  description: "Tech debt and concerns scan",
  prompt: <read from ./agents/concerns-hunter.md, set project_root and output_file=concerns-analysis.md>
)
```

### Agent 5: Integration Mapper

```
Agent(
  description: "External integration mapping",
  prompt: <read from ./agents/integration-mapper.md, set project_root and output_file=integrations-analysis.md>
)
```

---

## Step 3 — Collect and Verify

<action>Verify all 5 output files exist in `{output_folder}/codebase-analysis/`:
- `stack-analysis.md`
- `architecture-analysis.md`
- `quality-analysis.md`
- `concerns-analysis.md`
- `integrations-analysis.md`
</action>

<action>If any agent failed, log which one and note the gap. Do not re-run — present partial results.</action>

---

## Step 4 — Summary

<action>Read all 5 output files and produce a brief summary:

```markdown
## Codebase Analysis Complete

| Dimension | File | Key Findings |
|-----------|------|-------------|
| Stack | stack-analysis.md | {languages}, {frameworks}, {package count} |
| Architecture | architecture-analysis.md | {pattern}, {module count} |
| Quality | quality-analysis.md | {test coverage}, {lint status} |
| Concerns | concerns-analysis.md | {critical count}, {high count} |
| Integrations | integrations-analysis.md | {external service count} |

Outputs: `{output_folder}/codebase-analysis/`

Recommended next steps:
- `sprintpilot-assess` — deep-dive tech debt and migration assessment
- `sprintpilot-reverse-architect` — extract formal architecture document
- `bmad-create-prd` — informed by codebase analysis
```
</action>