ai-developer-skill-os 1.0.0

package/skills/engineering/migration/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: migration
+description: >-
+  Nâng cấp dependency, chuyển đổi framework và thay thế thư viện một cách an toàn với chiến lược không downtime.
+version: 1.0.0
+category: engineering
+tags: [migration, upgrade, dependencies, breaking-change, npm, framework]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Migration & Dependency Upgrade
+
+> **Language rule:**
+> Use **English** for: package names, version numbers, commands, config keys, technical terms.
+> Use **the user's language** for: explanations, risk summaries, and step-by-step instructions.
+
+> ⚠️ **Always create a rollback plan before starting any migration.**
+> Never apply breaking upgrades to production without a verified fallback.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User wants to upgrade a package or dependency
+- Framework has a new major version (React 17→19, Vue 2→3, Next.js 13→15)
+- A library is deprecated or has a security vulnerability (CVE)
+- User wants to replace one library with another
+- `project-audit` flagged outdated or risky dependencies (P1/P2)
+- User says "update packages", "upgrade to v5", "migrate to new version"
+
+---
+
+## Scope
+
+- ✅ Dependency version upgrades (patch, minor, major)
+- ✅ Framework version migrations with breaking changes
+- ✅ Library replacement (swap one library for another)
+- ✅ Package conflict resolution
+- ✅ Configuration updates required by new versions
+- ✅ Code changes required by breaking API changes
+- ✅ Rollback planning
+
+---
+
+## Non-goals
+
+- ❌ Do NOT upgrade everything at once — always upgrade incrementally
+- ❌ Do NOT skip reading the changelog/migration guide
+- ❌ Do NOT ignore peer dependency warnings without investigating
+- ❌ Do NOT apply breaking changes without a rollback plan
+- ❌ Do NOT upgrade dev dependencies and prod dependencies in the same step
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Security vulnerability (CVE) — upgrade immediately |
+| P1 | Breaking change affecting core functionality |
+| P2 | Deprecated API with upcoming removal |
+| P3 | Minor version lag — low risk, upgrade when convenient |
+
+---
+
+## Migration Types
+
+| Type | Risk | Strategy |
+|------|------|----------|
+| **Patch** (1.0.x → 1.0.y) | Low | Upgrade directly, verify tests |
+| **Minor** (1.x.0 → 1.y.0) | Low-Medium | Read changelog, upgrade, verify |
+| **Major** (x.0.0 → y.0.0) | High | Read migration guide, upgrade incrementally, test thoroughly |
+| **Framework** (React 17→19) | Very High | Follow official migration guide step by step |
+| **Library swap** | High | Strangler fig pattern — migrate incrementally |
+
+---
+
+## Workflow
+
+### Phase 1 — Audit Current State
+
+Before upgrading:
+1. List all dependencies with current versions
+2. Identify which are outdated (use `npm outdated` / `pnpm outdated`)
+3. Check for known CVEs (`npm audit` / `pnpm audit`)
+4. Classify each outdated package by migration type and risk
+5. Check peer dependency constraints
+
+```bash
+npm outdated          # See what's outdated
+npm audit             # Security vulnerabilities
+npx depcheck          # Unused dependencies
+```
+
+---
+
+### Phase 2 — Read Migration Guide
+
+For every major version upgrade:
+1. Read the official CHANGELOG or migration guide
+2. List all breaking changes that affect the project
+3. List all deprecated APIs still in use
+4. Estimate effort: number of files to change, complexity of changes
+
+Document findings before touching any code.
+
+---
+
+### Phase 3 — Plan the Migration
+
+Create an ordered upgrade sequence:
+
+**Rules:**
+- Security fixes first (P0)
+- Dev dependencies before prod dependencies (lower risk)
+- Upgrade one major dependency at a time — not everything together
+- Group related packages (e.g., all `@tanstack/*` together)
+
+**Example order:**
+```
+Step 1: Security patch — package-x 2.1.0 → 2.1.4 (CVE fix)
+Step 2: Dev tools — eslint 8 → 9 (no runtime impact)
+Step 3: Minor upgrades — axios 1.4 → 1.7 (non-breaking)
+Step 4: Major upgrade — react-query 4 → 5 (breaking — separate PR)
+```
+
+---
+
+### Phase 4 — Create Rollback Plan
+
+Before applying any change:
+```
+Rollback method:
+  Option A: git revert / git checkout to previous state
+  Option B: Pin version in package.json to previous known-good version
+  Option C: Feature flag to disable new behavior
+
+Rollback trigger:
+  - Tests fail after upgrade
+  - Runtime errors in staging
+  - Performance regression detected
+```
+
+---
+
+### Phase 5 — Execute the Upgrade
+
+For each package in the plan:
+
+1. **Upgrade package:**
+```bash
+npm install package-name@version
+# or
+pnpm add package-name@version
+```
+
+2. **Update configuration** (if required by new version)
+
+3. **Fix breaking changes** in code:
+   - Update import paths
+   - Replace deprecated APIs
+   - Update type signatures
+   - Update config files
+
+4. **Run verification** (see Phase 6) before moving to next package
+
+---
+
+### Phase 6 — Verify After Each Step
+
+After every upgrade step:
+- [ ] `npm install` / `pnpm install` — no resolution errors
+- [ ] `npm run build` — builds successfully
+- [ ] `npm run type-check` — no new TypeScript errors
+- [ ] `npm run lint` — clean
+- [ ] `npm test` — all tests pass
+- [ ] Manual smoke test of affected features
+
+**If any check fails → rollback this step before continuing.**
+
+---
+
+### Phase 7 — Library Replacement (Strangler Fig Pattern)
+
+When replacing one library with another (e.g., moment → date-fns):
+
+```
+Step 1: Install new library alongside old one
+Step 2: Create adapter/wrapper that abstracts the library
+Step 3: Migrate usage file by file (not all at once)
+Step 4: Verify each file after migration
+Step 5: Remove old library when 100% migrated
+Step 6: Remove adapter if no longer needed
+```
+
+This allows incremental migration with rollback possible at any step.
+
+---
+
+## Decision Tree
+
+```
+What type of upgrade?
+  ├── Patch/Minor → Upgrade directly, run tests
+  ├── Major       → Read changelog → plan → upgrade → verify
+  └── Framework   → Follow official migration guide step by step
+
+Security vulnerability?
+  ├── P0 (critical) → Upgrade immediately, prioritize over other work
+  └── P1/P2        → Include in next planned upgrade cycle
+
+Library replacement?
+  └── Use strangler fig pattern — never replace all at once
+```
+
+---
+
+## Output Format
+
+```
+📦 Migration Report
+─────────────────────────────────────────────────
+Scope:      [What was upgraded / migrated]
+Type:       [Patch / Minor / Major / Framework / Library swap]
+Risk:       [Low / Medium / High]
+
+Changes:
+  ✅ package-x:  2.1.0 → 2.1.4  (CVE fix — no code changes)
+  ✅ axios:      1.4.0 → 1.7.2  (minor — updated interceptor config)
+  ✅ react:      18.2.0 → 19.0.0 (major — updated 12 files)
+
+Breaking changes handled:
+  • [Description of breaking change and how it was resolved]
+
+📋 Rollback plan:
+  git revert <commit-hash> or pin to previous version in package.json
+
+✅ Verification:
+  Build:      PASS
+  Types:      Clean
+  Tests:      PASS (N tests)
+  Lint:       Clean
+  Smoke test: PASS
+
+⚠️  Known issues / follow-up:
+  • [Any remaining deprecated APIs to address]
+  • [Any packages still pending upgrade]
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Migration guide read for every major version change
+- [ ] Rollback plan documented before starting
+- [ ] Upgraded incrementally — one major change at a time
+- [ ] `npm audit` clean after upgrade
+- [ ] Build, types, lint, tests all pass
+- [ ] Smoke test of affected features complete
+- [ ] No new peer dependency warnings left unresolved
+- [ ] Breaking changes documented in output
+
+---
+
+## Common Migration Cheat Sheet
+
+```
+React 17 → 18:   Concurrent mode, new root API, Suspense updates
+React 18 → 19:   Server components, new hooks (useActionState), ref as prop
+Vue 2 → 3:       Composition API, new reactivity system, breaking changes in lifecycle
+Next.js 12 → 13: App Router introduced (pages/ still works)
+Next.js 13 → 14: Server Actions stable, metadata API
+Next.js 14 → 15: React 19, async params, updated caching defaults
+TanStack Query 4 → 5: New API (no more isLoading/isError split), object syntax
+```
+
+---
+
+## Examples
+
+See `examples/` folder.

package/skills/engineering/project-audit/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: project-audit
+description: >-
+  Kiểm toán toàn bộ dự án để phát hiện bug ẩn, rủi ro bảo mật, vấn đề hiệu năng và nợ kỹ thuật trước khi sửa code.
+version: 1.0.0
+category: engineering
+tags: [audit, review, bug-detection, architecture, security, performance]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Project Audit
+
+> **Language rule:**
+> Use **English** for: code references, file paths, severity labels, technical terms.
+> Use **the user's language** for: explanations, questions, and report summaries.
+
+> ⚠️ **CRITICAL: Do NOT modify any code during audit.**
+> The audit produces a report. Changes happen only after the user reviews and approves.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User says "audit", "review", "health check", "what's wrong with my project"
+- Before starting a large feature or refactor
+- After inheriting a codebase
+- Before a major release
+- When the system behaves unexpectedly and the root cause is unknown
+
+---
+
+## Scope
+
+- ✅ Detect hidden bugs, race conditions, and unstable areas
+- ✅ Review architecture and separation of concerns
+- ✅ Identify security vulnerabilities
+- ✅ Find performance bottlenecks
+- ✅ Audit dependencies (outdated, risky, unused)
+- ✅ Produce prioritized findings with recommended fixes
+
+---
+
+## Non-goals
+
+- ❌ Do NOT fix anything during the audit
+- ❌ Do NOT refactor code
+- ❌ Do NOT make assumptions — document uncertainty instead
+- ❌ Do NOT audit `node_modules`, `dist`, `build`, `.git`
+
+---
+
+## Audit Modes
+
+Choose based on context:
+
+| Mode | Scope | When to use |
+|------|-------|-------------|
+| **Quick** | Changed files only (git diff / recent edits) | Fast pre-commit check, small bug scope |
+| **Standard** | Current feature / module being worked on | Default — before implementing changes |
+| **Full** | Entire repository | Onboarding, pre-release, inherited codebase |
+
+**Default: Standard mode.**
+Use Full mode only when explicitly requested or before a major release.
+
+---
+
+## Severity Levels
+
+All findings use this shared scale:
+
+| Level | Label | Meaning |
+|-------|-------|---------|
+| P0 | Critical | Security breach, data loss, production crash — fix immediately |
+| P1 | High | Bug affecting core functionality — fix before shipping |
+| P2 | Medium | Performance issue or bad pattern — schedule soon |
+| P3 | Low | Technical debt, code smell — fix when possible |
+
+---
+
+## Workflow
+
+### Phase 1 — Project Discovery
+
+*(Use `context-manager` if project context is not yet loaded)*
+
+Analyze:
+- Framework, language, build system
+- Folder structure and architecture style
+- Key dependencies and their versions
+- Entry points, routing, data flow
+
+Output: **Project Overview** (2-5 lines)
+
+---
+
+### Phase 2 — Architecture Review
+
+Check:
+
+**Separation of concerns:**
+- Are UI components mixing API calls and business logic?
+- Are services doing too much?
+- Is there duplicated logic across modules?
+
+**Folder structure:**
+- Does file placement follow the declared architecture?
+- Are there misplaced files or responsibilities?
+
+**Patterns:**
+- Are patterns applied consistently? (hooks, services, stores)
+- Are there anti-patterns? (prop drilling, God components, circular imports)
+
+---
+
+### Phase 3 — Bug Detection
+
+#### Frontend
+
+Check for:
+- `useEffect` with missing or wrong dependency arrays
+- State updates after component unmount (memory leak)
+- Missing cleanup in subscriptions, timers, event listeners
+- Stale closures in async callbacks
+- Race conditions in data fetching
+- Infinite re-render loops
+- `key` prop issues in lists
+
+#### Backend
+
+Check for:
+- Unhandled promise rejections
+- Missing input validation
+- Incorrect HTTP status codes
+- Transaction issues (missing rollback on error)
+- Race conditions in concurrent operations
+
+#### API Layer
+
+Check for:
+- Inconsistent response handling
+- Missing error states
+- Duplicate requests without debounce/cancellation
+- Missing loading/error/empty states in UI
+
+---
+
+### Phase 4 — Security Audit
+
+Check for:
+- Hardcoded secrets, tokens, credentials in code
+- Sensitive data in `localStorage` or URL params
+- Missing authentication/authorization checks
+- SQL injection or NoSQL injection risks
+- XSS vulnerabilities (dangerouslySetInnerHTML, unsanitized input)
+- Insecure direct object references (IDOR)
+- CORS misconfiguration
+
+---
+
+### Phase 5 — Performance Audit
+
+Check for:
+- Large bundle size (missing code splitting, lazy loading)
+- Expensive computations on every render (missing `useMemo`, `useCallback`)
+- Unnecessary re-renders (missing `memo`, wrong dependency arrays)
+- N+1 query problems
+- Missing pagination on large datasets
+- Unoptimized images or assets
+
+---
+
+### Phase 6 — Dependency Audit
+
+Check:
+- Outdated packages with known CVEs
+- Packages with very low maintenance (abandoned)
+- Duplicate packages doing the same job
+- Unused dependencies in `package.json`
+- Major version gaps that indicate deferred upgrades
+
+---
+
+## Decision Tree
+
+```
+Which audit mode?
+  ├── Quick   → Read only git diff / recently changed files
+  ├── Standard → Read current feature/module files + related
+  └── Full    → Scan entire src/ directory systematically
+
+Issue found → Assess severity:
+  ├── P0 → Flag immediately, recommend pausing current work
+  ├── P1 → Include in required fixes before shipping
+  ├── P2 → Include in scheduled improvements
+  └── P3 → Log as technical debt
+
+No issues found in area → Mark as ✅ Clean
+```
+
+---
+
+## Output Format
+
+### Executive Summary
+
+```
+🏥 Project Health Report
+─────────────────────────
+Health:          [Excellent / Good / Needs Attention / Critical]
+Risk Level:      [Low / Medium / High / Critical]
+Audit Mode:      [Quick / Standard / Full]
+Files Reviewed:  [N]
+Total Findings:  [N]  (P0: N · P1: N · P2: N · P3: N)
+```
+
+### Findings (one per issue)
+
+```
+───────────────────────────────
+ID:        AUDIT-001
+Severity:  P1 — High
+Location:  src/hooks/useUserData.ts:47
+Problem:   useEffect fetches data but missing cleanup — causes state update
+           on unmounted component, triggering React warning and potential
+           memory leak under slow networks.
+Impact:    Console errors in production, potential memory leak.
+Root cause: No AbortController or isMounted flag used.
+Fix:       Add AbortController + cleanup return in useEffect.
+Effort:    ~15 min
+```
+
+### Priority Roadmap
+
+```
+🗺️  Fix Roadmap
+──────────────────
+P0 — Fix immediately (before anything else):
+  • [AUDIT-00X] [Brief description]
+
+P1 — Fix before shipping:
+  • [AUDIT-00X] [Brief description]
+
+P2 — Schedule this sprint:
+  • [AUDIT-00X] [Brief description]
+
+P3 — Technical debt backlog:
+  • [AUDIT-00X] [Brief description]
+```
+
+### Next Steps
+
+```
+🔗 Recommended next skills:
+  → bug-fix        (for P0/P1 issues)
+  → refactor       (for architecture issues)
+  → migration      (for outdated dependencies)
+  → frontend-performance  (for P2 performance issues)
+
+⏳ Awaiting your approval to proceed with fixes.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Correct audit mode selected for the task
+- [ ] All 6 phases covered (or scoped ones for Quick/Standard)
+- [ ] Every finding has: ID, severity, location, problem, root cause, fix, effort
+- [ ] Priority roadmap is ordered correctly (P0 first)
+- [ ] No code was modified during audit
+- [ ] User informed — awaiting approval before any changes
+
+---
+
+## Examples
+
+See `examples/` folder.