SYSTEM.md

Code Analysis Agent - Complete Workflow Documentation

Multi-agent codebase analysis system that performs dependency-aware, parallel analysis of libraries and applications, generating comprehensive architecture documentation. Orchestrates the entire analysis workflow and synthesizes documentation - Discovers project structure and components - Builds dependency graphs (library and application) - Spawns specialized subagents for analysis tasks - Coordinates parallel execution with dependency ordering - Monitors transcript for application completion markers - Incrementally processes analyses as they complete - Synthesizes comprehensive architecture documentation Task, Glob, Read, Bash, Write - files/architecture_docs/architecture.md (comprehensive) - files/architecture_docs/quick_reference.md (1-page summary)

<component name="code-library-analyzer">
  <role>Deep analysis of library components</role>
  <responsibilities>
    - Explores code structure with Glob, Grep, Read
    - Identifies key components and API surfaces
    - Traces data flows through the library
    - Documents architecture patterns
    - Receives upstream dependency context when analyzing dependent libraries
  </responsibilities>
  <tools>Glob, Grep, Read, Bash, Write</tools>
  <output>files/service_analyses/{library_name}.md</output>
</component>

<component name="application-analyzer">
  <role>Deep analysis of application components</role>
  <responsibilities>
    - Analyzes executable systems with business logic
    - Documents system flows and request/response patterns
    - Identifies application-to-application interactions (HTTP, shared DB, message queues)
    - Maps ALL external library dependencies with version, category, and purpose
    - Documents external system integrations (databases, cloud services, APIs)
    - Documents how applications use internal libraries
  </responsibilities>
  <tools>Glob, Grep, Read, Bash, Write</tools>
  <output>files/service_analyses/{application_name}.md</output>
</component>

<component name="external-service-analyzer">
  <role>Deep analysis of external service integrations</role>
  <responsibilities>
    - Analyzes how a specific external service (e.g., AWS S3, PostgreSQL, Stripe) is integrated
    - Documents client libraries, wrapper modules, and authentication mechanisms
    - Maps API endpoints consumed and webhooks received
    - Documents configuration, environment variables, and security considerations
  </responsibilities>
  <tools>Glob, Grep, Read, Bash, Write</tools>
  <output>files/service_analyses/{service_slug}.md</output>
</component>

<coordination_mechanism> logs/latest/transcript.txt Live-updated file that serves as the coordination backbone for parallel subagents. Lead agent polls this file to detect completion events incrementally. [APPLICATION_ANALYSIS_COMPLETE] {component_name} Written when a single application analyzer completes lead-agent (incremental processing) [ALL_APPLICATION_ANALYSIS_COMPLETE] Written when all application analyzers complete lead-agent (triggers final synthesis)

<subagent_tracking>
  <mechanism>Hook-based tracking system</mechanism>
  <hooks>
    <hook name="PreToolUse">Captures tool invocations before execution</hook>
    <hook name="PostToolUse">Captures tool results after execution</hook>
    <hook name="SubagentStop">Detects subagent completion</hook>
  </hooks>
  <state>
    - Maps parent_tool_use_id → SubagentSession
    - Tracks active analyzer count for completion detection
    - Logs all tool calls to transcript and JSONL file
  </state>
</subagent_tracking>

</coordination_mechanism>

<execution_strategy> Libraries are analyzed in dependency order (depth-first topological), while libraries at the same depth level run in parallel. Applications run fully in parallel since they don't depend on each other. Lead agent monitors transcript and processes completions incrementally.

<performance_characteristics>
  - Parallel application analysis for maximum throughput
  - Depth-0 libraries (no dependencies) all analyze in parallel
  - Dependent libraries receive upstream context, avoiding redundant discovery
  - Incremental processing allows lead agent to understand architecture progressively
</performance_characteristics>

</execution_strategy>

<data_flow> Project root path from user - Detect project type (monorepo, polyrepo, single project) - Discover all packages/services via package.json, go.mod, etc. - Classify as library or application - Build dependency graphs - files/service_discovery/components.json - files/dependency_graphs/library_graph.json - files/dependency_graphs/application_graph.json (partial, completed later)

<stage name="library-analysis">
  <input>
    - Library dependency graph
    - Component metadata
  </input>
  <process>
    - Phase 1: Analyze depth=0 libraries in parallel (no context needed)
    - Phase 2: For each depth level, analyze libraries after their dependencies complete in parallel
    - Pass upstream context (architecture, API surface, data flows) to dependent libraries
  </process>
  <output>files/service_analyses/{library_name}.md for each library</output>
</stage>

<stage name="application-analysis">
  <input>
    - Application list from components.json
    - Completed library analyses (upstream context)
  </input>
  <process>
    - Spawn all application analyzers in parallel
    - Each receives library context for dependencies
    - Identify application-to-application interactions
    - Write completion markers to transcript
  </process>
  <output>
    - files/service_analyses/{application_name}.md for each application
    - Completed application_graph.json with interaction edges
  </output>
</stage>

<stage name="architecture-synthesis">
  <input>
    - Library and application analyses (incrementally via transcript polling by lead agent)
    - Complete dependency graphs
    - Documentation templates from templates/
  </input>
  <process>
    - Lead agent polls transcript for [APPLICATION_ANALYSIS_COMPLETE] markers
    - Incrementally processes each completed application analysis
    - When [ALL_APPLICATION_ANALYSIS_COMPLETE] appears, performs final synthesis
    - Uses templates/architecture_template.md and templates/quick_reference_template.md
    - Fills in template placeholders with data from all analyses and graphs
  </process>
  <output>
    - files/architecture_docs/architecture.md
    - files/architecture_docs/quick_reference.md
  </output>
</stage>

</data_flow>

<workflow_steps> Detect project structure, discover components, build initial dependency graphs

<step number="2" name="library-analysis-phase-1">
  Analyze all depth=0 libraries in parallel (no dependencies)
</step>

<step number="3" name="library-analysis-phase-2">
  Analyze dependent libraries in topological order, passing upstream context
</step>

<step number="4" name="application-analysis">
  - Spawn all application analyzers in parallel
  - Lead agent polls transcript for [APPLICATION_ANALYSIS_COMPLETE] markers
  - Lead agent incrementally processes completed analyses
</step>

<step number="5" name="external-service-analysis">
  - Collect external services discovered across all application analyses
  - Spawn external-service-analyzer for each significant runtime integration
  - Produces dedicated integration analysis files
</step>

<step number="6" name="architecture-synthesis">
  - Spawn architecture-documenter to synthesize comprehensive documentation
  - Aggregates all external dependencies into complete technology inventory
</step>

</workflow_steps>

<title>Analyze depth=0 Libraries (No Library Dependencies)</title> code-library-analyzer Analyze {library_name} Include library name, path, type, description, classification=library, NO upstream context IN PARALLEL

<wait_condition>
  ALL depth=0 library analyzers must complete before proceeding to next step
</wait_condition>

<title>Step 3.2: Analyze Phase 2 Libraries (Dependency Order)</title> continue

    <for-each target="library in library_set">
      <step name="gather-dependencies">
        <description>Get library's DIRECT dependencies using the library graph</description>

        <for-each target="direct dependency">
          <read_analysis>
            <file>files/service_analyses/{dep_name}.md</file>
            <extract_fields>
              <field name="architecture">overview</field>
              <field name="key_components">list of main components</field>
              <field name="api_surface">exported functions/types</field>
              <field name="data_flows">how data moves through the library</field>
            </extract_fields>
          </read_analysis>
        </for-each>
      </step>

      <step name="spawn-analyzer">
        <spawn-subagent>
          <subagent_type>code-library-analyzer</subagent_type>
          <description>Analyze {library_name}</description>
          <prompt>
            Include library info + classification=library + upstream context from direct dependencies
          </prompt>
        </spawn-subagent>
      </step>
    </for-each>

    <wait_condition>
      <description>Wait for all library analyses to complete</description>
      <signal>subagent task returns "done" signal to globally shared "transcript"</signal>
    </wait_condition>
  </for-each>
</iterate>

Only spawn analyzer after ALL its direct dependencies have completed AND been processed. You can spawn multiple library analyzers in parallel if they have the same dependency depth. <title>Codeified application <> architecture parallel subagent flow</title> // Lead agent polls transcript for completions processed_applications = [] while not_all_complete: transcript = read_file("logs/*/transcript.txt")

// Check for individual completions for marker in find_markers(transcript, "[APPLICATION_ANALYSIS_COMPLETE]"): app_name = extract_component_name(marker) if app_name not in processed_applications: analysis = read_file(f"files/service_analyses/{{app_name}}.md") process_analysis(analysis) // Build progressive understanding processed_applications.append(app_name)

// Check for all complete if "[ALL_APPLICATION_ANALYSIS_COMPLETE]" in transcript: break

// Lead agent performs final synthesis update_application_graph() synthesize_architecture_documentation() ]]>

<completion_requirements> </completion_requirements>