ai-developer-skill-os 9.3.0 → 10.1.0

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

@@ -0,0 +1,321 @@
+---
+name: qk-prompt-compiler
+version: 11.1.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."
+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 v11.1 — 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. 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
+```
+
+---
+
+## 2. 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.
+
+---
+
+## 3. 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)
+```
+
+---
+
+## 4. 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)
+```
+
+---
+
+## 5. 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.
+
+---
+
+## 6. 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."*
+
+---
+
+## 7. 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]
+````
+
+---
+
+## 8. 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]
+```
+
+---
+
+## 9. 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).
+```

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

@@ -0,0 +1,137 @@
+---
+name: qk-ui-engineer
+version: 10.1.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)."
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - coding-standards
+workflow: feature-delivery
+triggers:
+  - "build ui"
+  - "làm giao diện"
+  - "css"
+  - "layout"
+  - "component"
+  - "figma"
+  - "design ui"
+  - "design tokens"
+  - "design system"
+  - "review ui"
+  - "audit giao diện"
+  - "anti-slop"
+  - "lỗi spacing"
+---
+
+# qk-ui-engineer — Build UI & Component (Design Tokens & Anti-Slop Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 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.
+> **Verification Principle:** PASS is a verified conclusion, never a target. Zero visual hacks.
+
+### 🛡️ Anti-Overengineering Rule (CẤM XÉ NHỎ VÔ TỘI VẠ)
+- **Không chia nhỏ quá đà (No micro-splitting):** Tuyệt đối KHÔNG tách một component 70 dòng thành 5 file con (`CardHeader.tsx`, `CardIcon.tsx`, `CardBadge.tsx`, `CardWrapper.tsx`) nếu các phần tử đó chỉ dùng độc quyền trong Card đó. Giữ chúng cùng một file (co-location) để dễ đọc và bảo trì.
+- **Không lạm dụng thư viện animation nặng:** Ưu tiên CSS Transitions thuần túy (`transition: all 150ms ease-in-out`) thay vì tự ý cài đặt thêm các package nặng (Framer Motion, GSAP) nếu yêu cầu chỉ là hover/focus đơn giản.
+
+### 🔒 No Unrelated Changes Rule (CẤM SỬA LAN MAN)
+- Chỉ sửa các component hoặc file style trong phạm vi UI được chỉ định.
+- **CẤM** đổi theme/palette toàn cục nếu chỉ nhận nhiệm vụ sửa 1 component.
+- **CẤM** reformat các file layout/page không liên quan.
+
+### 🛡️ Anti-Fake-Pass Rule (CẤM ÉP PASS ẢO - R-G-14.5)
+- **CẤM** dùng `overflow: hidden` trên `body` hoặc root wrapper để che giấu lỗi vỡ layout / tràn viền ngang.
+- **CẤM** dùng `as any` hoặc `@ts-ignore` để giấu lỗi props mismatch giữa UI và design token variants.
+- **CẤM** bỏ qua contrast ratio bằng cách tự ý làm mờ text cho "nghệ thuật" mà vi phạm WCAG.
+
+### ⚖️ Verify Before Claim Rule (XÁC MINH TRƯỚC KHI BÁO CÁO)
+- **Không tự xưng đạt chuẩn nếu chưa rà soát:** Không tự nhận "Đạt chuẩn WCAG 4.5:1" nếu chưa đối chiếu màu chữ và màu nền theo bảng màu. Không tự nhận "Mobile responsive hoàn hảo" nếu chưa kiểm tra overflow ngang và touch target.
+- **Báo cáo trung thực:** Nếu chưa chạy được browser preview thật, ghi rõ: `"Trạng thái: NOT VERIFIED — Đã kiểm tra tĩnh CSS & Tokens. Khuyến nghị user mở trình duyệt để verify trải nghiệm thị giác"`.
+
+---
+
+## 2. Ranh Giới & Phạm Vi Kỹ Thuật (Hard Boundaries)
+
+### ✅ Việc skill này BẮT BUỘC làm:
+- **Design Token Discipline:** 100% màu sắc, khoảng cách, font-size và border-radius phải lấy từ theme/tokens. Cấm tuyệt đối magic numbers (`#2371e2` trần trụi hoặc `margin: 19px`).
+- **Đầy Đủ Interaction States:** Mọi thành phần tương tác BẮT BUỘC có đủ: `Default`, `Hover`, `Focus-visible` (ring bàn phím rõ ràng), `Active`, `Disabled` (giảm opacity, cursor-not-allowed) và `Loading`.
+- **Responsive Mobile-First:** Không bao giờ để giao diện bị tràn chiều ngang (horizontal overflow) trên màn hình hẹp (< 375px). Touch target tối thiểu 44x44px trên mobile.
+- **Anti-Slop Polish:** Loại bỏ các lỗi thị giác: lệch trục căn chỉnh, nhảy giật layout khi tải ảnh (thiếu `aspect-ratio`), font-size quá nhỏ khó đọc.
+- **Planning Gate & Exceptions:** Nếu tạo component mới kèm design system token ảnh hưởng ≥ 2 files, tạo `implementation_plan.md` với `RequestFeedback: true`. Ngoại lệ: chỉnh sửa CSS/JSX trong 1 component đơn lẻ được bỏ qua planning gate.
+
+### ❌ Việc skill này TUYỆT ĐỐI KHÔNG làm (Chuyển giao quyền):
+- Viết API handler, middleware hay query cơ sở dữ liệu → Chuyển sang `qk-backend-data`.
+- Chạy quét bảo mật OWASP hoặc đo lường sâu hiệu năng Core Web Vitals → Chuyển sang `qk-code-review`.
+
+---
+
+## 3. Quy Trình Kỹ Nghệ Giao Diện 4 Bước (Sequential Procedure)
+
+```
+[Bước 1: Token & Contract]   ── Đọc theme/tokens có sẵn, xác định bảng màu ngữ nghĩa
+            │
+            ▼
+[Bước 2: Component Markup]   ── Viết JSX/HTML với semantic tags, co-locate sub-elements
+            │
+            ▼
+[Bước 3: States & Polish]    ── Thêm Hover, Focus-visible, Loading Skeleton & Transitions
+            │
+            ▼
+[Bước 4: Anti-Slop Audit]    ── Quét 57 tiêu chí: Spacing, Contrast, Typo & Mobile Overflow
+```
+
+### Chi tiết các bước:
+1. **Token & Contract:** Khai báo hoặc tái sử dụng semantic tokens: Primary, Secondary, Surface, Border, Text-primary, Text-muted.
+2. **Component Markup:** Ưu tiên semantic tags (`<button>`, `<nav>`, `<article>`) thay vì lạm dụng `<div>` gắn `onClick`.
+3. **States & Polish:** Đảm bảo khi bấm tab trên bàn phím, vòng focus sáng rõ. Thêm micro-transitions nhẹ nhàng.
+4. **Anti-Slop Audit:** Kiểm tra padding trên/dưới có cân đối không, text trên nền tối/sáng có đủ độ tương phản không.
+
+---
+
+## 4. Xử Lý Sự Cố Giao Diện (Failure Path Protocol)
+
+Nếu giao diện bị vỡ layout hoặc tràn viền ngang:
+1. **Dừng lại ngay:** Không dùng các "hack xấu" như `overflow: hidden` trên toàn trang `<body>` để giấu lỗi tràn viền.
+2. **Truy tìm phần tử gây tràn:** Kiểm tra các phần tử có `width: 100vw`, fixed `width: 600px` hoặc chữ quá dài không có `break-words`.
+3. **Khắc phục sạch sẽ:** Sử dụng `max-w-full`, `flex-wrap`, hoặc `grid-cols-1 md:grid-cols-2`. Nếu không khắc phục được, revert về layout baseline trước đó.
+
+---
+
+## 5. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi làm UI | Hành vi kỹ thuật đặc thù |
+|---|---|---|
+| `frontend` | Component architecture, clean CSS, token mapping, state binding | Tạo reusable atoms/molecules, tách CSS module / Tailwind |
+| `ui/ux` | Visual harmony, whitespace, typography hierarchy, design consistency | Đánh giá tỉ lệ tương phản, nhịp điệu thị giác (visual rhythm) |
+| `fullstack` | UI kết nối thực tế với API data, form validation feedback, skeletons | Hiển thị lỗi form trực quan (inline validation), empty state có CTA |
+| `qa` | Accessibility tags, keyboard navigation, tab order, visual regression | Kiểm tra tab-index, aria attributes, aria-expanded trên dropdown/modal |
+
+---
+
+## 6. Báo Cáo Nghiệm Thu Chuẩn Xác (Truth-First Report)
+
+```markdown
+🎨 UI Engineering Summary                             [Role: <role> | Component: <Tên>]
+─────────────────────────────────────────────────────────────────────
+Trạng thái:          [SUCCESS | BLOCKED | FAILED | PARTIAL]
+Phạm vi thực tế:    [Xây dựng Component mới / Tinh chỉnh Style]
+Công nghệ CSS:      [Tailwind CSS / CSS Modules / Vanilla CSS]
+
+Các tệp giao diện (Laser Focus):
+  • [NEW] [ComponentName.tsx](file:///<workspace-root>/path): [Mô tả vai trò]
+
+Kiểm soát Anti-Slop & Truth-First:
+  • Design Tokens:      ✅ 100% dùng token, 0 magic colors/px
+  • Interaction States: ✅ Đầy đủ Hover, Focus-visible, Disabled
+  • Mobile View:        ✅ Không tràn ngang, touch target ≥ 44px
+  • 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
+```

package/.agents/workflows/feature-delivery.yml

@@ -44,7 +44,7 @@ steps:
     name: "Load context"
     purpose: "Hiểu codebase hiện tại đủ để implement đúng cách"
     required: true
-    skip_if: "Context graph đã có từ qk-context-loader"
+    skip_if: "Context graph đã có từ qk-orchestrator"
     inputs:
       - affected_areas
     outputs:

package/.agents/workflows/production-release.yml

@@ -21,7 +21,7 @@ ide_binding:
 steps:
   - id: gate_1_validation
     name: "Gate 1: Validation Gate"
-    purpose: "Đảm bảo qk-validation-gate đã pass trước khi release"
+    purpose: "Đảm bảo qk-code-review đã pass trước khi release"
     required: true
     skip_if: null
     inputs: []