name: codebase-summary description: Analyze a codebase and generate comprehensive documentation including architecture, components, interfaces, workflows, and dependencies. Creates an AI-optimized knowledge base (index.md) and can consolidate into AGENTS.md, README.md, or CONTRIBUTING.md. Use when the user wants to document a codebase, create AGENTS.md, understand system architecture, generate developer documentation, or asks to "summarize the codebase".

Codebase Summary

Generate comprehensive codebase documentation optimized for AI assistants and developers.

Parameters

Gather all parameters upfront in a single prompt:

Workflow

Step 1: Setup

1. Validate codebase_path exists
2. Create output_dir if needed
3. If update_mode and index.md exists:
   • Run git log --oneline -20 to identify recent changes
   • Focus analysis on modified components

Step 2: Analyze Structure

Run the structure analyzer:

python {baseDir}/scripts/analyze_structure.py "{codebase_path}" --depth 4 --output "{output_dir}/codebase_info.md"

Run the dependency extractor:

python {baseDir}/scripts/extract_dependencies.py "{codebase_path}" --output "{output_dir}/dependencies.md"

Then manually analyze:

• Identify packages, modules, major components
• Map architectural patterns (MVC, microservices, etc.)
• Find key interfaces, APIs, entry points

Step 3: Generate Documentation

Create these files in {output_dir}/:

index.md - Primary AI context file:

• AI instructions for using the documentation
• Quick reference table mapping questions to files
• Table of contents with summaries for each file
• Brief codebase overview

architecture.md:

• System architecture with Mermaid graph diagram
• Layer descriptions
• Design patterns used
• Key design decisions with rationale

components.md:

• Component overview with Mermaid classDiagram
• Per-component: purpose, location, key files, dependencies, interface

interfaces.md:

• API endpoints with request/response formats
• Internal interfaces and implementations
• Error codes and handling

data_models.md:

• ER diagram with Mermaid erDiagram
• Per-model: table, fields, indexes, relationships

workflows.md:

• Key processes with Mermaid sequenceDiagram
• Step-by-step breakdowns
• Error handling

See {baseDir}/references/documentation-templates.md for templates.

Step 4: Review

If check_consistency:

• Verify terminology consistency across documents
• Check cross-references are valid

If check_completeness:

• Identify undocumented components
• Note gaps from language/framework limitations

Save findings to {output_dir}/review_notes.md.

Step 5: Consolidate (if enabled)

If consolidate is true:

1. Create file at codebase root (not in output_dir)
2. Use consolidate_target as filename
3. Tailor content to target:

Default AGENTS.md prompt: Focus on information NOT in README.md or CONTRIBUTING.md—file purposes, directory structure, coding patterns, testing instructions, package guidance.

Step 6: Summary

Report:

1. What was documented
2. Next steps for using documentation
3. How to add index.md to AI assistant context
4. If update_mode: summarize detected changes

Output Structure

{consolidate_target}           # At codebase root if consolidate=true
{output_dir}/
├── index.md                   # Primary AI context (read this first)
├── codebase_info.md          # Structure analysis output
├── architecture.md           # System architecture
├── components.md             # Component details
├── interfaces.md             # APIs and interfaces
├── data_models.md            # Data models
├── workflows.md              # Key workflows
├── dependencies.md           # Dependencies output
└── review_notes.md           # Review findings

Progress Indicators

Provide updates:

Setting up...
✅ Created {output_dir}

Analyzing structure...
✅ Found X packages across Y languages
✅ Identified Z components

Generating documentation...
✅ Created index.md
✅ Generated architecture.md, components.md...

Reviewing...
✅ Consistency check complete
✅ Found N gaps documented in review_notes.md

Done!
✅ Documentation at {output_dir}
✅ Primary context file: {output_dir}/index.md

Resources

• Scripts: {baseDir}/scripts/analyze_structure.py, {baseDir}/scripts/extract_dependencies.py
• Templates: {baseDir}/references/documentation-templates.md