ai-developer-skill-os 9.3.1 → 10.2.0

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

@@ -0,0 +1,444 @@
+---
+name: qk-prompt-compiler
+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
+rules:
+  - global
+  - prompt-compiler
+workflow: prompt-compilation
+triggers:
+  - "viết prompt"
+  - "compile prompt"
+  - "viết lại prompt"
+  - "chuẩn hóa prompt"
+  - "prompt compiler"
+  - "tối ưu prompt"
+  - "prompt delta"
+  - "control plane"
+  - "prompt rulebook"
+---
+
+# 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.`
+>
+> Language rule: Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 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
+```
+
+---
+
+## 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:
+
+```text
+SYSTEM / PLATFORM RULES
+        ↓
+PROJECT RULES
+        ↓
+GLOBAL RULES
+        ↓
+RELEVANT SKILL
+        ↓
+PROJECT CONTEXT / DEV_PROFILE.md
+        ↓
+EXISTING ARCHITECTURE & CODE
+        ↓
+USER REQUIREMENT ◄── [NGUỒN CHÍNH XÁC ĐỊNH MỤC TIÊU CỐT LÕI (WHAT)]
+        ↓
+AI INTERPRETATION
+        ↓
+EXECUTION PLAN   ◄── [QUY CHUẨN KỸ THUẬT & RANH GIỚI BẢO VỆ (HOW & BOUNDARIES)]
+```
+
+> [!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)**.
+> 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.
+
+---
+
+## 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:
+
+### Trục Phức Tạp (Complexity Levels)
+- **L0 — Trivial:** Sửa lỗi chính tả, format markdown, giải thích lý thuyết.
+- **L1 — Simple:** Sửa 1 hàm nhỏ, tinh chỉnh CSS cục bộ của 1 component.
+- **L2 — Normal:** Bug logic thông thường, thêm 1 endpoint/hook trong module hiện tại.
+- **L3 — Complex:** Tính năng liên tầng (FE + BE), tái cấu trúc module, tích hợp luồng dữ liệu mới.
+- **L4 — High Architecture:** Thiết kế lại kiến trúc, phân tách service, thay đổi flow toàn hệ thống.
+
+### Trục Rủi Ro (Risk Levels)
+- **R0 — Safe:** Thao tác chỉ đọc (Read-only), audit mã nguồn, viết tài liệu, đo lường.
+- **R1 — Low:** Thay đổi nhỏ, local UI, dễ dàng rollback trong vài giây, không side-effect.
+- **R2 — Medium:** Logic nghiệp vụ, sửa hàm/tiện ích dùng chung, có nguy cơ hồi quy (regression).
+- **R3 — High:** Sửa đổi liên tầng, thay đổi API contract, database schema migration, cấu hình CI/CD.
+- **R4 — Critical:** Thao tác phá hủy (destructive: DROP, TRUNCATE, DELETE), bảo mật/auth, dữ liệu Production.
+
+### Ma Trận Quyết Định Chế Độ Thực Thi (Mode Selection Matrix)
+
+```text
+IF Complexity >= L3                     ──► Minimum CONFIRM
+IF Risk >= R2                           ──► Minimum CONFIRM
+IF Risk >= R3                           ──► CONFIRM + Explicit Risk Report
+IF destructive / auth / production data  ──► BẮT BUỘC CONFIRM (Chờ duyệt [Proceed])
+IF thiếu thông tin / intent mơ hồ        ──► BẮT BUỘC ASK (Hỏi lại, không đoán)
+```
+
+---
+
+## 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*:
+
+```text
+CHANGE BUDGET QUY ĐỊNH:
+
+Files:
+  - Kỳ vọng (Expected): 1–3 files
+  - Tối đa (Maximum): 5 files (trừ khi user chỉ định rõ ràng)
+
+Dependencies:
+  - Mặc định: 0 new dependencies (CẤM tự ý npm install thêm package nếu chưa hỏi)
+
+API:
+  - Không thay đổi API Contract (trừ khi yêu cầu là thiết kế API mới)
+
+Database:
+  - Không thay đổi schema / migration (trừ khi yêu cầu là sửa database)
+
+Architecture:
+  - Tuyệt đối không tự ý rewrite kiến trúc
+
+Behavior:
+  - Chỉ thay đổi đúng behavior mà câu lệnh yêu cầu, giữ nguyên mọi luồng khác
+```
+
+### Xử Lý Khi Vượt Budget:
+Nếu trong quá trình làm, AI phát hiện cần sửa > 5 files hoặc phải thêm thư viện:
+```text
+STOP NGAY LẬP TỨC
+      ↓
+BÁO CÁO VƯỢT BUDGET (Lý do vì sao cần mở rộng)
+      ↓
+RECOMPILE PROMPT MỚI
+      ↓
+CHỜ USER DUYỆT (CONFIRM)
+```
+
+---
+
+## 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":**
+> 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**.
+
+Khi phát hiện scope thực tế vượt quá Compiled Scope:
+1. **STOP EXPANSION:** Dừng ngay việc can thiệp vào các file mới phát sinh.
+2. **Báo cáo mở rộng phạm vi (Scope Expansion Report):**
+   - *Phạm vi ban đầu:* `LoginForm.tsx`
+   - *Phụ thuộc mới phát hiện:* `auth.ts`, `backend middleware`
+   - *Nguyên nhân kỹ thuật:* Vì sao bắt buộc phải sửa xuyên tầng.
+   - *Đánh giá rủi ro:* Mức độ rủi ro tăng từ `R1` lên `R3`.
+3. **Recompile & Confirm:** Trình bày Compiled Prompt mới và chờ bạn xác nhận trước khi chạm vào backend.
+
+---
+
+## 7. Cổng Bằng Chứng Khẳng Định (Evidence Gate)
+
+```text
+NGUYÊN TẮC THÉP:
+CLAIM LEVEL <= EVIDENCE LEVEL
+(Mức độ khẳng định của AI KHÔNG ĐƯỢC vượt quá bằng chứng thực tế thu thập được)
+```
+
+AI phân loại trạng thái nghiệm thu thành 3 cấp bậc rõ ràng:
+
+1. **`VERIFIED` (Đã chứng minh):**
+   - Đã chạy lệnh test/build thực tế trong terminal và kết quả PASS.
+   - Bằng chứng: Tên lệnh test + mã exit code 0 + log pass.
+
+2. **`PARTIALLY VERIFIED` (Chứng minh một phần):**
+   - Đã kiểm tra tĩnh (Static analysis, `tsc --noEmit`, linting) PASS.
+   - Chưa chạy integration test hoặc chưa test trực tiếp trên browser/API thật.
+   - Báo cáo rõ: *"Đã pass kiểm tra kiểu và cú pháp. Cần test luồng thực tế."*
+
+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."*
+
+---
+
+## 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:
+
+````markdown
+## 🧠 1. Tôi hiểu yêu cầu
+[1–2 câu tóm tắt chính xác mục tiêu kỹ thuật thực sự của bạn]
+
+## 📝 2. Prompt tôi sẽ dùng (Compiled Execution Prompt)
+```text
+Role: <vai trò chuyên trách trong DEV_PROFILE.md: fe | be | fullstack | data | ai-engineer | devops | qa>
+Objective: <mục tiêu kỹ thuật đo lường được, định nghĩa rõ "DONE = ?">
+Context: <stack công nghệ & module liên quan từ DEV_PROFILE.md và codebase>
+Source of Truth: <thứ tự ưu tiên: file cung cấp > DB/API thực tế > code hiện tại>
+Scope:
+  - IN-SCOPE: <files/hàm/component cụ thể được phép sửa>
+  - OUT-OF-SCOPE: <phần bất biến tuyệt đối không được đụng vào>
+Constraints: <Minimal Safe Change, YAGNI, không phá vỡ API/DB hiện có, zero fake pass>
+Process: <các bước logic tối giản>
+Acceptance Criteria:
+  - [ ] <Tiêu chí kiểm chứng được 1>
+  - [ ] <Tiêu chí kiểm chứng được 2>
+```
+
+## 🔍 3. Prompt Delta (Tôi đã diễn giải thêm)
+
+### User đã yêu cầu:
+- [Ý chính hoặc nguyên văn câu lệnh ngắn bạn đưa]
+
+### AI suy luận từ context:
+- [Những điểm kỹ thuật AI bổ sung dựa trên mã nguồn thực tế]
+
+### AI KHÔNG tự giả định:
+- [Những ranh giới AI tự khóa lại: không rewrite, không đổi DB, không sửa lan man]
+
+## 📊 4. Đánh Giá Rủi Ro & Ngân Sách Thay Đổi (Risk & Budget)
+- **Độ phức tạp / Rủi ro:** `L[0-4]` / `R[0-4]` — [Đánh giá ngắn]
+- **Ngân sách file (Change Budget):** Tối đa [N] files (`path/to/file1`, `path/to/file2`)
+- **Dependencies mới:** 0 package
+
+## 📋 5. Các bước thực hiện
+1. [Khảo sát call-flow]
+2. [Thực thi tối thiểu an toàn]
+3. [Xác minh theo Evidence Gate]
+
+## ⚡ 6. Execution Mode
+**[ AUTO | CONFIRM | ASK ]** — [Lý do lựa chọn mode dựa trên ma trận Risk & Complexity]
+````
+
+---
+
+## 9. Báo Cáo Nghiệm Thu Thực Thi (Execution Report)
+
+Sau khi hoàn tất công việc:
+
+```markdown
+## ✅ Báo Cáo Thực Thi (Execution Report)
+
+### 1. Scope & Budget Đối Chiếu
+- Files dự kiến: [N files] | Files thực tế sửa: [N files] ──► [Trong Budget / Vượt Budget]
+- Dependencies mới: 0
+
+### 2. Chi Tiết Thay Đổi
+- `path/to/file1.ts`: Sửa logic root cause tại hàm `handleAuth`
+- `path/to/file2.tsx`: Cập nhật UI loading state
+
+### 3. Bằng Chứng Nghiệm Thu (Evidence Gate)
+- **Claim Level:** [ VERIFIED | PARTIALLY VERIFIED | UNVERIFIED ]
+- **Evidence:** [Lệnh test đã chạy / Cú pháp tsc / Static inspection]
+
+### 4. Rủi Ro Còn Lại & Hướng Dẫn Test Tay
+- [Chỉ rõ cho người dùng cách verify thực tế trên trình duyệt/terminal]
+```
+
+---
+
+## 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] |