@nebutra/next-unicorn-skill 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-02-09
+
+### Changed
+
+- **Architecture: Decouple detection from recommendation** — The pattern catalog no longer contains hardcoded library names, versions, licenses, best practices, or alternatives. Library recommendations are now provided dynamically by the caller via the `Recommender` callback, enabling AI agents to leverage their generalization ability and Context7 MCP for real-time, context-aware recommendations.
+- **New `Recommender` type** — `analyze()` now requires a `recommender: (detection) => LibraryRecommendation | null` callback. Return `null` to skip false positives.
+- **New `scanCodebase()` export** — Standalone scanner for AI agents to inspect detections before providing recommendations.
+- **UX Auditor decoupled** — `recommendedLibrary` is no longer hardcoded per category; the auditor reports status (present/partial/missing) with factual rationale, leaving library choice to the AI agent.
+- **Impact Scorer decoupled** — Removed 200+ line `DOMAIN_DIMENSION_AFFINITY` mapping and `DOMAIN_BASE_EFFORT` table. Scoring uses confidence-based defaults with optional `dimensionHints` and `baseEffortHours` overrides from the AI agent.
+- **Migration Planner decoupled** — Removed `DOMAIN_MIGRATION_PRIORITY` mapping. Sorting within each risk phase uses file co-location + composite score. AI agents can influence ordering via scoring.
+- **`Detection` type simplified** — Removed `suggestedLibrary` field. Detections now contain only what was detected (file, line range, pattern, confidence, domain).
+- **`VerificationItem` type added** — `verifyAllRecommendations()` now accepts `Array<VerificationItem | null>` instead of `Detection[]`, decoupling verification from scanner output.
+- **`AnalyzeResult` includes `scanResult`** — Success results now include raw `ScanResult` for AI agent further analysis.
+- Pattern catalog reduced from 880 to 370 lines (detection-only, no recommendation data)
+- SKILL.md rewritten to 150 lines following Anthropic SKILL spec principles (concise, high freedom for recommendations)
+- Test count increased from 191 to 198
+
+### Removed
+
+- All hardcoded library recommendations from `PatternDefinition` (`suggestedLibrary`, `suggestedVersion`, `license`, `bestPractice`, `alternatives`)
+- All hardcoded UX audit library recommendations and rationale strings
+- `DOMAIN_DIMENSION_AFFINITY` (68-domain × 7-dimension static mapping)
+- `DOMAIN_BASE_EFFORT` (25-domain effort estimate table)
+- `DOMAIN_MIGRATION_PRIORITY` (domain tier ordering)
+
 ## [2.0.0] - 2026-02-08
 
 ### Added

package/README.md

@@ -7,11 +7,11 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/TsekaLuk/Next-Unicorn-Skill/actions/workflows/ci.yml"><img src="https://github.com/TsekaLuk/Next-Unicorn-Skill/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/Nebutra/Next-Unicorn-Skill/actions/workflows/ci.yml"><img src="https://github.com/Nebutra/Next-Unicorn-Skill/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://www.npmjs.com/package/@nebutra/next-unicorn-skill"><img src="https://img.shields.io/npm/v/@nebutra/next-unicorn-skill.svg?color=blue" alt="npm version" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript" /></a>
-  <a href="./tests/"><img src="https://img.shields.io/badge/tests-191%20passed-brightgreen.svg" alt="Tests" /></a>
+  <a href="./tests/"><img src="https://img.shields.io/badge/tests-198%20passed-brightgreen.svg" alt="Tests" /></a>
   <a href="./tests/"><img src="https://img.shields.io/badge/properties-29%20verified-purple.svg" alt="Property Tests" /></a>
 </p>
 
@@ -37,19 +37,42 @@ Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't f
 
 ## Quick Start
 
+### From npmjs.org (recommended)
+
 ```bash
-# npm
 npm install @nebutra/next-unicorn-skill
-
-# pnpm
+# or
 pnpm add @nebutra/next-unicorn-skill
+```
+
+### From GitHub Packages
+
+Configure your `.npmrc` first:
+
+```shell
+echo "@nebutra:registry=https://npm.pkg.github.com" >> .npmrc
+```
+
+Then install:
 
-# bun
-bun add @nebutra/next-unicorn-skill
+```bash
+npm install @nebutra/next-unicorn-skill
 ```
 
 ```typescript
-import { analyze } from '@nebutra/next-unicorn-skill';
+import { analyze, scanCodebase } from '@nebutra/next-unicorn-skill';
+import type { Recommender } from '@nebutra/next-unicorn-skill';
+
+// The recommender function: AI agent decides which library fits each detection
+const recommender: Recommender = (detection) => {
+  // AI agent uses its knowledge + project context to recommend
+  // Return null to skip a detection (false positive, intentional custom code)
+  return {
+    library: 'zustand',       // dynamically chosen, not hardcoded
+    version: '^5.0.0',        // verified via Context7
+    license: 'MIT',
+  };
+};
 
 const result = await analyze({
   input: {
@@ -66,6 +89,7 @@ const result = await analyze({
     priorityFocusAreas: ['i18n', 'observability', 'auth-security'],
   },
   context7Client: myContext7Client,
+  recommender,  // AI agent provides library recommendations
   // Optional Phase 2 clients:
   vulnClient: myOsvClient,          // vulnerability scanning
   registryClient: myRegistryClient,  // auto-update
@@ -75,6 +99,7 @@ const result = await analyze({
 
 if (result.success) {
   console.log(result.prettyJson);
+  // result.scanResult contains raw detections for further AI analysis
 }
 ```
 
@@ -106,12 +131,14 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 ## How It Works
 
 ```
-Input ─> Validator ─> Scanner ─> Context7 Verifier ─> Impact Scorer
-  ─> Conflict Detection ─> Vuln Scanner ─> License Filter
+Input ─> Validator ─> Scanner ─> Recommender (AI Agent) ─> Context7 Verifier
+  ─> Impact Scorer ─> Conflict Detection ─> Vuln Scanner ─> License Filter
   ─> Migration Planner ─> UX Auditor ─> Auto-Updater
   ─> Serializer ─> PR Creator ─> Output
 ```
 
+**Key architecture**: The scanner detects WHAT is hand-rolled; the **Recommender** (AI agent or caller) decides WHAT library to use. No library recommendations are hardcoded — they are provided dynamically based on project context, ecosystem knowledge, and Context7 verification.
+
 Each stage is a pure function with structured I/O. All external dependencies (Context7, OSV, npm registry, GitHub API) are **injected via interfaces** for testability.
 
 ### Before / After
@@ -211,11 +238,16 @@ const logger = pino({
 |--------|------|:--------:|-------------|
 | `input` | `InputSchema` | Yes | Project metadata, goals, constraints, focus areas |
 | `context7Client` | `Context7Client` | Yes | Context7 MCP client for doc verification |
+| `recommender` | `Recommender` | Yes | Maps each detection → library recommendation (AI agent provides this) |
 | `vulnClient` | `VulnerabilityClient` | No | OSV client for vulnerability scanning |
 | `registryClient` | `RegistryClient` | No | Package registry client for auto-update |
 | `platformClient` | `PlatformClient` | No | GitHub/GitLab client for PR creation |
 | `gitOps` | `GitOperations` | No | Git CLI operations for PR creation |
 
+### `scanCodebase(input): Promise<ScanResult>`
+
+Standalone scanner — returns detections and workspace info without recommendations. AI agents can call this first, then provide recommendations via the `Recommender` callback.
+
 ### Output Structure
 
 ```jsonc
@@ -257,7 +289,7 @@ const logger = pino({
 ## Testing
 
 ```bash
-pnpm test          # 191 tests (vitest + fast-check)
+pnpm test          # 198 tests (vitest + fast-check)
 pnpm typecheck     # TypeScript strict mode
 pnpm build         # Compile to dist/
 ```
@@ -306,9 +338,13 @@ Releases are automated via GitHub Actions:
 # Tag a new version
 git tag v2.0.0
 git push origin v2.0.0
-# → CI runs tests → creates GitHub Release → publishes to npm
+# → CI runs tests → creates GitHub Release → publishes to npmjs + GitHub Packages
 ```
 
+Packages are also published automatically on every push to `main` via the CI workflow.
+
+> **Required Secrets**: `NPM_TOKEN` (npmjs.org publish token). `GITHUB_TOKEN` is provided automatically.
+
 See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
 ## License

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: analyze-and-recommend-third-party-optimizations
 description: Scans any codebase and identifies where hand-rolled implementations should be replaced by battle-tested third-party libraries, producing structured migration plans with Context7-verified recommendations
-version: 2.0.0
+version: 1.0.1
 author: TsekaLuk
 tags:
   - code-analysis
@@ -20,299 +20,130 @@ tags:
 
 ## Purpose
 
-This SKILL scans a codebase to identify hand-rolled implementations that should be replaced by mature, battle-tested third-party libraries. It produces structured, actionable artifacts: comparison tables, 7-dimension impact scores, phased migration plans, deletion checklists, and UX completeness audits — all verified against real documentation via Context7 MCP.
+Scan a codebase to identify hand-rolled implementations that should be replaced by third-party libraries. The scanner detects WHAT is hand-rolled; the AI agent decides WHAT to recommend based on project context, current ecosystem knowledge, and Context7 MCP verification.
 
-## Prerequisites
+## Architecture
 
-- Node.js 18+ runtime
-- Access to Context7 MCP service (for library verification)
-- A valid `InputSchema` JSON describing the target project
+```
+Scanner (deterministic)     →  AI Agent (generative)        →  Pipeline (deterministic)
+Regex patterns detect          Agent recommends library         Score, plan, audit,
+hand-rolled code               using knowledge + Context7       filter, serialize
+```
+
+**Key principle**: The pattern catalog contains NO hardcoded library recommendations. Library choices depend on project framework, runtime, existing dependencies, and current ecosystem state — all of which the AI agent evaluates dynamically.
 
 ## Standard Operating Procedure
 
 ### Step 1: Validate Input
 
-Parse and validate the incoming `InputSchema` JSON using Zod schema validation. The input must include:
-
-- **Project metadata**: repository path, languages, package managers, current libraries map
-- **Optimization goals**: array of goals describing what the project wants to improve
-- **Constraints**: license allowlist, excluded libraries, max dependency count
-- **Priority focus areas**: Vibe Coding Domains to prioritize (i18n, seo, growth-hacking, ai-model-serving, agent-architecture, content-marketing, cross-border-ecommerce, observability, auth-security, ux-completeness)
-- **Impact weights** (optional): custom weights for the 7 scoring dimensions
-
-If validation fails, return a structured error response with field-level messages. Do not proceed.
+Parse and validate `InputSchema` JSON via Zod. Required fields:
+- **Project metadata**: repo path, languages, package managers, current libraries
+- **Optimization goals**: what the project wants to improve
+- **Constraints**: license allowlist, excluded libraries
+- **Priority focus areas**: Vibe Coding Domains to prioritize
 
 ### Step 2: Scan Codebase
 
-Walk the project file tree and match source files against the pattern catalog. The scanner:
+Run `scanCodebase(input)` to walk the file tree and match against regex patterns. The scanner:
 
-1. Detects workspace roots for monorepo support (package.json, pyproject.toml, etc.)
-2. Scans each workspace independently
-3. Matches code patterns against a catalog covering 10 Vibe Coding Domains
-4. Records each detection with: file path, line range, pattern category, confidence score, suggested library, and domain tag
-5. Skips unreadable files (binary, permissions) gracefully
+1. Detects workspace roots for monorepo support
+2. Matches code against 20+ domain patterns (i18n, auth, state-management, etc.)
+3. Records each detection with: file path, line range, pattern category, confidence score, domain
+4. Returns `ScanResult` with detections and workspace info
 
-### Step 3: Verify with Context7 MCP
+Detections contain **no library suggestions** — only what was detected and where.
 
-For each detected recommendation, verify the suggested library against real, version-correct documentation:
+### Step 3: Recommend Libraries (AI Agent)
 
-1. Call `resolve-library-id` with the library name to obtain the canonical Context7 identifier
-2. Call `get-library-docs` to retrieve version-specific documentation and confirm the use case
-3. Set verification status:
-   - **verified** — Context7 confirmed the library and use case
-   - **unverified** — Context7 could not resolve the library identifier
-   - **unavailable** — Context7 service was unreachable (after one retry)
+For each detection, recommend the best library based on:
 
-### Step 4: Score Impact
+1. **Project context** — framework (Next.js → next-intl, Vite → @lingui/core), runtime (Edge → jose, not jsonwebtoken), existing deps
+2. **Ecosystem knowledge** — use your training knowledge of current best practices
+3. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm the library exists and get latest version/docs
 
-Compute a 7-dimension impact score for each recommendation:
+Return a `LibraryRecommendation` per detection:
+```typescript
+{ library: string; version: string; license: string }
+```
 
-| Dimension | Range |
-|-----------|-------|
-| Scalability | 1–10 |
-| Performance | 1–10 |
-| Security | 1–10 |
-| Maintainability | 1–10 |
-| Feature Richness | 1–10 |
-| UX | 1–10 |
-| UI Aesthetics | 1–10 |
+Return `null` to skip a detection (intentional custom code, false positive, etc.).
 
-- Compute a **composite score** as the weighted average of all dimensions
-- Apply a **1.2× priority boost** (capped at 10) for recommendations in priority focus areas
-- Assign **migration risk** (low / medium / high) and **estimated effort** in developer-hours
+**False positive filtering** — skip 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)
 
-### Step 5: Build Migration Plan
-
-Group recommendations into ordered phases based on risk:
+### Step 4: Score Impact
 
-1. **Phase 1** — Low-risk changes (quick wins)
-2. **Phase 2** — Medium-risk changes (moderate refactoring)
-3. **Phase 3** — High-risk changes (require adapter strategies)
+Compute 7-dimension impact scores (scalability, performance, security, maintainability, feature richness, UX, UI aesthetics) with composite score, migration risk, and estimated effort.
 
-For high-risk items, generate an **Adapter Strategy** specifying:
-- Wrapper interface
-- Legacy code being wrapped
-- Target library to transition to
+### Step 5: Build Migration Plan
 
-Build a **deletion checklist** listing every file and code range to remove after migration, with estimated lines saved.
+Group recommendations into phases by risk (low → medium → high), ordered by domain priority (infrastructure first, presentation last). High-risk items include adapter strategies.
 
 ### Step 6: Audit UX Completeness
 
-Evaluate the frontend codebase across 8 UX categories:
-
-1. **Accessibility (A11y)** — ARIA attributes, semantic HTML, keyboard navigation
-2. **Error states** — Error boundaries, error messages, fallback UI
-3. **Empty states** — Empty data placeholders, zero-state illustrations
-4. **Loading states** — Skeletons, spinners, suspense boundaries
-5. **Form validation** — Client-side validation, error messages, field states
-6. **Performance feel** — Optimistic updates, transitions, lazy loading
-7. **Copy consistency** — i18n usage, consistent terminology
-8. **Design system alignment** — Component library usage, token adherence
-
-For each gap found, map it to a recommended library with a rationale.
+Evaluate frontend codebase across 8 UX categories: accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment.
 
 ### Step 7: Apply Constraints and Serialize
 
-1. **Dependency conflict detection** — Flag conflicts with existing libraries, set migration risk to high
-2. **License filtering** — Exclude recommendations whose library license is not in the allowlist
-3. **Serialize** the final `OutputSchema` to pretty-printed JSON (2-space indent) with round-trip guarantee
-
-### Step 8: Vulnerability Scanning (Optional)
-
-Scan both current and recommended dependencies for known security vulnerabilities:
+Filter by license allowlist, detect dependency conflicts, serialize to JSON.
 
-1. Query the **OSV** (Open Source Vulnerabilities) database via injected `VulnerabilityClient`
-2. Scan **current dependencies** for known CVEs and advisories
-3. Scan **recommended replacement libraries** to prevent "upgrade into a vulnerability" scenarios
-4. Filter findings by `minimumSeverity` threshold (critical > high > medium > low)
-5. Compute summary: total scanned, count by severity, fixable vs unfixable
-6. Generate SARIF output for CI/CD integration (GitHub Code Scanning)
+### Optional Steps
 
-If the OSV service is unavailable, set `serviceUnavailable: true` and continue the pipeline.
+- **Step 8**: Vulnerability scanning via OSV database
+- **Step 9**: Auto-update existing dependencies via registry queries
+- **Step 10**: PR auto-creation via GitHub/GitLab API
 
-### Step 9: Auto-Update Existing Dependencies (Optional)
+## Programmatic API
 
-Analyze all existing dependencies and recommend version upgrades:
+```typescript
+import { analyze, scanCodebase } from './src/index.js';
+import type { Recommender } from './src/index.js';
 
-1. Query package registries (npm, PyPI, crates.io, Go) via injected `RegistryClient`
-2. Apply configurable **update policy**: patch/minor/major strategy, pinned packages, min-age window
-3. Verify changelogs via **Context7 MCP** to detect breaking changes, new features, deprecations
-4. Score each update using the same **7-dimension impact model**
-5. Classify urgency: critical (fixes CVE), urgent (deprecated), recommended (new features), routine
-6. Group related packages (e.g. all `@babel/*` together)
-7. Build structured update plan with summary statistics
+// Step 1: Scan standalone (for AI agent inspection)
+const scanResult = await scanCodebase(validatedInput);
 
-If the registry is unavailable, skip the update plan silently.
-
-### Step 10: PR Auto-Creation (Optional)
-
-Automatically create GitHub/GitLab pull requests for updates and migrations:
-
-1. **Plan PRs** — Security fixes as separate PRs, grouped updates, migration PRs by phase
-2. **Generate code changes** — Update version in manifest files, scaffold adapter code for migrations
-3. **Build PR descriptions** — Rich markdown with impact tables, vulnerability details, reviewer checklist
-4. **Create branches and PRs** — Via injected `PlatformClient` and `GitOperations`
-5. **Deduplicate** — Update existing PRs instead of creating duplicates
-6. **Enforce limits** — Respect `maxOpenPRs`, prioritize security fixes first
-
-PR titles follow conventional commit format: `fix(deps):`, `chore(deps):`, `refactor(domain):`.
-
-## Output Artifacts
-
-The SKILL produces a single `OutputSchema` JSON containing:
-
-- `recommendedChanges` — Array of recommendations with impact scores, verification status, and adapter strategies
-- `filesToDelete` — Array of file paths to remove after migration
-- `linesSavedEstimate` — Total lines of code saved
-- `uxAudit` — Structured UX completeness checklist
-- `migrationPlan` — Phased plan with deletion checklist
-- `vulnerabilityReport` (optional) — Vulnerability findings, summary, SARIF output
-- `updatePlan` (optional) — Scored dependency updates with groups and summary
-- `pullRequests` (optional) — Created/updated PR results with status summary
-
-## Usage
-
-```bash
-# Run the analysis
-npx tsx src/index.ts < input.json > output.json
-
-# Or import programmatically
-import { analyze } from './src/index.js';
+// Step 2: Full pipeline with recommender
+const recommender: Recommender = (detection) => ({
+  library: 'zustand',
+  version: '^5.0.0',
+  license: 'MIT',
+});
 
 const result = await analyze({
   input: inputJson,
   context7Client: myContext7Client,
-  // Phase 2 optional clients:
-  vulnClient: myOsvClient,          // enables vulnerability scanning
-  registryClient: myRegistryClient,  // enables auto-update
-  platformClient: myGitHubClient,    // enables PR creation
-  gitOps: myGitOperations,           // enables PR creation
+  recommender, // AI agent provides this
 });
 ```
 
-## Vibe Coding Domain Coverage (68 domains, ISO 25010-aligned)
-
-Domains are NOT "tech stack" labels — they are problem areas most likely to be hand-rolled where mature libraries should be preferred. Organized by ISO 25010 quality characteristics.
-
-### A. UX Completeness & Design System (Usability / UI quality)
-
-| Domain | Examples |
-|--------|----------|
-| ux-completeness | radix-ui, react-aria, framer-motion |
-| ui-aesthetics | tailwindcss, class-variance-authority |
-| design-system | @radix-ui/themes, @chakra-ui/react |
-| theming-dark-mode | next-themes, tailwindcss dark mode |
-| a11y-accessibility | react-aria, axe-core, eslint-plugin-jsx-a11y |
-| responsive-mobile-ux | tailwindcss, react-responsive |
-| empty-loading-error-states | react-loading-skeleton, react-error-boundary |
-| forms-ux | react-hook-form, formik |
-| validation-feedback | zod, yup, vest |
-| navigation-information-architecture | next/navigation, react-router |
-| notifications-inapp | sonner, react-hot-toast |
-| tables-data-grid-ux | @tanstack/react-table, ag-grid |
-| filters-sort-search-ux | @tanstack/react-table, fuse.js |
-| onboarding-guided-tour | react-joyride, shepherd.js |
-
-### B. SEO / i18n / Content (Discoverability / Global-ready)
-
-| Domain | Examples |
-|--------|----------|
-| seo | next-seo, schema-dts, next-sitemap |
-| i18n | next-intl, react-i18next, FormatJS |
-| localization-ux | @formatjs/intl, date-fns/locale |
-| content-marketing | contentlayer, next-mdx-remote, sanity |
-| landing-page-conversion | next-seo, posthog, ab-testing libs |
-
-### C. Growth & Data (Experimentation / Analytics)
-
-| Domain | Examples |
-|--------|----------|
-| growth-hacking | posthog, launchdarkly, mixpanel |
-| analytics-tracking | posthog-js, segment, plausible |
-| attribution-measurement | segment, mixpanel |
-| ab-testing-experimentation | posthog, growthbook, statsig |
-| product-led-growth | posthog, canny, intercom |
-| retention-lifecycle-crm | customer.io, braze |
-| referrals-virality | referral-saasquatch |
-
-### D. App / Frontend Architecture (Maintainability / Modularity)
-
-| Domain | Examples |
-|--------|----------|
-| agent-architecture | @modelcontextprotocol/sdk, ai (Vercel AI SDK) |
-| frontend-architecture | next.js, remix, vite |
-| state-management | zustand, jotai, @tanstack/react-query |
-| data-fetching-caching | @tanstack/react-query, swr, apollo-client |
-| error-handling-resilience | react-error-boundary, neverthrow |
-| realtime-collaboration | yjs, liveblocks, socket.io |
-| file-upload-media | uploadthing, tus-js-client |
-| search-discovery | meilisearch, typesense, algolia |
-
-### E. Backend / Platform (Scalability / Reliability / Compatibility)
-
-| Domain | Examples |
-|--------|----------|
-| api-design-contracts | openapi, trpc, graphql-codegen |
-| backend-architecture | fastify, hono, nestjs |
-| database-orm-migrations | prisma, drizzle, knex |
-| caching-rate-limit | rate-limiter-flexible, ioredis |
-| jobs-queue-scheduler | bullmq, temporal, inngest |
-| webhooks-integrations | svix, hookdeck |
-| feature-flags-config | unleash, launchdarkly, growthbook |
-| multi-tenancy-saas | @clerk/nextjs, auth0 |
-
-### F. Security / Compliance (Security)
-
-| Domain | Examples |
-|--------|----------|
-| auth-security | next-auth, passport, jose |
-| permissions-rbac-ux | casl, casbin |
-| security-hardening | helmet, csp-header |
-| privacy-compliance | consent-manager, cookie-consent |
-| fraud-abuse-prevention | arcjet, cloudflare turnstile |
-
-### G. Observability / Ops (Reliability / Operability)
-
-| Domain | Examples |
-|--------|----------|
-| observability | pino, opentelemetry, sentry |
-| logging-tracing-metrics | pino, @opentelemetry/sdk-node |
-| error-monitoring | @sentry/node, bugsnag |
-| alerting-incident-response | pagerduty, opsgenie |
-
-### H. Delivery / Quality / DevEx (Maintainability / DevEx)
-
-| Domain | Examples |
-|--------|----------|
-| testing-strategy | vitest, playwright, fast-check |
-| ci-cd-release | changesets, semantic-release |
-| devex-tooling | turborepo, nx, biome |
-| documentation-sop | typedoc, storybook, mintlify |
-| code-quality-linting | eslint, biome, prettier |
-| dependency-management | renovate, depcheck |
-
-### I. Performance / Cost (Performance efficiency)
-
-| Domain | Examples |
-|--------|----------|
-| performance-web-vitals | @next/bundle-analyzer, lighthouse |
-| backend-performance | autocannon, clinic.js |
-| cost-optimization | aws-cost-explorer, infracost |
-
-### J. AI Engineering
-
-| Domain | Examples |
-|--------|----------|
-| ai-model-serving | transformers.js, onnxruntime, langchain |
-| ai-evaluation-observability | langfuse, promptfoo |
-| rag-vector-search | @pinecone-database/pinecone, chromadb |
-
-### K. Business Domains (optional)
-
-| Domain | Examples |
-|--------|----------|
-| cross-border-ecommerce | stripe, shopify-api, taxjar |
-| payments-billing | stripe, lemon-squeezy |
-| marketplace-platform | medusa, saleor |
-
-> **Extensibility:** The enum covers official domains. Use `customDomains?: string[]` in the input schema for community/project-specific domains without breaking the type system.
+## Output Artifacts
+
+Single `OutputSchema` JSON containing:
+- `recommendedChanges` — recommendations with scores, verification status, adapter strategies
+- `filesToDelete` — file paths to remove after migration
+- `linesSavedEstimate` — total lines saved
+- `uxAudit` — UX completeness checklist
+- `migrationPlan` — phased plan with deletion checklist
+- `vulnerabilityReport` (optional)
+- `updatePlan` (optional)
+- `pullRequests` (optional)
+
+## Vibe Coding Domain Coverage (20+ detection patterns)
+
+| Category | Domains |
+|----------|---------|
+| UX / Design | ux-completeness, a11y-accessibility, forms-ux, state-management |
+| SEO / i18n / Content | seo, i18n, content-marketing |
+| Growth / Data | growth-hacking |
+| App Architecture | agent-architecture, data-fetching-caching, error-handling-resilience |
+| Backend / Platform | database-orm-migrations, auth-security |
+| Observability | observability, logging-tracing-metrics |
+| Testing | testing-strategy |
+| AI Engineering | ai-model-serving |
+| Business | cross-border-ecommerce |
+| File / Media | file-upload-media |
+
+> **Extensibility:** Use `customDomains?: string[]` in input for project-specific domains.

package/dist/analyzer/pattern-catalog.d.ts

@@ -2,6 +2,12 @@ import type { VibeCodingDomain } from '../schemas/input.schema.js';
 /**
  * Defines a pattern that identifies hand-rolled code which could be
  * replaced by a battle-tested third-party library.
+ *
+ * NOTE: This interface intentionally contains NO library recommendation data.
+ * Library recommendations are the AI agent's responsibility — the agent uses
+ * its own knowledge + Context7 MCP to determine the best library for each
+ * detection at runtime, considering the project's framework, existing deps,
+ * and architectural context.
  */
 export interface PatternDefinition {
     /** Unique identifier for this pattern (e.g., "i18n-manual-pluralization") */
@@ -14,18 +20,15 @@ export interface PatternDefinition {
     filePatterns: string[];
     /** Regex patterns to match hand-rolled code */
     codePatterns: RegExp[];
-    /** The library recommended to replace the hand-rolled code */
-    suggestedLibrary: string;
-    /** Recommended version of the suggested library */
-    suggestedVersion: string;
-    /** SPDX license identifier of the suggested library */
-    license: string;
     /** Base confidence score for this pattern (0–1) */
     confidenceBase: number;
 }
 /**
- * Returns the full pattern catalog covering all Vibe Coding domains.
- * Each domain has at least 1–2 patterns.
+ * Returns the full pattern catalog covering Vibe Coding domains.
+ * Each covered domain has 2–3 patterns for hand-rolled code detection.
+ *
+ * The catalog defines WHAT to detect, not WHAT to recommend.
+ * Library recommendations are generated dynamically by the AI agent.
  */
 export declare function getPatternCatalog(): PatternDefinition[];
 /**

package/dist/analyzer/pattern-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/analyzer/pattern-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,gBAAgB,CAAC;IACzB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,EAAE,CAmVvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAExE"}
+{"version":3,"file":"pattern-catalog.d.ts","sourceRoot":"","sources":["../../src/analyzer/pattern-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,gBAAgB,CAAC;IACzB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,EAAE,CAuiBvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAExE"}