repo-quality-orchestrator

name: repo-quality-orchestrator description: Orchestrates sub-agents to audit and safely clean up messy TypeScript codebases. Use when asked to "clean up AI-generated code", "reduce duplication", "improve folder organization", "enforce modularity", or "grade code quality". metadata: version: 1.0.0

Repo Quality Orchestrator

Use this skill to grade and remediate TypeScript code quality without changing intended behavior.

Primary objective

Clean up messy, repetitive AI-generated code while preserving behavior, public contracts, and delivery safety.

Required files

• plan/code-quality-audit-tracking.md: append-only audit log for every analyzed/updated file.
• plan/repo-organization-map.md: source of truth for folder intent and dependency boundaries.

If either file is missing, create it from:

• references/code-quality-audit-tracking-template.md
• references/repo-organization-map-template.md

Rubric (1-5 per dimension)

Scoring method

• Weight mapping: High=3, Medium=2, Low=1.
• Formula: weighted_percent = sum(score * weight) / (5 * sum(weights)) * 100.

Oversized file policy (hard gate)

Treat file size as a quality risk indicator, not a standalone verdict.

Tiered LOC thresholds:

• >250 LOC: warning - review for split opportunities
• >350 LOC: high priority - refactor planning required
• >500 LOC: critical - treat as unsafe unless explicitly exempt

Structural trigger checks (apply regardless of LOC):

• More than 10 top-level exports
• Any function longer than 60 lines
• Mixed concerns in one file (for example domain logic + transport + persistence)
• More than 3 side-effectful dependencies in a single module

Scoring caps when oversized:

• Warning tier: cap Modularity and cohesion at 3/5
• High-priority tier: cap Modularity and cohesion and Structural organization and boundaries at 2/5
• Critical tier: cap both dimensions at 1/5 unless exempted with explicit rationale

Required remediation flow for oversized files:

1. Create a split plan first (target modules, ownership, API preservation strategy).
2. Refactor in phases (max 2 extractions per pass).
3. Re-run verification after each phase: lint:fix, typecheck, build, test, test:e2e.
4. If public API break risk is unclear, defer and log an open question instead of guessing.

Workflow

1. Create or update tracking files and define target batch scope.
2. Process files in small batches (10-20 files max per run).
3. For each file:
   • Score every rubric dimension.
   • Record findings with severity, confidence, and evidence.
   • Record folder placement status against plan/repo-organization-map.md.
   • List prioritized improvements.
4. If improvements are high-confidence and safe, implement them immediately.
5. If uncertainty remains, log open questions before editing.
6. Verify with: lint:fix, typecheck, build, test, test:e2e.
7. Record results, score deltas, unresolved questions, and next batch.

Evidence format (required)

Every finding must include:

• Severity: high|medium|low
• Confidence: high|medium|low
• Evidence: path:line plus concrete behavior or structure mismatch

Do not include ungrounded opinions or style-only findings.

Repository organization contract

Use plan/repo-organization-map.md to evaluate placement and dependencies.

For each folder in that map, define:

• Purpose: what belongs there
• Exclusions: what does not belong there
• Allowed imports: permitted dependency directions
• Ownership notes: who or what maintains this area

For file moves:

• Move only with high confidence and explicit map evidence.
• Prefer small local moves over broad tree rewrites.
• Preserve public import/API paths unless explicitly approved.
• Batch move limit: max 10 files before re-running verification.

Module intent docs policy

Every touched TypeScript module should include and maintain this header:

/**
 * Module: <path-or-name>
 * Intent: <why this module exists>
 * Responsibilities: <what this module owns>
 * Public API: <exports and contracts>
 * Invariants: <rules that must stay true>
 * Side Effects: <none|list>
 * Maintenance: Update this block when exports, invariants, side effects, or ownership change.
 */

Keep the block concise and factual.

Safety boundaries

• Primary objective is cleanup quality, not architecture churn.
• Do not change public APIs/contracts unless explicitly required and documented.
• Do not do broad rewrites in a single pass.
• Do not do speculative refactors without evidence.
• Do not do style-only churn.

Default edit budget per pass:

• Max 3 non-test files touched
• Max ~200 LOC net change

If budget is exceeded, stop and log phased follow-up work.

Failure policy

If improvements cause failures:

1. Classify the failure:
   • genuine implementation bug
   • ambiguity/design question
2. If genuine bug, fix implementation.
3. If ambiguity, revert risky change and log open question in tracking file.
4. Re-run impacted tests twice to guard against flakes.

Context-efficiency rules

• Read only target file plus directly related neighbors.
• Avoid full-repo deep reads in one pass.
• Keep reports compact; do not dump full file contents.
• Prefer phased improvements over large all-at-once rewrites.

Required output format

Return:

1. Files Audited
2. Files Updated
3. Score Deltas
4. Open Questions
5. Verification Results
6. Next Batch