@nebutra/next-unicorn-skill 1.0.3 → 1.0.5

package/README.md

@@ -11,7 +11,7 @@
   <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-198%20passed-brightgreen.svg" alt="Tests" /></a>
+  <a href="./tests/"><img src="https://img.shields.io/badge/tests-210%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>
 
@@ -31,9 +31,9 @@
 
 Every codebase accumulates hand-rolled implementations that should be mature libraries. Custom date formatters, DIY loggers, bespoke state machines, ad-hoc i18n — **Vibe Coding debt**.
 
-Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't find code you wrote that *should become* a dependency.
+Snyk, Dependabot, and Renovate manage your *existing* dependencies. They can't find code you wrote that *should become* a dependency — or capabilities your project is *missing entirely*.
 
-**Next-Unicorn does both** — and verifies every recommendation against real documentation via [Context7 MCP](https://context7.com).
+**Next-Unicorn does all three** — replacement, gap analysis, and dependency management — verified against real documentation via [Context7 MCP](https://context7.com).
 
 ## Quick Start
 
@@ -61,18 +61,36 @@ npm install @nebutra/next-unicorn-skill
 
 ```typescript
 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',
-  };
-};
+import type { Recommender, GapRecommendation } from '@nebutra/next-unicorn-skill';
+
+// The recommender: AI agent decides which library fits each detection
+const recommender: Recommender = (detection) => ({
+  library: '@lingui/core',
+  version: '^4.0.0',
+  license: 'MIT',
+  rationale: 'Compile-time i18n with near-zero runtime overhead',
+  ecosystem: [
+    { library: '@lingui/macro', version: '^4.0.0', role: 'Tagged templates' },
+    { library: '@lingui/cli', version: '^4.0.0', role: 'CI message extraction' },
+  ],
+  antiPatterns: ['Avoid i18next if bundle size matters — Lingui compiles away'],
+  alternatives: [
+    { library: 'next-intl', when: 'Next.js App Router with server components' },
+  ],
+});
+
+// Gap analysis: capabilities the project should have but doesn't
+const gaps: GapRecommendation[] = [
+  {
+    domain: 'observability',
+    description: 'No structured logging detected',
+    recommendedLibrary: {
+      name: 'pino', version: '^9.0.0', license: 'MIT',
+      rationale: 'Fastest Node.js JSON logger with redaction and child loggers',
+    },
+    priority: 'critical',
+  },
+];
 
 const result = await analyze({
   input: {
@@ -83,27 +101,22 @@ const result = await analyze({
       currentLibraries: { react: '18.2.0', next: '14.1.0' },
     },
     optimizationGoals: ['reduce custom code', 'improve maintainability'],
-    constraints: {
-      licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'],
-    },
+    constraints: { licenseAllowlist: ['MIT', 'Apache-2.0', 'ISC'] },
     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
-  platformClient: myGitHubClient,    // PR creation
-  gitOps: myGitOperations,           // PR creation
+  recommender,
+  gaps,
 });
 
 if (result.success) {
   console.log(result.prettyJson);
-  // result.scanResult contains raw detections for further AI analysis
+  // result.scanResult — raw detections + structural findings for AI analysis
+  // result.output.gapAnalysis — Context7-verified gap recommendations
 }
 ```
 
-Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent (Claude Code, Kiro, etc.).
+Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent (Claude Code, Kiro, Cursor, etc.).
 
 ## Features
 
@@ -111,17 +124,19 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 
 | Feature | Description |
 |---------|-------------|
-| **Pattern-based scanning** | Detects hand-rolled code across 68 Vibe Coding Domains (ISO 25010-aligned) |
-| **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't (e.g., no error monitoring, no rate limiting, no event-driven workflows) |
-| **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives — not just "use library X" |
-| **Context7 verification** | Every recommendation verified against real, version-correct documentation |
+| **Pattern-based scanning** | Detects hand-rolled code across 30 domains with 40+ regex patterns (design-system, auth, state-management, etc.) |
+| **Structural analysis** | Detects monorepo architecture gaps: missing token layers, dependency flow violations, hardcoded config values |
+| **Gap analysis** | AI agent identifies missing capabilities — not just hand-rolled code, but things you should have but don't |
+| **Ecosystem-level recommendations** | Solutions include rationale, companion packages, anti-patterns, and alternatives |
+| **Context7 verification** | Every recommendation (replacements AND gaps) verified with exponential backoff retry |
 | **7-dimension impact scoring** | Scalability, performance, security, maintainability, feature richness, UX, UI aesthetics |
 | **Phased migration plans** | Low / medium / high risk phases with adapter strategies |
 | **Deletion checklists** | Every file and line range to remove, with estimated lines saved |
 | **UX completeness audit** | A11y, error/empty/loading states, form validation, design system alignment |
+| **Design system support** | Two paths: scaffold from reference repos (Primer, Polaris, Supabase, Dub) or extract from existing code |
 | **Monorepo support** | Detects npm, pip, cargo, go workspaces independently |
 
-### Dependency Management (v2.0)
+### Dependency Management
 
 | Feature | Description |
 |---------|-------------|
@@ -133,13 +148,14 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 ## How It Works
 
 ```
-Input ─> Validator ─> Scanner ─> Recommender (AI Agent) ─> Context7 Verifier
+Input ─> Validator ─> Scanner + Structure Analyzer
+  ─> Gap Analysis (AI Agent) ─> 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.
+**Key architecture**: The scanner detects WHAT is hand-rolled; the structure analyzer detects architectural gaps; the **Recommender** (AI agent or caller) decides WHAT 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.
 
@@ -166,14 +182,14 @@ function t(key, locale) {
 <td>
 
 ```tsx
-// next-intl — Context7 verified, MIT
-// Impact: 9.2/10 composite
-// Migration risk: low | Effort: 8h
-import { useTranslations } from 'next-intl';
+// @lingui/core — Context7 verified, MIT
+// Ecosystem: @lingui/macro + @lingui/cli
+// Impact: 9.2/10 | Risk: low | Effort: 8h
+import { useLingui } from '@lingui/react';
 
 export default function Page() {
-  const t = useTranslations('common');
-  return <h1>{t('greeting')}</h1>;
+  const { t } = useLingui();
+  return <h1>{t`greeting`}</h1>;
 }
 ```
 
@@ -199,8 +215,8 @@ function logRequest(req) {
 
 ```typescript
 // pino — Context7 verified, MIT
-// Impact: 9.0/10 composite
-// Migration risk: low | Effort: 4h
+// Gap analysis: "No structured logging detected"
+// Priority: critical
 import pino from 'pino';
 const logger = pino({
   level: 'info',
@@ -217,11 +233,15 @@ const logger = pino({
 | Feature | Next-Unicorn | Snyk | Dependabot | Renovate |
 |---------|:---:|:---:|:---:|:---:|
 | Finds hand-rolled code to replace | **Yes** | | | |
+| Identifies missing capabilities (gaps) | **Yes** | | | |
+| Structural architecture analysis | **Yes** | | | |
 | Recommends new libraries | **Yes** | | | |
+| Ecosystem-level solutions | **Yes** | | | |
 | 7-dimension impact scoring | **Yes** | | | |
 | Context7 doc verification | **Yes** | | | |
 | Phased migration plans | **Yes** | | | |
 | UX completeness audit | **Yes** | | | |
+| Design system scaffold/extraction | **Yes** | | | |
 | Deletion checklists | **Yes** | | | |
 | Vulnerability scanning | **Yes** | Yes | Yes | |
 | Scans *recommended* libs for vulns | **Yes** | | | |
@@ -249,14 +269,18 @@ const logger = pino({
 
 ### `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.
+Standalone scanner — returns detections, workspace info, and structural findings (design system layer analysis, dependency flow violations). AI agents can call this first, then provide recommendations via the `Recommender` callback.
+
+### `analyzeStructure(repoPath, workspaces): StructuralAnalysis`
+
+Standalone structure analyzer — detects missing design system layers, dependency flow violations, hardcoded config values, and missing shared presets in monorepos.
 
 ### Output Structure
 
 ```jsonc
 {
   "recommendedChanges": [...],     // Replacement recommendations with impact scores
-  "gapAnalysis": [...],            // (optional) Missing capabilities with prioritized recs
+  "gapAnalysis": [...],            // (optional) Context7-verified gap recommendations
   "filesToDelete": [...],          // Files to remove after migration
   "linesSavedEstimate": 1250,      // Total lines saved
   "uxAudit": [...],                // UX completeness (8 categories)
@@ -272,16 +296,16 @@ Standalone scanner — returns detections and workspace info without recommendat
 
 ## Vibe Coding Domains
 
-68 domains across 11 categories, aligned with ISO/IEC 25010:
+68 domains across 11 categories, aligned with ISO/IEC 25010. 30 domains have scanner patterns; the rest are covered by AI agent gap analysis.
 
 | Category | Count | Examples |
 |----------|:-----:|---------|
-| UX / Design | 14 | `ux-completeness`, `a11y-accessibility`, `forms-ux`, `design-system` |
+| UX / Design | 14 | `design-system`, `a11y-accessibility`, `forms-ux`, `empty-loading-error-states` |
 | SEO / i18n | 5 | `seo`, `i18n`, `content-marketing` |
 | Growth / Data | 7 | `analytics-tracking`, `ab-testing-experimentation` |
-| Frontend Arch | 8 | `state-management`, `data-fetching-caching`, `agent-architecture` |
-| Backend / Platform | 8 | `database-orm-migrations`, `jobs-queue-scheduler`, `feature-flags-config` |
-| Security | 5 | `auth-security`, `permissions-rbac-ux`, `fraud-abuse-prevention` |
+| Frontend Arch | 8 | `state-management`, `data-fetching-caching`, `realtime-collaboration` |
+| Backend / Platform | 8 | `database-orm-migrations`, `caching-rate-limit`, `feature-flags-config` |
+| Security | 5 | `auth-security`, `security-hardening`, `fraud-abuse-prevention` |
 | Observability | 4 | `logging-tracing-metrics`, `error-monitoring` |
 | Delivery / DevEx | 6 | `testing-strategy`, `ci-cd-release`, `dependency-management` |
 | Performance | 3 | `performance-web-vitals`, `cost-optimization` |
@@ -293,7 +317,7 @@ Standalone scanner — returns detections and workspace info without recommendat
 ## Testing
 
 ```bash
-pnpm test          # 198 tests (vitest + fast-check)
+pnpm test          # 210 tests (vitest + fast-check)
 pnpm typecheck     # TypeScript strict mode
 pnpm build         # Compile to dist/
 ```
@@ -330,6 +354,13 @@ pnpm build         # Compile to dist/
 | [`update-plan.md`](./templates/update-plan.md) | Dependency update plan |
 | [`prd-template.md`](./templates/prd-template.md) | PRD for stakeholder presentation |
 
+## References
+
+| Reference | Purpose |
+|-----------|---------|
+| [`design-system-sources.md`](./references/design-system-sources.md) | 25+ curated design system repos for scaffolding (Primer, Polaris, Dub, Supabase, etc.) |
+| [`design-system-extraction.md`](./references/design-system-extraction.md) | Workflow for extracting a design system from existing code (6 principles, 5 phases) |
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
@@ -340,8 +371,8 @@ Releases are automated via GitHub Actions:
 
 ```bash
 # Tag a new version
-git tag v2.0.0
-git push origin v2.0.0
+git tag v1.0.5
+git push origin v1.0.5
 # → CI runs tests → creates GitHub Release → publishes to npmjs + GitHub Packages
 ```
 

package/SKILL.md

@@ -1,27 +1,15 @@
 ---
 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: 1.0.3
-author: TsekaLuk
-tags:
-  - code-analysis
-  - third-party-libraries
-  - migration-planning
-  - dependency-optimization
-  - context7-verification
-  - ux-audit
-  - impact-scoring
-  - vulnerability-scanning
-  - auto-update
-  - pr-automation
+description: >-
+  Scan a codebase to identify hand-rolled implementations that should be replaced
+  by third-party libraries, and identify missing capabilities the project should
+  have. Produce structured migration plans with Context7-verified recommendations.
+  Use when analyzing technical debt, auditing dependency health, reviewing
+  hand-rolled code, planning library migrations, or assessing capability gaps.
 ---
 
 # Analyze and Recommend Third-Party Optimizations
 
-## Purpose
-
-Two-pronged analysis: (1) detect hand-rolled code that should be replaced by libraries, and (2) identify missing capabilities the project should have. The scanner pre-filters; the AI agent provides unicorn-grade recommendations — ecosystem-level solutions with rationale, anti-patterns, and alternatives, verified via Context7 MCP.
-
 ## Architecture
 
 ```
@@ -31,82 +19,60 @@ hand-rolled code               2. Identify capability gaps         filter, seria
                                using knowledge + Context7
 ```
 
-**Key principles**:
-- No hardcoded library recommendations — the AI agent evaluates project context dynamically
-- Two analysis modes: **replacement** (hand-rolled code → library) and **gap** (missing capability → library)
+**Design constraints**:
+- No hardcoded library recommendations — evaluate project context dynamically
+- Two analysis modes: **replacement** (hand-rolled code found) and **gap** (capability missing entirely)
 
 ## Standard Operating Procedure
 
 ### Step 1: Validate Input
 
-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
+Parse and validate `InputSchema` JSON via Zod. Read `src/schemas/input.schema.ts` for the full schema.
 
 ### Step 2: Scan Codebase
 
-Run `scanCodebase(input)` to walk the file tree and match against regex patterns. The scanner:
+Run `scanCodebase(input)`. The scanner:
 
-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
+1. Detect workspace roots for monorepo support
+2. Match code against 20+ domain patterns (i18n, auth, state-management, etc.)
+3. Record each detection with: file path, line range, pattern category, confidence score, domain
+4. Return `ScanResult` with detections and workspace info
 
-Detections contain **no library suggestions** — only what was detected and where.
+Detections contain no library suggestions — only what was detected and where.
 
 ### Step 2.5: Gap Analysis (AI Agent)
 
-Beyond what the scanner detects (hand-rolled code), analyze what the project is **missing entirely**. Review `currentLibraries`, `languages`, `optimizationGoals`, and `priorityFocusAreas` to identify capability gaps.
-
-Think at the level of unicorn-grade products:
-- "No structured logging" → recommend pino + OpenTelemetry ecosystem
-- "No error monitoring" → recommend Sentry with source maps + release health
-- "No event-driven workflows" → recommend Inngest for reliable async tasks
-- "Using nodemailer" → recommend Resend for modern transactional email
-- "No rate limiting or bot protection" → recommend Arcjet as unified security layer
-- "REST API without type safety" → recommend tRPC for end-to-end types
-
-Provide each gap as a `GapRecommendation`:
-```typescript
-{
-  domain: string;                // e.g., "observability"
-  description: string;           // e.g., "No structured logging detected"
-  recommendedLibrary: { name, version, license, rationale?, ecosystem?, antiPatterns?, alternatives? };
-  priority: 'critical' | 'recommended' | 'nice-to-have';
-}
-```
+Beyond scanner detections, analyze what the project is **missing entirely**. Inspect:
+
+1. **Installed dependencies** — identify low-level tools that should be upgraded to platform-level solutions
+2. **Monorepo structure** — identify missing architectural layers (e.g., shared token package, shared config preset)
+3. **Cross-cutting concerns** — identify absent capabilities: structured logging, error monitoring, rate limiting, event-driven workflows, transactional email, type-safe API layer
+4. **Architecture patterns** — identify opportunities for multi-package solutions (e.g., design-tokens → tailwind-config → ui three-layer architecture for design systems)
+
+Analyze at three levels of depth:
+- **Single library gap**: missing one tool (e.g., no form validation library)
+- **Ecosystem gap**: missing a coordinated set of tools (e.g., no observability stack)
+- **Architecture gap**: missing an entire structural layer (e.g., no design system, no shared config)
 
-Pass gaps to `analyze()` via the `gaps` option. They appear in the output as `gapAnalysis`.
+Provide each gap as a `GapRecommendation`. Read `src/index.ts` for the interface. Pass gaps via the `gaps` option in `analyze()`.
+
+**Design system gaps** — Two paths depending on project maturity:
+- **No existing frontend**: Scaffold from reference repos. Read `references/design-system-sources.md` for curated sources and sparse-checkout workflow.
+- **Existing frontend without formal design system**: First extract the spec (audit → tokens → classify → document) via `references/design-system-extraction.md`, then implement the architecture via `references/design-system-sources.md`.
 
 ### Step 3: Recommend Solutions (AI Agent)
 
-For each detection, recommend a **solution** — not just a library, but an ecosystem-level answer. Consider:
+For each scanner detection, recommend a **solution**. Consider:
 
 1. **Ecosystem composition** — recommend companion libraries that work together
-   (e.g., `@lingui/core` + `@lingui/macro` + `@lingui/cli` for compile-time i18n with TMS integration)
-2. **Rationale** — explain WHY this specific choice fits this project's framework, runtime, and scale
-3. **Anti-patterns** — what NOT to use and why (e.g., "Never use jsonwebtoken — no edge runtime support; use jose")
+2. **Rationale** — explain WHY this choice fits this project's framework, runtime, and scale
+3. **Anti-patterns** — what NOT to use and why
 4. **Alternatives** — different solutions for different architectural contexts
 5. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm the library exists and get latest version/docs
 
-Return a `LibraryRecommendation` per detection:
-```typescript
-{
-  library: string;           // required — primary package
-  version: string;           // required
-  license: string;           // required
-  rationale?: string;        // recommended — WHY this choice
-  ecosystem?: Array<{...}>;  // when solution involves multiple packages
-  antiPatterns?: string[];   // when common mistakes exist
-  alternatives?: Array<{...}>;  // when architecture affects the choice
-}
-```
-
-Return `null` to skip a detection (intentional custom code, false positive, etc.).
+Read `src/index.ts` for the `LibraryRecommendation` interface. Return `null` to skip a detection.
 
-**False positive filtering** — skip if:
+**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)
@@ -114,15 +80,15 @@ Return `null` to skip a detection (intentional custom code, false positive, etc.
 
 ### Step 4: Score Impact
 
-Compute 7-dimension impact scores (scalability, performance, security, maintainability, feature richness, UX, UI aesthetics) with composite score, migration risk, and estimated effort.
+Call `computeImpactScore()` for each detection. Optionally provide `dimensionHints` and `baseEffortHours` for more accurate scoring. Read `src/scorer/impact-scorer.ts` for the interface.
 
 ### Step 5: Build Migration Plan
 
-Group recommendations into phases by risk (low → medium → high), ordered by domain priority (infrastructure first, presentation last). High-risk items include adapter strategies.
+Call `buildMigrationPlan()` to group recommendations into phases by risk (low, medium, high). High-risk items include adapter strategies.
 
 ### Step 6: Audit UX Completeness
 
-Evaluate frontend codebase across 8 UX categories: accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment.
+Call `auditUxCompleteness()` to evaluate 8 UX categories. The auditor determines status (present/partial/missing). Fill in `recommendedLibrary` on partial/missing items based on project context.
 
 ### Step 7: Apply Constraints and Serialize
 
@@ -130,73 +96,21 @@ Filter by license allowlist, detect dependency conflicts, serialize to JSON.
 
 ### Optional Steps
 
-- **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
-
-## Programmatic API
-
-```typescript
-import { analyze, scanCodebase } from './src/index.js';
-import type { Recommender, GapRecommendation } from './src/index.js';
-
-// Step 1: Scan standalone (for AI agent inspection)
-const scanResult = await scanCodebase(validatedInput);
-
-// Step 2: Full pipeline with recommender + gap analysis
-const recommender: Recommender = (detection) => ({
-  library: 'zustand',
-  version: '^5.0.0',
-  license: 'MIT',
-  rationale: 'Minimal state library — no providers, 1KB gzipped',
-});
-
-const gaps: GapRecommendation[] = [
-  {
-    domain: 'observability',
-    description: 'No structured logging detected',
-    recommendedLibrary: {
-      name: 'pino', version: '^9.0.0', license: 'MIT',
-      rationale: 'Fastest Node.js JSON logger with redaction and child loggers',
-    },
-    priority: 'critical',
-  },
-];
-
-const result = await analyze({
-  input: inputJson,
-  context7Client: myContext7Client,
-  recommender,
-  gaps,  // AI agent identifies missing capabilities
-});
-```
+- **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`)
 
-## Output Artifacts
+## 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
+- `uxAudit` — UX completeness checklist (8 categories)
 - `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.
+Read `src/schemas/output.schema.ts` for the full schema.

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

@@ -25,10 +25,13 @@ export interface PatternDefinition {
 }
 /**
  * Returns the full pattern catalog covering Vibe Coding domains.
- * Each covered domain has 2–3 patterns for hand-rolled code detection.
+ *
+ * Domain assignment rules:
+ * - Each pattern goes in its MOST SPECIFIC domain (e.g., A/B test → ab-testing-experimentation, not growth-hacking)
+ * - Parent domains (growth-hacking, observability, ux-completeness) are used only when no specific child domain fits
+ * - Domains with no regex-detectable patterns are left for Gap Analysis (AI Agent)
  *
  * 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;;;;;;;;;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"}
+{"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;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,EAAE,CAkqBvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAExE"}