name: ai-assistant-internals
description: Deep analysis of AI assistant CLI internals including tool registry, context pipeline, MCP integration, sub-agent coordination, and cost optimization
version: "1.0"
applies_to:
  - codebase_analysis
  - github_analysis
variables:
  depth: comprehensive
stages:
  - name: tool_registry_analysis
    type: custom
    target: tools
    uses_history: false
    enabled: true
    prompt: >
      Analyze the tool registry and dispatch system in this AI assistant codebase.

      For each tool/agent capability:
      1. Tool name and purpose
      2. Input schema (parameters, types, required vs optional)
      3. Output schema (return types, error conditions)
      4. Dispatch mechanism (how the LLM selects and invokes it)
      5. Related tools that are commonly chained together

      Output JSON with:
      - "tools": array of {name, purpose, input_schema, output_schema, dispatch_mechanism, related_tools[]}
      - "tool_categories": grouping by function (file_ops, web_search, agent_mgmt, shell_exec, etc.)
      - "dispatch_pattern": how tool calls are parsed, validated, and routed

  - name: context_pipeline
    type: custom
    target: context
    uses_history: true
    enabled: true
    prompt: >
      Document how user queries, system context, conversation history, and file context are assembled into LLM prompts.

      Cover:
      1. System prompt construction (static vs dynamic parts)
      2. User context collection (current directory, git state, open files)
      3. Conversation history management (truncation, summarization, checkpointing)
      4. File context injection (how code is read and formatted for the model)
      5. Context window optimization strategies

      Output JSON with:
      - "system_prompt_structure": sections and their purposes
      - "context_sources": array of {source, description, priority, fallback_behavior}
      - "history_management": truncation/summary strategy
      - "file_context_format": how files are represented in prompts
      - "optimization_strategies": techniques to stay within token limits

  - name: mcp_patterns
    type: custom
    target: mcp
    uses_history: true
    enabled: true
    prompt: >
      Extract Model Context Protocol (MCP) integration patterns from this codebase.

      Document:
      1. MCP client initialization and configuration
      2. Server discovery and connection lifecycle
      3. Tool/resource exposure via MCP
      4. Authentication and security boundaries
      5. Error handling for MCP server failures

      Output JSON with:
      - "mcp_client": initialization and config patterns
      - "server_management": discovery, connect, disconnect, health checks
      - "exposed_capabilities": tools/resources surfaced to MCP
      - "security_model": auth, sandboxing, permission boundaries
      - "failure_modes": retry, fallback, and user notification strategies

  - name: agent_coordination
    type: custom
    target: agents
    uses_history: true
    enabled: true
    prompt: >
      Analyze sub-agent creation, task delegation, and multi-agent coordination patterns.

      Identify:
      1. Agent lifecycle (create, run, pause, resume, terminate)
      2. Task delegation strategies (how work is split across agents)
      3. Inter-agent communication (message passing, shared state)
      4. Result aggregation and merging from multiple agents
      5. Parent-child relationship management and oversight

      Output JSON with:
      - "agent_lifecycle": states and transitions
      - "delegation_patterns": strategies for splitting work
      - "communication_model": how agents share data
      - "result_aggregation": merging outputs from parallel agents
      - "oversight_mechanisms": how parent agents monitor children

  - name: cost_optimization
    type: custom
    target: cost
    uses_history: true
    enabled: true
    prompt: >
      Review token usage tracking, cost estimation, and optimization strategies.

      Document:
      1. How input/output tokens are measured per request
      2. Cost estimation methodology (pricing models, caching)
      3. Optimization techniques (prompt compression, selective context, model tiering)
      4. Budget controls and user-facing cost feedback
      5. Trade-offs between cost and response quality

      Output JSON with:
      - "token_measurement": how tokens are counted and attributed
      - "cost_estimation": pricing logic and display
      - "optimization_techniques": array of {name, description, impact, implementation_location}
      - "budget_controls": limits, warnings, and enforcement
      - "quality_tradeoffs": when and how cost is prioritized over quality

post_process:
  reorder_sections:
    - overview
    - tool_registry
    - context_pipeline
    - mcp_integration
    - agent_coordination
    - cost_optimization
    - examples
    - advanced_topics
  add_metadata:
    enhanced: true
    workflow: ai-assistant-internals
    deep_analysis: true