ai-developer-skill-os 8.2.0 → 8.3.0

package/.agents/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Quang Khánh
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Quang Khánh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.agents/README.md

@@ -1,90 +1,90 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.2.0
-
-> **v8.2.0 "EDAOS v8.2 — Governed Capability Metadata & Eval Platform"**
-
-Hệ sinh thái AI Developer Skill OS tiến hóa lên phiên bản **V8.2.0 (EDAOS v8.2)** với kiến trúc **Manifest-First & Eval Platform**, giúp giảm tối đa chi phí nhận thức (cognitive load) cho các AI Agent thế hệ mới (như Antigravity) nhờ chỉ định ranh giới định lượng, đồ thị phụ thuộc O(1), và các Blueprint Plugins quy chuẩn cho từng ngành nghề kỹ thuật.
-
----
-
-## 🏗️ 4 Trụ Cột Kiến Trúc Cốt Lõi (EDAOS v8.2 Architecture)
-
-### 1. Manifest-First & O(1) Registry Engine
-Không còn phụ thuộc vào việc đọc/scan toàn bộ markdown mệt mỏi. AI Agent tra cứu siêu dữ liệu từ `.agents/registry/index.yaml` và kiểm duyệt chu trình không lặp (acyclic validation) thông qua O(1) graph JSON (`.agents/registry/graph.json`). Tốc độ hiểu và phân công năng lực đạt ngưỡng sub-second!
-
-### 2. V8.2 Blueprint Plugins & Universal 4-Folder Architecture
-Khởi tạo dự án (chỉ đạo qua `qk-project-bootstrap`) hỗ trợ sinh file `project.yaml` gốc từ thư viện Blueprint Plugins:
-- **RAG / AI Agents:** Cấu trúc 4 thư mục chuẩn thực chiến: `prompts/`, `data/` (bảo vệ `data/raw` bất biến), `agents/`, và `evals/`.
-- **Standard Software Coding:** Kiến trúc module sạch vững chắc với `DESIGN.md` và rào cản kiểm duyệt tự động.
-- **Automation Workflows:** Các luồng tích hợp n8n và dữ liệu lớn.
-
-### 3. Eval Pipeline Platform (Khép Kín Kiểm Định)
-Chấm dứt việc tin tưởng AI blindly. Mọi Capability đều có thẻ điểm định lượng (`scorecard.yaml`), kết nối log thực thi thực tế từ thư mục `evals/traces/` qua cổng thẩm định sắt đá `qk-validation-gate`. Trách nhiệm định lượng 0–100 với sai số 0% (zero tolerance for fabrication).
-
-### 4. Domain Patterns Separation (Bảo Vệ Kernel)
-Các hệ thống AI chuyên sâu (như **Xây dựng DDC 192 skills**, bóc tách BIM/IFC, ERP) được tải lập trình viên cấu hình dạng Module dưới `knowledge/domain-patterns/` thay vì phơi bày trực tiếp vào 30 Core Developer Skills, giữ cho đồ thị cốt lõi luôn nhanh bén mượt mà!
-
----
-
-## 🧩 Danh sách 30 Master Skills (Core Developer Capabilities)
-
-Các kỹ năng được quản lý bằng **Capability Graph** và được đánh giá liên tục thông qua Evaluation Suite. Bao gồm 7 lĩnh vực:
-1. **Core & Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-project-memory`, `qk-help`
-2. **Product & Architecture:** `qk-product-specification`, `qk-project-bootstrap`, `qk-frontend-architecture`
-3. **Frontend & UI:** `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-builder`, `qk-fe-api-integration`, `qk-ui-audit`
-4. **Backend & Data:** `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-access-policy`
-5. **Engineering & Delivery:** `qk-feature-delivery`, `qk-bug-resolution`, `qk-engineering-standard`, `qk-system-evolution`, `qk-docs`
-6. **Quality & Testing:** `qk-test-engineering`, `qk-validation-gate`, `qk-web-quality-gate`, `qk-project-health`
-7. **Security, DevOps & Analytics:** `qk-security-audit`, `qk-db-optimizer`, `qk-devops-platform`, `qk-production-release`, `qk-agent-observability`, `qk-ai-builder`
-
----
-
-## 💻 Cách Cài Đặt (Installation)
-
-### Cách 1: NXP (Không cần cài global) - MỚI
-```bash
-npx ai-developer-skill-os init
-```
-
-### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
-```bash
-npm i -g ai-developer-skill-os
-```
-
-### Chạy bằng tham số (Command Line Arguments)
-```bash
-# Cài Antigravity Global (toàn máy)
-npx ai-developer-skill-os init --ide=antigravity --scope=2
-
-# Cài Antigravity Local (chỉ dự án này)
-npx ai-developer-skill-os init --ide=antigravity --scope=1
-
-# Cài Cursor Local
-npx ai-developer-skill-os init --ide=cursor --scope=1
-```
-
-## 📦 Các IDE/AI Assistant Được Hỗ Trợ
-- (1) Cursor
-- (2) Windsurf
-- (3) Cline / Roo Code
-- (4) Antigravity / Gemini
-- (5) Codex
-- (6) Kilo Code
-
----
-
-## 🧪 Đánh Giá Tự Động (Agent Evaluation)
-
-Hệ thống đi kèm một bộ Runner nội bộ để kiểm toán **Routing Intelligence**. Bất kỳ cập nhật nào vào hệ thống Kỹ năng đều phải vượt qua bài kiểm tra hóc búa (Bypass Security, Boundary Attacks, Ambiguous Prompts):
-
-```bash
-npm run test:agent
-npm run test:graph
-npm run test:registry
-```
-
-## 🚀 Hướng Dẫn Sử Dụng
-Sau khi cài đặt thành công, hãy gõ lệnh:
-```bash
-./qk-help
-```
-để kích hoạt AI Orchestrator và khám phá sức mạnh của hệ điều hành!
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.2.1
+
+> **v8.2.1 "EDAOS v8.2 — Governed Capability Metadata & Eval Platform"**
+
+Hệ sinh thái AI Developer Skill OS tiến hóa lên phiên bản **v8.2.1 (EDAOS v8.2)** với kiến trúc **Manifest-First & Eval Platform**, giúp giảm tối đa chi phí nhận thức (cognitive load) cho các AI Agent thế hệ mới (như Antigravity) nhờ chỉ định ranh giới định lượng, đồ thị phụ thuộc O(1), và các Blueprint Plugins quy chuẩn cho từng ngành nghề kỹ thuật.
+
+---
+
+## 🏗️ 4 Trụ Cột Kiến Trúc Cốt Lõi (EDAOS v8.2 Architecture)
+
+### 1. Manifest-First & O(1) Registry Engine
+Không còn phụ thuộc vào việc đọc/scan toàn bộ markdown mệt mỏi. AI Agent tra cứu siêu dữ liệu từ `.agents/registry/index.yaml` và kiểm duyệt chu trình không lặp (acyclic validation) thông qua O(1) graph JSON (`.agents/registry/graph.json`). Tốc độ hiểu và phân công năng lực đạt ngưỡng sub-second!
+
+### 2. V8.2 Blueprint Plugins & Universal 4-Folder Architecture
+Khởi tạo dự án (chỉ đạo qua `qk-project-bootstrap`) hỗ trợ sinh file `project.yaml` gốc từ thư viện Blueprint Plugins:
+- **RAG / AI Agents:** Cấu trúc 4 thư mục chuẩn thực chiến: `prompts/`, `data/` (bảo vệ `data/raw` bất biến), `agents/`, và `evals/`.
+- **Standard Software Coding:** Kiến trúc module sạch vững chắc với `DESIGN.md` và rào cản kiểm duyệt tự động.
+- **Automation Workflows:** Các luồng tích hợp n8n và dữ liệu lớn.
+
+### 3. Eval Pipeline Platform (Khép Kín Kiểm Định)
+Chấm dứt việc tin tưởng AI blindly. Mọi Capability đều có thẻ điểm định lượng (`scorecard.yaml`), kết nối log thực thi thực tế từ thư mục `evals/traces/` qua cổng thẩm định sắt đá `qk-validation-gate`. Trách nhiệm định lượng 0–100 với sai số 0% (zero tolerance for fabrication).
+
+### 4. Domain Patterns Separation (Bảo Vệ Kernel)
+Các hệ thống AI chuyên sâu (như **Xây dựng DDC 192 skills**, bóc tách BIM/IFC, ERP) được tải lập trình viên cấu hình dạng Module dưới `knowledge/domain-patterns/` thay vì phơi bày trực tiếp vào 30 Core Developer Skills, giữ cho đồ thị cốt lõi luôn nhanh bén mượt mà!
+
+---
+
+## 🧩 Danh sách 30 Master Skills (Core Developer Capabilities)
+
+Các kỹ năng được quản lý bằng **Capability Graph** và được đánh giá liên tục thông qua Evaluation Suite. Bao gồm 7 lĩnh vực:
+1. **Core & Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-project-memory`, `qk-help`
+2. **Product & Architecture:** `qk-product-specification`, `qk-project-bootstrap`, `qk-frontend-architecture`
+3. **Frontend & UI:** `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-builder`, `qk-fe-api-integration`, `qk-ui-audit`
+4. **Backend & Data:** `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-access-policy`
+5. **Engineering & Delivery:** `qk-feature-delivery`, `qk-bug-resolution`, `qk-engineering-standard`, `qk-system-evolution`, `qk-docs`
+6. **Quality & Testing:** `qk-test-engineering`, `qk-validation-gate`, `qk-web-quality-gate`, `qk-project-health`
+7. **Security, DevOps & Analytics:** `qk-security-audit`, `qk-db-optimizer`, `qk-devops-platform`, `qk-production-release`, `qk-agent-observability`, `qk-ai-builder`
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+### Cách 1: NXP (Không cần cài global) - MỚI
+```bash
+npx ai-developer-skill-os init
+```
+
+### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
+```bash
+npm i -g ai-developer-skill-os
+```
+
+### Chạy bằng tham số (Command Line Arguments)
+```bash
+# Cài Antigravity Global (toàn máy)
+npx ai-developer-skill-os init --ide=antigravity --scope=2
+
+# Cài Antigravity Local (chỉ dự án này)
+npx ai-developer-skill-os init --ide=antigravity --scope=1
+
+# Cài Cursor Local
+npx ai-developer-skill-os init --ide=cursor --scope=1
+```
+
+## 📦 Các IDE/AI Assistant Được Hỗ Trợ
+- (1) Cursor
+- (2) Windsurf
+- (3) Cline / Roo Code
+- (4) Antigravity / Gemini
+- (5) Codex
+- (6) Kilo Code
+
+---
+
+## 🧪 Đánh Giá Tự Động (Agent Evaluation)
+
+Hệ thống đi kèm một bộ Runner nội bộ để kiểm toán **Routing Intelligence**. Bất kỳ cập nhật nào vào hệ thống Kỹ năng đều phải vượt qua bài kiểm tra hóc búa (Bypass Security, Boundary Attacks, Ambiguous Prompts):
+
+```bash
+npm run test:agent
+npm run test:graph
+npm run test:registry
+```
+
+## 🚀 Hướng Dẫn Sử Dụng
+Sau khi cài đặt thành công, hãy gõ lệnh:
+```bash
+./qk-help
+```
+để kích hoạt AI Orchestrator và khám phá sức mạnh của hệ điều hành!

package/.agents/docs/CHI_TIET_SKILLS.md

@@ -1,126 +1,126 @@
-# Từ Điển Chi Tiết 22 Siêu Kỹ Năng (Master Skills)
-
-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).
-
----
-
-## 🏗️ 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 tâm", 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.
-
-### 3. `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.
-
-### 4. `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.
-
-### 5. `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.
-
-### 6. `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.
-
----
-
-## 🎨 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).*
-
-### 7. `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.
-
-### 8. `qk-ui-builder` (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ế.
-
-### 9. `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.
-
----
-
-## 💻 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ể.*
-
-### 10. `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).
-
-### 11. `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.
-
-### 12. `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.
-
-### 13. `qk-db-optimizer` (Tối Ưu Database)
-- **Mô tả:** Phân tích EXPLAIN plan, tìm N+1 queries, đề xuất index và tối ưu query performance.
-- **Khi nào dùng:** Truy vấn chậm, performance DB issue.
-
-### 14. `qk-fe-api-integration` (Tích Hợp API Frontend)
-- **Mô tả:** Consume API Backend, quản lý State, bind vào UI — tuân thủ kiến trúc Base dự án.
-- **Khi nào dùng:** Khi cần gọi API từ frontend, map DTO, xử lý Loading/Error states.
-
----
-
-## 🛡️ 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.*
-
-### 15. `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.
-
-### 16. `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.
-
-### 17. `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.
-
----
-
-## 🚀 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. `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. `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.
-
----
-
-## 🤖 Lớp 6: AI Builder Layer (Tích hợp AI)
-
-### 20. `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.
-
----
-
-## 📚 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. `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. `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.
+# Từ Điển Chi Tiết 22 Siêu Kỹ Năng (Master Skills)
+
+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).
+
+---
+
+## 🏗️ 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 tâm", 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.
+
+### 3. `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.
+
+### 4. `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.
+
+### 5. `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.
+
+### 6. `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.
+
+---
+
+## 🎨 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).*
+
+### 7. `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.
+
+### 8. `qk-ui-builder` (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ế.
+
+### 9. `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.
+
+---
+
+## 💻 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ể.*
+
+### 10. `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).
+
+### 11. `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.
+
+### 12. `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.
+
+### 13. `qk-db-optimizer` (Tối Ưu Database)
+- **Mô tả:** Phân tích EXPLAIN plan, tìm N+1 queries, đề xuất index và tối ưu query performance.
+- **Khi nào dùng:** Truy vấn chậm, performance DB issue.
+
+### 14. `qk-fe-api-integration` (Tích Hợp API Frontend)
+- **Mô tả:** Consume API Backend, quản lý State, bind vào UI — tuân thủ kiến trúc Base dự án.
+- **Khi nào dùng:** Khi cần gọi API từ frontend, map DTO, xử lý Loading/Error states.
+
+---
+
+## 🛡️ 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.*
+
+### 15. `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.
+
+### 16. `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.
+
+### 17. `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.
+
+---
+
+## 🚀 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. `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. `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.
+
+---
+
+## 🤖 Lớp 6: AI Builder Layer (Tích hợp AI)
+
+### 20. `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.
+
+---
+
+## 📚 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. `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. `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.
 

package/.agents/docs/MIGRATION-CLEANUP-V8.1.3.md

@@ -1,36 +1,36 @@
-# V8.1.3 Repository Cleanup Record
-
-## Objective
-
-Remove V7 legacy artifacts and establish
-V8 Control Plane as single source of truth.
-
-## Removed
-
-- `/skills`
-- `/skills.json`
-- `/.agents/skills.json`
-
-## Archived
-
-- `tests/agent-evaluation` legacy markdown cases
-
-## New Authority
-
-Skill metadata:
-
-`.agents/skills/*/SKILL.md`
-
-Registry:
-
-`.agents/registry/`
-
-Generated:
-
-- `skills-index.yml`
-- `capability-graph.yml`
-
-## Verification
-
-- `npm run test:agent`
-- `npm run test:graph`
+# V8.1.3 Repository Cleanup Record
+
+## Objective
+
+Remove V7 legacy artifacts and establish
+V8 Control Plane as single source of truth.
+
+## Removed
+
+- `/skills`
+- `/skills.json`
+- `/.agents/skills.json`
+
+## Archived
+
+- `tests/agent-evaluation` legacy markdown cases
+
+## New Authority
+
+Skill metadata:
+
+`.agents/skills/*/SKILL.md`
+
+Registry:
+
+`.agents/registry/`
+
+Generated:
+
+- `skills-index.yml`
+- `capability-graph.yml`
+
+## Verification
+
+- `npm run test:agent`
+- `npm run test:graph`

package/.agents/docs/MIGRATION-STATUS.md

@@ -1,35 +1,35 @@
-# V8 Migration Status
-
-| Skill | Version | Status | Workflow |
-|---|---|---|---|
-| qk-orchestrator | 8.0.0 | stable | internal |
-| qk-bug-resolution | 8.0.0 | stable | bug-resolution |
-| qk-context-loader | 8.0.0 | stable | internal |
-| qk-feature-delivery | 8.0.0 | stable | feature-delivery |
-| qk-validation-gate | 8.0.0 | stable | code-review |
-| qk-engineering-standard | 8.0.0 | stable | code-review |
-| qk-project-memory | 8.0.0 | stable | documentation |
-| qk-project-health | 8.0.0 | stable | code-review |
-| qk-system-evolution | 8.0.0 | stable | refactor |
-| qk-docs | 8.0.0 | stable | documentation |
-| qk-api-lifecycle | 8.0.0 | stable | feature-delivery |
-| qk-fe-api-integration | 8.0.0 | stable | feature-delivery |
-| qk-data-lifecycle | 8.0.0 | stable | feature-delivery |
-| qk-ui-builder | 8.0.0 | stable | feature-delivery |
-| qk-ui-system-builder | 8.0.0 | stable | feature-delivery |
-| qk-ui-audit | 8.0.0 | stable | code-review |
-| qk-db-optimizer | 8.0.0 | stable | refactor |
-| qk-access-policy | 8.0.0 | stable | feature-delivery |
-| qk-production-release | 8.0.0 | stable | internal |
-| qk-project-bootstrap | 8.0.0 | stable | feature-delivery |
-| qk-ai-builder | 8.0.0 | stable | feature-delivery |
-| qk-help | 8.0.0 | deprecated | internal |
-| qk-frontend-architecture | 8.1.0 | experimental | feature-delivery |
-| qk-design-system-engineering | 8.1.0 | experimental | feature-delivery |
-| qk-web-quality-gate | 8.1.0 | experimental | feature-delivery |
-| qk-test-engineering | 8.1.0 | experimental | feature-delivery |
-| qk-security-audit | 8.1.0 | experimental | security-audit |
-| qk-product-specification | 8.1.0 | experimental | spec-driven-development |
-
-Progress:
-22/22 stable, 6 experimental, 1 deprecated
+# V8 Migration Status
+
+| Skill | Version | Status | Workflow |
+|---|---|---|---|
+| qk-orchestrator | 8.0.0 | stable | internal |
+| qk-bug-resolution | 8.0.0 | stable | bug-resolution |
+| qk-context-loader | 8.0.0 | stable | internal |
+| qk-feature-delivery | 8.0.0 | stable | feature-delivery |
+| qk-validation-gate | 8.0.0 | stable | code-review |
+| qk-engineering-standard | 8.0.0 | stable | code-review |
+| qk-project-memory | 8.0.0 | stable | documentation |
+| qk-project-health | 8.0.0 | stable | code-review |
+| qk-system-evolution | 8.0.0 | stable | refactor |
+| qk-docs | 8.0.0 | stable | documentation |
+| qk-api-lifecycle | 8.0.0 | stable | feature-delivery |
+| qk-fe-api-integration | 8.0.0 | stable | feature-delivery |
+| qk-data-lifecycle | 8.0.0 | stable | feature-delivery |
+| qk-ui-builder | 8.0.0 | stable | feature-delivery |
+| qk-ui-system-builder | 8.0.0 | stable | feature-delivery |
+| qk-ui-audit | 8.0.0 | stable | code-review |
+| qk-db-optimizer | 8.0.0 | stable | refactor |
+| qk-access-policy | 8.0.0 | stable | feature-delivery |
+| qk-production-release | 8.0.0 | stable | internal |
+| qk-project-bootstrap | 8.0.0 | stable | feature-delivery |
+| qk-ai-builder | 8.0.0 | stable | feature-delivery |
+| qk-help | 8.0.0 | deprecated | internal |
+| qk-frontend-architecture | 8.1.0 | experimental | feature-delivery |
+| qk-design-system-engineering | 8.1.0 | experimental | feature-delivery |
+| qk-web-quality-gate | 8.1.0 | experimental | feature-delivery |
+| qk-test-engineering | 8.1.0 | experimental | feature-delivery |
+| qk-security-audit | 8.1.0 | experimental | security-audit |
+| qk-product-specification | 8.1.0 | experimental | spec-driven-development |
+
+Progress:
+22/22 stable, 6 experimental, 1 deprecated