codebase-mapper

What this skill does

# Codebase Mapper Knowledge Base

## Purpose

Generate a human-readable project guide for unfamiliar codebases. Output is narrative, didactic material - not technical dumps or AI-oriented analysis. Target audience: a smart colleague on their first day.

## Output Structure

All output goes to `.codebase-map/` in the project root:

```
.codebase-map/
  INDEX.md                    # Entry point with navigable summary
  00-executive-summary.md     # Plain-language summary for anyone (non-technical)
  01-overview.md              # What is this project, who is it for
  02-features.md              # Functional capabilities
  03-tech-stack.md            # Technologies and dependencies
  04-architecture.md          # How code is organized, layers, components
  05-workflows.md             # Main user/system flows with diagrams
  06-data-model.md            # Data structures, entities, relationships
  07-getting-started.md       # Where to start working, key files, dev setup
  08-open-questions.md        # Gaps, unknowns, things to ask the team
  09-project-anatomy.md       # Config files, env vars, scripts, directory tree
  10-configuration-guide.md   # Configuration recipes, operations, troubleshooting
  11-glossary.md              # Domain and technical glossary (plain definitions)
  _internal/
    context-brief.md          # Phase 1 exploration output (internal reference)
    interconnect.md           # Phase 1b structured map: contracts, invariants, domain rules (optional)
```

## Core Principles

### Tone
- Narrative, conversational, didactic
- Write for the audience in the Project Profile (see references/audience-adaptation.md); default to a smart colleague on their first day when no profile exists
- Progressive disclosure: big picture first, then details
- Honest about gaps - never fabricate or speculate

### Content Rules
- Every technical term gets a brief inline explanation on first use
- File paths always included - reference actual code paths for every claim
- Diagrams inline - Mermaid blocks embedded in documents, not separate files
- No AI boilerplate: no "In this document we will...", no "Let's dive in", no trailing summaries

### Diagram Standards
- Use Mermaid syntax exclusively
- Keep diagrams focused - max 15-20 nodes per diagram
- Split complex systems into multiple smaller diagrams
- Use descriptive node labels, not abbreviations
- Supported types: mindmap, flowchart, sequence, erDiagram, block-beta

## Agent Coordination

### Phase 1 - Explore
Single `codebase-explorer` agent reads the project and writes `_internal/context-brief.md`, which leads with a `## Project Profile` (type, audience, register) and a `## Why / Context` dossier.

### Phase 1.5 - Confirm Profile
The `map-codebase` command surfaces the inferred Project Profile and lets the user confirm or adjust it before the writers run. The confirmed profile drives register and depth across all documents.

### Phase 1b - Interconnect Map
Single `senior-review:semantic-interconnect-mapper` agent reads the context brief and writes `_internal/interconnect.md` (contracts, invariants, domain rules, integration hot-spots). Optional: if it fails, the pipeline continues in degraded mode. The `tech-writer`, `flow-writer`, `ops-writer`, and `guide-reviewer` cite this map instead of paraphrasing code.

### Phase 2 - Write
Six parallel writer agents, each reading context-brief.md:
- `overview-writer` - 00-executive-summary.md (plain-language), 01-overview.md, 02-features.md (mindmap)
- `tech-writer` - 03-tech-stack.md, 04-architecture.md (component diagram)
- `flow-writer` - 05-workflows.md, 06-data-model.md (flowcharts, sequence, ER)
- `onboarding-writer` - 07-getting-started.md, 08-open-questions.md
- `ops-writer` - 09-project-anatomy.md (config files, env vars, scripts, directory tree)
- `config-writer` - 10-configuration-guide.md (config recipes, operations, troubleshooting)

### Phase 3 - Review
Single `guide-reviewer` agent reads all documents, adds cross-references, fixes consistency, checks register consistency against the Project Profile, writes `11-glossary.md`, and produces INDEX.md with per-audience reading paths.

## References

Read on demand, not upfront:
- `references/writing-guidelines.md` - voice, tone, structure, audience as a parameter
- `references/audience-adaptation.md` - Project Profile schema, register matrix, archetypes, the "for everyone" rule
- `references/diagram-patterns.md` - Mermaid templates for each document

## Standalone Documentation

Beyond the pipeline, the plugin provides standalone documentation agents:
- `documentation-engineer` - Bottom-up technical documentation from code analysis (API docs, architecture, tutorials, refactoring)
- `doc-humanizer` - Rewrites existing documentation to follow the writing guidelines

Both agents use the same writing guidelines and diagram patterns as the pipeline writers.