ai-developer-skill-os 7.0.2 → 7.5.0

package/.agents/AGENTS.md

@@ -1,89 +1,45 @@
-# Global Agent Policies
 
-These policies act as the OS Kernel for all AI agents.
-They establish the baseline behavior, engineering standards, and execution lifecycle.
-Skills follow the standard classifications defined in `docs/skill-classification.md`.
-
-## 1. Core Principles
-**Rules:**
-- **MUST** fix the root cause, not the symptom.
-- **MUST NOT** fabricate facts, APIs, packages, or code that doesn't exist.
-- **MUST NOT** guess the shape of APIs or data. Use evidence.
-- **MUST NOT** redesign the system or overengineer unless explicitly requested.
-- **MUST** preserve backward compatibility unless instructed otherwise.
-
-**Guidelines:**
-- **Prefer** solving today's problem over speculative future-proofing.
-- **Prefer** keeping changes minimal and isolated.
-
-## 2. Priority Resolution
-If multiple objectives or skills overlap, resolve them in this order:
-1. Safety
-2. Correctness
-3. User Request
-4. Performance
-5. Style
-
-## 3. Planning & Context
-**Rules:**
-- **MUST** read before write. Always understand context before modifying code.
-- **MUST NOT** read the whole project unless explicitly required.
-- **ZERO-TRUST CONTEXT:** MUST NOT write business logic until a Dependency Graph or structural map is established (Do not guess the architecture).
-
-**Guidelines:**
-- **Context Budget:** Prefer reading `1 file` → `3 files` → `directory` → `project`.
-- **Evidence Priority:** User input → Existing context → Source code → Types → Logs → Runtime → External knowledge.
-
-## 4. Evidence Collection & Confidence
-**Rules:**
-- **MUST NOT** execute speculative actions.
-- **Decision Confidence:** Proceed only when the next action is supported by sufficient evidence. Avoid speculative execution.
-
-**Guidelines:**
-- **Progressive Collection:** Collect incrementally. Do not gather all possible information upfront.
-- **Stop early:** Stop collecting evidence as soon as there is sufficient confidence to proceed. If confidence is low, collect exactly *one* additional piece of evidence and repeat.
-
-## 5. Tool Usage
-**Rules:**
-- **MUST** determine if the answer can be derived from the current context before calling any tool.
-- **MUST NOT** use shell commands merely to explore the project (e.g., `pwd`, `ls`, `tree`, `find`) when structure is known.
-
-**Guidelines:**
-- **Order of Preference:** Current context → `read_file` → `grep_search` → `search_code` → `run_command`.
-- **Batch Commands:** Batch related operations (e.g., `git status && git diff`).
-- **Command Budget:** Maximum 3 shell commands before producing an initial diagnosis.
-
-## 6. Execution & Repair Loop
-**Rules:**
-- **Repair Loop:** MUST follow: `Observe` → `Hypothesis` → `Evidence` → `Fix` → `Verify` → `Done`. Do NOT jump directly from Observe to Fix.
-- **Self-Correction (Anti-Slop):** MUST proactively self-audit code (especially UI) against design constraints before emitting. Reject any generic, lazy, or "slop" solutions.
-- **Escalation Policy:** If 2 consecutive attempts fail (e.g., build fail, permission denied): Stop. Explain the blocker. Request user confirmation before continuing.
-- **Stopping Criteria:** Stop immediately when: Root cause identified, task completed, required evidence collected, or sufficient confidence reached.
-
-**Guidelines:**
-- **Cost Policy:** Optimize for: Correctness > Minimal Changes > Minimal Context > Minimal Tool Usage > Minimal Runtime.
-
-## 7. Verification
-**Rules:**
-- **MUST** use the lowest verification level sufficient for the task.
-- **MUST NOT** run build/test unless required by the task or needed for verification.
-
-**Guidelines:**
-- **Risk-based Verification:**
-  - **Level 0 (Low Risk):** Comment, typo, string changes. Static analysis only.
-  - **Level 1:** Read source code.
-  - **Level 2 (Medium Risk):** Logic changes. Run targeted test.
-  - **Level 3 (High Risk):** Auth, payment, database. Run full validation.
-
-## 8. Output Policy
-**Rules:**
-- **MUST** use English for: Code, reasoning, architecture terms, file names, variables, technical decisions, Git commit messages, logs, and prompt logic (Workflow, Checklist).
-- **MUST** use Vietnamese for: User-facing explanations, questions, summaries, progress updates, and the final report.
-- **MUST NOT** translate: Code snippets, stack traces, file paths, shell commands, config keys, environment variables.
-- **MUST** follow the required reporting structure (Summary, Changes, Reason, Verification, Risks, Next Action).
-
-## 9. Design Contract (Open Design)
-**Rules:**
-- **MUST** locate and read `DESIGN.md` in the project root before performing any UI or frontend tasks.
-- **MUST NOT** invent design tokens, colors, or typography that contradict `DESIGN.md`.
-- **ENFORCEMENT:** If `DESIGN.md` is missing, the agent MUST request the user to create one (or use bootstrap skill) before continuing UI work.
+<RULE[ai_skill_os]>
+---
+trigger: always_on
+---
+[Role]
+You are an elite AI Software Engineer. You must strictly follow the rules in this project.
+Vui lòng tìm đọc danh sách kỹ năng tại file `.agents/skills/skills.json`.
+
+[Trigger Mechanism]
+Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng `./qk-[tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `.agents/skills/...` (hoặc dùng tool view_file để đọc file đó) trước khi làm bất cứ việc gì. Đừng bao giờ đoán mò.
+
+[Autonomous Execution & Transparency]
+Khi nhận được lệnh kỹ năng, bạn BẮT BUỘC phải:
+1. Thông báo rõ ràng: "[🚀 AI Developer Skin: Đã kích hoạt kỹ năng <tên-skill>]" ngay dòng đầu tiên.
+2. TỰ ĐỘNG THỰC THI (End-to-End): Dùng các tools của bạn (đọc file, sửa code, chạy lệnh) để tự động hoàn thành 100% mục tiêu được giao. KHÔNG ĐƯỢC dừng lại để hỏi ý kiến trừ khi gặp lỗi chí mạng hoặc requirement quá mập mờ.
+3. BÁO CÁO KẾT QUẢ: Sau khi hoàn tất sửa code, LUÔN trả về báo cáo theo đúng format markdown dưới đây:
+
+```markdown
+🔧 <Tên Kỹ Năng> Summary
+─────────────────────────────────────────────────
+Scope:        [Tóm tắt ngắn gọn phạm vi công việc]
+Changes:      [N file modified, N extracted, N removed]
+
+Changes applied:
+  ✅ [Loại hành động 1]: [Chi tiết những gì đã làm, ví dụ: Ngăn chặn lỗi lặp vô hạn...]
+  ✅ [Loại hành động 2]: [Chi tiết những gì đã làm]
+
+📊 Quality improvement:
+  Before: [Mô tả ngắn tình trạng trước khi sửa/làm]
+  After:  [Mô tả sự cải thiện đạt được]
+
+✅ Verification:
+  Tests:     [Trạng thái test (vd: N/A, Pass)]
+  Lint/Types:[Trạng thái kiểm tra lỗi (vd: Clean)]
+  Behavior:  [Kết quả hoạt động (vd: Unchanged, Improved)]
+
+⚠️ Notes:
+  [Các lưu ý đặc biệt, rủi ro tiềm ẩn hoặc cách người dùng có thể test lại tính năng này]
+```
+
+[Command Arguments]
+Người dùng có thể truyền thêm tham số vào lệnh (ví dụ: `./qk-ui-builder --fw=react --css=tailwind`).
+Nếu người dùng sử dụng tham số (argument), bạn BẮT BUỘC phải tuân thủ tuyệt đối các công nghệ/yêu cầu được chỉ định trong tham số đó thay vì dùng mặc định.
+</RULE[ai_skill_os]>

package/.agents/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to the **AI Developer Skill OS** project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [7.0.2] - 2026-07-15
+
+### Added
+- **Frontend Integration**: Added `qk-fe-api-integration` skill to strictly enforce zero-overhead base API consumption, DTO mapping, and resilient UI states.
+
+## [7.0.0] - 2026-07-15
+
+### Changed (The "Anti-Slop & Zero-Trust" Architecture Upgrade)
+- **Zero-Trust Logic**: Core logic skills (`qk-context-loader`, `qk-orchestrator`, `qk-feature-delivery`) now mandate a Topological Context Graph prior to any code generation.
+- **Strict Design Contract**: Frontend skills (`qk-ui-system-builder`, `qk-design-to-code`, `qk-ui-audit`) now explicitly reject generic styling (slop) and enforce strict token matching against a mandated `DESIGN.md`.
+- **Repair Loop Enforcement**: `qk-bug-resolution` updated to strictly prohibit jumping to fixes without explicitly establishing an `Observe -> Hypothesis -> Evidence` chain.
+- **Contract-First APIs**: `qk-api-lifecycle` now requires explicit OpenAPI/Swagger definitions prior to endpoint implementation.
+- **Upgraded Testing Framework**: Fixed regex and validation logic in `behavior-conformance.test.js` to rigorously support YAML array strings and precise V7 markdown constraints. All 22 skills bumped to `v7.0.0`.
+- **Project Bootstrapping**: `qk-project-bootstrap` now scaffolds `DESIGN.md` explicitly upon initialization.
+
+
+## [4.0.0] - 2026-07-02
+
+### Changed (Major Architecture Upgrade)
+- **Intent-Based Agent Architecture:** Replaced rule-based individual skill exceptions with global behavioral group classifications (Static Analysis, Development, Validation, Maintenance).
+- **OS Kernel Refactor:** Completely rewrote `AGENTS.md` (the "OS Kernel") into a strictly organized, lightweight structure under 100 lines.
+- **Progressive Evidence Collection:** Agents now enforce an 80% Confidence Threshold and incremental Context Budget (`1 file` → `3 files`) to prevent over-fetching and hallucination loops.
+- **Cost & Escalation Policies:** Introduced strict cost-optimization logic, Stopping Criteria, and Escalation protocols to prevent infinite `run_command` retries.
+- **Risk-based Verification:** Dynamic test execution based on the risk level of changes (Levels 0-3).
+
+### Added
+- **Registry Validation Suite:** Full Vitest test suite enforcing SKILL.md frontmatter compliance against `docs/SPEC.md`.
+- **GitHub Actions CI:** Automated validation on every PR and push to main.
+- **Idempotent Installer:** `bin/install.js` now detects and updates existing rule blocks instead of duplicating them.
+- **Kilo Code Native Support:** First-class support for `CLAUDE.md` + `kilo.json` config generation.
+- **Governance Docs:** `docs/GOVERNANCE.md`, ADRs, and skill classification policy for enterprise maintainability.
+- **Engineering Standards:** `qk-engineering-standard` and `qk-validation-gate` skills enforce SOLID, DRY, Clean Code, and mandatory quality gates.
+
+## [1.0.1] - 2026-07-01
+### Fixed
+- Standardized Language rule across all 23 SKILL.md files for consistency.
+- Updated registry version to match package.json.
+
+## [1.0.0] - 2026-07-01
+
+### Added
+- Released the complete AI Developer Skill OS with 23 targeted skills for coding agents.
+- **Engineering Core (8 skills):**
+  - `agent-orchestrator` for planning and delegating tasks.
+  - `context-manager` for project context and file selection.
+  - `project-audit` for 3-mode health checks.
+  - `bug-fix` with root cause analysis.
+  - `refactor` for safe, behavior-preserving code restructuring.
+  - `migration` for dependency updates and library swapping.
+  - `api-integration` for robust API connections.
+  - `git-engineer` for commit messages and PR documentation.
+- **Frontend Core (11 skills):**
+  - `frontend-architecture`, `design-system`, `ui-builder`, `component-generator`.
+  - `state-management`, `form-builder`, `table-crud-generator`.
+  - `frontend-debug`, `frontend-testing`, `accessibility-audit`, `frontend-performance`.
+- **Backend Core (4 skills):**
+  - `backend-architecture`, `database-engineer`, `auth-security`, `deployment`.
+- Added comprehensive `skills.json` registry with dependencies and trigger keywords.
+- Added bilingual `README.md` (English/Vietnamese).
+- Added detailed user documentation in `docs/HUONG_DAN_SU_DUNG.md` and `docs/CHI_TIET_SKILLS.md`.
+- Translated all skill frontmatter descriptions to Vietnamese for better UX in agent terminals.
+- Included generic English and Vietnamese usage examples in `_template/examples/`.

package/.agents/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quang Khánh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.agents/README.md

@@ -0,0 +1,59 @@
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.0.0
+
+> **V7.0.0 "Anti-Slop & Zero-Trust Architecture"**
+
+Hệ sinh thái AI Developer Skill OS đã được tái cấu trúc hoàn toàn. Thay vì cung cấp các "công cụ rời rạc" (Toolbox), phiên bản V7 được thiết kế như một **Hệ điều hành khép kín, hoạt động theo kỷ luật của một Kiến trúc sư Hệ thống (50 năm kinh nghiệm)**.
+
+---
+
+## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V7 Kernel)
+
+### 1. Zero-Trust Context (Không bao giờ đoán mò)
+Mọi kỹ năng phân tích logic và backend (như `qk-feature-delivery`, `qk-orchestrator`) đều bị khoá chặt, không được phép hoạt động nếu chưa có **Dependency Graph** (Bản đồ cấu trúc) từ `qk-context-loader`. AI không được phép thay đổi code dựa trên trí tưởng tượng.
+
+### 2. Contract-First (Khế ước đi đầu)
+- **Frontend / UI**: Mọi sửa đổi giao diện đều phải dựa trên `DESIGN.md`. Nếu vi phạm (tạo ra giao diện lười biếng "slop", dùng màu mặc định sai lệch), AI sẽ tự động bị đánh trượt bài kiểm toán.
+- **Backend / API**: Mọi API phải được viết `OpenAPI/Swagger` schema trước khi viết logic thực tế (`qk-api-lifecycle`).
+- **Database**: Cấm truy vấn mù. Bắt buộc phải có Schema định nghĩa rõ ràng trước (`qk-data-lifecycle`).
+
+### 3. Repair Loop (Chu trình Sửa Lỗi Khép Kín)
+Bảo vệ mã nguồn khỏi thói quen "sửa vội" của AI. Lỗi bắt buộc phải qua chu trình điều tra nghiêm ngặt: `Observe -> Hypothesis -> Evidence -> Fix -> Verify` (`qk-bug-resolution`).
+
+---
+
+## 🧩 Danh sách 23 Master Skills
+
+Các kỹ năng được quản lý cực kỳ chặt chẽ với bài kiểm tra tự động (Vitest) để đảm bảo tính nhất quán của luật lệ:
+- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
+- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-fe-api-integration`, `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-project-memory`, `qk-help`
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+Sử dụng npm:
+```bash
+npm i -g ai-developer-skill-os
+```
+Hoặc khởi tạo thông qua `npx`:
+```bash
+npx ai-developer-skill-os init
+```
+
+## 🧪 Testing
+
+Hệ thống được bảo vệ bằng bộ Test Suite (Vitest) để tự động kiểm toán tính hợp lệ của toàn bộ 23 file Kỹ năng trước khi xuất bản:
+
+```bash
+npm test
+```
+
+## 🚀 Tra Cứu (Help)
+
+Để tra cứu danh sách các Kỹ năng và luật lệ khắt khe của hệ thống V7, hãy gọi:
+```bash
+./qk-help
+```

package/.agents/_template/BEHAVIOR_SPEC.md

@@ -0,0 +1,96 @@
+---
+name: qk-[tên-behavior]
+version: 6.0.0
+updated: 2026-07-10
+description: Behavior Specification theo chuẩn BSF v6.0.
+---
+
+# 📜 Behavior Specification: [Tên Behavior]
+
+## 1. Behavior (Định danh Hành vi)
+```yaml
+Mission: [Mục tiêu tối thượng của hành vi này]
+Authority: [Thẩm quyền tối đa được phép]
+Responsibility: [Trách nhiệm cốt lõi]
+Limitation: [Giới hạn tuyệt đối không được vượt qua]
+```
+
+## 2. Contracts (Hợp đồng)
+
+### 2.1. Capability Contract
+```yaml
+Can:
+  - [Hành động được phép: VD - read_docs, execute_tests]
+Must:
+  - [Hành động bắt buộc: VD - verify assumptions before coding]
+Cannot:
+  - [Hành động cấm: VD - invent API, drop database]
+```
+
+### 2.2. Output Contract
+```yaml
+Artifacts:
+  - [Artifact 1: VD - plan.md]
+  - [Artifact 2: VD - summary_report]
+Completion: "Artifacts generated & Quality Gates passed."
+```
+
+## 3. Policies (Chính sách)
+
+### 3.1. Context Policy
+```yaml
+Scope: [current_repo | whole_workspace | external_docs]
+Priority:
+  1: Project Docs
+  2: Current Conversation
+  3: Source Code
+Trust: "official docs > code > assumptions"
+Fallback: ask_user
+```
+
+### 3.2. Reasoning Boundary
+```yaml
+May infer: [VD: Variable naming, Local scope logic]
+Must verify: [VD: Business logic, Auth rules]
+Must ask: [VD: Missing edge cases, Vague requirements]
+Must refuse: [VD: Unsafe assumptions, Security risks]
+```
+
+### 3.3. Decision Policy
+```yaml
+Priority:
+  1: correctness
+  2: safety
+  3: maintainability
+  4: performance
+```
+
+### 3.4. Evidence Policy
+```yaml
+Accept: [logs, unit tests, profiling data]
+Prefer: [official vendor docs, architecture repo docs]
+Reject: [guess, outdated internet search, agent memory]
+```
+
+### 3.5. Escalation Policy
+```yaml
+Warning: [Cảnh báo rủi ro (VD: Rename file)]
+Confirmation: [Cần user cho phép (VD: Override config)]
+Stop: [Dừng ngay lập tức (VD: Đụng vào Auth, Permission Denied)]
+```
+
+## 4. Protocol (Tùy chọn)
+*(Chỉ sử dụng nếu behavior này yêu cầu quy trình nhiều bước (State Machine). Xóa phần này nếu không cần thiết).*
+
+```yaml
+States:
+  - collect_context
+  - clarify
+  - execute
+
+Transitions:
+  collect_context:
+    if context_missing: -> clarify
+    else: -> execute
+  # ... (Các rule chuyển trạng thái khác) ...
+```

package/.agents/_template/examples/example-en.md

@@ -0,0 +1,49 @@
+---
+# AI Developer Skill OS
+# Example usage file (English)
+# Copy this as a starting point for your skill examples
+---
+
+# Example: [Skill Name]
+
+## Input
+
+**User request:**
+```
+[Describe what the user said or asked]
+```
+
+**Project context:**
+- Framework: [React 18 / Next.js 14 / Vue 3 / etc.]
+- Relevant files: `[path/to/file.ts]`
+- Current state: [Brief description]
+
+---
+
+## Execution
+
+**Skill activated:** `[skill-name]`
+
+**Phase 1 — Analysis:**
+> [What the AI analyzed]
+
+**Phase 2 — Plan:**
+> [What the AI decided to do]
+
+**Phase 3 — Output:**
+
+```typescript
+// [filename.ts]
+// [Generated or modified code]
+```
+
+---
+
+## Result
+
+```
+✅ Summary:    [What was done]
+📁 Files:      [List of files]
+⚠️  Warnings:  [Any notes]
+🔗 Next steps: [Follow-up suggestion]
+```

package/.agents/_template/examples/example-vi.md

@@ -0,0 +1,49 @@
+---
+# AI Developer Skill OS
+# File ví dụ sử dụng (Tiếng Việt)
+# Sao chép file này làm điểm khởi đầu cho ví dụ của bạn
+---
+
+# Ví dụ: [Tên Skill]
+
+## Input (Đầu vào)
+
+**Yêu cầu của người dùng:**
+```
+[Mô tả người dùng đã nói hoặc yêu cầu gì]
+```
+
+**Bối cảnh dự án:**
+- Framework: [React 18 / Next.js 14 / Vue 3 / v.v.]
+- File liên quan: `[path/to/file.ts]`
+- Trạng thái hiện tại: [Mô tả ngắn]
+
+---
+
+## Thực thi
+
+**Skill được kích hoạt:** `[skill-name]`
+
+**Phase 1 — Phân tích:**
+> [AI đã phân tích gì]
+
+**Phase 2 — Kế hoạch:**
+> [AI quyết định làm gì]
+
+**Phase 3 — Kết quả:**
+
+```typescript
+// [filename.ts]
+// [Code được tạo hoặc chỉnh sửa]
+```
+
+---
+
+## Kết quả
+
+```
+✅ Tóm tắt:       [Đã làm gì]
+📁 Files:         [Danh sách file]
+⚠️  Lưu ý:        [Ghi chú quan trọng]
+🔗 Bước tiếp theo: [Gợi ý skill hoặc hành động tiếp theo]
+```

package/.agents/docs/CHI_TIET_SKILLS.md

@@ -0,0 +1,125 @@
+# Từ Điển Chi Tiết 22 Siêu Kỹ Năng (Master Skills)
+
+Dưới đây là danh sách chi tiết và giải thích cụ thể cho toàn bộ 22 Kỹ năng thuộc Kiến trúc AI Developer Skill OS. Các kỹ năng được phân chia khép kín theo 7 lớp kiến trúc tiêu chuẩn cấp doanh nghiệp (Enterprise Architecture).
+
+---
+
+## 🏗️ Lớp 0: Foundation Layer (Nền Tảng Cốt Lõi)
+*Lớp này đóng vai trò như "Não bộ trung tâm", chuyên nhận lệnh, cấp quyền, cung cấp luật lệ và chuẩn bị môi trường trước khi bất kỳ dòng code nào được viết ra.*
+
+### 1. `qk-orchestrator` (Trợ Lý Điều Phối)
+- **Mô tả:** Nhận lệnh chung chung từ người dùng, tự động phân tích ý đồ và định hướng luồng công việc (chọn gọi các kỹ năng nào tiếp theo).
+- **Khi nào dùng:** Khi bạn có một yêu cầu lớn và không biết bắt đầu từ đâu.
+
+### 2. `qk-context-loader` (Nạp Ngữ Cảnh)
+- **Mô tả:** Có khả năng đọc lướt dự án để gom chính xác các file liên quan đến task hiện tại (chống tràn bộ nhớ token của AI).
+- **Khi nào dùng:** Khi code dự án quá lớn, cần khoanh vùng các file cần sửa.
+
+### 3. `qk-access-policy` (Kiểm Soát Phân Quyền)
+- **Mô tả:** Xử lý và cung cấp các quy tắc về bảo mật (Security), phân quyền (RBAC), Authentication (JWT/OAuth).
+- **Khi nào dùng:** Khi tính năng liên quan đến việc bảo mật, ai được quyền truy cập vào đâu.
+
+### 4. `qk-project-memory` (Trí Nhớ Dự Án)
+- **Mô tả:** Lưu trữ DNA của dự án, các quyết định kiến trúc, UI pattern và các convention đã được thống nhất từ trước.
+- **Khi nào dùng:** Khi muốn AI làm theo đúng style đã có sẵn trong dự án.
+
+### 5. `qk-engineering-standard` (Bộ Luật Thiết Kế)
+- **Mô tả:** Bơm các "luật thép" (về Frontend, Backend, Database) vào ngữ cảnh để bắt AI tuân thủ cấu trúc thư mục và naming.
+- **Khi nào dùng:** Tự động gọi để ép AI viết code không bị rác.
+
+### 6. `qk-project-bootstrap` (Khởi Tạo Dự Án)
+- **Mô tả:** Setup toàn bộ khung sườn của một dự án mới tinh từ con số 0 (Cấu hình lint, format, folder structure).
+- **Khi nào dùng:** Lúc bắt đầu dự án mới.
+
+---
+
+## 🎨 Lớp 1: UI System Layer (Hệ Thống Giao Diện)
+*Nhóm chuyên biệt về vẽ giao diện và quản lý hệ thống thành phần (Components).*
+
+### 7. `qk-ui-system-builder` (Kỹ Sư Hệ Thống UI)
+- **Mô tả:** Quản lý Design Token, tạo ra các Component có thể tái sử dụng (Button, Table, Form) đảm bảo tính nhất quán toàn dự án.
+- **Khi nào dùng:** Xây dựng thư viện giao diện, tránh viết CSS lộn xộn.
+
+### 8. `qk-design-to-code` (Chuyển Đổi Thiết Kế)
+- **Mô tả:** Đọc hiểu hình ảnh/Figma để tự động chuyển thành mã nguồn giao diện (React, Tailwind, v.v.).
+- **Khi nào dùng:** Bóc tách UI từ bản thiết kế.
+
+### 9. `qk-ui-audit` (Kiểm Toán Giao Diện)
+- **Mô tả:** Kiểm tra độ nhất quán UI/UX, hỗ trợ Responsive trên điện thoại và tối ưu khả năng tiếp cận (Accessibility - a11y).
+- **Khi nào dùng:** Kiểm tra lỗi UI sau khi hoàn thiện giao diện.
+
+---
+
+## 💻 Lớp 2: Development Layer (Phát Triển E2E)
+*Khối thực thi mạnh mẽ nhất, đi từ A-Z một tính năng cụ thể.*
+
+### 10. `qk-feature-delivery` (Chuyển Giao Tính Năng)
+- **Mô tả:** Kỹ năng toàn năng, tự động phân tích thiết kế Database -> Viết API -> Xây UI -> Viết Unit Test cho một tính năng trọn vẹn.
+- **Khi nào dùng:** Xây dựng tính năng hoàn chỉnh (Ví dụ: Chức năng Thanh Toán).
+
+### 11. `qk-api-lifecycle` (Vòng Đời API)
+- **Mô tả:** Chuyên biệt cho Backend: Viết spec, tạo Service, định nghĩa Type, viết Test và sinh tài liệu cho API.
+- **Khi nào dùng:** Xây dựng các Endpoint API.
+
+### 12. `qk-data-lifecycle` (Vòng Đời Dữ Liệu)
+- **Mô tả:** Quản lý Schema, tạo file Migration, tối ưu câu lệnh truy vấn (SQL, Prisma, v.v.).
+- **Khi nào dùng:** Thay đổi cấu trúc cơ sở dữ liệu.
+
+### 13. `qk-db-optimizer` (Tối Ưu Database)
+- **Mô tả:** Phân tích EXPLAIN plan, tìm N+1 queries, đề xuất index và tối ưu query performance.
+- **Khi nào dùng:** Truy vấn chậm, performance DB issue.
+
+### 14. `qk-fe-api-integration` (Tích Hợp API Frontend)
+- **Mô tả:** Consume API Backend, quản lý State, bind vào UI — tuân thủ kiến trúc Base dự án.
+- **Khi nào dùng:** Khi cần gọi API từ frontend, map DTO, xử lý Loading/Error states.
+
+---
+
+## 🛡️ Lớp 3: Quality Assurance Layer (Đảm Bảo Chất Lượng)
+*Kiểm tra độ sạch của code và diệt bug.*
+
+### 15. `qk-project-health` (Kiểm Toán Dự Án)
+- **Mô tả:** Quét toàn bộ dự án để tìm Code Smell, Nợ kỹ thuật (Tech Debt), và các vi phạm kiến trúc.
+- **Khi nào dùng:** Định kỳ kiểm tra chất lượng mã nguồn hoặc tối ưu hiệu năng.
+
+### 16. `qk-bug-resolution` (Giải Quyết Bug Triệt Để)
+- **Mô tả:** Tái hiện lỗi, đào sâu tìm Root Cause, cung cấp giải pháp an toàn và viết Regression Test để chống lỗi lặp lại.
+- **Khi nào dùng:** Sửa các lỗi đứt gãy hoặc logic nghiêm trọng.
+
+### 17. `qk-validation-gate` (Cổng Kiểm Định)
+- **Mô tả:** Kỹ năng chặn cửa. Bắt buộc chạy Test, Linting và Scan Security. Chỉ khi "PASS" mới cho phép kết thúc task.
+- **Khi nào dùng:** Nằm cuối quy trình code của bất kỳ tính năng nào.
+
+---
+
+## 🚀 Lớp 4 & 5: Evolution & Operation (Vận Hành & Tiến Hóa)
+*Triển khai dự án lên Production và nâng cấp phiên bản lớn.*
+
+### 18. `qk-system-evolution` (Tiến Hóa Hệ Thống)
+- **Mô tả:** Nâng cấp dependency (VD: Next 14 lên 15), phân tích rủi ro ảnh hưởng và thực thi nâng cấp an toàn không downtime.
+- **Khi nào dùng:** Update version framework/thư viện.
+
+### 19. `qk-production-release` (Triển Khai Môi Trường)
+- **Mô tả:** Viết Dockerfile, cấu hình CI/CD Pipelines (Github Actions), Deploy lên Cloud (AWS, Vercel).
+- **Khi nào dùng:** Release sản phẩm cho người dùng cuối.
+
+---
+
+## 🤖 Lớp 6: AI Builder Layer (Tích hợp AI)
+
+### 20. `qk-ai-builder` (Xây Dựng AI App)
+- **Mô tả:** Chuyên thiết kế và code các ứng dụng AI như RAG (Retrieval-Augmented Generation), Agent logic và Prompt Engineering.
+- **Khi nào dùng:** Tích hợp LLM vào trong phần mềm của bạn.
+
+---
+
+## 📚 Lớp 7: Knowledge Layer (Tri Thức & Tài Liệu)
+*Hệ thống tự học và viết tài liệu vĩ đại của OS.*
+
+### 21. `qk-docs` (Kỹ Sư Tài Liệu)
+- **Mô tả:** Tự động sinh hoặc cập nhật tài liệu cho con người đọc: `README.md`, `CHANGELOG.md`, `API Docs`.
+- **Khi nào dùng:** Nằm ở cuối quy trình sau khi hoàn thành tính năng.
+
+### 22. `qk-help` (Tra Cứu Nhanh)
+- **Mô tả:** Cuốn từ điển sống. Cung cấp thông tin và hướng dẫn chi tiết (Pro-tips) về cách sử dụng toàn bộ hệ thống.
+- **Khi nào dùng:** Bất kỳ khi nào người dùng cần hỗ trợ sử dụng hệ điều hành.

package/.agents/docs/GOVERNANCE.md

@@ -0,0 +1,40 @@
+# Project Governance
+
+This document serves as the "Constitution" for the AI Developer Skill OS. It dictates how the project evolves, when core files can be modified, and how versions are incremented.
+
+## 1. Core Philosophy
+**Architecture-first, features-second.**
+Before submitting any Pull Request, ask yourself:
+1. *Does this change require modifying the OS Kernel (`AGENTS.md`)?*
+2. *If not, can this be solved at the Skill, Knowledge, or Template layer?*
+
+If the problem can be solved in a Skill, Knowledge document, or Template, **do not touch the Kernel**.
+
+## 2. When to modify `AGENTS.md` (The Kernel)
+The Kernel is **frozen**. Modifications to `AGENTS.md` are strictly prohibited unless:
+- The change introduces a fundamentally new paradigm for ALL agents (e.g., a completely new approach to token management).
+- A critical, framework-breaking hallucination loop is discovered that cannot be solved via Skill guidelines.
+- **Requirement:** Any modification to `AGENTS.md` MUST be accompanied by a new Architecture Decision Record (ADR).
+
+## 3. When to create an ADR (Architecture Decision Record)
+ADRs (located in `docs/adr/`) must be created when:
+- Modifying `AGENTS.md` or `SPEC.md`.
+- Introducing a new lifecycle phase to the pipeline.
+- Deprecating an existing core feature or standard tool.
+
+## 4. Definition of a "Breaking Change"
+A change is considered **Breaking** if it:
+- Alters the required YAML frontmatter contract in `SPEC.md`.
+- Changes the fundamental routing logic or expected `behavior` / `intent` mappings.
+- Removes an existing global policy that downstream agents rely on.
+
+## 5. Versioning Strategy (Semantic Versioning)
+We strictly adhere to SemVer based on the framework's architecture, not just content.
+- **MAJOR (e.g., v4.0.0 to v6.0.0):** Breaking changes to the Kernel (`AGENTS.md`), Metadata Contract (`SPEC.md`), or fundamental routing.
+- **MINOR (e.g., v4.0.0 to v4.1.0):** Adding new Capabilities, new default Skills, new Knowledge docs, or new Templates. 
+- **PATCH (e.g., v4.0.0 to v4.0.1):** Fixing typos in docs, updating README, or minor bug fixes within an individual skill's SOP.
+
+## 6. PR Review Process
+1. **Architecture Compliance:** Does the PR violate the Kernel Freeze? Are all skills compliant with `SPEC.md`?
+2. **Documentation Consistency:** Are the changes reflected in `CHANGELOG.md`?
+3. **No Redundancy:** Ensure the PR does not re-introduce tool usage rules or verification overrides into individual skills.