codemap

Files (9)

• .my-ai-tools-managed
• SKILL.md
• ARCHITECTURE.md.template · templates/
• CONCERNS.md.template · templates/
• CONVENTIONS.md.template · templates/
• INTEGRATIONS.md.template · templates/
• STACK.md.template · templates/
• STRUCTURE.md.template · templates/
• TESTING.md.template · templates/

SKILL.md (first lines)

## What I do

Analyze your entire codebase and create 7 comprehensive documentation files in `.planning/codebase/`:

- **STACK.md** - Technologies, dependencies, configuration
- **INTEGRATIONS.md** - 3rd party providers, APIs, databases, auth providers
- **ARCHITECTURE.md** - System patterns, layers, data flow
- **STRUCTURE.md** - Directory layout, key locations, naming conventions
- **CONVENTIONS.md** - Code style, patterns, error handling
- **TESTING.md** - Framework, structure, mocking, coverage
- **CONCERNS.md** - Tech debt, bugs, security, performance issues

## When to use me

Use this skill when you need to:

- **Onboard** new developers to understand the codebase quickly
- **Plan** new features with full context of existing patterns
- **Understand** code conventions before making changes
- **Identify** technical debt and areas of concern
- **Document** the current state of the project

## How it works

This skill orchestrates 4 parallel agents, each exploring a specific focus area:

1. **Tech Agent** → Analyzes stack and integrations → STACK.md, INTEGRATIONS.md
2. **Architecture Agent** → Analyzes patterns and structure → ARCHITECTURE.md, STRUCTURE.md
3. **Quality Agent** → Analyzes conventions and testing → CONVENTIONS.md, TESTING.md
4. **Concerns Agent** → Identifies tech debt and issues → CONCERNS.md

Each agent:

- Explores the codebase in a fresh context
- Uses templates from `$SKILL_PATH/templates/`
- Writes documents directly to `.planning/codebase/`
- Returns only confirmation (not document contents)

The orchestrator:

- Creates `.planning/codebase/` directory
- Spawns 4 parallel agents with `run_in_background=true`
- Collects confirmations
- Verifies all documents created
- Commits the codebase map (if configured)

## Process

### Step 1: Check Existing Map

If `.planning/codebase/` already exists, prompt:

```
.planning/codebase/ already exists. What's next?
1. Refresh - Delete existing and remap codebase
2. Update - Keep existing, only update specific documents
3. Skip - Use existing codebase map as-is
```

### Step 2: Create Structure

Create the output directory:

```bash
mkdir -p .planning/codebase
```

### Step 3: Spawn Parallel Agents

Use the `Task` tool with `agent_type="explore"` and `run_in_background=true` for parallel execution.

**Tech Agent:**

```
agent_type: explore
description: Map codebase tech stack
prompt: |
	Focus: tech

	Analyze this codebase for technology stack and external integrations.

	Write these documents to .planning/codebase/:
	- STACK.md - Languages, runtime, frameworks, dependencies, configuration
	- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.
```

**Architecture Agent:**

```
agent_type: explore
description: Map codebase architecture
prompt: |
	Focus: arch

	Analyze this codebase architecture and directory structure.

	Write these documents to .planning/codebase/:
	- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
	- STRUCTURE.md - Directory layout, key locations, naming conventions

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.
```

**Quality Agent:**

```
agent_type: explore
description: Map codebase conventions
prompt: |
	Focus: quality

	Analyze this codebase for coding conventions and testing patterns.

	Write these documents to .planning/codebase/:
	- CONVENTIONS.md - Code style, naming, patterns, error handling

From suwandre/my-codex-config, MIT.

More from suwandre/my-codex-config