Codebase Summary

Generate comprehensive codebase documentation optimized for AI assistants and developers.

Parameters

Gather all parameters upfront in a single prompt:

Parameter	Default	Description
codebase_path	Current directory	Path to analyze
output_dir	.sop/summary	Documentation output directory
consolidate	false	Create consolidated file at codebase root
consolidate_target	AGENTS.md	Target: AGENTS.md, README.md, or CONTRIBUTING.md
check_consistency	true	Check for cross-document inconsistencies
check_completeness	true	Identify documentation gaps
update_mode	false	Update existing docs based on git changes

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:

Target	Focus
AGENTS.md	AI context, directory structure, coding patterns, testing
README.md	Project overview, installation, usage, getting started
CONTRIBUTING.md	Dev setup, coding standards, contribution workflow

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