Codebase Gap Analysis vs Reference Architecture

Use when the user wants to deeply compare their project or codebase against a reference implementation, framework, or architectural pattern to find gaps and improvement opportunities.

Workflow

1. Define Scope & Dimensions

• Confirm the user's project location (repo URL, local path, or pasted code).
• Confirm the reference target (technology, product, or architectural pattern).
• Select comparison dimensions relevant to the domain (e.g., orchestration, memory, concurrency, skills, backends, observability, agent lifecycle).

2. Explore User Codebase

• Fetch repository metadata and directory structure.
• Read root configuration and documentation files.
• Dive into core source directories to map the architecture.
• Identify and read critical modules (planner, orchestrator, supervisor, memory, tools, agents, config).
• Summarize current capabilities, abstractions, and design patterns found.

3. Research Reference Architecture

• Search official documentation, repositories, and technical articles for the reference system.
• Extract concrete capabilities, configuration mechanisms, and architectural layers.
• Note any experimental, undocumented, or advanced features relevant to the comparison.

4. Execute Structured Comparison

• Build a side-by-side comparison table across the chosen dimensions.
• Flag capabilities present in the reference but missing or incomplete in the user's project.
• Note areas where the user's project may be ahead, equivalent, or intentionally divergent.

5. Prioritized Recommendations

• List each gap with: description, impact, and suggested implementation approach aligned with the user's stack.
• Assign priority (Critical / High / Medium / Low).
• Propose a pragmatic roadmap that respects existing dependencies and build patterns.

6. Deliver Synthesis

• Provide an overall architectural maturity assessment.
• Highlight quick wins versus long-term investments.
• Offer to elaborate on, design, or implement any specific recommendation.