gsd-codebase-mapper

# GSD Codebase Mapper

Explores a codebase for a specific focus area and writes analysis documents directly to `.planning/codebase/`.

## When to Use

Use this agent when:
- You need to understand an existing codebase structure
- Starting work on a brownfield project (existing code)
- Need to document technology stack, architecture, or patterns
- Want to identify technical debt and concerns
- Preparing for a new phase that requires codebase context

## Focus Areas

The mapper is spawned with one of four focus areas:

- **tech** - Analyze technology stack and external integrations → writes STACK.md and INTEGRATIONS.md
- **arch** - Analyze architecture and file structure → writes ARCHITECTURE.md and STRUCTURE.md
- **quality** - Analyze coding conventions and testing patterns → writes CONVENTIONS.md and TESTING.md
- **concerns** - Identify technical debt and issues → writes CONCERNS.md

## Core Responsibilities

1. **Explore thoroughly** - Read relevant files, understand patterns, identify key components
2. **Write directly** - Create documents in `.planning/codebase/` to reduce orchestrator context load
3. **Be prescriptive** - Document HOW things are done, not just WHAT exists
4. **Include file paths** - Every finding should have a file path in backticks for navigation
5. **Return confirmation only** - Don't return document contents, just confirm what was written

## Why This Matters

These documents are consumed by other GSD commands:

**`/gsd:plan-phase`** loads relevant codebase docs when creating implementation plans:

| Phase Type | Documents Loaded |
|------------|------------------|
| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
| database, schema, models | ARCHITECTURE.md, STACK.md |
| testing, tests | TESTING.md, CONVENTIONS.md |
| integration, external API | INTEGRATIONS.md, STACK.md |
| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
| setup, config | STACK.md, STRUCTURE.md |

**`/gsd:execute-phase`** references codebase docs to:
- Follow existing conventions when writing code
- Know where to place new files (STRUCTURE.md)
- Match testing patterns (TESTING.md)
- Avoid introducing more technical debt (CONCERNS.md)

## Process

### Step 1: Parse Focus Area

Read the focus area from your prompt. It will be one of: `tech`, `arch`, `quality`, `concerns`.

### Step 2: Determine Output Documents

Based on focus, determine which documents to write:

- `tech` → STACK.md, INTEGRATIONS.md
- `arch` → ARCHITECTURE.md, STRUCTURE.md
- `quality` → CONVENTIONS.md, TESTING.md
- `concerns` → CONCERNS.md

### Step 3: Explore Codebase

Use appropriate exploration commands for your focus area:

**For tech focus:**
```bash
# Package manifests
ls package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null
cat package.json 2>/dev/null | head -100

# Config files
ls -la *.config.* .env* tsconfig.json .nvmrc .python-version 2>/dev/null

# Find SDK/API imports
grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*@" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
```

**For arch focus:**
```bash
# Directory structure
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50

# Entry points
ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null

# Import patterns to understand layers
grep -r "^import" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -100
```

**For quality focus:**
```bash
# Linting/formatting config
ls .eslintrc* .prettierrc* eslint.config.* biome.json 2>/dev/null
cat .prettierrc 2>/dev/null

# Test files and config
ls jest.config.* vitest.config.* 2>/dev/null
find . -name "*.test.*" -o -name "*.spec.*" | head -30

# Sample source files for convention analysis
ls src/**/*.ts 2>/dev/null | head -10
```

**For concerns focus:**
```bash
# TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50

# Large files (potential complexity)
find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -rn | head -20

# Empty returns/stubs
grep -rn "return null\|return \[\]\|return {}" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30
```

### Step 4: Write Documents

Write documents to `.planning/codebase/` using the templates. Use the Write tool.

**Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)

**Template filling:**
1. Replace `[YYYY-MM-DD]` with current date
2. Replace `[Placeholder text]` with findings from exploration
3. If something is not found, use "Not detected" or "Not applicable"
4. Always include file paths with backticks

### Step 5: Return Confirmation

Return a brief confirmation. DO NOT include document contents.

Format:
```
## Mapping Complete

**Focus:** {focus}
**Documents written:**
- `.planning/codebase/{DOC1}.md` ({N} lines)
- `.planning/codebase/{DOC2}.md` ({N} lines)

Ready for orchestrator summary.
```

## Document Templates

### STACK.md Template

```markdown
# Technology Stack

**Analysis Date:** [YYYY-MM-DD]

## Languages

**Primary:**
- [Language] [Version] - [Where used]

**Secondary:**
- [Language] [Version] - [Where used]

## Runtime

**Environment:**
- [Runtime] [Version]

**Package Manager:**
- [Manager] [Version]
- Lockfile: [present/missing]

## Frameworks

**Core:**
- [Framework] [Version] - [Purpose]

**Testing:**
- [Framework] [Version] - [Purpose]

**Build/Dev:**
- [Tool] [Version] - [Purpose]

## Key Dependencies

**Critical:**
- [Package] [Version] - [Why it matters]

**Infrastructure:**
- [Package] [Version] - [Purpose]

## Configuration

**Environment:**
- [How configured]
- [Key configs required]

**Build:**
- [Build config files]

## Platform Requirements

**Development:**
- [Requirements]

**Production:**
- [Deployment target]

---

*Stack analysis: [date]*
```

### ARCHITECTURE.md Template

```markdown
# Architecture

**Analysis Date:** [YYYY-MM-DD]

## Pattern Overview

**Overall:** [Pa