ai-developer-skill-os 9.3.1 → 10.2.0

package/.agents/docs/CHI_TIET_SKILLS.md

@@ -1,126 +0,0 @@
-# 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/HUONG_DAN_SU_DUNG.md

@@ -1,120 +0,0 @@
-# Hướng Dẫn Sử Dụng — AI Developer Skill OS
-
-**Tác giả:** Quang Khánh  
-**Phiên bản:** v7.5.0 (Anti-Slop & Zero-Trust Architecture)
-
-Chào mừng bạn đến với **AI Developer Skill OS**, hệ điều hành kỹ năng (Skill Framework) biến các trợ lý AI (Gemini, Antigravity, Claude Code, Cursor, Windsurf) từ một "cỗ máy sinh code" thành một **Senior Software 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.
-
----
-
-## 1. Cơ chế hoạt động (Tại sao lại cần Skin/Skill này?)
-
-Thông thường, khi bạn yêu cầu AI "Làm cho tôi tính năng X", AI sẽ nhảy ngay vào viết code. Điều này ở các dự án lớn thường dẫn đến: phá vỡ kiến trúc, tạo ra code rác, và không tuân thủ các component dùng chung.
-
-Với hệ điều hành 22 Master Skills này:
-1. Bạn đưa ra yêu cầu thông qua **`qk-orchestrator`**.
-2. Hệ thống sẽ tự động gọi **`qk-context-loader`** để gom đúng file (tránh tràn ngữ cảnh).
-3. Kế tiếp, **`qk-engineering-standard`** sẽ gắn các "luật thép" (rules) của dự án vào ngữ cảnh.
-4. AI kích hoạt kỹ năng thực thi E2E như **`qk-feature-delivery`** để code và test trọn vẹn.
-5. Cuối cùng, **`qk-validation-gate`** chặn lại kiểm tra lỗi, trước khi giao cho **`qk-docs`** tự động cập nhật tài liệu.
-
----
-
-## 2. Hướng dẫn cài đặt qua NPM (Khuyên dùng)
-
-Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn có thể cài vào bất kỳ dự án nào cực kỳ nhanh chóng.
-
-Mở terminal tại gốc dự án của bạn và chạy lệnh cài đặt tương ứng với công cụ AI bạn đang dùng:
-
-```bash
-npx ai-developer-skill-os init
-```
-
-Quá trình cài đặt sẽ hỏi bạn 2 câu quan trọng:
-
-**Câu 1: Bạn đang dùng IDE nào?**
-Hệ thống sẽ tự động tạo file cấu hình tương ứng (ví dụ `.cursorrules`, `.windsurfrules`, `.clinerules`) và bơm sẵn System Prompt vào để AI tự nhận diện các skill.
-
-**Câu 2: Phạm vi cài đặt?**
-- **(1) Local:** Cài vào thư mục `skills/` (hoặc `.agents/` cho Gemini) ngay trong dự án. Thích hợp cho làm việc nhóm.
-- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Chỉ cài 1 lần, áp dụng cho mọi dự án.
-
-> 💡 **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ấu hình thủ công (Dành cho IDE / CLI cụ thể)
-
-#### Cho Gemini IDE / Antigravity
-**Không cần cấu hình gì thêm!** Hệ thống tự nhận diện các file trong `.agents/` hoặc thư mục cấu hình toàn cục.
-
-#### Cho Cursor / Windsurf (AI Code Editors)
-Tạo file `.cursorrules` hoặc `.windsurfrules` ở gốc dự án:
-```md
-# AI Developer Skill OS by Quang Khánh
-
-When answering or generating code, you MUST act as an expert engineer using the skills defined in `./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 `./skills/` trước khi thực hiện.
-Speak to me in Vietnamese, but write all code in English.
-```
-
-#### Cho Claude Code / Kilo Code (CLI Agents)
-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 `./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 `./skills/` trước khi phân tích hoặc viết code.
-```
-
----
-
-## 3. 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ộ AI-OS này chưa, hãy mở khung chat AI trong dự án và gõ cú pháp lệnh:
-> **`./qk-help`** Hãy liệt kê cho tôi các khối kỹ năng của hệ thống.
-
-✅ **Thành công:** Nếu AI trả lời bằng tiếng Việt, liệt kê đúng mô hình 7 Lớp (Foundation, UI, Development, Quality, Evolution, Operation, AI, Knowledge).
-❌ **Thất bại:** Nếu AI trả lời chung chung, bạn cần kiểm tra lại đường dẫn file cấu hình ở bước trên.
-
----
-
-## 4. 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 cách chuyên nghiệp và tiết kiệm thời gian nhất là bạn sử dụng cú pháp: **`./qk-[tên-skill]`**
-
-Dưới đây là các câu lệnh (prompt) mẫu cực kỳ hiệu quả mà bạn nên dùng:
-
-### 🎯 Ví dụ 1: Giao phó tổng thể (Orchestrator)
-> **`./qk-orchestrator`** Tôi muốn thêm tính năng Đăng nhập bằng Google. Hãy lên kế hoạch và gọi các skill cần thiết để thực hiện từ A-Z.
-
-### 🎯 Ví dụ 2: Phát triển Tính năng E2E (Feature Delivery)
-> **`./qk-feature-delivery`** Hãy tạo màn hình Dashboard thống kê doanh thu. Lưu ý cập nhật Database, tạo API và dùng UI Component có sẵn.
-
-### 🎯 Ví dụ 3: Fix lỗi cứng đầu (Bug Resolution)
-> **`./qk-bug-resolution`** Code đang bị crash với lỗi `Hydration error`. Hãy tìm Root Cause, sửa an toàn và đảm bảo viết Regression Test để chống hồi quy.
-
-### 🎯 Ví dụ 4: Xây dựng Giao diện (UI System Builder)
-> **`./qk-ui-system-builder`** Hãy tạo cho tôi một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token của dự án. Không viết inline CSS rác.
-
-### 🎯 Ví dụ 5: Audit & Tối ưu (Project Health)
-> **`./qk-project-health`** Hãy kiểm tra nhanh cho tôi thư mục `src/components/` xem có bị Code Smell hoặc vi phạm Architecture không.
-
----
-
-## 💡 5. Mẹo & Workflow Thực Chiến (Best Practices)
-
-Để khai thác tối đa sức mạnh của 22 kỹ năng, bí quyết là **tin tưởng vào chuỗi Handoff tự động** của hệ thống thay vì phải gọi từng lệnh nhỏ lẻ.
-
-### 🌟 Bắt đầu một tính năng hoàn toàn mới
-Thay vì bảo AI tạo từng file, hãy yêu cầu một lần:
-* `> Hãy dùng ./qk-feature-delivery để tạo chức năng Giỏ hàng (Cart).`
-Hệ thống sẽ tự động đi từ DB -> API -> UI và đẩy sang `qk-validation-gate` để kiểm tra lỗi.
-
-### 🌟 Khi dự án bắt đầu lộn xộn
-* `> Hãy chạy ./qk-project-health để kiểm tra toàn bộ nợ kỹ thuật (Tech Debt). Sau đó hãy dùng ./qk-docs để cập nhật lại cấu trúc thư mục mới nhất vào README.`
-
-### 🌟 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 dùng ./qk-system-evolution để phân tích tầm ảnh hưởng (Impact Analysis) nếu tôi cập nhật Next.js lên phiên bản 15.`
-
-👉 Chúc bạn tận hưởng cảm giác code như một Chief Architect thực thụ!

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

@@ -1,36 +0,0 @@
-# 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 +0,0 @@
-# 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

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

@@ -1,10 +0,0 @@
-# V8 Migration Protocol
-
-Every migrated skill MUST meet the following criteria before being marked as `status: stable`:
-
-- [ ] **Preserve original capability**: Do not alter the core instructions and behavior of the skill unless fixing bugs.
-- [ ] **Add V8 frontmatter**: Update the frontmatter strictly according to `_template/SKILL.md`.
-- [ ] **Map workflow**: Ensure `workflow` references an existing V8 workflow (e.g. `feature-delivery`, `bug-resolution`, `code-review`).
-- [ ] **Define verification**: Include the `verification` block with a valid `strategy`.
-- [ ] **Define selection**: Include the `selection` block with `priority` and appropriate `confidence_threshold`.
-- [ ] **Generate registry successfully**: Must pass schema validation in `node tooling/validate-skills.js` and `node tooling/generate-registry.js` without warnings.

package/.agents/docs/ROADMAP-V8.2.md

@@ -1,78 +0,0 @@
-# V8.2 Roadmap: Adaptive Agent OS
-
-## Triết lý cốt lõi (Core Philosophy)
-**Self Improving = Self Optimizing, NOT Self Modifying.**
-Hệ thống chuyển mình từ "Governed Capability Graph" sang "Decision Intelligence Layer" với khả năng "học từ vận hành" thông qua:
-```
-Observe -> Analyze -> Recommend -> Human Approval -> Controlled Evolution
-```
-
----
-
-## 4 Ranh giới Anti-Pattern (Boundaries)
-Để tránh lặp lại sự phình to không kiểm soát, V8.2 thiết lập 4 rào cản tuyệt đối:
-
-### Boundary 1 — Skill Inflation
-- Giữ nguyên giới hạn 30 capabilities.
-- KHÔNG tạo các skill như `qk-react-performance`, `qk-nextjs-specialist`. Những kỹ năng này thuộc **Knowledge Layer** (kiến thức tham khảo), không phải **Decision Capability Layer**.
-
-### Boundary 2 — Frontend Fragmentation
-- Giữ vững cấu trúc: `qk-frontend-architecture` -> `delegates_to` -> `qk-ui-builder`.
-- KHÔNG chia nhỏ frontend thành: `component`, `hooks`, `css`, `state`. Điều này sẽ phá vỡ boundary ra quyết định.
-
-### Boundary 3 — Graph Complexity
-- Chỉ giữ 5 loại relations cốt lõi (phục vụ Decision): `depends_on`, `conflicts_with`, `delegates_to`, `implemented_by`, `feeds`.
-- KHÔNG thêm các quan hệ Semantic mờ nhạt (như `related_to`, `similar_to`) biến graph thành Knowledge Map.
-
-### Boundary 4 — Agent Authority
-- **Agent được phép**: observe, measure, recommend, simulate.
-- **Agent KHÔNG được phép**: modify stable skill, change schema, promote itself, rewrite governance.
-
----
-
-## Lộ trình 4 Phase (V8.2 Execution Phases)
-
-### Phase 1 — Decision Memory (Ưu tiên số 1)
-Thu thập dữ liệu làm nền tảng cho Adaptive Routing.
-- Cấu trúc `decision_record`: Lưu trữ `input`, `candidates`, `selected`, `rejected`, `reason`, `confidence`, `human_feedback`.
-- Ghi nhớ "Vì sao chọn Skill này? Vì sao loại Skill kia?" để Agent có thể phân tích pattern.
-
-### Phase 2 — Skill Analytics
-Đánh giá sức khỏe của từng Capability thông qua công thức đa chiều:
-```yaml
-skill_health:
-  quality_score
-  usage_score
-  conflict_score
-  freshness_score
-  overall_score
-```
-*Lưu ý: Không chỉ đánh giá dựa trên tần suất sử dụng (usage), vì có những skill quan trọng nhưng ít gọi (như security).*
-
-### Phase 3 — Adaptive Routing
-Chuyển đổi từ đánh giá tĩnh sang động (với trọng số).
-- `dynamic score = intent_match + boundary_fit + historical_success + human_feedback`
-- **Ràng buộc tối thượng**: `Decision Boundary > Ranking Score`. Dù Score cao đến đâu, nếu vi phạm Boundary vẫn phải bị loại (Reject).
-
-### Phase 4 — Human Feedback Loop
-Thu thập phản hồi từ người dùng (Human correction).
-- **Khóa an toàn**: Human Feedback chỉ đóng vai trò là `routing signal` (tín hiệu định tuyến), không được phép trực tiếp thay đổi/đột biến (mutation) logic của Skill.
-
----
-
-## Tầm nhìn V8.3+: Enterprise Multi-Agent (Deferred Domains)
-Các lĩnh vực dưới đây được khóa lại và không phát triển trong V8.2:
-1. **Product Management (`qk-product-strategy`)**: Ưu tiên, roadmap, market, user.
-2. **Backend Architecture (`qk-backend-architecture`)**: Phân định service boundary, architecture style, scalability.
-3. **Cloud Architecture (`qk-cloud-architecture`)**: AWS/GCP/Azure, networking, cost.
-4. **AI Engineering (`qk-ai-engineering`)**: Quản trị AI system, LLM architecture, RAG, prompt evaluation.
-
----
-
-## Non-Goals
-V8.2 will NOT:
-- create autonomous skill generation
-- modify stable capabilities automatically
-- replace human architecture review
-- optimize only for usage frequency
-- increase skill count without new decision boundary

package/.agents/docs/V8-CERTIFICATION.md

@@ -1,27 +0,0 @@
-# V8 Certification
-
-V8 preserves validated V7 knowledge while introducing structured retrieval, workflow reuse, verification contracts, and lifecycle management.
-
-Skills:
-22/22 stable
-
-Registry:
-generated
-
-Schema:
-validated
-
-Legacy:
-0
-
-Retrieval tests:
-PASS
-
-Workflow tests:
-PASS
-
-Ambiguity:
-PASS
-
-Migration:
-completed

package/.agents/docs/decisions/ADR-001-v8-migration.md

@@ -1,58 +0,0 @@
-# ADR-001: V8 Architecture Migration Strategy
-
-**Date:** 2026-07  
-**Status:** Accepted  
-**Deciders:** Quang Khánh
-
----
-
-## Context
-
-V7 (7.5.1) had 22 skills, each a monolithic SKILL.md containing:
-- Routing logic
-- Execution workflow
-- Verification steps
-- Rules and policies
-
-This made skills hard to reuse, workflows inconsistent across skills, and AI agents often confused about which skill to choose.
-
----
-
-## Decision
-
-Migrate to V8 **Agent Knowledge System** using **Structured Monolith** approach:
-
-1. **Keep skills** — don't split SKILL.md into multiple files
-2. **Add schema** — new frontmatter fields (intent, triggers, workflow ref, verification)
-3. **Extract workflows** — move execution pipelines to shared `workflows/*.yml`
-4. **Extract rules** — move global policies to `rules/*.md`
-5. **Add registry** — generated `registry/skills-index.yml` for AI retrieval
-
----
-
-## Rationale
-
-**Why not split SKILL.md into separate files?**  
-- Migration cost too high (22 skills × 4 extractions = 88 operations)
-- Risk of losing embedded knowledge in the split
-- Structured Monolith achieves the same retrieval benefit via references
-
-**Why pilot 5 skills first?**  
-- Schema may need adjustment based on real agent behavior
-- Safer to validate on 5 before committing to 22
-
-**Why keep git history instead of `archive/` folder?**  
-- V7.5.1 tagged at git → complete history available
-- Archive folder in repo creates noise for AI agents
-- Clean break is cleaner than carrying historical artifacts
-
----
-
-## Consequences
-
-- ✅ Workflows are now reusable (shared across skills)
-- ✅ AI retrieval is faster (registry index)
-- ✅ Rules are explicit and non-duplicated
-- ✅ Verification is mandatory and standardized
-- ⚠️ New schema requires migration of all 22 skills (3 weeks)
-- ⚠️ `skills.json` is now generated, not authoritative

package/.agents/docs/decisions/ADR-002-workflow-separation.md

@@ -1,50 +0,0 @@
-# ADR-002: Workflow Separation from Skills
-
-**Date:** 2026-07  
-**Status:** Accepted
-
----
-
-## Context
-
-In V7, each SKILL.md contained its own workflow embedded in the body. This meant:
-- Workflow for bug-fixing existed in `qk-bug-resolution/SKILL.md`
-- Similar steps were duplicated across multiple skills
-- No way to reuse or compose workflows
-
----
-
-## Decision
-
-Extract workflows into dedicated `workflows/*.yml` files. Skills reference workflows by name:
-
-```yaml
-# In SKILL.md frontmatter:
-workflow: bug-resolution  # → workflows/bug-resolution.yml
-```
-
-Each workflow step MUST define `inputs` and `outputs` (not just `actions`) so agents understand what a step achieves, not just how to do it.
-
----
-
-## Rationale
-
-**Why YAML instead of Markdown?**  
-- Machine-readable: easier for agents to parse step inputs/outputs
-- Structured: enforces schema compliance
-- If found to be too rigid, can switch to Markdown+frontmatter without breaking skill references
-
-**Why inputs/outputs per step?**  
-- Agents need to know WHAT each step achieves, not just HOW
-- Enables future: step skipping based on already-available outputs
-- Better debugging: "step X failed because output Y was not produced"
-
----
-
-## Consequences
-
-- ✅ Workflows are reusable across skills
-- ✅ Each step has clear contract (inputs → outputs)
-- ✅ Easier to add new skills that reuse existing workflows
-- ⚠️ YAML can be verbose — acceptable tradeoff for clarity
-- ⚠️ If workflow changes, all referencing skills remain valid (they only reference by name)

package/.agents/docs/decisions/ADR-003-registry-generated.md

@@ -1,54 +0,0 @@
-# ADR-003: Registry as Generated Artifact
-
-**Date:** 2026-07  
-**Status:** Accepted
-
----
-
-## Context
-
-V7 had `skills.json` as the primary manifest — manually maintained, often drifting from actual SKILL.md content. This created two sources of truth.
-
-V8 needs a retrieval index for AI agents to find the right skill without reading all 22 SKILL.md files.
-
----
-
-## Decision
-
-`registry/skills-index.yml` is a **generated file**. It is produced by `tooling/generate-registry.js` by reading all `SKILL.md` frontmatter.
-
-`SKILL.md` is the single source of truth. The registry is a derivative.
-
-```
-SKILL.md (source of truth)
-    ↓
-tooling/generate-registry.js
-    ↓
-registry/skills-index.yml (DO NOT EDIT MANUALLY)
-```
-
-`skills.json` is kept as a compatibility manifest for platforms that expect it (e.g., Antigravity v7 convention). It is also generated, not manually maintained.
-
----
-
-## Rationale
-
-**Why not edit the registry manually?**  
-- Two sources of truth always drift
-- Triggers, intent, complexity are already defined in SKILL.md
-- Generator can be run as a pre-commit hook or on demand
-
-**Why keep skills.json?**  
-- Antigravity and some platforms discover skills via `skills.json`
-- Backward compatibility for v7 skill consumers
-- It's generated, so no maintenance burden
-
----
-
-## Consequences
-
-- ✅ Single source of truth: SKILL.md
-- ✅ No drift between skill and registry
-- ✅ Registry update is automatic when skills are updated
-- ⚠️ Requires running generator after any SKILL.md change
-- ⚠️ If generator is not run, registry may be stale (mitigated by pre-commit hook)

package/.agents/docs/decisions/ADR-008-skill-boundary-review.md

@@ -1,27 +0,0 @@
-# ADR 008: Skill Boundary Review (V8.1.3)
-
-## Tiêu đề
-Định hướng tương lai cho ranh giới của `qk-validation-gate` và `qk-ai-builder`.
-
-## Bối cảnh
-Trong quá trình hoàn thiện Agent Engineering OS (V8.1.3), quá trình kiểm toán phát hiện rằng một số skill ban đầu có phạm vi hoạt động (scope) quá rộng hoặc chưa phân vai rõ ràng, dễ dẫn đến conflict. Tuy nhiên, để không làm vỡ kiến trúc (scope creep) trong giai đoạn chốt Control Plane, chúng ta quyết định giữ nguyên nhưng ghi chú định hướng cho V8.2.
-
-## Quyết định
-
-### 1. Về `qk-validation-gate`
-- **Hiện trạng:** Đang đóng vai trò validation coordinator.
-- **Định hướng (V8.2):** Sẽ được định hình rõ thành `release decision orchestrator`.
-- **Ranh giới tương lai:** Không trực tiếp chạy test, không trực tiếp scan security, không audit quality. Nhiệm vụ của nó là tổng hợp kết quả từ `qk-test-engineering`, `qk-security-audit`, và `qk-web-quality-gate` để ra quyết định cuối cùng (gate decision).
-
-### 2. Về `qk-ai-builder`
-- **Hiện trạng:** Đang quá rộng (gồm cả frontend AI apps, general AI coding, prompt writing...).
-- **Định hướng (V8.2):** Đổi tên (rename semantic) thành `qk-agent-platform-engineering`.
-- **Ranh giới tương lai:**
-  - **Owns:** agent architecture, MCP integration, skill generation, agent runtime patterns.
-  - **Does not own:** frontend AI apps, general AI coding, prompt writing.
-
-## Trạng thái
-Đề xuất được chấp nhận (Deferred to V8.2).
-
-## Hệ quả
-Ngăn chặn các kỹ năng này bị phình to trong quá trình triển khai thực tế. Chuẩn bị sẵn sàng cấu trúc cho giai đoạn V8.2 (Self-Improving Agent).