codebase-analysis

name	codebase-analysis
description	Execute a structured codebase exploration workflow to gather insights. Use when asked to "analyze codebase", "explore codebase", "understand this codebase", or "map the codebase".
argument-hint	<analysis-context or feature-description> [--teams]
model	inherit
user-invocable	true
disable-model-invocation	false
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion

Codebase Analysis Workflow

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

CRITICAL: Complete ALL 3 phases. The workflow is not complete until Phase 3: Post-Analysis Actions is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

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 is provided, use it as the analysis context
   • If no arguments, set context to "general codebase understanding"

2. Run deep-analysis workflow:

   • Check if $ARGUMENTS contains --teams flag
   • If --teams is present:
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/teams-deep-analysis/SKILL.md and follow its workflow
     • Remove --teams from the analysis context
   • Otherwise:
     • Read ${CLAUDE_PLUGIN_ROOT}/skills/deep-analysis/SKILL.md and follow its workflow (default)
   • Pass the analysis context from step 1
   • This handles exploration (parallel code-explorer agents) and synthesis (codebase-synthesizer agent)

3. Verify results:

   • Ensure the synthesis covers the analysis context adequately
   • If critical gaps remain, use Glob/Grep to fill them directly

---

Phase 2: Reporting

Goal: Present a structured analysis to the user.

1. Load report template:

   • Read ${CLAUDE_PLUGIN_ROOT}/skills/codebase-analysis/references/report-template.md
   • Use it to structure the presentation

2. Present the analysis: Structure the report with these sections:

   • Executive Summary — Lead with the most important finding
   • Architecture Overview — How the codebase is structured
   • 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

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

1. Present action menu:

   Use AskUserQuestion with multiSelect: true to present all available actions:

   • Save report as Markdown file — Write the full report to a file
   • Update README.md with analysis insights — Add architecture/structure info to README
   • Update CLAUDE.md with analysis insights — Add patterns/conventions to CLAUDE.md
   • Keep a condensed summary in memory — Retain a quick-reference summary in conversation context
   • Address actionable insights — Fix challenges and implement recommendations from the report

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

2. Execute selected actions in the following fixed order:

   Action: Save Report as Markdown File

   • Check if a docs/ directory exists in the project root
     • If yes, suggest default path: docs/codebase-analysis.md
     • If no, suggest default path: codebase-analysis.md in the project root
   • Use AskUserQuestion to let the user confirm or customize the file path
   • Write the full report content (same as Phase 2 output) to the confirmed path using the Write tool
   • Confirm the file was saved

   Action: Update README.md

   • Read the existing README.md at the project root
     • If no README.md exists, skip this action and inform the user
   • Draft updates based on analysis insights — focus on:
     • Architecture overview
     • Project structure
     • Tech stack summary
   • Present the draft to the user for approval using AskUserQuestion with options:
     • Apply — Apply the drafted updates
     • Modify — Let the user describe what to change, then re-draft
     • Skip — Skip this action entirely
   • If approved, apply updates using the Edit tool

   Action: Update CLAUDE.md

   • Read the existing CLAUDE.md at the project root
     • If no CLAUDE.md exists, use AskUserQuestion to ask if one should be created
     • If user declines, skip this action

---

Error Handling

If any phase fails:

1. Explain what went wrong
2. Ask the user how to proceed:
   • Retry the phase
   • Skip to next phase (with partial results)
   • Abort the workflow

---

Agent Coordination

Exploration and synthesis agent coordination is handled by the deep-analysis skill in Phase 1. See that skill for agent model tiers and failure handling details.

---

Additional Resources

• For report structure, see references/report-template.md
• For actionable insights format, see references/actionable-insights-template.md