codebase-analysis

Codebase Analysis Workflow

Execute a structured 3-phase codebase analysis workflow to gather insights.

Accept the following inputs:

• analysis-context (optional): What to analyze and why. Defaults to "general codebase understanding" if not provided.

Phase Overview

1. Deep Analysis — Explore and synthesize codebase findings via the deep-analysis skill
2. Reporting — Present structured analysis to the user
3. Post-Analysis Actions — Save, document, or retain analysis insights

Phase 1: Deep Analysis

Goal: Explore the codebase and synthesize findings.

1. Determine analysis context:
2. If analysis-context input is provided, use it as the analysis context
3. If no input, set context to "general codebase understanding"

1. Check for cached results:
2. Check if .agents/sessions/exploration-cache/manifest.md exists
3. If found, read the manifest and verify: codebase_path matches the current working directory, and timestamp is within the configured cache TTL (default 24 hours)
4. If cache is valid, prompt the user to choose:
5. Use cached results (show the formatted cache date) — Read cached synthesis from .agents/sessions/exploration-cache/synthesis.md and recon from recon_summary.md. Set CACHE_HIT = true and CACHE_TIMESTAMP to the cache's timestamp. Skip step 3 and proceed directly to step 4.
6. Run fresh analysis — Remove the cache manifest file, set CACHE_HIT = false, and proceed to step 3
7. If no valid cache: set CACHE_HIT = false and proceed to step 3

1. Run deep-analysis workflow:
2. Refer to the deep-analysis skill for the full exploration and synthesis workflow.
3. Pass the analysis context from step 1
4. This handles reconnaissance, team planning, approval (auto-approved when skill-invoked), team creation, parallel exploration (code-explorer agents), and synthesis (code-synthesizer agent)
5. After completion, set CACHE_TIMESTAMP = null (fresh results, no prior cache)

1. Verify results and capture metadata:
2. Ensure the synthesis covers the analysis context adequately
3. If critical gaps remain, search for files and file contents to fill them directly
4. Record analysis metadata for Phase 2 reporting: whether results were cached (CACHE_HIT), cache timestamp if applicable (CACHE_TIMESTAMP), and the number of explorer agents used (from the deep-analysis team plan, or 0 if cached)

Phase 2: Reporting

Goal: Present a structured analysis to the user.

1. Load diagram guidance:
2. Refer to the technical-diagrams skill for Mermaid diagram syntax and styling rules.
3. Use Mermaid diagrams in the Architecture Overview and Relationship Map sections

1. Use the report template (see Report Template section below) to structure the presentation.

1. Present the analysis:

Structure the report with these sections:

• Executive Summary — Lead with the most important finding
• Architecture Overview — How the codebase is structured
• Tech Stack — Core technologies, frameworks, and tools detected
• Critical Files — The 5-10 most important files with details
• Patterns & Conventions — Recurring patterns and coding conventions
• Relationship Map — How components connect to each other
• Challenges & Risks — Technical risks and complexity hotspots
• Recommendations — Actionable next steps, each citing the challenge it addresses
• Analysis Methodology — Agents used, cache status, scope, and duration

1. Proceed immediately to Phase 3.

Do NOT stop here. Do NOT wait for user input. The report is presented, but the workflow requires Post-Analysis Actions. Continue directly to Phase 3 now.

Phase 3: Post-Analysis Actions

Goal: Let the user save, document, or retain analysis insights from the report through a multi-step interactive flow.

Step 1: Select actions

Prompt the user to choose (the user may select multiple options):

• Save Codebase Analysis Report — Write the structured report to a markdown file
• Save a custom report — Generate a report tailored to your specific goals (you'll provide instructions next)
• Update project documentation — Add/update README.md, CLAUDE.md, or AGENTS.md with analysis insights
• Keep a condensed summary in memory — Retain a quick-reference summary in conversation context

If the user selects no actions, the workflow is complete. Thank the user and end.

Step 2: Execute selected actions

Process selected actions in the following fixed order. Complete all sub-steps for each action before moving to the next.

Action: Save Codebase Analysis Report

Step 2a-1: Prompt for file location

• Check if an internal/docs/ directory exists in the project root
• If yes, suggest default path: internal/docs/codebase-analysis-report-{YYYY-MM-DD}.md
• If no, suggest default path: codebase-analysis-report-{YYYY-MM-DD}.md in the project root
• Prompt the user to confirm or customize the file path

Step 2a-2: Generate and save the report

• Use the report template already loaded in Phase 2 Step 1
• Generate the full structured report using the Phase 2 analysis findings and the template structure
• Create the file at the confirmed path
• Confirm the file was saved

Action: Save Custom Report

Step 2b-1: Gather report requirements

• Prompt the user to describe the goals and requirements for their custom report — what it should focus on, what questions it should answer, and any format preferences

Step 2b-2: Prompt for file location

• Check if an internal/docs/ directory exists in the project root
• If yes, suggest default path: internal/docs/custom-report-{YYYY-MM-DD}.md
• If no, suggest default path: custom-report-{YYYY-MM-DD}.md in the project root
• Prompt the user to confirm or customize the file path

Step 2b-3: Generate and save the custom report

• Generate a report shaped by the user's requirements from Step 2b-1, drawing from the Phase 2 analysis data — this is a repackaging of existing findings, not a re-analysis
• Create the file at the confirmed path
• Confirm the file was saved

Action: Update Project Documentation

Step 2c-1: Select documentation files and gather directions

Prompt the user to choose (the user may select multiple options):

• README.md — Add architecture, structure, and tech stack information
• CLAUDE.md — Add patterns, conventions, critical files, and architectural decisions
• AGENTS.md — Add agent descriptions, capabilities, and coordination patterns

Then prompt the user for update directions for all selected files: "What content from the analysis should be added or updated? Provide general directions or specific sections to focus on (applies across all selected files, or specify per-file directions)."

Step 2c-2: Generate and approve documentation drafts

For each selected file, read the existing file and generate a draft based on the user's directions and Phase 2 analysis data:

• README.md: Read existing file at project root. If no README.md exists, skip and inform the user. Draft updates focusing on architecture, project structure, and tech stack.
• CLAUDE.md: Read existing file at project root. If none exists, ask if one should be created (if declined, skip). Draft updates focusing on patterns, conventions, critical files, and architectural decisions.
• AGENTS.md: Read existing file at project root (create new if none exists). Draft content focusing on agent inventory (name, model, purpose), capabilities and tool access, coordination patterns, skill-agent mappings, and model tiering rationale.

Present all drafts together in a single output, clearly labeled by file. Then prompt the user to choose:

• Apply all — Apply all drafted updates
• Modify — Specify which file(s) to revise and what to change (max 3 revision cycles, then must Apply or Skip)
• **S