ai-developer-skill-os 8.3.0 → 9.0.0

package/.agents/skills/qk-system-evolution/evals/scorecard.yaml

@@ -0,0 +1,26 @@
+name: qk-system-evolution-eval
+description: Đánh giá độ an toàn của quy trình nâng cấp System & Framework
+version: 9.0.0
+threshold: 90 # Việc nâng cấp framework mang rủi ro sập hệ thống rất cao
+
+metrics:
+  - id: rollback_safety
+    name: Cơ chế Rollback bắt buộc
+    description: Agent có thiết lập và ghi chép lại lệnh rollback trước khi nâng cấp không?
+    weight: 40
+    criteria:
+      - Phải yêu cầu/lưu lại Rollback command (git tag / version trước đó) trước khi sửa code (40đ)
+
+  - id: changelog_awareness
+    name: Phân tích Breaking Changes
+    description: Agent có đọc Changelog thay vì nhắm mắt upgrade không?
+    weight: 35
+    criteria:
+      - Quét và liệt kê các Breaking Changes từ Changelog/Migration Guide trước khi chạy (35đ)
+
+  - id: incremental_upgrade
+    name: Nâng cấp gia tăng (Incremental)
+    description: Có nâng cấp từng phần và chạy test xác minh thay vì Big-bang không?
+    weight: 25
+    criteria:
+      - Chạy test ngay sau khi nâng cấp 1 package thay vì update hàng loạt (25đ)

package/.agents/skills/qk-test-engineering/SKILL.md

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-test-engineering
-version: 8.1.0
+version: 9.0.0
 status: experimental
 description: "Công cụ quyết định chiến lược kiểm thử (Unit, Integration, E2E, Coverage, Regression, Mock)."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: capability
 
 intent:
@@ -129,6 +129,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Convention / Pattern (vd: chiến lược Test Pyramid, mock provider Vitest/Jest, boundary test).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] Có code hoặc requirement rõ ràng cần kiểm thử.
 

package/.agents/skills/qk-test-engineering/capability.yaml

@@ -0,0 +1,28 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-test-engineering"
+version: "9.0.0"
+description: "Công cụ quyết định chiến lược kiểm thử (Unit, Integration, E2E, Coverage, Regression, Mock)."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "qk-test-engineering"
+  references:
+    - "architecture"
+    - "anti-patterns"
+    - "playwright"
+    - "vitest"
+    - "storybook-testing"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "test pyramid"
+    - "coverage strategy"
+    - "regression planning"
+  does_not_own:
+    - "business logic implementation"
+    - "writing tests"
+  conflicts_with: []

package/.agents/skills/qk-test-engineering/evals/scorecard.yaml

@@ -0,0 +1,26 @@
+name: qk-test-engineering-eval
+description: Đánh giá tư duy Chiến lược Kiểm thử (Test Strategy)
+version: 9.0.0
+threshold: 85 # Đảm bảo tư vấn chiến lược rõ ràng và bao quát rủi ro
+
+metrics:
+  - id: pyramid_strategy
+    name: Chiến lược Test Pyramid
+    description: Chiến lược có phân bổ hợp lý giữa Unit, Integration và E2E không?
+    weight: 35
+    criteria:
+      - Phân tách rõ ràng loại test nào dùng cho logic nào thay vì bắt viết E2E cho mọi thứ (35đ)
+
+  - id: boundary_testing_r_sec_04
+    name: Negative & Boundary Testing (R-SEC-04)
+    description: Có bao phủ các test cases ranh giới để ngăn chặn tấn công/lỗi dữ liệu không?
+    weight: 35
+    criteria:
+      - Bắt buộc đưa ra các test case biên (Boundary) và trường hợp lỗi (Negative tests) (35đ)
+
+  - id: mocking_strategy
+    name: Chiến lược Mock/Stub
+    description: Có tư vấn rõ ràng khi nào nên Mock và khi nào dùng Database thật không?
+    weight: 30
+    criteria:
+      - Phân biệt rõ việc Mock API bên thứ ba vs Integration DB nội bộ (30đ)

package/.agents/skills/qk-ui-audit/SKILL.md

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-ui-audit
-version: 8.0.0
+version: 9.0.0
 status: stable
 description: "Kiểm toán giao diện (UI) với 57-check Anti-Slop checklist — fail nếu score < 76/85 base."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: utility
 
 intent:
@@ -85,6 +85,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Convention / Pattern (vd: 57 check Anti-Slop, độ tương phản A11y, Design Contract).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Các mẫu lỗi AI-Slop phổ biến mới phát hiện trong UI dự án.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Lỗi lệch vài pixel hoặc sai color shade lẻ tẻ.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Các mẫu lỗi AI-Slop phổ biến mới phát hiện trong UI dự án.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Lỗi lệch vài pixel hoặc sai color shade lẻ tẻ.
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] `DESIGN.md` exists in project root
 - [ ] Target UI file(s) or component(s) are specified

package/.agents/skills/qk-ui-audit/capability.yaml

@@ -0,0 +1,23 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-ui-audit"
+version: "9.0.0"
+description: "Kiểm toán giao diện (UI) với 57-check Anti-Slop checklist — fail nếu score < 76/85 base."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "ui-standards"
+    - "anti-slop"
+  references:
+    - "design-system"
+    - "security"
+    - "anti-patterns"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "qk-ui-audit"
+  does_not_own: []
+  conflicts_with: []

package/.agents/skills/qk-ui-audit/evals/scorecard.yaml

@@ -0,0 +1,26 @@
+name: qk-ui-audit-eval
+description: Đánh giá khả năng rà soát UI Anti-Slop
+version: 9.0.0
+threshold: 90 # Đóng vai trò chốt chặn UI chất lượng cao, không khoan nhượng với Slop
+
+metrics:
+  - id: design_contract_compliance
+    name: Tuân thủ Hợp đồng Thiết kế (DESIGN.md)
+    description: Có bắt lỗi chính xác các giá trị hardcode không nằm trong Design Tokens không?
+    weight: 40
+    criteria:
+      - Tìm và đánh dấu các mã màu hex, px hardcode vi phạm token của DESIGN.md (40đ)
+
+  - id: anti_slop_detection
+    name: Nhận diện AI-Slop (Generic aesthetics)
+    description: Có phát hiện được các thiết kế chung chung, xám xịt, viền nhạt nhòa không?
+    weight: 30
+    criteria:
+      - Trừ điểm nặng các thẻ card thiếu chiều sâu, text quá nhỏ, hoặc thiếu hover state (30đ)
+
+  - id: accessibility_check
+    name: Kiểm tra Trải nghiệm Tiếp cận (A11y)
+    description: Có rà soát các thẻ ARIA, độ tương phản và Semantic HTML không?
+    weight: 30
+    criteria:
+      - Cảnh báo các element tương tác (button, link) thiếu roles, alt text hoặc độ tương phản < 4.5:1 (30đ)

package/.agents/skills/qk-ui-builder/capability.yaml

@@ -0,0 +1,29 @@
+schema_version: 1
+id: "qk-ui-builder"
+version: "9.0.0"
+description: "Xây dựng, sửa, audit, và học UI — từ Figma/ảnh, map API, fix bug UI, đến redesign cấu trúc."
+dependencies:
+  - "feature-delivery"
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "ui-implementation"
+    - "component-patterns"
+    - "design-system-integration"
+  references:
+    - "design-system"
+    - "architecture"
+    - "accessibility"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "ui-component-implementation"
+    - "design-token-application"
+  does_not_own:
+    - "visual-direction"
+    - "brand-identity"
+  conflicts_with: []
+  delegates_to: []

package/.agents/skills/qk-ui-builder/evals/scorecard.yaml

@@ -0,0 +1,26 @@
+name: qk-ui-builder-eval
+description: Đánh giá việc thiết kế và xây dựng giao diện người dùng (UI)
+version: 9.0.0
+threshold: 85 # Đảm bảo giao diện hiện đại, chuẩn token và thẩm mỹ cao
+
+metrics:
+  - id: design_token_compliance
+    name: Tuân thủ Design Token (DESIGN.md)
+    description: Code sinh ra có sử dụng chuẩn token màu sắc và kích thước của hệ thống không?
+    weight: 45
+    criteria:
+      - Tuyệt đối sử dụng các biến CSS từ hợp đồng thiết kế, không dùng màu vô danh giá trị cứng (45đ)
+
+  - id: modern_rich_aesthetics
+    name: Thẩm mỹ hiện đại (Anti-Slop)
+    description: Giao diện có sinh động, tinh tế và loại bỏ cảm giác AI sơ sài không?
+    weight: 30
+    criteria:
+      - Sử dụng tráng gương, hover effect và bố cục rõ rệt, không làm giao diện đơn điệu (30đ)
+
+  - id: component_reusability
+    name: Tính tái sử dụng và tinh gọn
+    description: Cấu trúc component có gọn gàng và dễ mở rộng trong tương lai không?
+    weight: 25
+    criteria:
+      - Chia nhỏ logic sang custom hooks hoặc sub-components hợp lý (25đ)

package/.agents/skills/qk-ui-system-builder/SKILL.md

@@ -1,12 +1,12 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-ui-system-builder
-version: 8.0.0
+version: 9.0.0
 status: stable
 description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
-# ── V8: Classification ─────────────────────────────────────
+# ── V9: Classification ─────────────────────────────────────
 type: capability
 
 intent:
@@ -97,6 +97,136 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 
 ---
 
+## Memory Workflow
+
+### Pre-flight Retrieve (Trước khi thực thi)
+- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
+  bắt buộc tra cứu:
+  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
+  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
+
+- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
+  - Architecture
+  - Hard Bug
+  - Convention
+  - Pattern
+  - Tech Debt Pattern
+  - 👉 *Domain Focus:* Architecture / Convention (vd: ánh xạ 1:1 từ contract DESIGN.md sang biến CSS).
+
+- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
+  Không được xem Memory là Source of Truth.
+  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
+
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+
+### Learning Flow (AI tự học có kiểm soát)
+- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
+  - Hard Bug có khả năng tái diễn.
+  - Pattern làm việc lặp lại trong dự án.
+  - Convention hoặc quy tắc kiến trúc mới.
+  - Quyết định Architecture quan trọng.
+  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
+  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
+
+- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
+- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
+- AI không được tự động Promote Candidate Memory thành Project Knowledge.
+
+---
+
+### Post-flight Harvest (Đề xuất → Phê duyệt)
+Sau khi hoàn thành task:
+- AI đánh giá các Candidate Memory đã tạo.
+- Nếu phát hiện tri thức có giá trị tái sử dụng:
+  - Đề xuất người dùng xem xét.
+  - Gửi yêu cầu phê duyệt thông qua:
+    - `/learn`
+    - `qk-project-memory`
+- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
+
+```
+.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
+```
+
+- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
+  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
+
+---
+
+### Ignore (Không đưa vào Memory)
+Không lưu:
+- Trace log của một session đơn lẻ.
+- Temporary debugging data.
+- Output của một lần chạy test/scan.
+- Report health tạm thời của một đợt kiểm tra.
+- Lỗi nhỏ chỉ xảy ra một lần.
+- Thông tin không có khả năng tái sử dụng.
+- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
+
+---
+
+### Golden Rule
+> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
+> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
+
+---
+---
+---
+---
+
 ## Preconditions
 - [ ] `DESIGN.md` exists with color, spacing, typography tokens
 

package/.agents/skills/qk-ui-system-builder/capability.yaml

@@ -0,0 +1,25 @@
+# Auto-generated from SKILL.md frontmatter
+schema_version: 1
+id: "qk-ui-system-builder"
+version: "9.0.0"
+description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract."
+tools:
+  - "filesystem"
+  - "terminal"
+knowledge:
+  owns:
+    - "design-tokens"
+    - "ui-system"
+  references:
+    - "design-system"
+eval:
+  scorecard: "evals/scorecard.yaml"
+decision_boundary:
+  owns:
+    - "tokens"
+    - "ui-system"
+  does_not_own:
+    - "page implementation"
+    - "visual direction"
+  conflicts_with:
+    - "qk-design-system-engineering"