Codebase Auditor (L2 Coordinator)

Coordinates 9 specialized audit workers to perform comprehensive codebase quality analysis.

Purpose & Scope

• Coordinates 9 audit workers (ln-621 through ln-629) running in parallel
• Research current best practices for detected tech stack via MCP tools ONCE
• Pass shared context to all workers (token-efficient)
• Aggregate worker results into single consolidated report
• Create single refactoring task in Linear under Epic 0 with all findings
• Manual invocation by user; not part of Story pipeline

Workflow

1. Discovery: Load tech_stack.md, principles.md, package manifests, auto-discover Team ID
2. Research: Query MCP tools for current best practices per major dependency ONCE
3. Build Context: Create contextStore with best practices + tech stack metadata
4. Domain Discovery: Detect project domains from folder structure (NEW)
5. Delegate: Two-stage delegation - global workers + domain-aware workers (UPDATED)
6. Aggregate: Collect worker results, group by domain, calculate scores
7. Generate Report: Build consolidated report with Domain Health Summary, Findings by Domain
8. Create Task: Create Linear task in Epic 0 titled "Codebase Refactoring: [YYYY-MM-DD]"

Phase 1: Discovery

Load project metadata:

• docs/project/tech_stack.md - detect tech stack for research
• docs/principles.md - project-specific quality principles
• Package manifests: package.json, requirements.txt, go.mod, Cargo.toml
• Auto-discover Team ID from docs/tasks/kanban_board.md

Extract metadata only (not full codebase scan):

• Programming language(s)
• Major frameworks/libraries
• Database system(s)
• Build tools
• Test framework(s)

Phase 2: Research Best Practices (ONCE)

For each major dependency identified in Phase 1:

1. Use mcp__Ref__ref_search_documentation for current best practices
2. Use mcp__context7__get-library-docs for up-to-date library documentation
3. Focus areas by technology type:

Build contextStore:

{
  "tech_stack": {...},
  "best_practices": {...},
  "principles": {...},
  "codebase_root": "..."
}

Phase 3: Domain Discovery

Purpose: Detect project domains from folder structure for domain-aware auditing.

Algorithm:

1. Priority 1: Explicit domain folders

   • Check for: src/domains/*/, src/features/*/, src/modules/*/
   • Monorepo patterns: packages/*/, libs/*/, apps/*/
   • If found (>1 match) → use these as domains

2. Priority 2: Top-level src/ folders*

   • List folders: src/users/, src/orders/, src/payments/
   • Exclude infrastructure: utils, shared, common, lib, helpers, config, types, interfaces, constants, middleware, infrastructure, core
   • If remaining >1 → use as domains

3. Priority 3: Fallback to global mode

   • If <2 domains detected → domain_mode = "global"
   • All workers scan entire codebase (backward-compatible behavior)

Heuristics for domain detection:

Output:

{
  "domain_mode": "domain-aware",
  "all_domains": [
    {"name": "users", "path": "src/users", "file_count": 45, "is_shared": false},
    {"name": "orders", "path": "src/orders", "file_count": 32, "is_shared": false},
    {"name": "shared", "path": "src/shared", "file_count": 15, "is_shared": true}
  ]
}

Shared folder handling:

• Folders named shared, common, utils, lib, core → mark is_shared: true
• Shared code audited but grouped separately in report
• Does not affect domain-specific scores

Phase 4: Delegate to Workers

Phase 4a: Global Workers (PARALLEL)

Global workers scan entire codebase (not domain-aware):

...