analyze-agent-codebase

Analyze Agent Codebases

Reconstruct behavior from real entry points, call chains, state transitions, and persistence. Documentation explains intent; code and tests establish implementation. Respond in the user's language unless asked otherwise.

Boundaries

• Follow repository instructions, documentation routes, and read-only constraints.
• Default to read-only. Write analysis documents only when requested; do not modify implementation.
• Use source, dependency wiring, configuration, schemas, migrations, and tests as evidence.
• Label important claims confirmed, inferred, or unknown, localizing these labels in the report. Explain inferences and gaps.
• Cite paths, symbols, and relevant entry-to-effect call chains. Names such as agent, memory, plan, or tool do not prove capabilities.

Choose the scope

Use the smallest sufficient scope: a vertical slice for a mechanism question, an architecture report for several mechanisms, or a dossier when multiple documents are requested. For a dossier, read analysis axes and structure.

Check existing analyses for scope, evidence, and revision; update the appropriate document instead of creating duplicate overviews.

Investigate

1. Freeze scope. Record repository root, revision, requested questions, exclusions, output format, languages, build entry points, generated directories, and initial worktree state. Distinguish production code from tests, fixtures, examples, generated code, vendors, and historical documents.
2. Trace the runtime. Follow entry point -> configuration and dependency wiring -> agent/workflow construction -> execution loop -> model, tool, collaboration, and persistence effects -> events, recovery, and presentation. Follow registries through loaders, macros, decorators, or configuration until the actual implementation is connected.
3. Trace each question vertically. Use a real trigger: input -> authorization and validation -> state change -> effects -> result -> error and recovery. Select only mechanisms present in the code.
4. Record evidence as you read. Use the table below. A claim about subagents, for example, needs the creator, context transfer, isolation, and result path.
5. Explain ownership. Identify control and state authority, sync/async connections, context/session/Memory/history lifecycles, tool/Skill/prompt/permission boundaries, and failure, retry, cancellation, idempotency, and recovery limits. Record documentation drift.
6. Cross-check. Reverse-reference key symbols to verify production wiring. Inspect tests, schemas, flags, platforms, adapters, and alternate entries. Tests prove only covered behavior; mark unexecuted checks not_run. Compare authoritative documentation unless the user prohibits reading it.