ai-developer-skill-os 2.1.1 → 3.0.0

package/skills/qk-project-memory/SKILL.md

@@ -1,33 +1,35 @@
----
-name: qk-project-memory
-description: Trí nhớ dài hạn: quyết định kiến trúc, rule, convention, ui-patterns.
-mode_supported: [enterprise]
-input: [Query about architecture/rules]
-output: [Relevant project DNA context]
-workflow: [1. Truy vấn Memory -> 2. Trả về DNA dự án]
-allowed_tools: [read_file]
-handoff_to: [none]
----
-
-# 🛠️ qk-project-memory - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Trí nhớ dài hạn: quyết định kiến trúc, rule, convention, ui-patterns.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `none`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
+---
+name: qk-project-memory
+version: 3.0.0
+updated: 2026-07-02
+description: Store and retrieve long-term project context across sessions.
+category: utilities
+priority: low
+tags: [memory, context, storage]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User asks to remember a specific configuration, rule, or architectural decision.
+inputs: [Context to remember]
+outputs: [Memory file updated]
+allowed_tools: [write_to_file, read_file]
+pipeline: [analyze, implement, complete]
+---
+
+# 🛠️ qk-project-memory - Standard Operating Procedure
+
+> **Goal:** "Bộ nhớ dài hạn". Giúp Agent nhớ lại các cấu hình, đường dẫn API hoặc luật lệ riêng của dự án mà không cần User nhắc lại.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Fact Extraction):**
+   - Extract the core facts from the conversation (e.g., "The project uses pnpm, not npm").
+2. **Implement (Storage):**
+   - Append the fact to `.ai-memory.md` or a similar configuration file.
+
+## 🛡️ 2. Constraints & Rules
+- **Keep it small:** Do not write entire source files into memory. Only save abstract facts and rules.
+
+## 🤝 3. Handoff Pipeline
+1. `complete`: Output confirmation.
+
+## 📝 4. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Đã ghi nhớ thông tin gì.

package/skills/qk-system-evolution/SKILL.md

@@ -1,315 +1,63 @@
----
-name: qk-system-evolution
-description: Nâng cấp version, Impact Analysis, dry-run, apply và rollback.
-mode_supported: [enterprise]
-input: [Upgrade target]
-output: [Upgraded system]
-workflow: [1. Analyze -> 2. Plan -> 3. Dry-run -> 4. Apply -> 5. Verify -> 6. Rollback (if fail)]
-allowed_tools: [run_command, write_to_file]
-handoff_to: [qk-validation-gate]
----
-
-# 🛠️ qk-system-evolution - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Nâng cấp version, Impact Analysis, dry-run, apply và rollback.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-validation-gate`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
-
-## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
-
-*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
-
----
-
-
-
-# Migration & Dependency Upgrade
-
-> **Language rule:**
-> Use English for: code, identifiers, file names, architecture terms, technical decisions.
-> Use the user's language for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
-
-> ⚠️ **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.
+---
+name: qk-system-evolution
+version: 3.0.0
+updated: 2026-07-02
+description: Safely upgrade dependencies, migrate frameworks, and manage rollbacks.
+category: operations
+priority: high
+tags: [upgrade, migration, devops, dependencies]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User wants to update a library, upgrade a framework (e.g., Next.js 13 to 14), or perform a major refactor.
+inputs: [Target package, Target version]
+outputs: [Upgraded codebase, Rollback plan]
+allowed_tools: [run_command, grep_search, read_file]
+pipeline: [analyze, plan, implement, validate, complete]
+---
+
+# 🛠️ qk-system-evolution - Standard Operating Procedure
+
+> **Goal:** Quản lý các thay đổi lớn cấp hệ thống (Major Updates) một cách an toàn, luôn có đường lui (Rollback) nếu xảy ra sự cố.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Impact Analysis):**
+   - Read the Changelog or Migration Guide for the new version.
+   - Identify Breaking Changes and Deprecated APIs.
+   - Search the codebase to see how many files are affected.
+2. **Plan (Rollback Strategy):**
+   - Document the exact Git commands or NPM commands needed to revert the system if the upgrade fails completely.
+3. **Implement (Dry-Run & Upgrade):**
+   - Apply the dependency updates in `package.json`.
+   - Run Codemods (if provided by the library).
+   - Manually fix code affected by Breaking Changes.
+4. **Verify (System Test):**
+   - Reinstall dependencies cleanly (`npm ci` or `yarn install`).
+   - Run the build process to ensure the system compiles.
+
+## 🛡️ 2. Constraints & Rules
+- **Safety First:** Never run `npm update` blindly across all packages. Update only what was requested.
+- **Lockfiles:** Do not delete `package-lock.json` or `yarn.lock` unless resolving extreme merge conflicts.
+- **Always Rollback:** If the system produces >50 compilation errors after an upgrade and you cannot fix them in 1 turn, immediately trigger the Rollback Plan.
+
+## 🌳 3. Decision Tree
+```text
+Are there Breaking Changes in the target version?
+  ├── YES → Create a migration checklist based on the official docs. Update code systematically.
+  └── NO (Minor/Patch) → Update version and run tests.
+
+Did the Build fail after the update?
+  ├── YES → Are there too many errors to fix easily?
+  │       ├── YES → Execute Rollback Plan (`git reset --hard HEAD`).
+  │       └── NO → Fix the specific API changes.
+  └── NO → Proceed to Validation.
+```
+
+## 🤝 4. Handoff Pipeline
+1. `validate`: Run the full test suite and `npm run build` via `qk-validation-gate`.
+2. `complete`: Generate the Evolution report.
+
+## 📝 5. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Đã nâng cấp package nào, từ vX lên vY.
+- **Chi tiết (Changes):** Số lượng file phải sửa do Breaking Changes.
+- **Kế hoạch lùi (Reasoning/Risks):** Ghi rõ lệnh Rollback để User copy-paste nếu cần.
+- **Xác thực (Verification):** Kết quả của Build/Test.