Analyze and Recommend Third-Party Optimizations

Architecture

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:

• No hardcoded library recommendations — evaluate project context dynamically
• Two analysis modes: replacement (hand-rolled code found) and gap (capability missing entirely)
• Human-in-the-loop: 4 gates at irreversible, preference-driven, or costly decision points
• Language: all output (gates, tables, recommendations, rationale) MUST match the user's input language. If user writes in Chinese, respond in Chinese. If English, respond in English. Never mix.

Gate Protocol

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:

• If user says "do it all automatically", ask "confirm skip ALL gates?" first
• After user decides, execute automatically and report results with rollback instructions

Standard Operating Procedure

Step 1: Validate Input

Parse and validate InputSchema JSON via Zod. Read src/schemas/input.schema.ts for the full schema.

Step 2: Scan Codebase

Run scanCodebase(input). The scanner:

1. Detect workspace roots for monorepo support
2. Match code against 30+ domain patterns (i18n, auth, state-management, code-organization, etc.)
3. Run structural analysis: design system layers (monorepo), code organization (all projects)
4. Return ScanResult with:
   • detections — hand-rolled code patterns found
   • structuralFindings — architectural + code organization issues
   • codeOrganizationStats — project-wide metrics (file counts, naming conventions, circular dep count)
   • workspaces — monorepo workspace info

Detections and findings contain no recommendations — only facts.

GATE 1: Triage Detections

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.

Step 2.5: Gap Analysis (AI Agent)

Analyze what the project is missing entirely:

1. Installed dependencies — low-level tools that should be upgraded to platform-level solutions
2. Monorepo structure — missing architectural layers (e.g., shared token package, shared config preset)
3. Cross-cutting concerns — absent capabilities: structured logging, error monitoring, rate limiting, transactional email, type-safe API layer
4. Architecture patterns — opportunities for multi-package solutions (e.g., design-tokens → tailwind-config → ui)

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:

• No existing frontend: Read references/design-system-sources.md for curated repos and sparse-checkout workflow.
• Existing frontend: Read references/design-system-extraction.md for extraction workflow, then references/design-system-sources.md for implementation.

Step 2.7: Code Organization Analysis

Phase A — Collect facts (MUST use tools, DO NOT estimate)

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.

Phase B — Recommend solutions (use your knowledge + Context7)

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:

• Directory is in tests/, __tests__/, __mocks__/, fixtures/, generated/, .storybook/
• File is auto-generated (has // @generated or /* eslint-disable */ at top)
• Directory has <3 files (too few to judge)

GATE 2: Code Organization Preferences

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.

Step 3: Recommend Solutions (AI Agent)

For each accepted detection, recommend a solution:

1. Stack coherence — consider how libraries fit the project's overall stack
2. Ecosystem composition — recommend companion libraries that work together
3. Rationale — explain WHY this choice fits this project's framework, runtime, and scale
4. Anti-patterns — what NOT to use and why
5. Alternatives — different solutions for different architectural contexts
6. Migration snippet — read the detected code (file path + line range) and generate before/after examples
7. Context7 verification — call resolve-library-id + query-docs to confirm existence and get latest docs

Read src/index.ts for the LibraryRecommendation interface. Return null to skip a detection.

Skip a detection if:

• Code has comments explaining why it is custom
• Detection is in test/mock/fixture files
• Library is already in project dependencies (suggest version update instead)
• Hand-rolled code is simpler than the library (3-line utility vs 50KB dep)

GATE 3: Accept/Reject Recommendations

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.

Step 4–7: Score, Plan, Audit, Serialize

The pipeline handles these automatically:

• Scoring: confidence-based dimension scores (overridable via dimensionHints)
• Migration plan: auto-grouped by risk (low/medium/high), sorted by file co-location
• UX audit: provide via uxAudit option. Evaluate 8 categories (accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment)
• Constraints: license allowlist filtering, dependency conflict detection, JSON serialization

Optional Steps

• Step 8: Vulnerability scan via OSV database (vulnClient)
• Step 9: Auto-update existing dependencies (registryClient)
• Step 10: PR auto-creation via GitHub/GitLab (platformClient + gitOps)

GATE 4: Before Irreversible Actions

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.

MCP Integration

Prefer MCP tools when available; fall back to shell commands if not.

• Context7 MCP (required) — resolve-library-id + query-docs for library verification
• GitHub MCP (preferred for PRs) — structured PR create/update/query; fallback: gh CLI
• Git MCP / GitKraken MCP (preferred for scaffold) — structured repo browse/sparse-checkout; fallback: git CLI

Output

Single OutputSchema JSON containing:

• recommendedChanges — replacement recommendations with scores, verification, adapter strategies
• gapAnalysis (optional) — missing capabilities with prioritized recommendations
• filesToDelete — file paths to remove after migration
• linesSavedEstimate — total lines saved
• uxAudit — UX completeness checklist (8 categories)
• migrationPlan — phased plan with deletion checklist
• vulnerabilityReport (optional)
• updatePlan (optional)
• pullRequests (optional)

Read src/schemas/output.schema.ts for the full schema.