Codebase Analysis Workflow

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

Phase Overview

1. Deep Analysis — Explore and synthesize codebase findings via 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:

   • If arguments are provided, use them as the analysis context
   • If no arguments, set context to "general codebase understanding"

2. Check for cached results:

   • Check if .agents/sessions/exploration-cache/manifest.md exists
   • 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)
   • If cache is valid, prompt the user to choose:
     • 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.
     • Run fresh analysis — Remove the cache manifest file, set CACHE_HIT = false, and proceed to step 3
   • If no valid cache: set CACHE_HIT = false and proceed to step 3

3. Run deep-analysis workflow:

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

4. Verify results and capture metadata:

   • Ensure the synthesis covers the analysis context adequately
   • If critical gaps remain, search for files and file contents to fill them directly
   • 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:

   • Refer to the technical-diagrams skill for Mermaid diagram conventions and styling rules.
   • Use Mermaid diagrams in the Architecture Overview and Relationship Map sections

2. Load report template:

   • Use the Report Template below to structure the presentation

3. 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

4. Proceed immediately to Phase 3.

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 (multiple selections allowed):

• 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
• Generate the full structured report using the Phase 2 analysis findings and the template structure
• Write the report to 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
• Write the report to 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 (multiple selections allowed):

• 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)
• Skip all — Skip all documentation updates

If approved, apply updates to the files.

Action: Keep Insights in Memory

• Present a condensed Codebase Quick Reference inline in the conversation:
  • Architecture — 1-2 sentence summary of how the codebase is structured
  • Key Files — 3-5 most critical files with one-line descriptions
  • **Co