| name | codebase-analyzer |
| description | Analyzes codebase using adaptive parallel Explore subagents based on task complexity. Selects agent roles from a pool, launches Explore agents, then delegates report generation to codebase-analysis-reporter subagent. |
| user-invocable | false |
Codebase Analyzer Skill
Orchestrates parallel codebase analysis using built-in Explore subagents. Adaptively selects which agent roles to activate based on task complexity, then delegates report synthesis to a specialized subagent.
Core Principles
- Adaptive Agent Selection: Select roles from a pool based on task complexity — no fixed count
- Task-Type Awareness: Adapt prompts and focus based on task type
- Delegated Reporting: Raw findings go to
codebase-analysis-reporter subagent for synthesis
Input Parameters
| Parameter | Required | Description |
|---|
task_description | Yes | Description of the development task |
description | Yes | Task description from user |
task_path | Yes | Path to task directory |
artifact_name | No | Override output filename (default: codebase-analysis.md) |
Execution Workflow
Step 1: Parse Input and Determine Focus
Extract keywords, component names, file hints, domain, and technology hints from the description.
Determine primary focus from the task description:
| Signal in Description | Primary Focus | Key Questions |
|---|
| Error/crash/broken language | Find buggy code path | Where does the issue occur? What's the execution flow? |
| Improve/enhance/existing | Find existing feature | What files implement this feature? How does it work? |
| Add/new/create | Find patterns/integration points | What similar patterns exist? Where should this integrate? |
Step 2: Select Agent Roles
Choose which roles to activate from the pool. Each role is a distinct analysis concern.
| Role | Purpose | When Needed |
|---|
| File Discovery | Find relevant files by patterns, keywords, naming | Almost always |
| Code Analysis | Analyze code structure, patterns, execution flow | When understanding existing behavior matters |
| Context Discovery | Find tests, consumers, dependencies | When understanding impact/coverage matters |
| Pattern Mining | Find similar implementations as templates | New features following existing patterns |
| Migration Target | Analyze target technology/compatibility | Migrations comparing current vs target |
Decision signals:
- Specificity (exact files mentioned → fewer agents)
- Scope breadth (multiple domains → more agents)
- Uncertainty (unclear location → more agents)
- Task type (bugs tend focused, features broad, migrations broadest)
Examples:
| Task Description | Roles Selected | Count |
|---|
"Fix null check in utils/parser.ts" | File Discovery + Code Analysis (combined) | 1 |
| "Add sorting to user table" | File Discovery, Code Analysis | 2 |
| "Fix login timeout" | File Discovery + Code Analysis (combined), Context Discovery | 2 |
| "Add OAuth authentication system" | File Discovery, Code Analysis, Context Discovery | 3 |
| "Add export feature similar to import" | File Discovery, Code Analysis, Pattern Mining | 3 |
| "Migrate from REST to GraphQL" | File Discovery, Code Analysis, Context Discovery, Migration Target | 4 |
When selecting fewer agents, merge related concerns into a single prompt — don't drop concerns.
State which roles you selected and why (1 sentence).
Step 3: Read Prompt Templates and Launch Agents
STOP — Do NOT skip this step. Do NOT write prompts from memory.
Before launching ANY Explore agent, you MUST use the Read tool to load the prompt template for each selected role. This is non-negotiable.
3a. Read templates — Use the Read tool to load ONLY the files for your selected roles:
| Role | Read This File |
|---|
| File Discovery | references/file-discovery.md |
| Code Analysis | references/code-analysis.md |
| Context Discovery | references/context-discovery.md |
| Pattern Mining | references/pattern-mining.md |
| Migration Target | references/migration-target.md |
If combining roles into one agent, also read references/combined.md for merging guidance.
3b. Adapt templates — Replace [description] with the actual task description. Select the correct task-type section (Bug / Enhancement / Feature).
3c. Launch agents — Use the Task tool with subagent_type="Explore" — one call per selected role, all in ONE message.
IMPORTANT: Every Explore agent prompt MUST include this instruction:
IMPORTANT: Do NOT create, write, or modify any files. Output all findings as text in your response only.
SELF-CHECK: Did you read the template files with the Read tool? If not, go back to 3a. Do not proceed.
Step 4: Delegate Report Generation
After all Explore agents complete, delegate to codebase-analysis-reporter subagent via Task tool:
Task tool:
subagent_type: "maister-codebase-analysis-reporter"
description: "Merge findings into analysis report"
prompt: |
You are the codebase-analysis-reporter. Merge these raw findings into a structured analysis report.
Task description: [description]
Agent roles used: [list of roles]
Agent count: [N]
Output path: [task_path]/analysis/[artifact_name]
## Raw Findings
### [Role 1 Name]
[paste raw output from agent 1]
### [Role 2 Name]
[paste raw output from agent 2]
[... for each agent]
The subagent produces the final report at {task_path}/analysis/{artifact_name} and returns structured results.
Step 5: Return Results to Orchestrator
Pass through the subagent's structured output:
status: success|partial|failed
report_path: analysis/[artifact_name]
summary: "[1-2 sentence summary]"
files_found: [count]
complexity: simple|moderate|complex
risk_level: low|low-medium|medium|medium-high|high
Error Handling
- No files found: Report partial results, suggest user provide more specific hints
- Agent timeout: Use results from completed agents, note incomplete analysis
- Conflicting results: Pass all perspectives to reporter subagent, which highlights conflicts
Integration
| Orchestrator | Phase | artifact_name |
|---|
| development orchestrator | Phase 1 | codebase-analysis.md (default) |
| migration orchestrator | Phase 1 | current-state-analysis.md |
| performance orchestrator | Phase 1 | codebase-analysis.md (default) |
