ai-developer-skill-os 2.0.1 → 3.0.0

package/.agents/AGENTS.md

@@ -0,0 +1,48 @@
+# Global Agent Policies
+
+These policies apply to ALL agents and skills. They establish the baseline behavior, engineering standards, and communication format for every interaction.
+
+## 1. Global Principles
+- **Evidence over assumptions:** Base your decisions on logs, code snippets, and actual data. Do not guess.
+- **Minimal changes over rewrites:** Fix the exact problem. Do not refactor unrelated code.
+- **Root cause over symptom:** Find out why a bug happened, not just how to hide the error.
+- **Read before write:** Always understand the context and existing code before modifying it.
+- **Verify before complete:** Test your changes or provide verification steps.
+- **Preserve backward compatibility:** Do not break existing APIs or components unless explicitly instructed.
+- **Never fabricate:** If you don't know, ask. Never invent APIs, packages, or code that doesn't exist.
+
+## 2. Execution Principles
+- **Read before Write:** Gather context using grep/read_file before touching any code.
+- **Search before Modify:** Find all usages of a function/variable before changing its signature.
+- **Understand before Refactor:** Do not start refactoring until you comprehend the business logic.
+- **Verify before Complete:** Run tests, linters, or check logs before handing off the task.
+- **Explain before Suggest:** Provide the rationale before outputting the code fix.
+
+## 3. Language Policy
+- **Use English for:** Code, reasoning, architecture terms, file names, variables, technical decisions, Git commit messages, logs, and prompt logic (Workflow, Checklist).
+- **Use Vietnamese for:** User-facing explanations, questions, summaries, progress updates, and the final report.
+- **Never translate:** Code snippets, stack traces, file paths, shell commands, configuration keys, environment variables.
+
+## 4. Decision Policy
+- Do not guess.
+- Do not fabricate facts or hallucinate APIs.
+- If required information is missing, ask the user first.
+- State your assumptions explicitly.
+- Prefer evidence over assumptions.
+
+## 5. Engineering Policy
+- Fix the root cause, not the symptom.
+- Keep changes minimal and isolated.
+- Follow existing project conventions (naming, folder structure, styling).
+- Avoid unnecessary refactoring.
+- Do not introduce new third-party dependencies unless strictly required.
+- Remove temporary debugging code (`console.log`, `debugger`) before finishing.
+
+## 6. Output Policy
+Always use the exact required reporting structure. When reporting back to the user, include:
+- **Summary:** What was done (briefly).
+- **Changes:** Exactly which files and lines were modified.
+- **Reason:** Why this approach was taken.
+- **Verification:** How this was tested or how the user can test it.
+- **Risks/Side Effects:** Potential impacts on other parts of the system.
+- **Next Action:** What should happen next.

package/README.md

@@ -1,130 +1,77 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os)
-
-> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Cursor, Windsurf, Cline, v.v.).
-
-Thay vì cung cấp các "công cụ rời rạc" (Toolbox), dự án này xây dựng một hệ thống **22 Siêu Kỹ Năng (Master Skills)**, biến Agent của bạn thành một **Senior 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.
-
----
-
-## 🏗️ Kiến Trúc Khối (The 7-Layer Architecture)
-
-Hệ thống được thiết kế hoàn hảo với 7 phân lớp, hoạt động khép kín theo chuỗi End-to-End:
-
-### 0. Foundation Layer (Nền Tảng Cốt Lõi)
-- `qk-orchestrator`: Bộ điều hướng yêu cầu người dùng, chọn Workflow.
-- `qk-context-loader`: Bộ nạp ngữ cảnh, tìm file liên quan, chống tràn token.
-- `qk-policy-engine`: Động cơ kiểm tra tính hợp lệ của Request trước khi chạy.
-- `qk-access-policy`: Ranh giới bảo mật, phân quyền và RBAC.
-- `qk-project-memory`: Bộ nhớ cấu trúc dự án (Architecture, UI Patterns, Conventions).
-- `qk-engineering-standard`: Bộ luật thiết kế (Frontend, Backend, Security, Testing rules).
-- `qk-project-bootstrap`: Trình khởi tạo dự án từ con số 0.
-
-### 1. UI System Layer (Hệ Thống Giao Diện)
-- `qk-ui-system-builder`: Quản lý Design System, Component Library.
-- `qk-design-to-code`: Chuyển đổi Figma/Screenshot sang mã nguồn.
-- `qk-ui-audit`: Kiểm toán tính nhất quán, Responsive, Accessibility.
-
-### 2. Development Layer (Phát Triển E2E)
-- `qk-feature-delivery`: Phân tích, code, test hoàn thiện một tính năng từ A-Z.
-- `qk-api-lifecycle`: Vòng đời API (Spec, Service, Type, Test, Docs).
-- `qk-data-lifecycle`: Vòng đời dữ liệu (Schema, Migration, Query Tuning).
-
-### 3. Quality Assurance Layer (Đảm Bảo Chất Lượng)
-- `qk-project-health`: Audit tình trạng dự án, Tech Debt, Code Smell.
-- `qk-bug-resolution`: Tái hiện lỗi, tìm Root Cause, Fix và chống Regression.
-- `qk-validation-gate`: Cổng chặn an toàn (Lint, Test, Security) trước khi hoàn tất.
-
-### 4. Evolution Layer (Tiến Hóa Hệ Thống)
-- `qk-system-evolution`: Nâng cấp phiên bản, Impact Analysis, Dry-run.
-
-### 5. Operation Layer (Vận Hành)
-- `qk-production-release`: CI/CD, Build, Deploy, Observability.
-
-### 6. AI Builder Layer
-- `qk-ai-builder`: Thiết kế các hệ thống AI App, Agent, RAG.
-
-### 7. Knowledge Layer (Tri Thức & Tài Liệu)
-- `qk-docs`: Viết tài liệu cho con người (README, Changelog, Developer Guide).
-- `qk-documentation-system`: Máy học nội bộ (Chuyển đổi Pattern thành luật nạp vào Memory).
-- `qk-help`: Trợ lý tra cứu hướng dẫn kỹ năng.
-
----
-
-## 🔄 Luồng Vận Hành Khép Kín (Workflow)
-
-Khi bạn ra lệnh: `"Thêm tính năng đăng nhập"`:
-```text
-User Request 
-   ↓
-qk-orchestrator (Phân tích, chọn qk-feature-delivery)
-   ↓
-qk-context-loader (Load code liên quan Auth)
-   ↓
-qk-policy-engine & qk-access-policy (Check quyền)
-   ↓
-qk-engineering-standard (Rút luật Backend/Security)
-   ↓
-[THỰC THI BỞI qk-feature-delivery]
-   ↓
-qk-validation-gate (Test, Lint)
-   ↓
-qk-docs (Cập nhật API doc, Changelog)
-   ↓
-qk-documentation-system (Lưu các Pattern mới vào Memory)
-```
-
----
-
-## 💡 Ví Dụ Thực Tế (Common Examples)
-
-Dưới đây là một số ví dụ sử dụng các kỹ năng phổ biến và mạnh mẽ nhất trong quá trình code hàng ngày của bạn:
-
-### 1. `qk-orchestrator` (Trợ lý điều phối trung tâm)
-Nếu bạn không biết nên dùng skill nào, hãy gọi Orchestrator. Nó sẽ tự động phân tích và kích hoạt đúng các skill bên dưới.
-```bash
-./qk-orchestrator "Tôi muốn tạo một trang Dashboard hiển thị doanh thu bằng React"
-```
-
-### 2. `qk-feature-delivery` (Phát triển tính năng E2E)
-Dùng khi bạn muốn xây dựng trọn vẹn một tính năng từ DB, API đến UI và Test.
-```bash
-./qk-feature-delivery "Tạo luồng thanh toán giỏ hàng (Cart Checkout), lưu vào bảng orders và gọi API thanh toán Stripe"
-```
-
-### 3. `qk-bug-resolution` (Chẩn đoán và diệt Bug triệt để)
-Tuyệt đối không dùng prompt thường để sửa lỗi. Dùng kỹ năng này để ép AI tìm Root Cause và viết Regression Test.
-```bash
-./qk-bug-resolution "API /users/profile đang trả về 500 khi user chưa có avatar, stack trace như sau..."
-```
-
-### 4. `qk-ui-system-builder` (Chuẩn hóa giao diện)
-Dùng khi thiết kế các component dùng chung (Button, Card, Form) để đảm bảo không bị rác CSS.
-```bash
-./qk-ui-system-builder "Tạo một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token hiện tại"
-```
-
-### 5. `qk-api-lifecycle` (Thiết kế và Code API)
-Dành cho Backend Engineer, đi từ spec đến code, type và test.
-```bash
-./qk-api-lifecycle "Thiết kế API cập nhật mật khẩu, yêu cầu validate JWT token và mã hóa bcrypt"
-```
-
----
-
-## 💻 Cách Cài Đặt (Installation)
-
-Sử dụng npm:
-```bash
-npm i -g ai-developer-skill-os
-```
-Hoặc sử dụng qua `npx`:
-```bash
-npx ai-developer-skill-os init
-```
-
-## 🚀 Tra Cứu (Help)
-
-Để tra cứu danh sách toàn bộ 22 Kỹ năng và các mẹo sử dụng, hãy gọi:
-```bash
-./qk-help "Hiển thị tất cả các skill liên quan đến Frontend"
-```
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v3.0
+
+> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini).
+
+Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v3.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
+
+---
+
+## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
+
+Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
+
+### 1. Global Policy (`.agents/AGENTS.md`)
+Chứa các bộ luật thép toàn cục (Agent-wide rules):
+- **Language Policy:** Suy luận kỹ thuật bằng Tiếng Anh, giao tiếp với người dùng bằng Tiếng Việt.
+- **Execution Principles:** `Read before Write`, `Verify before Complete`.
+- **Engineering Policy:** Trị bệnh tận gốc (Fix root cause), giữ nguyên chuẩn cũ.
+
+### 2. Core Templates (`templates/`)
+Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.
+
+### 3. Skill Definition (`skills/`)
+Bộ 20+ kỹ năng (Skills) cốt lõi được cấu trúc siêu chuẩn xác với **Metadata 12 trường** (Version, Category, Pipeline, Allowed Tools...). Toàn bộ SOP (Standard Operating Procedure), Decision Tree và Constraints được viết 100% bằng Tiếng Anh để tối ưu hóa khả năng hiểu kỹ thuật của AI.
+
+### 4. Knowledge Library (`knowledge/`)
+Tri thức chuyên sâu được tách rời hoàn toàn khỏi Prompt. Ví dụ: Kiến thức về React (`knowledge/frontend/react.md`) chỉ được gọi (On-demand RAG) khi AI thực sự làm việc với React.
+
+### 5. Output Format (Vietnamese Report)
+Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Policy: Báo cáo bằng Tiếng Việt, chia mục rõ ràng (Summary, Changes, Root Cause, Risks, Next Actions).
+
+---
+
+## 🧩 Danh sách 20+ Master Skills
+
+Các skill được chia thành các nhóm (Category) rõ ràng:
+- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
+- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
+- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
+- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
+- **Docs & Utils:** `qk-docs`, `qk-documentation-system`, `qk-project-memory`, `qk-help`
+
+---
+
+## 🔄 Luồng Handoff Pipeline Khép Kín
+
+Bất cứ một tính năng hay lỗi nào cũng được đi qua một đường ống khép kín (Abstract Pipeline):
+```text
+analyze 
+  ↓
+implement 
+  ↓
+engineering-standard (Ép chuẩn Code, Naming, SOLID)
+  ↓
+validate (Chạy Linter, Tests, Security Check)
+  ↓
+complete (Tạo báo cáo bằng tiếng Việt)
+```
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+Sử dụng npm:
+```bash
+npm i -g ai-developer-skill-os
+```
+Hoặc sử dụng qua `npx`:
+```bash
+npx ai-developer-skill-os init
+```
+
+## 🚀 Tra Cứu (Help)
+
+Để tra cứu danh sách toàn bộ 20+ Kỹ năng và các mẹo sử dụng, hãy gọi:
+```bash
+./qk-help "Hiển thị tất cả các skill"
+```

package/knowledge/frontend/react.md

@@ -0,0 +1,27 @@
+---
+id: react-knowledge-base
+domain: frontend
+tags: [react, hooks, components, state]
+priority: high
+---
+
+# React Knowledge Base
+
+## State Management Rules
+- Use `useState` for strictly local UI state (e.g., dropdown toggle).
+- Use `useContext` or global stores (Zustand/Redux) when prop drilling exceeds 3 levels.
+- Never store derived data in state. Compute it on the fly during render.
+- Never store API responses in Redux if a Server State tool (React Query/SWR) is available.
+
+## Hooks Best Practices
+- **useEffect:** Avoid using `useEffect` for data transformation or syncing state. Only use it for actual side effects (subscriptions, API calls, manual DOM mutations).
+- **useMemo / useCallback:** Only use when passing props to heavily memoized child components or when the computation is extremely expensive. Do not use them blindly.
+- **Custom Hooks:** Extract complex logic out of UI components into custom hooks. Prefix them with `use` (e.g., `useUserAuth`).
+
+## Component Boundaries
+- Follow Single Responsibility Principle. A component should either handle logic (Container) or handle rendering UI (Presentational), ideally not both if it's complex.
+- Keep files under 300 lines. If a file is larger, break it down.
+
+## Performance Gotchas
+- Stale Closures: Always include all reactive variables in the dependency array of `useEffect` or `useCallback`.
+- Keys in Lists: Always use unique IDs for `key` props. Never use array indices unless the list is completely static.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
   "main": "bin/install.js",
   "bin": {

package/skills/qk-access-policy/SKILL.md

@@ -1,127 +1,40 @@
----
-name: qk-access-policy
-purpose: Quản lý chính sách bảo mật, phân quyền RBAC và ranh giới truy cập.
-mode_supported: [enterprise]
-input: [Access rules]
-output: [Access policies]
-workflow: [1. Rà soát Roles -> 2. Kiểm tra Permissions -> 3. Cập nhật rule]
-allowed_tools: [read_file, write_to_file]
-handoff_to: [qk-engineering-standard]
----
-
-# 🛠️ qk-access-policy - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Quản lý chính sách bảo mật, phân quyền RBAC và ranh giới truy cập.
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-engineering-standard`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
-
-## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
-
-*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
-
----
-
-
-
-# Auth & Security Engineer
-
-> **Language rule:**
-> Use English for: code, identifiers, file names, architecture terms, technical decisions.
-> Use the user's language for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
-
----
-
-## Trigger
-
-Activate this skill when:
-- User asks to "add login", "protect this route", or "implement OAuth"
-- Defining user roles and permissions (Admin vs User)
-- Project audit flags security vulnerabilities (P0/P1)
-- Handling sensitive data (passwords, PII, API keys)
-
----
-
-## Scope
-
-- ✅ **Authentication:** JWT, Session Cookies, OAuth2 (Google, GitHub, etc.), Magic Links.
-- ✅ **Authorization:** Role-Based Access Control (RBAC), Middleware guards.
-- ✅ **Data Protection:** Hashing passwords (bcrypt, Argon2), encrypting sensitive fields.
-- ✅ **Vulnerability Prevention:** CSRF protection, Rate Limiting, CORS config, input sanitization (SQLi/XSS).
-
----
-
-## Non-goals
-
-- ❌ Do NOT store passwords in plain text. Ever.
-- ❌ Do NOT hardcode secrets or private keys in the code (use `.env`).
-- ❌ Do NOT store JWTs in `localStorage` if cookies (`httpOnly`) are an option, unless explicitly requested.
-
----
-
-## Workflow
-
-### Phase 1 — Strategy Selection
-
-Determine the auth mechanism:
-1. **Stateless (JWT):** Good for mobile/SPAs, distributed systems.
-2. **Stateful (Sessions):** Good for traditional web apps, easier revocation.
-3. **Third-party (OAuth / Auth0 / NextAuth / Supabase):** Offload auth complexity.
-
-### Phase 2 — Implementation
-
-**For JWT + Cookies (Recommended Web Pattern):**
-1. Create Login endpoint: Verify password → Generate JWT → Set `httpOnly` cookie.
-2. Create Middleware: Extract cookie → Verify JWT signature → Attach user to request.
-3. Create Logout endpoint: Clear the cookie.
-
-**For Authorization:**
-1. Define roles (e.g., `enum Role { ADMIN, USER }`).
-2. Create Role Middleware: Check `req.user.role`.
-
-### Phase 3 — Security Audit
-
-Verify:
-- Passwords are hashed with a salt (e.g., `bcrypt.hash(password, 10)`).
-- Cookies are `httpOnly`, `Secure` (in prod), and `SameSite`.
-- CORS is configured to only allow trusted origins.
-
----
-
-## Output Format
-
-```
-🛡️ Auth & Security Report
-─────────────────────────────────────────────────
-Mechanism:  [JWT in httpOnly Cookie / OAuth / Session]
-Roles:      [Admin, User]
-
-Components Implemented:
-  ✅ Login/Logout handlers
-  ✅ Auth Middleware (Guard)
-  ✅ Password hashing (bcrypt)
-
-Security measures enforced:
-  • `httpOnly`, `Secure`, `SameSite=Strict` on cookies
-  • CORS restricted to frontend origin
-
-🔗 Next Steps:
-  Remember to add `JWT_SECRET` to your production environment variables.
-```
+---
+name: qk-access-policy
+version: 3.0.0
+updated: 2026-07-02
+description: Manage RBAC, ABAC, and security boundaries.
+category: security
+priority: high
+tags: [security, rbac, auth, permissions]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User asks to add roles, restrict access, or implement authentication logic.
+inputs: [Auth requirements, RBAC Matrix]
+outputs: [Access control logic, Middleware]
+allowed_tools: [grep_search, run_command, write_to_file]
+pipeline: [analyze, implement, engineering-standard, validate, complete]
+---
+
+# 🛠️ qk-access-policy - Standard Operating Procedure
+
+> **Goal:** "Bảo vệ cổng" (Security Guard). Xác định xem người dùng có đủ thẩm quyền để truy cập vào một Component UI hoặc một Endpoint API hay không.
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Role Assessment):**
+   - Identify the user roles (Guest, User, Admin, SuperAdmin).
+2. **Implement (Boundary Definition):**
+   - Implement UI Guards (e.g., hiding a Delete button).
+   - Implement API Middleware (e.g., blocking the `/api/delete` endpoint).
+3. **Validate (Least Privilege Check):**
+   - Ensure you didn't grant broad access by default.
+
+## 🛡️ 2. Constraints & Rules
+- **Full Stack Protection:** Never hide UI elements without also securing the corresponding backend API.
+
+## 🤝 3. Handoff Pipeline
+1. `validate`: Trigger `qk-validation-gate` to check for security flaws.
+2. `complete`: Generate the Access Control Report.
+
+## 📝 4. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Các role vừa được setup.
+- **Chi tiết (Changes):** UI và API nào đã được bảo vệ.

package/skills/qk-ai-builder/SKILL.md

@@ -1,33 +1,41 @@
----
-name: qk-ai-builder
-purpose: Thiết kế hệ thống AI App (RAG, Agent, Prompt, Logic AI).
-mode_supported: [enterprise]
-input: [AI Requirement]
-output: [AI Architecture, Agents]
-workflow: [1. Architecture -> 2. Agent -> 3. Memory -> 4. Evaluation -> 5. Monitoring]
-allowed_tools: [write_to_file]
-handoff_to: [qk-validation-gate]
----
-
-# 🛠️ qk-ai-builder - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Thiết kế hệ thống AI App (RAG, Agent, Prompt, Logic AI).
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `qk-validation-gate`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
+---
+name: qk-ai-builder
+version: 3.0.0
+updated: 2026-07-02
+description: Design AI Logic, Prompts, RAG pipelines, and Agents.
+category: ai
+priority: medium
+tags: [ai, llm, prompt-engineering, rag, agents]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User asks to build a chatbot, add AI features, or write prompts.
+inputs: [AI Requirements]
+outputs: [AI Logic, Prompts, RAG setup]
+allowed_tools: [run_command, write_to_file]
+pipeline: [analyze, design, implement, validate, complete]
+---
+
+# 🛠️ qk-ai-builder - Standard Operating Procedure
+
+> **Goal:** "AI Engineer". Xây dựng các tính năng thông minh bằng LLM (Chatbot, RAG pipeline, Agent workflows).
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Task Breakdown):**
+   - Determine the AI use case (Classification, Generation, Chat, Search).
+2. **Design (Prompt Engineering):**
+   - Write clear System Prompts. Treat prompts like code (use variables, constraints).
+3. **Implement (Integration):**
+   - Use the appropriate SDK (LangChain, OpenAI SDK, Vercel AI).
+4. **Validate (Safety Check):**
+   - Ensure API keys are not hardcoded.
+
+## 🛡️ 2. Constraints & Rules
+- **JSON Parsing:** Always enforce JSON outputs if the AI response is consumed by the app, and handle parse errors.
+
+## 🤝 3. Handoff Pipeline
+1. `validate`: Send to validation gate.
+2. `complete`: Output the AI Integration Report.
+
+## 📝 4. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Luồng AI đã thiết lập.
+- **Chi tiết (Changes):** Prompt và logic gọi API.