ai-developer-skill-os 1.8.1 → 2.0.0

package/README.md

@@ -1,171 +1,130 @@
-# 🚀 AI Developer Skill OS
-
-[![npm version](https://badge.fury.io/js/ai-developer-skill-os.svg)](https://badge.fury.io/js/ai-developer-skill-os)
-[![Author](https://img.shields.io/badge/Author-Quang%20Kh%C3%A1nh-blue.svg)](https://github.com/phamquangkhanh2999)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-
-> **"Biến mọi AI Code Editor (Cursor, Windsurf, Cline) thành một Senior Engineer thực thụ với 23 kỹ năng được lập trình sẵn."**
-
----
-
-## 🌟 Tại sao bạn cần Skill OS?
-
-Các AI Editor hiện tại rất thông minh, nhưng nếu không có quy trình rõ ràng, chúng thường **lan man, tự ý sửa code lung tung, hoặc viết code không theo chuẩn kiến trúc**. 
-
-**AI Developer Skill OS (by Quang Khánh)** giải quyết triệt để vấn đề này bằng cách:
-- 🧠 **Ép AI tư duy theo Workflow (Chain-of-Thought):** Phân tích trước, code sau.
-- 🛡️ **Scope & Non-goals rõ ràng:** Khoá chặt giới hạn, tuyệt đối không cho AI sửa hỏng các file không liên quan.
-- 🎨 **Output chuyên nghiệp:** Mọi câu trả lời của AI đều được định dạng thành bảng biểu, báo cáo y hệt một hệ thống thật.
-
-### Hệ thống 23 Kỹ năng (Skillset)
-- 🛠️ **Engineering Core (8 skills):** Agent Orchestrator (Lên kế hoạch), Context Manager, Project Audit, Bug Fix, Refactor, API Integration, Migration, Git Engineer.
-- 🎨 **Frontend (11 skills):** Frontend Architecture, Design System, UI Builder, Component Generator, State Management, Form Builder, Table CRUD, Debug, Testing, Performance, A11Y Audit.
-- ⚙️ **Backend (4 skills):** Backend Architecture, Database Engineer, Auth & Security, Deployment (DevOps).
-
-👉 [Xem chi tiết chức năng của toàn bộ 23 Skills tại đây](docs/CHI_TIET_SKILLS.md)
-
----
-
-## 📦 Cài đặt (Installation)
-
-Bạn có thể cài đặt bộ Skill này vào bất kỳ dự án nào cực kỳ nhanh chóng qua NPM hoặc Git.
-
-### Cách 1: Sử dụng NPM (Khuyên dùng)
-Mở terminal tại thư mục gốc dự án của bạn và chạy:
-```bash
-npx ai-developer-skill-os init
-```
-Hệ thống sẽ cung cấp cho bạn 2 tuỳ chọn cực kỳ linh hoạt:
-- **(1) Local:** Cài vào thư mục ẩn `.qk-ai-skill-os/` ngay trong dự án. (Phù hợp khi làm việc nhóm, commit lên Git để ai cũng xài được).
-- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Từ đó trở đi, bạn mở **BẤT KỲ DỰ ÁN NÀO** cũng sẽ tự động gọi được 23 kỹ năng mà không cần tải lại file! (Rất tuyệt vời cho cá nhân sử dụng).
-
-> 💡 **Tính năng Tự động Dọn dẹp (Auto-Cleanup):** Mỗi khi cài đặt lại, hệ thống sẽ tự động quét và xóa sạch các kỹ năng phiên bản cũ để tối ưu dung lượng và tránh xung đột cho máy tính của bạn. Mọi thứ hoàn toàn tự động!
-
-### Cách 2: Sử dụng Git Submodule
-Nếu bạn không dùng Node.js, bạn có thể nhúng trực tiếp qua Git (Chỉ hỗ trợ dạng Local):
-```bash
-git submodule add https://github.com/phamquangkhanh2999/ai-developer-skill-os.git .qk-ai-skill-os
-```
-
----
-
-## 🛠️ Cấu hình cho IDE / AI Agent
-
-Sau khi thư mục kỹ năng đã xuất hiện trong dự án của bạn, hãy cấu hình để AI biết cách sử dụng nó.
-
-### Cho Antigravity / Gemini IDE
-**Không cần cấu hình gì thêm!** Nếu bạn đã cài đặt bằng cờ `--gemini` (thư mục `.agents/skills/`), hệ thống sẽ tự động quét và load toàn bộ 23 kỹ năng này. Bạn có thể sử dụng ngay lập tức!
-
-### Cho Claude Code / Kilo Code (CLI Agents)
-#### Cách 1: Cài đặt Native (Khuyên dùng cho Kilo Code)
-Chạy `npx ai-developer-skill-os init` và chọn **(6) Kilo Code**.
-Hệ thống sẽ tự động:
-- Copy toàn bộ skills vào `.kilo/skills/` (Local) hoặc `~/.kilo/skills/` (Global)
-- Cấu hình `kilo.json` hoặc `~/.config/kilo/kilo.json` để Kilo nhận diện
-- Tạo file `CLAUDE.md` như hướng dẫn bổ sung
-
-Sau đó mở Kilo Code, dùng `<leader>t` hoặc `/themes` để kiểm tra skills đã được cài.
-
-#### Cách 2: Thủ công
-Tạo file `CLAUDE.md` (hoặc `KILO.md`) ở gốc dự án và dán đoạn sau vào:
-```md
-# System Instructions
-Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
-
-Vui lòng tìm đọc danh sách kỹ năng tại file `./.qk-ai-skill-os/skills.json`.
-ĐẶC BIỆT LƯU Ý: Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng `./qk [tên-skill]`, bạn BẮT BUỘC phải gọi và đọc nội dung file `SKILL.md` tương ứng trong thư mục `./.qk-ai-skill-os/skills/` trước khi phân tích hoặc viết code.
-Luôn giao tiếp bằng tiếng Việt nhưng viết code, đặt tên biến, comment trong code bằng tiếng Anh.
-```
-
-### Cho Cline / Roo Code (VS Code Extensions)
-Tạo file `.clinerules` hoặc `.roorules` ở gốc dự án và dán nội dung:
-```md
-Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
-Vui lòng tìm đọc danh sách kỹ năng tại file `./.qk-ai-skill-os/skills.json`.
-Bất cứ khi nào người dùng gõ lệnh `./qk [tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `./.qk-ai-skill-os/skills/`.
-Luôn giao tiếp bằng tiếng Việt nhưng viết code bằng tiếng Anh.
-```
-
-### Cho GitHub Copilot
-Tạo file `.github/copilot-instructions.md` và dán đoạn prompt tương tự như trên vào file này để Copilot học được các kỹ năng.
-
----
-
-## 🎯 Cách kiểm tra cài đặt thành công
-
-Để biết AI của bạn đã thực sự "nhập môn" bộ Skill OS này chưa, hãy mở khung chat AI trong dự án và gõ cú pháp lệnh chuyên nghiệp sau:
-> **`./qk project-audit`** Hãy cho tôi biết bạn sẽ làm những gì.
-
-✅ **Thành công:** Nếu AI trả lời bằng tiếng Việt, liệt kê đúng các bước khám bệnh (Phase 1, Phase 2, Phase 3...) theo đúng như trong file `SKILL.md` của `project-audit`.
-❌ **Thất bại:** Nếu AI trả lời chung chung hoặc bảo không biết skill này là gì, bạn cần kiểm tra lại đường dẫn file cấu hình ở bước trên.
-
----
-
-## 🚀 Cách gọi lệnh Skill chuyên nghiệp (Usage)
-
-AI sẽ tự động nhận diện skill qua ngữ cảnh, nhưng để chắc chắn 100% và tiết kiệm thời gian gõ prompt, bạn hãy dùng cú pháp lệnh độc quyền: **`./qk-[tên-skill]`**
-
-Dưới đây là các ví dụ cụ thể để bạn copy - paste và trải nghiệm ngay:
-
-### 1. Nhờ AI lên kế hoạch (Planning) & Kiến trúc
-> **`./qk-agent-orchestrator`** Hãy lên kế hoạch làm tính năng Giỏ Hàng cho tôi. Nhớ gọi thêm **`./qk-context-manager`** để đọc cấu trúc dự án trước nhé.
-
-### 2. Xây dựng Giao diện (Frontend/UI)
-> **`./qk-ui-builder`** & **`./qk-design-system`** Hãy tạo cho tôi một màn hình Đăng Nhập (Login) xịn xò. Đảm bảo Responsive và dùng đúng chuẩn Component.
-
-### 3. Thiết kế Database (Backend)
-> **`./qk-database-engineer`** Hãy viết cho tôi schema Prisma cho bảng Product và User có quan hệ 1-N. Tối ưu index cho truy vấn nhanh.
-
-### 4. Tìm và Diệt Bug (Debugging)
-> **`./qk-frontend-debug`** & **`./qk-bug-fix`** Code đang bị crash với lỗi `Hydration error`. Hãy tìm nguyên nhân gốc rễ và sửa dứt điểm giúp tôi.
-
----
-
-## 💡 Mẹo & Workflow Thực Chiến (Best Practices)
-
-Để khai thác tối đa sức mạnh của 23 kỹ năng, bí quyết là **kết hợp (chaining) nhiều skill** lại với nhau trong cùng một luồng công việc. Dưới đây là các Workflow kinh điển:
-
-### 🌟 1. Workflow Bắt đầu một New Chat (Bắt buộc)
-Khi mở một New Chat, AI hoàn toàn chưa biết gì về dự án. Đừng bắt nó code ngay!
-* **Bước 1:** `> Dùng ./qk-context-manager để đọc cấu trúc toàn bộ dự án này.`
-* **Bước 2:** `> Dùng ./qk-agent-orchestrator để phân tích yêu cầu sau đây và lên kế hoạch: [Yêu cầu của bạn]`
-
-### 🌟 2. Workflow Làm tính năng mới (VD: Tích hợp API)
-Muốn tạo một màn hình hiển thị danh sách từ API trả về? Hãy gõ:
-* `> Hãy dùng ./qk-api-integration để tạo file gọi API fetch danh sách Users.`
-* `> Tiếp theo dùng ./qk-state-management để lưu data này vào Zustand/Redux.`
-* `> Cuối cùng dùng ./qk-ui-builder để vẽ màn hình Table hiển thị data đó.`
-
-### 🌟 3. Workflow Chống "Phá Code" (Safe Refactor)
-Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
-* `> Hãy chạy ./qk-project-audit để dò xem việc đổi tên biến X có ảnh hưởng đến các component khác không.`
-* `> OK, giờ hãy dùng ./qk-refactor để sửa lại một cách an toàn.`
-
----
-
-## 💎 **Danh sách đầy đủ các Kỹ năng đang có trong Skill OS:**
-*(Bạn có thể gọi trực tiếp trên Terminal hoặc Chat)*
-
-> 💡 **Mẹo (Pro-Tip):** Bất cứ khi nào bạn quên mất danh sách kỹ năng hoặc cách dùng, chỉ cần gõ lệnh `./qk-help` (hoặc `@qk-help`), hệ thống sẽ xuất ra toàn bộ cẩm nang sử dụng và bí kíp kết hợp Kỹ năng (Skill Chaining) ngay lập tức!
-
-| Kỹ năng (Skill) | Nhiệm vụ chuyên môn |
-|-----------------|---------------------|
-| 🧠 **`qk-help`** | **[MỚI] Sách hướng dẫn tra cứu nhanh danh sách Skill và Bí kíp kết hợp** |
-| 🧑‍💻 **`qk-ui-builder`** | Xây dựng UI, vẽ Màn hình, chia Layout, tạo Modal cực đẹp |
-| 🏗️ **Engineering** | `qk-project-audit`, `qk-agent-orchestrator` | Kiểm toán dự án, lập kế hoạch, quản lý Git, Refactor code. |
-| 🎨 **Frontend** | `qk-ui-builder`, `qk-frontend-performance` | Dựng UI, tối ưu tốc độ, test component, quản lý State. |
-| ⚙️ **Backend** | `qk-database-engineer`, `qk-auth-security` | Thiết kế DB Schema, bảo mật JWT/OAuth, cấu hình CI/CD. |
-
-👉 [Xem danh sách toàn bộ Kỹ năng tại đây](docs/CHI_TIET_SKILLS.md)
-
----
-
-<div align="center">
-  <b>Được thiết kế và phát triển bởi Quang Khánh (QK)</b><br>
-  <i>Empowering Vietnamese Developers with World-Class AI Workflows.</i>
-</div>
-
----
-
-## 📄 License
-Được phát hành dưới giấy phép [MIT](LICENSE). Tự do sử dụng, chỉnh sửa và chia sẻ.
+# 🚀 AI Developer Skill OS (ai-developer-skill-os)
+
+> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Cursor, Windsurf, Cline, v.v.).
+
+Thay vì cung cấp các "công cụ rời rạc" (Toolbox), dự án này xây dựng một hệ thống **22 Siêu Kỹ Năng (Master Skills)**, biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự học, tự kiểm toán và tự viết tài liệu.
+
+---
+
+## 🏗️ Kiến Trúc Khối (The 7-Layer Architecture)
+
+Hệ thống được thiết kế hoàn hảo với 7 phân lớp, hoạt động khép kín theo chuỗi End-to-End:
+
+### 0. Foundation Layer (Nền Tảng Cốt Lõi)
+- `qk-orchestrator`: Bộ điều hướng yêu cầu người dùng, chọn Workflow.
+- `qk-context-loader`: Bộ nạp ngữ cảnh, tìm file liên quan, chống tràn token.
+- `qk-policy-engine`: Động cơ kiểm tra tính hợp lệ của Request trước khi chạy.
+- `qk-access-policy`: Ranh giới bảo mật, phân quyền và RBAC.
+- `qk-project-memory`: Bộ nhớ cấu trúc dự án (Architecture, UI Patterns, Conventions).
+- `qk-engineering-standard`: Bộ luật thiết kế (Frontend, Backend, Security, Testing rules).
+- `qk-project-bootstrap`: Trình khởi tạo dự án từ con số 0.
+
+### 1. UI System Layer (Hệ Thống Giao Diện)
+- `qk-ui-system-builder`: Quản lý Design System, Component Library.
+- `qk-design-to-code`: Chuyển đổi Figma/Screenshot sang mã nguồn.
+- `qk-ui-audit`: Kiểm toán tính nhất quán, Responsive, Accessibility.
+
+### 2. Development Layer (Phát Triển E2E)
+- `qk-feature-delivery`: Phân tích, code, test hoàn thiện một tính năng từ A-Z.
+- `qk-api-lifecycle`: Vòng đời API (Spec, Service, Type, Test, Docs).
+- `qk-data-lifecycle`: Vòng đời dữ liệu (Schema, Migration, Query Tuning).
+
+### 3. Quality Assurance Layer (Đảm Bảo Chất Lượng)
+- `qk-project-health`: Audit tình trạng dự án, Tech Debt, Code Smell.
+- `qk-bug-resolution`: Tái hiện lỗi, tìm Root Cause, Fix và chống Regression.
+- `qk-validation-gate`: Cổng chặn an toàn (Lint, Test, Security) trước khi hoàn tất.
+
+### 4. Evolution Layer (Tiến Hóa Hệ Thống)
+- `qk-system-evolution`: Nâng cấp phiên bản, Impact Analysis, Dry-run.
+
+### 5. Operation Layer (Vận Hành)
+- `qk-production-release`: CI/CD, Build, Deploy, Observability.
+
+### 6. AI Builder Layer
+- `qk-ai-builder`: Thiết kế các hệ thống AI App, Agent, RAG.
+
+### 7. Knowledge Layer (Tri Thức & Tài Liệu)
+- `qk-docs`: Viết tài liệu cho con người (README, Changelog, Developer Guide).
+- `qk-documentation-system`: Máy học nội bộ (Chuyển đổi Pattern thành luật nạp vào Memory).
+- `qk-help`: Trợ lý tra cứu hướng dẫn kỹ năng.
+
+---
+
+## 🔄 Luồng Vận Hành Khép Kín (Workflow)
+
+Khi bạn ra lệnh: `"Thêm tính năng đăng nhập"`:
+```text
+User Request 
+   ↓
+qk-orchestrator (Phân tích, chọn qk-feature-delivery)
+   ↓
+qk-context-loader (Load code liên quan Auth)
+   ↓
+qk-policy-engine & qk-access-policy (Check quyền)
+   ↓
+qk-engineering-standard (Rút luật Backend/Security)
+   ↓
+[THỰC THI BỞI qk-feature-delivery]
+   ↓
+qk-validation-gate (Test, Lint)
+   ↓
+qk-docs (Cập nhật API doc, Changelog)
+   ↓
+qk-documentation-system (Lưu các Pattern mới vào Memory)
+```
+
+---
+
+## 💡 Ví Dụ Thực Tế (Common Examples)
+
+Dưới đây là một số ví dụ sử dụng các kỹ năng phổ biến và mạnh mẽ nhất trong quá trình code hàng ngày của bạn:
+
+### 1. `qk-orchestrator` (Trợ lý điều phối trung tâm)
+Nếu bạn không biết nên dùng skill nào, hãy gọi Orchestrator. Nó sẽ tự động phân tích và kích hoạt đúng các skill bên dưới.
+```bash
+./qk-orchestrator "Tôi muốn tạo một trang Dashboard hiển thị doanh thu bằng React"
+```
+
+### 2. `qk-feature-delivery` (Phát triển tính năng E2E)
+Dùng khi bạn muốn xây dựng trọn vẹn một tính năng từ DB, API đến UI và Test.
+```bash
+./qk-feature-delivery "Tạo luồng thanh toán giỏ hàng (Cart Checkout), lưu vào bảng orders và gọi API thanh toán Stripe"
+```
+
+### 3. `qk-bug-resolution` (Chẩn đoán và diệt Bug triệt để)
+Tuyệt đối không dùng prompt thường để sửa lỗi. Dùng kỹ năng này để ép AI tìm Root Cause và viết Regression Test.
+```bash
+./qk-bug-resolution "API /users/profile đang trả về 500 khi user chưa có avatar, stack trace như sau..."
+```
+
+### 4. `qk-ui-system-builder` (Chuẩn hóa giao diện)
+Dùng khi thiết kế các component dùng chung (Button, Card, Form) để đảm bảo không bị rác CSS.
+```bash
+./qk-ui-system-builder "Tạo một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token hiện tại"
+```
+
+### 5. `qk-api-lifecycle` (Thiết kế và Code API)
+Dành cho Backend Engineer, đi từ spec đến code, type và test.
+```bash
+./qk-api-lifecycle "Thiết kế API cập nhật mật khẩu, yêu cầu validate JWT token và mã hóa bcrypt"
+```
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+Sử dụng npm:
+```bash
+npm i -g ai-developer-skill-os
+```
+Hoặc sử dụng qua `npx`:
+```bash
+npx ai-developer-skill-os init
+```
+
+## 🚀 Tra Cứu (Help)
+
+Để tra cứu danh sách toàn bộ 22 Kỹ năng và các mẹo sử dụng, hãy gọi:
+```bash
+./qk-help "Hiển thị tất cả các skill liên quan đến Frontend"
+```

package/docs/CHI_TIET_SKILLS.md

@@ -1,117 +1,125 @@
-# Chi Tiết 23 Skills — AI Developer Skill OS
+# Từ Điển Chi Tiết 22 Siêu Kỹ Năng (Master Skills)
 
-**Tác giả:** Quang Khánh  
-**Phiên bản:** v1.0.1
-
-Tài liệu này giải thích chi tiết chức năng của từng Skill trong bộ Skill OS.
-AI sẽ đọc mô tả (description) bằng tiếng Anh để nhận diện, nhưng bạn có thể đọc tài liệu tiếng Việt này để hiểu AI có thể làm được gì.
+Dưới đây là danh sách chi tiết và giải thích cụ thể cho toàn bộ 22 Kỹ năng thuộc Kiến trúc AI Developer Skill OS. Các kỹ năng được phân chia khép kín theo 7 lớp kiến trúc tiêu chuẩn cấp doanh nghiệp (Enterprise Architecture).
 
 ---
 
-## 🛠️ Nhóm 1: Engineering Core (Kỹ thuật Cốt lõi)
+## 🏗️ Lớp 0: Foundation Layer (Nền Tảng Cốt Lõi)
+*Lớp này đóng vai trò như "Não bộ trung ương", chuyên nhận lệnh, cấp quyền, cung cấp luật lệ và chuẩn bị môi trường trước khi bất kỳ dòng code nào được viết ra.*
+
+### 1. `qk-orchestrator` (Trợ Lý Điều Phối)
+- **Mô tả:** Nhận lệnh chung chung từ người dùng, tự động phân tích ý đồ và định hướng luồng công việc (chọn gọi các kỹ năng nào tiếp theo).
+- **Khi nào dùng:** Khi bạn có một yêu cầu lớn và không biết bắt đầu từ đâu.
+
+### 2. `qk-context-loader` (Nạp Ngữ Cảnh)
+- **Mô tả:** Có khả năng đọc lướt dự án để gom chính xác các file liên quan đến task hiện tại (chống tràn bộ nhớ token của AI).
+- **Khi nào dùng:** Khi code dự án quá lớn, cần khoanh vùng các file cần sửa.
 
-Đây là các kỹ năng chung quản lý toàn bộ dự án, kiến trúc và mã nguồn.
+### 3. `qk-policy-engine` (Động Cơ Chính Sách)
+- **Mô tả:** Xét duyệt xem yêu cầu của người dùng hoặc hành động của AI có vi phạm các nguyên tắc cốt lõi của dự án không.
+- **Khi nào dùng:** Được AI tự động gọi trước khi thực thi để đảm bảo tính hợp lệ.
 
-### 1. `agent-orchestrator` (Người Điều Phối)
-- **Mô tả:** AI không tự viết code mà đóng vai trò như một Project Manager. Phân tích yêu cầu phức tạp của bạn, chia nhỏ thành các tác vụ (Task) và quyết định gọi các Skill nào theo thứ tự nào.
-- **Khi nào dùng:** Khi bạn giao một việc lớn ("Làm cho tôi tính năng thanh toán") mà không biết bắt đầu từ đâu.
+### 4. `qk-access-policy` (Kiểm Soát Phân Quyền)
+- **Mô tả:** Xử lý và cung cấp các quy tắc về bảo mật (Security), phân quyền (RBAC), Authentication (JWT/OAuth).
+- **Khi nào dùng:** Khi tính năng liên quan đến việc bảo mật, ai được quyền truy cập vào đâu.
 
-### 2. `context-manager` (Quản Lý Ngữ Cảnh)
-- **Mô tả:** Xác định file nào cần đọc, đọc cấu trúc thư mục, ghi nhớ kiến trúc hệ thống để AI không bị "quên" hoặc đọc tràn ngập các file không cần thiết.
-- **Khi nào dùng:** Khi bắt đầu một dự án mới tinh, hoặc khi AI cần nắm bắt bức tranh tổng thể.
+### 5. `qk-project-memory` (Trí Nhớ Dự Án)
+- **Mô tả:** Lưu trữ DNA của dự án, các quyết định kiến trúc, UI pattern và các convention đã được thống nhất từ trước.
+- **Khi nào dùng:** Khi muốn AI làm theo đúng style đã có sẵn trong dự án.
 
-### 3. `project-audit` (Kiểm Toán Dự Án)
-- **Mô tả:** Quét toàn bộ mã nguồn hoặc các file bạn vừa thay đổi để tìm kiếm bug tiềm ẩn, code smell, lỗ hổng bảo mật hoặc nợ kỹ thuật. AI sẽ xuất ra một báo cáo khám bệnh chi tiết.
-- **Khi nào dùng:** Trước khi refactor lớn, trước khi release, hoặc muốn kiểm tra code mình viết có sạch không.
+### 6. `qk-engineering-standard` (Bộ Luật Thiết Kế)
+- **Mô tả:** Bơm các "luật thép" (về Frontend, Backend, Database) vào ngữ cảnh để bắt AI tuân thủ cấu trúc thư mục và naming.
+- **Khi nào dùng:** Tự động gọi để ép AI viết code không bị rác.
 
-### 4. `bug-fix` (Chuyên Gia Sửa Lỗi)
-- **Mô tả:** Dò tìm nguyên nhân gốc rễ (root cause) của một lỗi dựa trên stack trace hoặc mô tả của bạn. Không chữa cháy tạm thời, cung cấp bản fix tối thiểu và an toàn nhất.
-- **Khi nào dùng:** Khi app bị crash, test fail, màn hình trắng.
+### 7. `qk-project-bootstrap` (Khởi Tạo Dự Án)
+- **Mô tả:** Setup toàn bộ khung sườn của một dự án mới tinh từ con số 0 (Cấu hình lint, format, folder structure).
+- **Khi nào dùng:** Lúc bắt đầu dự án mới.
+
+---
 
-### 5. `refactor` (Tái Cấu Trúc Code)
-- **Mô tả:** Làm sạch code, tách hàm, tách component, xóa code thừa, dọn dẹp biến mà **không làm thay đổi logic hoạt động**.
-- **Khi nào dùng:** Khi code quá rối rắm (spaghetti code), cần dọn dẹp cho dễ bảo trì.
+## 🎨 Lớp 1: UI System Layer (Hệ Thống Giao Diện)
+*Nhóm chuyên biệt về vẽ giao diện và quản lý hệ thống thành phần (Components).*
 
-### 6. `api-integration` (Kỹ Sư Tích Hợp API)
-- **Mô tả:** Nhận bất kỳ input nào (curl, swagger, postman, backend controller) và sinh ra một lớp gọi API hoàn chỉnh cho Frontend (Type chuẩn, xử lý lỗi, call Axios/Fetch/React Query).
-- **Khi nào dùng:** Khi Backend vừa làm xong API và bạn cần nối nó vào Frontend.
+### 8. `qk-ui-system-builder` (Kỹ Sư Hệ Thống UI)
+- **Mô tả:** Quản lý Design Token, tạo ra các Component có thể tái sử dụng (Button, Table, Form) đảm bảo tính nhất quán toàn dự án.
+- **Khi nào dùng:** Xây dựng thư viện giao diện, tránh viết CSS lộn xộn.
 
-### 7. `migration` (Nâng Cấp Hệ Thống)
-- **Mô tả:** Nâng cấp an toàn các thư viện cũ (như React 17 lên 19), chuyển đổi thư viện (Moment sang Date-fns) theo mô hình tăng dần, có kế hoạch Rollback.
-- **Khi nào dùng:** Khi cần update package có lỗ hổng bảo mật hoặc chuyển framework.
+### 9. `qk-design-to-code` (Chuyển Đổi Thiết Kế)
+- **Mô tả:** Đọc hiểu hình ảnh/Figma để tự động chuyển thành mã nguồn giao diện (React, Tailwind, v.v.).
+- **Khi nào dùng:** Bóc tách UI từ bản thiết kế.
 
-### 8. `git-engineer` (Quản Lý Git & Release)
-- **Mô tả:** Viết commit message cực chuẩn theo Conventional Commits, viết mô tả Pull Request, sinh Changelog và Release Notes cho sếp/khách hàng đọc.
-- **Khi nào dùng:** Khi code xong và cần đẩy code lên hoặc chuẩn bị release version mới.
+### 10. `qk-ui-audit` (Kiểm Toán Giao Diện)
+- **Mô tả:** Kiểm tra độ nhất quán UI/UX, hỗ trợ Responsive trên điện thoại và tối ưu khả năng tiếp cận (Accessibility - a11y).
+- **Khi nào dùng:** Kiểm tra lỗi UI sau khi hoàn thiện giao diện.
 
 ---
 
-## 🎨 Nhóm 2: Frontend (Giao Diện)
+## 💻 Lớp 2: Development Layer (Phát Triển E2E)
+*Khối thực thi mạnh mẽ nhất, đi từ A-Z một tính năng cụ thể.*
 
-Nhóm chuyên biệt cho việc xây dựng giao diện người dùng (UI/UX).
+### 11. `qk-feature-delivery` (Chuyển Giao Tính Năng)
+- **Mô tả:** Kỹ năng toàn năng, tự động phân tích thiết kế Database -> Viết API -> Xây UI -> Viết Unit Test cho một tính năng trọn vẹn.
+- **Khi nào dùng:** Xây dựng tính năng hoàn chỉnh (Ví dụ: Chức năng Thanh Toán).
 
-### 9. `frontend-architecture` (Kiến Trúc Frontend)
-- **Mô tả:** Đọc hiểu và ép AI phải tuân thủ việc đặt file ở đâu cho đúng chuẩn của project (Features-based, Layer-based, DDD...).
-- **Khi nào dùng:** Khi không biết nên tạo file component mới ở thư mục nào.
+### 12. `qk-api-lifecycle` (Vòng Đời API)
+- **Mô tả:** Chuyên biệt cho Backend: Viết spec, tạo Service, định nghĩa Type, viết Test và sinh tài liệu cho API.
+- **Khi nào dùng:** Xây dựng các Endpoint API.
 
-### 10. `design-system` (Hệ Thống Thiết Kế)
-- **Mô tả:** Ép AI phải dùng thư viện UI có sẵn (MUI, Shadcn, Tailwind...) thay vì tự viết HTML chay hay CSS inline lộn xộn.
-- **Khi nào dùng:** Đi kèm khi xây dựng UI để giữ tính nhất quán.
+### 13. `qk-data-lifecycle` (Vòng Đời Dữ Liệu)
+- **Mô tả:** Quản lý Schema, tạo file Migration, tối ưu câu lệnh truy vấn (SQL, Prisma, v.v.).
+- **Khi nào dùng:** Thay đổi cấu trúc cơ sở dữ liệu.
 
-### 11. `ui-builder` (Xây Dựng Giao Diện)
-- **Mô tả:** Lắp ráp các component nhỏ thành một màn hình/trang hoàn chỉnh, xử lý layout (Grid/Flexbox) và responsive (di động/máy tính).
-- **Khi nào dùng:** Khi bạn đưa wireframe/mockup và bảo "Làm cho tôi màn hình Dashboard".
+---
 
-### 12. `component-generator` (Tạo Component Đơn Lẻ)
-- **Mô tả:** Sinh ra các mảnh ghép UI nhỏ, tái sử dụng được (như Button, Card, Dropdown) với Props Type an toàn.
-- **Khi nào dùng:** Khi cần tạo một UI Component dùng chung.
+## 🛡️ Lớp 3: Quality Assurance Layer (Đảm Bảo Chất Lượng)
+*Kiểm tra độ sạch của code và diệt bug.*
 
-### 13. `state-management` (Quản Lý Trạng Thái)
-- **Mô tả:** Phân tích dữ liệu và quyết định nên dùng React Query, Redux, Zustand hay chỉ là useState local. Setup các store hoàn chỉnh.
-- **Khi nào dùng:** Khi phải truyền Props quá sâu, hoặc cần lưu cache dữ liệu.
+### 14. `qk-project-health` (Kiểm Toán Dự Án)
+- **Mô tả:** Quét toàn bộ dự án để tìm Code Smell, Nợ kỹ thuật (Tech Debt), và các vi phạm kiến trúc.
+- **Khi nào dùng:** Định kỳ kiểm tra chất lượng mã nguồn hoặc tối ưu hiệu năng.
 
-### 14. `form-builder` (Chuyên Gia Làm Form)
-- **Mô tả:** Sinh ra các Form phức tạp với validate đầu vào (Zod, Yup) kết hợp React Hook Form. Hiển thị báo lỗi chuẩn mực.
-- **Khi nào dùng:** Làm màn hình Đăng ký, Đăng nhập, Tạo mới dữ liệu.
+### 15. `qk-bug-resolution` (Giải Quyết Bug Triệt Để)
+- **Mô tả:** Tái hiện lỗi, đào sâu tìm Root Cause, cung cấp giải pháp an toàn và viết Regression Test để chống lỗi lặp lại.
+- **Khi nào dùng:** Sửa các lỗi đứt gãy hoặc logic nghiêm trọng.
 
-### 15. `table-crud-generator` (Làm Bảng Dữ Liệu)
-- **Mô tả:** Sinh ra bảng Data Grid hoàn chỉnh có phân trang (pagination), lọc, sắp xếp và các nút hành động (Thêm/Sửa/Xóa).
-- **Khi nào dùng:** Làm trang Admin quản trị.
+### 16. `qk-validation-gate` (Cổng Kiểm Định)
+- **Mô tả:** Kỹ năng chặn cửa. Bắt buộc chạy Test, Linting và Scan Security. Chỉ khi "PASS" mới cho phép kết thúc task.
+- **Khi nào dùng:** Nằm cuối quy trình code của bất kỳ tính năng nào.
 
-### 16. `frontend-debug` (Sửa Lỗi Frontend)
-- **Mô tả:** Chuyên trị các lỗi khó chịu của UI như: Hydration Error (Next.js), Infinite Re-render (lặp vô tận), lỗi vỡ CSS layout.
-- **Khi nào dùng:** Lỗi vỡ giao diện hoặc lỗi render của React.
+---
 
-### 17. `frontend-testing` (Kiểm Thử UI)
-- **Mô tả:** Viết Unit Test, Component Test (React Testing Library) hay E2E Test (Cypress/Playwright) giả lập hành vi người dùng thật.
-- **Khi nào dùng:** Khi sếp yêu cầu tăng Test Coverage hoặc bọc test cho tính năng quan trọng.
+## 🚀 Lớp 4 & 5: Evolution & Operation (Vận Hành & Tiến Hóa)
+*Triển khai dự án lên Production và nâng cấp phiên bản lớn.*
 
-### 18. `accessibility-audit` (Kiểm Tra Tiếp Cận)
-- **Mô tả:** Đảm bảo trang web chuẩn WCAG, dùng đúng thẻ Semantic HTML, có thể dùng phím Tab để điều hướng và hỗ trợ phần mềm đọc màn hình cho người khiếm thị.
-- **Khi nào dùng:** Làm các project chuẩn quốc tế, nhà nước, hoặc tối ưu SEO nâng cao.
+### 17. `qk-system-evolution` (Tiến Hóa Hệ Thống)
+- **Mô tả:** Nâng cấp dependency (VD: Next 14 lên 15), phân tích rủi ro ảnh hưởng và thực thi nâng cấp an toàn không downtime.
+- **Khi nào dùng:** Update version framework/thư viện.
 
-### 19. `frontend-performance` (Tối Ưu Hiệu Năng)
-- **Mô tả:** Chữa bệnh web chạy chậm. Tối ưu ảnh, chẻ nhỏ file JS (Code splitting, Lazy load), thêm `useMemo/useCallback` để tránh giật lag.
-- **Khi nào dùng:** Điểm Google Lighthouse thấp, web bị khựng khi cuộn.
+### 18. `qk-production-release` (Triển Khai Môi Trường)
+- **Mô tả:** Viết Dockerfile, cấu hình CI/CD Pipelines (Github Actions), Deploy lên Cloud (AWS, Vercel).
+- **Khi nào dùng:** Release sản phẩm cho người dùng cuối.
 
 ---
 
-## ⚙️ Nhóm 3: Backend (Máy Chủ)
+## 🤖 Lớp 6: AI Builder Layer (Tích hợp AI)
 
-Nhóm chuyên biệt cho việc xây dựng và quản lý API, máy chủ.
+### 19. `qk-ai-builder` (Xây Dựng AI App)
+- **Mô tả:** Chuyên thiết kế và code các ứng dụng AI như RAG (Retrieval-Augmented Generation), Agent logic và Prompt Engineering.
+- **Khi nào dùng:** Tích hợp LLM vào trong phần mềm của bạn.
+
+---
 
-### 20. `backend-architecture` (Kiến Trúc Backend)
-- **Mô tả:** Phân chia rạch ròi đâu là Controller (xử lý HTTP), đâu là Service (Xử lý nghiệp vụ), đâu là Repository (Gọi Database) để code không bị thành một đống bùi nhùi.
-- **Khi nào dùng:** Cấu trúc file cho backend mới hoặc thêm module mới.
+## 📚 Lớp 7: Knowledge Layer (Tri Thức & Tài Liệu)
+*Hệ thống tự học và viết tài liệu vĩ đại của OS.*
 
-### 21. `database-engineer` (Kỹ Sư Cơ Sở Dữ Liệu)
-- **Mô tả:** Thiết kế schema, vẽ quan hệ bảng, sinh script Migration, tối ưu hóa câu lệnh truy vấn (SQL, Prisma, Drizzle, MongoDB).
-- **Khi nào dùng:** Cần thêm bảng mới vào DB hoặc API truy vấn DB quá chậm.
+### 20. `qk-docs` (Kỹ Sư Tài Liệu)
+- **Mô tả:** Tự động sinh hoặc cập nhật tài liệu cho con người đọc: `README.md`, `CHANGELOG.md`, `API Docs`.
+- **Khi nào dùng:** Nằm ở cuối quy trình sau khi hoàn thành tính năng.
 
-### 22. `auth-security` (Bảo Mật & Phân Quyền)
-- **Mô tả:** Triển khai đăng nhập JWT, OAuth, thiết lập phân quyền (Admin vs User), phòng chống hacker tấn công bằng các cấu hình bảo mật chuẩn OWASP.
-- **Khi nào dùng:** Làm tính năng đăng nhập, bảo vệ API nhạy cảm.
+### 21. `qk-documentation-system` (Hệ Thống Trí Nhớ)
+- **Mô tả:** Quản trị Tri thức máy. Tự động rút trích các Quyết định Kỹ thuật (ADR) hoặc Pattern mới xuất hiện trong code, và nạp ngược lại vào `qk-project-memory`.
+- **Khi nào dùng:** Hệ thống "tự học" để Agent trở nên thông minh hơn qua từng ngày.
 
-### 23. `deployment` (Triển Khai DevOps)
-- **Mô tả:** Viết Dockerfile, cấu hình CI/CD bằng GitHub Actions, thiết lập luồng tự động build và deploy lên Vercel, AWS hoặc VPS.
-- **Khi nào dùng:** Lúc cần đưa code lên môi trường production cho khách hàng xem.
+### 22. `qk-help` (Tra Cứu Nhanh)
+- **Mô tả:** Cuốn từ điển sống. Cung cấp thông tin và hướng dẫn chi tiết (Pro-tips) về cách sử dụng toàn bộ hệ thống.
+- **Khi nào dùng:** Bất kỳ khi nào người dùng cần hỗ trợ sử dụng hệ điều hành.