Codemap

Codemap

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 runs four focus passes. Use parallel file-reading and file-writing workers when the runtime provides them. If suitable workers are unavailable, perform the same passes sequentially in the current context:

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

Each pass:

• Explores the codebase for its focus
• Uses templates from $SKILL_PATH/templates/
• Writes documents directly to .planning/codebase/
• Returns only confirmation (not document contents)

The orchestrator:

• Creates .planning/codebase/ directory
• Runs the four passes in parallel only when suitable workers are available
• Otherwise runs those passes sequentially in the current context
• Collects confirmations
• Verifies all documents created
• Commits the codebase map (if configured)

Process

Scope and Runtime

Accept an optional --paths <p1,p2,...> for an incremental map. Validate repository-relative prefixes before use: reject absolute paths, .. components, and shell metacharacters (;, backticks, $, &, |, <, >). If no supplied path is valid, stop and ask for a corrected scope; do not silently expand to the whole repository. Pass the same normalized scope to every mapper and every sequential pass. Do not interpolate unchecked input into shell commands.

Use the actual current date for all analysis-date placeholders. For scoped refreshes, retain documented information outside the scope and state which prefixes were rechecked.

Use parallel agents only when the runtime supports file-reading and file-writing workers. Do not assume an explore agent can write files or use a browser agent as a code mapper. If suitable workers are unavailable, perform the four focus passes sequentially in the current context, using the same scope and templates. Do not require GSD-specific SDK commands or agent types.

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:

mkdir -p .planning/codebase

Step 3: Run the Four Focus Passes

Run the passes in parallel only when the runtime supports file-reading and file-writing workers. Otherwise perform them sequentially in the current context. Parallel workers are optional, not required. Each pass must receive the validated scope, current date, and the appropriate template paths from $SKILL_PATH/templates/. The examples below describe assignments, not mandatory API parameter names. While a parallel worker is active, do not duplicate its exploration or write its documents.

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
	- TESTING.md - Framework, structure, mocking, coverage

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

Concerns Agent:

agent_type: explore
description: Map codebase concerns
prompt: |
	Focus: concerns

	Analyze this codebase for technical debt, known issues, and areas of concern.

	Write this document to .planning/codebase/:
	- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas

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