ai-developer-skill-os 10.1.0 → 10.2.0

package/.agents/skills/qk-product-spec/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-product-spec
-version: 10.1.0
+version: 10.2.0
 status: stable
 subtitle: "Viết Spec & PRD"
 description: "Chuyển hóa ý tưởng sơ khai thành đặc tả kỹ thuật chuẩn mực: PRD, Acceptance Criteria (BDD Given/When/Then), Gap Analysis và Đánh giá tính khả thi. Dùng khi: viết spec, viết PRD, phân tích yêu cầu, acceptance criteria, user story, bdd, gherkin, gap analysis, feasibility, đánh giá rủi ro, clarify requirements — TUYỆT ĐỐI KHÔNG dùng để trực tiếp viết code tính năng (dùng qk-feature-delivery)."
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
 tools:
   - filesystem
 rules:
@@ -29,6 +31,83 @@ triggers:
 
 ---
 
+## Memory Workflow
+
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### 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:
+  - `.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
+
+- 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.
+
+- 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)──>  .ai-local/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.
+
+---
+
+### 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.**
+
+---
+
 ## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
 
 > **Core Principle:** Right-size the specification. Do not write a 20-page enterprise PRD for a 10-line UI tweak. Scale the spec depth proportionally to the project risk and complexity.
@@ -111,3 +190,73 @@ Tiêu chí nghiệm thu cốt lõi (BDD Gherkin):
   Đã khởi tạo artifact: [implementation_plan.md](file:///C:/Users/qkhanh/.gemini/antigravity-ide/brain/f7ef21b2-6e3e-4177-a422-5ddcad5a5843/implementation_plan.md)
   👉 Hãy xem lại kế hoạch và bấm [Proceed] để bắt đầu viết code.
 ```
+
+---
+
+## 6. Mô Hình Độ Tin Cậy (Confidence Model)
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct evidence available | Proceed |
+| MEDIUM | Some assumptions needed | Note assumptions |
+| LOW | Insufficient evidence | EXIT: BLOCKED |
+
+---
+
+## 7. Thoái Ra Mã (Exit Codes)
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Task completed and verified | All acceptance criteria met |
+| PARTIAL | Task done with minor gaps | Some checks skipped |
+| BLOCKED | Missing precondition or info | Ask user |
+| FAILED | Task failed after max retries | Report error |
+
+---
+
+## 8. Bằng Chứng Định Dạng (Evidence Format)
+
+```
+[SEVERITY] path/to/file.ts:LINE
+Reason:     [why this matters]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [suggestion]
+```
+
+---
+
+## Platform-Specific Instructions
+
+### Antigravity (Google Gemini)
+- Uses `.agents/AGENTS.md` as entry point
+- Supports Cockpit integration
+- Rewrite absolute paths for global mode
+- `GEMINI.md` copied for global installs
+
+### Claude Code (Anthropic)
+- Reads `.claude/CLAUDE.md` automatically
+- Large context window (~200K tokens)
+- Can handle full skill files without trimming
+- Uses native tool format (Read, Write, Edit, Bash)
+
+### OpenCode (Open Source)
+- Reads `.opencode/config.yaml`
+- Context window ~128K tokens
+- Keep skill files lean when possible
+- Supports custom tool format
+
+---
+
+## Compliance
+
+| Check | Status |
+|-------|--------|
+| Runtime Standard | 11/11 |
+| Frontmatter Complete | ✅ |
+| Platforms Field | ✅ |
+| References Valid | ✅ |
+| Decision Trees | PASS |
+| Thresholds Defined | PASS |
+| schema_version | 10.2.0 |
+| runtime_version | 1 |
+| platforms | [antigravity, claude, opencode] |

package/.agents/skills/qk-prompt-compiler/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: qk-prompt-compiler
-version: 11.1.0
+version: 10.2.0
 status: stable
 subtitle: "Cổng Kiểm Soát Hành Vi & Biên Dịch Prompt (Control Plane & Behavioral Gate)"
 description: "Cổng kiểm soát hành vi (Control Plane / Behavioral Gate): Chuyển hóa câu lệnh tự nhiên thành Compiled Execution Prompt minh bạch, bóc tách Prompt Delta, áp dụng 4 lớp cổng chặn (Prompt Quality Gate, Risk Gate R0-R4, Change Budget Gate, Scope Expansion Gate, Evidence Gate CLAIM <= EVIDENCE), quyết định 3 chế độ thực thi (AUTO / CONFIRM / ASK) trước khi đụng vào code. Dùng khi: viết prompt, compile prompt, viết lại prompt, chuẩn hóa prompt, prompt compiler, tối ưu prompt, prompt delta, intent gate."
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
 tools:
   - filesystem
   - terminal
@@ -23,11 +25,11 @@ triggers:
   - "prompt rulebook"
 ---
 
-# qk-prompt-compiler v11.1 — Control Plane & Behavioral Gate
+# qk-prompt-compiler v10.2 — Control Plane & Behavioral Gate
 
 > **Core Principle:**
 > User speaks naturally. AI converts the request into an explicit, reviewable Execution Prompt before execution.
-> 
+>
 > **Core Maxims:**
 > 1. `AI MUST NEVER INCREASE THE USER'S INTENDED SCOPE SILENTLY.`
 > 2. `The AI may increase implementation detail, but must never silently increase business scope, behavioral scope, architectural scope, security scope, data scope, or change budget.`
@@ -36,64 +38,93 @@ triggers:
 
 ---
 
-## 1. Kiến Trúc Toàn Diện Control Plane
+## 1. Nguyên Tắc Cốt Lõi & Kiểm Soát Hành Vi (Core Maxims)
+
+> **Core Principle:** User speaks naturally. AI converts the request into an explicit, reviewable Execution Prompt before execution.
+> **Anti-Sprawl Principle:** AI MUST NEVER increase the user's intended scope silently. Implementation detail may increase; business scope, behavioral scope, architectural scope, security scope, data scope, and change budget must NOT.
+> **Evidence Principle:** CLAIM LEVEL <= EVIDENCE LEVEL. Never claim VERIFIED without executing the actual command.
+
+### 🛡️ Anti-Overengineering Rule (CẤM TẠO GIA TRỊ GIẢ)
+- **CẤM** tạo compiled prompt phức tạp cho request đơn giản (L0-L1). Compiled Prompt chỉ cần 3-5 thành phần cho task nhỏ.
+- **CẤM** auto-increase scope trong khi biên dịch prompt. User nói "fix login" → không tự động mở rộng thành "fix login + sửa database + update UI".
+- **Ưu tiên minimal compiled prompt**: 3 fields (Objective, Scope, Constraints) cho L0-L1, đầy đủ 9 fields cho L3-L4.
+
+### 🔒 Change Budget Enforcement (R-G-14.5)
+- **Hard cap files**: Maximum 5 files changed per compiled prompt execution.
+- **Zero new dependencies by default**: Cấm tự ý `npm install` thêm package nếu chưa hỏi user.
+- **API contract frozen**: Không đổi API contract trừ khi request explicitly yêu cầu thiết kế API mới.
+- **Database schema protected**: Không đổi schema/migration trừ khi request explicit.
+
+### ⚖️ Evidence Gate (R-G-14.7)
+- **VERIFIED**: Đã chạy lệnh test/build thực tế + exit code 0. Bằng chứng: lệnh + kết quả.
+- **PARTIALLY VERIFIED**: Đã kiểm tra tĩnh (tsc, lint) PASS. Chưa chạy integration test.
+- **UNVERIFIED**: Chỉ đọc code. CẤM ghi "100% fixed" hoặc "All green".
+
+### 🚨 Scope Expansion Gate (CẤM BẠCH TRỞ PHẠM VI)
+- **STOP ngay** khi phát hiện scope thực tế vượt Compiled Scope.
+- **Report Scope Expansion** với: ban đầu → mới phát hiện → lý do → rủi ro tăng.
+- **Recompile & CONFIRM** trước khi chạm vào file mới.
+
+---
+
+## 2. Kiến Trúc Toàn Diện Control Plane
 
 ```text
-                    USER REQUEST (Câu lệnh tự nhiên thô)
-                         │
-                         ▼
-                  ┌─────────────┐
-                  │ UNDERSTAND  │ ──► Nhận diện mục tiêu cốt lõi (Actual Goal)
-                  └──────┬──────┘
-                         ▼
-                  ┌─────────────┐
-                  │ INTERPRET   │ ──► Ánh xạ vào Context & DEV_PROFILE.md
-                  └──────┬──────┘
-                         ▼
-                  ┌─────────────┐
-                  │   COMPILE   │ ──► Sinh Compiled Execution Prompt (9 thành phần)
-                  └──────┬──────┘
-                         ▼
-              ┌──────────────────────┐
-              │ PROMPT QUALITY GATE  │ ──► Kiểm tra đủ 8 tiêu chí hợp đồng
-              └──────────┬───────────┘
-                         ▼
-              ┌──────────────────────┐
-              │  SCOPE / RISK GATE   │ ──► Đánh giá Complexity (L0–L4) & Risk (R0–R4)
-              └──────────┬───────────┘
-                         ▼
-              ┌──────────────────────┐
-              │ CHANGE BUDGET GATE   │ ──► Khóa ngân sách: Files, Deps, API, DB
-              └──────────┬───────────┘
-                         ▼
-                  ┌─────────────┐
-                  │ SHOW DELTA   │ ──► Công khai: User Said vs Inferred vs Not Assumed
-                  └──────┬──────┘
-                         ▼
-              ┌──────────────────────┐
-              │ AUTO / CONFIRM / ASK │ ──► Quyết định chế độ hành động
-              └──────────┬───────────┘
-                         ▼
-                      EXECUTE
-                         │
-                         ▼
-                  SCOPE EXPANSION?
-                    /          \
-                  NO            YES
-                  │              │
-                  ▼              ▼
-               VALIDATE       STOP EXPANSION + RECOMPILE + CONFIRM
-                  │
-                  ▼
-              EVIDENCE GATE (CLAIM LEVEL <= EVIDENCE LEVEL)
-                  │
-                  ▼
-             EXECUTION REPORT
+                     USER REQUEST (Câu lệnh tự nhiên thô)
+                          │
+                          ▼
+                   ┌─────────────┐
+                   │ UNDERSTAND  │ ──► Nhận diện mục tiêu cốt lõi (Actual Goal)
+                   └──────┬──────┘
+                          ▼
+                   ┌─────────────┐
+                   │ INTERPRET   │ ──► Ánh xạ vào Context & DEV_PROFILE.md
+                   └──────┬──────┘
+                          ▼
+                   ┌─────────────┐
+                   │   COMPILE   │ ──► Sinh Compiled Execution Prompt (9 thành phần)
+                   └──────┬──────┘
+                          ▼
+               ┌──────────────────────┐
+               │ PROMPT QUALITY GATE  │ ──► Kiểm tra đủ 8 tiêu chí hợp đồng
+               └──────────┬───────────┘
+                          ▼
+               ┌──────────────────────┐
+               │  SCOPE / RISK GATE   │ ──► Đánh giá Complexity (L0–L4) & Risk (R0–R4)
+               └──────────┬───────────┘
+                          ▼
+               ┌──────────────────────┐
+               │ CHANGE BUDGET GATE   │ ──► Khóa ngân sách: Files, Deps, API, DB
+               └──────────┬───────────┘
+                          ▼
+                   ┌─────────────┐
+                   │ SHOW DELTA   │ ──► Công khai: User Said vs Inferred vs Not Assumed
+                   └──────┬──────┘
+                          ▼
+               ┌──────────────────────┐
+               │ AUTO / CONFIRM / ASK │ ──► Quyết định chế độ hành động
+               └──────────┬───────────┘
+                          ▼
+                       EXECUTE
+                          │
+                          ▼
+                   SCOPE EXPANSION?
+                     /          \
+                   NO            YES
+                   │              │
+                   ▼              ▼
+                VALIDATE       STOP EXPANSION + RECOMPILE + CONFIRM
+                   │
+                   ▼
+               EVIDENCE GATE (CLAIM LEVEL <= EVIDENCE LEVEL)
+                   │
+                   ▼
+              EXECUTION REPORT
 ```
 
 ---
 
-## 2. Thứ Bậc Ngữ Cảnh Hóa Biên Dịch (Context-Aware Compilation Hierarchy)
+## 3. Thứ Bậc Ngữ Cảnh Hóa Biên Dịch (Context-Aware Compilation Hierarchy)
 
 Để không gây hiểu lầm rằng "User Request có độ ưu tiên thấp nhất", hệ thống quy định phân tầng nhận thức rõ ràng:
 
@@ -118,12 +149,12 @@ EXECUTION PLAN   ◄── [QUY CHUẨN KỸ THUẬT & RANH GIỚI BẢO VỆ (H
 ```
 
 > [!IMPORTANT]
-> **User Requirement** luôn là nguồn sự thật duy nhất xác định **Mục tiêu bạn muốn làm gì (WHAT)**.  
+> **User Requirement** luôn là nguồn sự thật duy nhất xác định **Mục tiêu bạn muốn làm gì (WHAT)**.
 > Các tầng Rules, Profile và Codebase bên trên quyết định **Cách AI được phép thực hiện an toàn (HOW & CONSTRAINTS)** để không phá vỡ dự án.
 
 ---
 
-## 3. Phân Cấp Phức Tạp & Rủi Ro (Complexity vs Risk Gate)
+## 4. Phân Cấp Phức Tạp & Rủi Ro (Complexity vs Risk Gate)
 
 > **Nguyên tắc vàng:** `Complexity ≠ Risk`. Một thay đổi 1 dòng trong file cấu hình Production (`L1`) có thể mang rủi ro chí mạng (`R4`). Do đó, hai trục này phải được đánh giá độc lập:
 
@@ -153,7 +184,7 @@ IF thiếu thông tin / intent mơ hồ        ──► BẮT BUỘC ASK (Hỏi
 
 ---
 
-## 4. Ngân Sách Thay Đổi (Change Budget Gate)
+## 5. Ngân Sách Thay Đổi (Change Budget Gate)
 
 AI không chỉ được biết *được phép sửa gì*, mà phải bị khóa chặt *được phép sửa nhiều đến đâu*:
 
@@ -194,9 +225,9 @@ CHỜ USER DUYỆT (CONFIRM)
 
 ---
 
-## 5. Cổng Chặn Bành Trướng Phạm Vi (Scope Expansion Gate)
+## 6. Cổng Chặn Bành Trưởng Phạm Vi (Scope Expansion Gate)
 
-> **Chống hiện tượng "AI càng làm càng lan":**  
+> **Chống hiện tượng "AI càng làm càng lan":**
 > Ví dụ: Bạn yêu cầu `"fix bug login"`, AI ban đầu xác định chỉ sửa `LoginForm.tsx`. Nhưng khi inspect phát hiện lỗi do `LoginForm.tsx → auth.ts → api-client.ts → backend middleware`.
 
 **Quy tắc:** AI **TUYỆT ĐỐI KHÔNG ĐƯỢC TỰ Ý MỞ RỘNG SCOPE ÂM THẦM**.
@@ -212,7 +243,7 @@ Khi phát hiện scope thực tế vượt quá Compiled Scope:
 
 ---
 
-## 6. Cổng Bằng Chứng Khẳng Định (Evidence Gate)
+## 7. Cổng Bằng Chứng Khẳng Định (Evidence Gate)
 
 ```text
 NGUYÊN TẮC THÉP:
@@ -234,11 +265,11 @@ AI phân loại trạng thái nghiệm thu thành 3 cấp bậc rõ ràng:
 3. **`UNVERIFIED` (Chưa chứng minh):**
    - Chỉ mới đọc code hoặc sửa code mà môi trường không có test tự động.
    - **CẤM TUYỆT ĐỐI** ghi: "Đã fix xong 100%", "All green".
-   - BẮT BUỘC ghi rõ: *"Trạng thái: NOT VERIFIED — Đã sửa logic dựa trên code inspection. Cần người dùng kiểm thử thủ công."*
+   - **BẮT BUỘC** ghi rõ: *"Trạng thái: NOT VERIFIED — Đã sửa logic dựa trên code inspection. Cần người dùng kiểm thử thủ công."*
 
 ---
 
-## 7. Khung Hiển Thị Mặc Định (Default UI Block với Prompt Delta & Budget)
+## 8. Khung Hiển Thị Mặc Định (Default UI Block với Prompt Delta & Budget)
 
 Khi bạn đưa ra yêu cầu, AI mở đầu câu trả lời bằng cấu trúc minh bạch sau:
 
@@ -289,7 +320,7 @@ Acceptance Criteria:
 
 ---
 
-## 8. Báo Cáo Nghiệm Thu Thực Thi (Execution Report)
+## 9. Báo Cáo Nghiệm Thu Thực Thi (Execution Report)
 
 Sau khi hoàn tất công việc:
 
@@ -314,8 +345,100 @@ Sau khi hoàn tất công việc:
 
 ---
 
-## 9. Quy Tắc Vàng Hệ Thống (System Golden Rule)
+## 10. Quy Tắc Vàng Hệ Thống (System Golden Rule)
 
 ```text
 Before executing a non-trivial task, convert the user's natural-language request into an explicit, reviewable Execution Prompt, show the interpretation, assumptions, Prompt Delta and Change Budget, select AUTO/CONFIRM/ASK, enforce Scope Expansion Gates during execution, and report results strictly bounded by the Evidence Gate (CLAIM LEVEL <= EVIDENCE LEVEL).
 ```
+
+---
+
+## 11. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi compile prompt | Hành vi đặc thù |
+|---|---|---|
+| `frontend` | UI component changes, CSS, interaction | Compile with design-token constraints |
+| `backend` | API, database, service logic | Compile with Zod/Pydantic schemas |
+| `fullstack` | End-to-end feature | Compile with contract-first approach |
+| `devops` | Infrastructure, CI/CD, deployment | Compile with safety gates |
+| `qa` | Test, validation, verification | Compile with test-first approach |
+
+---
+
+## 12. Mô Hình Độ Tin Cậy (Confidence Model)
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Compiled prompt executed with all gates PASS | Report as VERIFIED |
+| MEDIUM | Scope expansion detected but within budget | Report with delta |
+| LOW | Gates failed or cannot verify | EXIT: BLOCKED or FAILED |
+
+---
+
+## 13. Bằng Chứng Định Dạng (Evidence Format)
+
+```
+[SEVERITY] scope: [compiled-scope-id]
+Claim Level: [VERIFIED|PARTIALLY VERIFIED|UNVERIFIED]
+Evidence:   [command executed + exit code]
+Delta:      [what AI added vs what user said]
+Confidence: [HIGH|MEDIUM|LOW]
+```
+
+**Example:**
+```
+[VERIFIED] scope: L2-bugfix-login
+Claim Level: VERIFIED
+Evidence:   npm test auth.test.ts → PASS (12/12)
+Delta:      User said "fix login" → AI added token refresh logic
+Confidence: HIGH
+```
+
+---
+
+## 14. Thoái Ra Mã (Exit Codes)
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Compiled prompt executed, all gates passed | Evidence gate PASS |
+| PARTIAL | Executed but scope expanded or partial verification | Scope expansion detected |
+| BLOCKED | Intent unclear or missing required context | ASK mode triggered |
+| FAILED | Gates failed or scope violation detected | Evidence gate FAIL |
+
+---
+
+## Platform-Specific Instructions
+
+### Antigravity (Google Gemini)
+- Uses `.agents/AGENTS.md` as entry point
+- Supports Cockpit integration
+- Rewrite absolute paths for global mode
+- `GEMINI.md` copied for global installs
+
+### Claude Code (Anthropic)
+- Reads `.claude/CLAUDE.md` automatically
+- Large context window (~200K tokens)
+- Can handle full skill files without trimming
+- Uses native tool format (Read, Write, Edit, Bash)
+
+### OpenCode (Open Source)
+- Reads `.opencode/config.yaml`
+- Context window ~128K tokens
+- Keep skill files lean when possible
+- Supports custom tool format
+
+---
+
+## Compliance
+
+| Check | Status |
+|-------|--------|
+| Runtime Standard | 11/11 |
+| Frontmatter Complete | ✅ |
+| Platforms Field | ✅ |
+| References Valid | ✅ |
+| Decision Trees | PASS |
+| Thresholds Defined | PASS |
+| schema_version | 10.2.0 |
+| runtime_version | 1 |
+| platforms | [antigravity, claude, opencode] |

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

@@ -1,9 +1,11 @@
 ---
 name: qk-ui-engineer
-version: 10.1.0
+version: 10.2.0
 status: stable
 subtitle: "Build UI & Component"
 description: "Kỹ sư Giao diện & Design System toàn diện: Xây dựng Design Tokens, phát triển UI Components responsive đầy đủ interaction states, và kiểm toán 57 tiêu chí Anti-Slop UI. Dùng khi: build ui, làm giao diện, css, layout, component, figma, design tokens, token library, design system, variants, review ui, audit giao diện, lỗi spacing — TUYỆT ĐỐI KHÔNG dùng khi viết API/Database (dùng qk-backend-data) hoặc đo lường SEO/Web Vitals sâu (dùng qk-code-review)."
+platforms: [antigravity, claude, opencode]
+runtime_version: 1
 tools:
   - filesystem
   - terminal
@@ -33,6 +35,83 @@ triggers:
 
 ---
 
+## Memory Workflow
+
+### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
+- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
+  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
+  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
+
+---
+
+### 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:
+  - `.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
+
+- 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.
+
+- 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)──>  .ai-local/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.
+
+---
+
+### 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.**
+
+---
+
 ## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
 
 > **Core Principle:** Co-locate tightly coupled UI elements. Do not over-modularize simple components into micro-files. A beautiful UI is disciplined in its tokens and clean in its markup.
@@ -135,3 +214,73 @@ Kiểm soát Anti-Slop & Truth-First:
   • Visual Verification: [Đã verify qua browser / NOT VERIFIED (Cần user test mắt)]
   • Zero Hack:          ✅ Không dùng overflow: hidden trên body, không ép kiểu props
 ```
+
+---
+
+## 7. Mô Hình Độ Tin Cậy (Confidence Model)
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct evidence available | Proceed |
+| MEDIUM | Some assumptions needed | Note assumptions |
+| LOW | Insufficient evidence | EXIT: BLOCKED |
+
+---
+
+## 8. Thoái Ra Mã (Exit Codes)
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Task completed and verified | All acceptance criteria met |
+| PARTIAL | Task done with minor gaps | Some checks skipped |
+| BLOCKED | Missing precondition or info | Ask user |
+| FAILED | Task failed after max retries | Report error |
+
+---
+
+## 9. Bằng Chứng Định Dạng (Evidence Format)
+
+```
+[SEVERITY] path/to/file.ts:LINE
+Reason:     [why this matters]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [suggestion]
+```
+
+---
+
+## Platform-Specific Instructions
+
+### Antigravity (Google Gemini)
+- Uses `.agents/AGENTS.md` as entry point
+- Supports Cockpit integration
+- Rewrite absolute paths for global mode
+- `GEMINI.md` copied for global installs
+
+### Claude Code (Anthropic)
+- Reads `.claude/CLAUDE.md` automatically
+- Large context window (~200K tokens)
+- Can handle full skill files without trimming
+- Uses native tool format (Read, Write, Edit, Bash)
+
+### OpenCode (Open Source)
+- Reads `.opencode/config.yaml`
+- Context window ~128K tokens
+- Keep skill files lean when possible
+- Supports custom tool format
+
+---
+
+## Compliance
+
+| Check | Status |
+|-------|--------|
+| Runtime Standard | 11/11 |
+| Frontmatter Complete | ✅ |
+| Platforms Field | ✅ |
+| References Valid | ✅ |
+| Decision Trees | PASS |
+| Thresholds Defined | PASS |
+| schema_version | 10.2.0 |
+| runtime_version | 1 |
+| platforms | [antigravity, claude, opencode] |