---
name: comprehensive-codebase-map
description: Use when the colony needs a complete multi-perspective map of a complex codebase
type: colony
domains: [codebase, analysis, mapping]
agent_roles: [surveyor-provisions, surveyor-nest, surveyor-disciplines, surveyor-pathogens, architect, scout]
workflow_triggers: [colonize]
task_keywords: [map, architecture, layout, disciplines, provisions, pathogens]
priority: normal
version: "1.0"
---

# Comprehensive Codebase Map

## Purpose

Comprehensive codebase analysis using 4 parallel specialist agents that each produce focused documents. Together, these 7 documents give the colony complete understanding of the codebase -- its structure, flows, surfaces, risks, and conventions.

## When to Use

- User says "map the codebase" or "full analysis"
- Colony needs deep understanding before major planning
- Onboarding to a complex existing codebase
- After significant changes to verify understanding is current
- Pre-milestone planning on large projects

## Instructions

### 1. Specialist Agent Dispatch

Launch 4 parallel analysis agents:

**Agent A -- Architect Analyst:**
```
Produces:
  1. ARCHITECTURE.md -- System design, module boundaries, dependency graph
  2. DATA-FLOWS.md   -- How data moves through the system
```

**Agent B -- API Cataloger:**
```
Produces:
  3. API-SURFACES.md  -- All public APIs, endpoints, interfaces
  4. INTEGRATIONS.md  -- External services, third-party connections
```

**Agent C -- Quality Scout:**
```
Produces:
  5. CONVENTIONS.md   -- Code style, naming patterns, architectural decisions
  6. TECH-DEBT.md     -- Prioritized debt inventory with severity
```

**Agent D -- Risk Assessor:**
```
Produces:
  7. RISK-MAP.md      -- Security, performance, and maintainability risks
```

### 2. Mapping Protocol

Each agent follows this protocol:

```
PHASE 1 -- Reconnaissance:
  Scan directory structure, identify file types, count modules
  
PHASE 2 -- Deep Read:
  Read source files relevant to their specialty
  Extract patterns, relationships, and anomalies
  
PHASE 3 -- Analysis:
  Cross-reference findings with other agents' domains
  Identify gaps and contradictions
  
PHASE 4 -- Document:
  Write structured findings to .aether/data/codebase/
```

### 3. Convergence

After all agents complete:

```
1. Merge agent findings into unified understanding
2. Resolve any contradictions between agent reports
3. Generate cross-references between documents
4. Produce CODEBASE-SUMMARY.md -- executive overview
5. Update codebase intelligence index
6. Emit mapping-complete pheromone
```

### 4. Document Formats

Each document follows:
```
# {Document Title}

## Overview
{One paragraph summary}

## Detailed Findings
{Structured findings}

## Cross-References
{Links to related documents}

## Recommendations
{Action items based on findings}

## Metadata
{Scan date, file count, agent ID}
```

### 5. Incremental Mapping

```
If prior mapping exists:
  1. Read previous documents
  2. Detect files changed since last mapping
  3. Only re-analyze changed files and affected modules
  4. Merge updated findings with existing documents
  5. Highlight deltas in each document
```

## Key Patterns

- **Parallel, not sequential**: All 4 agents run simultaneously.
- **Specialists, not generalists**: Each agent focuses on its domain deeply.
- **Cross-referenced**: Documents link to each other for navigation.
- **Incremental**: Re-mapping only touches what changed.

## Output Format

```
 MAPPING COMPLETE -- {project_name}
   Agents dispatched: 4
   Documents produced: 7 + 1 summary
   Files analyzed: {count}
   Duration: {time}
   
   Documents:
    ARCHITECTURE.md  -- {module_count} modules mapped
    DATA-FLOWS.md    -- {flow_count} data flows traced
    API-SURFACES.md  -- {api_count} APIs cataloged
    INTEGRATIONS.md  -- {integration_count} integrations found
    CONVENTIONS.md   -- {pattern_count} patterns identified
    TECH-DEBT.md     -- {debt_count} items ({critical} critical)
    RISK-MAP.md      -- {risk_count} risks assessed
   
   Location: .aether/data/codebase/
```

## Examples

**Full mapping:**
> "4 agents completed in 45 seconds. 7 documents produced. 142 files analyzed. Key finding: circular dependency between auth and user modules. Risk: 2 critical security items in API surfaces."

**Incremental update:**
> "Re-mapping after phase 3 changes. 12 files changed. Updated ARCHITECTURE.md and API-SURFACES.md. 3 new APIs cataloged, 2 deprecated APIs removed."