Scan a codebase to identify hand-rolled implementations that should be replaced by third-party libraries, and identify missing capabilities the project should have.
Scanner (deterministic) → AI Agent (generative) → Pipeline (deterministic)
1. Regex: detect hand-rolled code 1. Recommend library replacements Score, plan, audit,
2. FS: detect code org issues 2. Identify capability gaps filter, serialize
(god-dirs, circular deps, 3. Recommend org patterns + tooling
naming, barrel bloat) using knowledge + Context7
Design constraints:
Present structured choices at gates. NEVER skip or proceed without user response.
Format — table of findings/options + lettered choices + your recommendation with 1-sentence rationale. For high-impact gates, add a SWOT table. See references/code-organization-workflow.md for full Gate examples.
Rules:
Parse and validate InputSchema JSON via Zod. Read src/schemas/input.schema.ts for the full schema.
Run scanCodebase(input). The scanner:
ScanResult with:detections — hand-rolled code patterns foundstructuralFindings — architectural + code organization issuescodeOrganizationStats — project-wide metrics (file counts, naming conventions, circular dep count)workspaces — monorepo workspace infoDetections and findings contain no recommendations — only facts.
Why: Each accepted detection costs a Context7 verification call. False positives waste quota.
Present scan results as a triage table with columns: #, Domain, Pattern, File, Confidence, Action. Offer options: (A) accept all, (B) skip specific numbers, (C) high-confidence only. See references/code-organization-workflow.md#gate-1-triage-example for format.
Wait for user response. Proceed with accepted detections only.
Analyze what the project is missing entirely:
Analyze at three levels: single library gap, ecosystem gap, architecture gap.
Provide each gap as a GapRecommendation. Read src/index.ts for the interface.
Design system gaps — two paths:
references/design-system-sources.md for curated repos and sparse-checkout workflow.references/design-system-extraction.md for extraction workflow, then references/design-system-sources.md for implementation.You cannot infer file counts, naming conventions, or import cycles from knowledge. You MUST read the filesystem.
If using the npm library — scanResult.structuralFindings and scanResult.codeOrganizationStats already contain all findings. Skip to Phase B.
If not — run the shell commands in references/code-organization-workflow.md#phase-a-shell-commands-for-collecting-facts.
Record each finding with: directory/file path, count, type. These are facts.
For each finding, apply the MUST do / MUST NOT do decision tree in references/code-organization-workflow.md#phase-b-decision-tree. Do NOT recommend tools without Context7 verification.
For worked examples showing the full Fact → Read → Recommend flow, see references/code-organization-workflow.md#phase-b-worked-examples.
Skip rules — skip a finding if:
tests/, __tests__/, __mocks__/, fixtures/, generated/, .storybook/// @generated or /* eslint-disable */ at top)Why: Organization pattern and naming convention are team preferences, not technical correctness.
Present only if structural findings exist. For each preference, present a SWOT comparison with lettered options. See references/code-organization-workflow.md#gate-2-swot-examples for format.
Wait for user response on each preference. Proceed to Step 3 with confirmed choices.
For each accepted detection, recommend a solution:
resolve-library-id + query-docs to confirm existence and get latest docsRead src/index.ts for the LibraryRecommendation interface. Return null to skip a detection.
Skip a detection if:
Why: Each recommendation has real migration cost. User may have business, timeline, or architectural reasons to defer or reject.
Present ALL recommendations (replacements + gaps + code org tooling) as a decision table with columns: #, Domain, Replace what, With what, Risk, Files (affected count), Context7, Decision. Offer options: (A) accept all, (B) accept specific, (C) low-risk only, (D) defer all. See references/code-organization-workflow.md#gate-3-recommendation-table-example for format.
Wait for user response. Rejected items are excluded from migration plan, scoring, and PRs.
The pipeline handles these automatically:
dimensionHints)uxAudit option. Evaluate 8 categories (accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment)vulnClient)registryClient)platformClient + gitOps)Why: Creating PRs pushes branches to remote and notifies team members. File migrations modify the codebase. Both are irreversible.
Present only if Step 10 or file migration is about to execute. Show PR table and file migration table with rollback commands. Offer options: (A) execute all, (B) PRs only, (C) migration only, (D) dry run, (E) abort. See references/code-organization-workflow.md#gate-4-execution-confirmation-example for format.
Wait for user response. After execution, report results with rollback instructions.
Prefer MCP tools when available; fall back to shell commands if not.
resolve-library-id + query-docs for library verificationgh CLIgit CLISingle OutputSchema JSON containing:
recommendedChanges — replacement recommendations with scores, verification, adapter strategiesgapAnalysis (optional) — missing capabilities with prioritized recommendationsfilesToDelete — file paths to remove after migrationlinesSavedEstimate — total lines saveduxAudit — UX completeness checklist (8 categories)migrationPlan — phased plan with deletion checklistvulnerabilityReport (optional)updatePlan (optional)pullRequests (optional)Read src/schemas/output.schema.ts for the full schema.