@nebutra/next-unicorn-skill 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,119 @@ 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).
 
+## [2.1.0] - 2026-02-09
+
+### Breaking Changes
+
+- **`estimatedEffort` → `affectedFiles`** — replaced "developer-hours" estimation with concrete file count across all schemas, templates, and examples. AI programming has no concept of "effort hours". The field type changed from `number` (positive float) to `number` (non-negative integer).
+- **`estimatedTotalEffort` → `totalAffectedFiles`** — same change in `UpdatePlan.summary`.
+
+### Added
+
+- **`src/analyzer/types.ts`** — shared type definitions extracted to break circular dependencies (scanner ↔ structure-analyzer ↔ code-organization-analyzer). Zero circular deps confirmed via `madge --circular`.
+- **`src/orchestrator.ts`** — analysis pipeline extracted from index.ts. Entry point reduced from 517 lines to 65 lines (pure re-exports).
+- **CI circular dependency check** — `npx madge --circular` added to CI pipeline (zero new devDependencies).
+- **Language constraint** — SKILL.md output language now matches user's input language.
+
+### Changed
+
+- `index.ts` is now a pure re-export surface — all orchestration logic lives in `orchestrator.ts`
+- All templates updated: "Effort (hrs)" columns → "Files" columns
+- All example outputs updated to use `affectedFiles` field name
+- `RecommendedChange.affectedFiles` is now `z.number().int().nonnegative()` (was `z.number().positive()`)
+- `UpdateItem.affectedFiles` same type change
+
+## [1.0.8] - 2026-02-09
+
+### Added
+
+- **Human-in-the-loop Gate Protocol** — 4 explicit decision gates at irreversible, preference-driven, or costly decision points:
+  - Gate 1: Triage detections before Context7 verification (saves quota)
+  - Gate 2: Code organization preferences with SWOT analysis (team preferences)
+  - Gate 3: Accept/reject/defer recommendations (migration cost decisions)
+  - Gate 4: Confirm before PR creation and file migration (irreversible actions)
+- New `references/code-organization-workflow.md` — progressive disclosure reference with Gate examples, Phase A/B decision tree, and worked examples
+
+### Changed
+
+- SKILL.md refactored from 400 to 188 lines — verbose Gate/code-org examples extracted to references/ per progressive disclosure spec
+- Removed stale `org-mixed-export-style` reference from Phase A (pattern was moved to structural analyzer)
+- Gate Protocol compressed from 35 lines to 8 lines (meta-info)
+- All instructions converted to imperative voice per skill spec
+
+## [1.0.7] - 2026-02-09
+
+### Added
+
+- **Code Organization Analysis** — new deterministic module that detects structural code organization issues via filesystem traversal. Claude cannot infer these from knowledge alone.
+  - `god-directory` — directory with >15 source files (should split by feature/domain)
+  - `mixed-naming-convention` — files in same directory using different naming styles
+  - `deep-nesting` — directory tree exceeding 5 levels from `src/`
+  - `barrel-bloat` — index file with >10 re-exports
+  - `catch-all-directory` — `utils/helpers/shared/common/lib` with >10 files
+  - `circular-dependency` — import cycles detected via DFS graph traversal
+  - `mixed-export-style` — files mixing default export with 3+ named exports
+- 3 new scanner patterns in `code-organization` domain:
+  - `org-deep-relative-import` — imports traversing 3+ parent directories
+  - `org-barrel-reexport-wildcard` — `export * from` in index files
+  - `org-catch-all-utils-import` — imports from catch-all utils/helpers directories
+- New `code-organization` domain in `VibeCodingDomain` enum (69 total domains)
+- New `codeOrganizationStats` field in `ScanResult` (file counts, naming conventions, circular dep count)
+- New `analyzeCodeOrganization()` standalone export for programmatic use
+- SKILL.md Step 2.7 with Phase A (deterministic) / Phase B (generative) dual-phase design, MUST/MUST NOT decision table, 3 concrete examples, and skip rules
+- 29 new tests (176 total) covering all scanner patterns and structural analysis rules
+
+### Changed
+
+- `StructuralFinding.type` extended with 6 new code organization types + optional `metadata` field
+- Code organization analysis runs for ALL projects (not just monorepos, unlike design system analysis)
+- Architecture diagram in SKILL.md updated to reflect two-track scanner (regex + filesystem)
+- Scanner step description expanded to list all `ScanResult` fields explicitly
+
+## [1.0.3] - 2026-02-09
+
+### Added
+
+- **Gap Analysis** — AI agent can now identify capabilities the project is MISSING entirely, not just hand-rolled code to replace. New `GapRecommendation` type with `domain`, `description`, `recommendedLibrary`, and `priority` (critical/recommended/nice-to-have).
+- New `gaps` option in `AnalyzeOptions` — AI agent provides gap recommendations alongside scanner-based detections.
+- New `gapAnalysis` field in `OutputSchema` — gap recommendations appear in the output alongside `recommendedChanges`.
+- New `GapRecommendationSchema` Zod schema with full validation.
+- SKILL.md Step 2.5: Gap Analysis guidance for AI agents.
+- 3 new gap analysis tests (202 total).
+
+### Changed
+
+- `LibraryRecommendation` enriched with optional `rationale`, `ecosystem`, `antiPatterns`, `alternatives` fields — AI agent can express ecosystem-level solutions (e.g., Lingui + TMS + compile-time extraction).
+- `RecommendedChange.recommendedLibrary` output schema widened to match enriched `LibraryRecommendation`.
+- SKILL.md Step 3 renamed "Recommend Solutions" — guides AI agent to think at ecosystem level.
+- Summary table template updated to render rationale, ecosystem, anti-patterns, and alternatives.
+- README updated with gap analysis, ecosystem recommendations features and API docs.
+
+## [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,14 +7,21 @@
 </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://smithery.ai/skills/nebutra/next-unicorn-skill"><img src="https://img.shields.io/badge/Smithery-Next--Unicorn-orange.svg" alt="Smithery" /></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="https://www.npmjs.com/package/@nebutra/next-unicorn-skill"><img src="https://img.shields.io/npm/dm/@nebutra/next-unicorn-skill.svg?color=green" alt="npm downloads" /></a>
+  <a href="https://github.com/Nebutra/Next-Unicorn-Skill/stargazers"><img src="https://img.shields.io/github/stars/Nebutra/Next-Unicorn-Skill.svg?style=social" alt="GitHub Stars" /></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-176%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>
 
+<p align="center">
+  <b>English</b> | <a href="./README.zh-CN.md">简体中文</a>
+</p>
+
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#features">Features</a> &bull;
@@ -31,25 +38,72 @@
 
 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
 
+### From Smithery (recommended)
+
+Browse and install directly from the Smithery skill registry:
+
+> **[Next-Unicorn on Smithery](https://smithery.ai/skills/nebutra/next-unicorn-skill)**
+
+### From npmjs.org
+
 ```bash
-# npm
 npm install @nebutra/next-unicorn-skill
-
-# pnpm
+# or
 pnpm add @nebutra/next-unicorn-skill
+```
 
-# bun
-bun add @nebutra/next-unicorn-skill
+### From GitHub Packages
+
+Configure your `.npmrc` first:
+
+```shell
+echo "@nebutra:registry=https://npm.pkg.github.com" >> .npmrc
+```
+
+Then install:
+
+```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, 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: {
@@ -60,25 +114,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,
-  // 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 — 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
 
@@ -86,15 +137,21 @@ 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) |
-| **Context7 verification** | Every recommendation verified against real, version-correct documentation |
+| **Pattern-based scanning** | Detects hand-rolled code across 31 domains with 52 regex patterns (design-system, auth, state-management, code-organization, 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 |
+| **Code organization analysis** | Detects god directories, mixed naming conventions, deep nesting, barrel bloat, catch-all directories, and circular dependencies via import graph traversal |
+| **Human-in-the-loop gates** | 4 structured decision gates at irreversible/preference-driven points — triage, preferences (SWOT), accept/reject, execution confirmation |
 | **Monorepo support** | Detects npm, pip, cargo, go workspaces independently |
 
-### Dependency Management (v2.0)
+### Dependency Management
 
 | Feature | Description |
 |---------|-------------|
@@ -105,12 +162,62 @@ Or use as an **MCP SKILL** — provide [`SKILL.md`](./SKILL.md) to your AI agent
 
 ## How It Works
 
+### Architecture Diagram
+
+```mermaid
+flowchart TB
+    subgraph input [Input]
+        I[InputSchema JSON]
+    end
+
+    subgraph deterministic [Deterministic Layer — TypeScript]
+        V[Zod Validator]
+        S[Scanner — 52 regex patterns across 31 domains]
+        SA[Structure Analyzer — monorepo architecture, dependency flow, token layers]
+        C7[Context7 Verifier — exponential backoff, query ranking]
+        VS[Vuln Scanner — OSV database]
+        PC[Peer Checker — semver range validation]
+        PR[PR Strategy + Executor]
+    end
+
+    subgraph agent [AI Agent Layer — Claude generalization]
+        GA[Gap Analysis — single library / ecosystem / architecture gaps]
+        REC[Recommender — ecosystem-level solutions with rationale]
+        UX[UX Audit — 8 categories]
+        DS{Design System?}
+        DSE[Extract from existing code]
+        DSS[Scaffold from reference repos]
+    end
+
+    subgraph output [Output]
+        O[OutputSchema JSON]
+    end
+
+    I --> V --> S
+    S --> SA
+    S --> REC
+    SA --> GA
+    GA --> DS
+    DS -->|Existing frontend| DSE
+    DS -->|No frontend| DSS
+    GA --> O
+    REC --> C7 --> O
+    S --> PC --> O
+    S --> VS --> O
+    UX --> O
+    O --> PR
 ```
-Input ─> Validator ─> Scanner ─> Context7 Verifier ─> Impact Scorer
-  ─> Conflict Detection ─> Vuln Scanner ─> License Filter
-  ─> Migration Planner ─> UX Auditor ─> Auto-Updater
-  ─> Serializer ─> PR Creator ─> Output
-```
+
+### Design Principles
+
+| Principle | Implementation |
+|-----------|---------------|
+| **Occam's Razor** | Only 17 TS modules remain — each does something Claude cannot (regex, semver, file I/O, API calls, import graph traversal). Scoring, planning, UX audit, PR descriptions are AI-agent-driven. |
+| **No hardcoded recommendations** | Pattern catalog contains zero library names. The `Recommender` callback and `GapRecommendation` are filled by the AI agent at runtime. |
+| **Context7 best practices** | Exponential backoff (3 retries), query parameter for ranking, per-library isolation. Both replacements and gaps are verified. |
+| **Progressive disclosure** | SKILL.md is 111 lines. `references/` files load only when design system gaps are detected. |
+| **Two analysis modes** | **Replacement**: scanner finds hand-rolled code → agent recommends library. **Gap**: agent identifies missing capabilities → verified via Context7. |
+| **Design system support** | Structure analyzer detects missing layers. Two paths: scaffold from 25+ reference repos, or extract spec from existing code (6 principles, 5 phases). |
 
 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.
 
@@ -137,14 +244,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>;
 }
 ```
 
@@ -170,8 +277,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',
@@ -188,11 +295,17 @@ 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** | | | |
+| Code organization analysis | **Yes** | | | |
+| Human-in-the-loop gates | **Yes** | | | |
 | Deletion checklists | **Yes** | | | |
 | Vulnerability scanning | **Yes** | Yes | Yes | |
 | Scans *recommended* libs for vulns | **Yes** | | | |
@@ -211,16 +324,27 @@ 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) |
+| `gaps` | `GapRecommendation[]` | No | Missing capabilities the project should have (AI agent identifies these) |
 | `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, 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": [...],     // Recommendations with impact scores
+  "recommendedChanges": [...],     // Replacement recommendations with impact scores
+  "gapAnalysis": [...],            // (optional) Context7-verified gap recommendations
   "filesToDelete": [...],          // Files to remove after migration
   "linesSavedEstimate": 1250,      // Total lines saved
   "uxAudit": [...],                // UX completeness (8 categories)
@@ -236,17 +360,18 @@ const logger = pino({
 
 ## Vibe Coding Domains
 
-68 domains across 11 categories, aligned with ISO/IEC 25010:
+69 domains across 12 categories, aligned with ISO/IEC 25010. 31 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` |
+| Code Organization | 1 | `code-organization` (god-dirs, naming, circular deps, barrel bloat, nesting, catch-all) |
 | Delivery / DevEx | 6 | `testing-strategy`, `ci-cd-release`, `dependency-management` |
 | Performance | 3 | `performance-web-vitals`, `cost-optimization` |
 | AI Engineering | 3 | `ai-model-serving`, `rag-vector-search` |
@@ -257,7 +382,7 @@ const logger = pino({
 ## Testing
 
 ```bash
-pnpm test          # 191 tests (vitest + fast-check)
+pnpm test          # 176 tests (vitest + fast-check)
 pnpm typecheck     # TypeScript strict mode
 pnpm build         # Compile to dist/
 ```
@@ -294,23 +419,62 @@ 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) |
+| [`code-organization-workflow.md`](./references/code-organization-workflow.md) | Code organization decision tree, Gate examples (SWOT), Phase A/B workflow with worked examples |
+
+<!-- TODO: P1 — 项目 Logo: 设计一个 Logo 放在 README 顶部，同时用作 GitHub Social Preview -->
+<!-- TODO: P1 — Social Preview / OG Image: 到 GitHub repo Settings → Social preview 上传卡片图 -->
+<!-- TODO: P1 — Demo GIF: 录制 30 秒终端演示动图，放在 Quick Start 上方 -->
+<!-- TODO: P0 — GitHub Topics: 到 GitHub repo Settings → Topics 添加: mcp, ai-agent, claude-code, codebase-analysis, dependency-management, vulnerability-scanning, migration, context7, vibe-coding, skill -->
+<!-- TODO: P2 — Coverage 徽章: 配置 Codecov 或 Coveralls，在 CI 中上传覆盖率报告 -->
+<!-- TODO: P2 — Twitter/X: 创建项目 Twitter 账号或用个人账号发布公告，在 README 添加链接 -->
+<!-- TODO: P2 — Discord: 创建 Discord 服务器，在 README 添加邀请链接徽章 -->
+<!-- TODO: P3 — Awesome Lists: 提交 PR 到 awesome-mcp、awesome-claude-code、awesome-ai-tools 等列表 -->
+<!-- TODO: P3 — Product Hunt: 在 producthunt.com 发布项目 -->
+<!-- TODO: P3 — Hacker News: 发布 Show HN 帖子 -->
+<!-- TODO: P3 — GitHub Discussions: 到 GitHub repo Settings → Features → Discussions 开启 -->
+<!-- TODO: P3 — "Who's Using" 展示区: 有用户后在 README 加 logo 墙 -->
+
+## Star History
+
+<a href="https://star-history.com/#Nebutra/Next-Unicorn-Skill&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Nebutra/Next-Unicorn-Skill&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Nebutra/Next-Unicorn-Skill&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Nebutra/Next-Unicorn-Skill&type=Date" />
+ </picture>
+</a>
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
 
+## Security
+
+See [SECURITY.md](./SECURITY.md) for our security policy and how to report vulnerabilities.
+
 ## Releasing
 
 Releases are automated via GitHub Actions:
 
 ```bash
 # Tag a new version
-git tag v2.0.0
-git push origin v2.0.0
-# → CI runs tests → creates GitHub Release → publishes to npm
+git tag v1.0.5
+git push origin v1.0.5
+# → 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
 
-[MIT](./LICENSE) &copy; [TsekaLuk](https://github.com/TsekaLuk)
+[MIT](./LICENSE) &copy; [Nebutra](https://github.com/Nebutra)