ai-developer-skill-os 8.1.5 → 8.1.9

package/.agents/CHANGELOG.md

@@ -1,70 +1,113 @@
-# 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-ui-builder`, `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/`.
-
+# Changelog
+
+All notable changes to AI Developer Skill OS are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+---
+
+## [8.1.7] — 2026-07 — README Sync
+
+### Changed
+- **README Sync**: Synced `.agents/README.md` with root `README.md` so the installed documentation is fully up-to-date with V8.1 architecture.
+- Bumped version to `8.1.7`.
+
+---
+
+## [8.1.6] — 2026-07 — Design Intelligence Content & Sync
+
+### Added
+- **Design Intelligence Populated**: Sourced core market-standard knowledge (Tailwind, Radix, Apple, Vercel-like principles) into `.agents/knowledge/design-intelligence/` covering components, patterns, industries, themes, and references.
+- **Animation Knowledge**: Added `visual-language/animation.md` for micro-interactions and transition durations.
+- **Dependency Wiring**: Linked `qk-ui-system-builder` to `design-intelligence` so it utilizes the newly generated design constraints.
+- **Changelog Sync**: Synced `.agents/CHANGELOG.md` with root `CHANGELOG.md` so the installed copy reflects the true V8 evolution.
+
+### Changed
+- All skill descriptions properly translated to Vietnamese for ecosystem consistency.
+- Bumped version to `8.1.6` for final, truly complete Design Intelligence NPM Release.
+
+---
+
+## [8.1.4] — 2026-07 — Design Intelligence Pack
+
+### Added
+- **Design Intelligence Layer**: `.agents/knowledge/design-intelligence/` (industries, themes, patterns, visual-language, components, templates)
+- **Knowledge Dependencies**: `qk-design-system-engineering` and `qk-ui-builder` now have strict dependency bounds tied to Design Intelligence without bloating the Capability Graph.
+- **Design Routing Test Cases**: `design-intel-01`, `02`, `03` for validating routing logic in design scenarios.
+- **Re-introduced CLI Installer**: Restored and refactored `bin/install.js` to correctly copy `.agents` across global/local directories for easy NPM setup.
+
+### Changed
+- Refined **Decision Boundaries**: `qk-ui-builder` explicitly forbidden from defining visual direction or brand identity (strict capability bounds).
+- **README.md** reflects 30 Master Skills and the "Agent Engineering OS" mindset.
+- **package.json**: Version bump `8.1.4` and whitelisted files for npm publish.
+
+---
+
+## [8.1.3] — 2026-07 — Architecture Freeze & Governance
+
+### Added
+- **Capability Graph & Routing**: `.agents/registry/capability-graph.yml` to define skill relations (`depends_on`, `delegates_to`).
+- **Priority Governance**: `.agents/rules/priorities.yml` enforcing safety layers (`P1: System Integrity`, `P2: Guardrails`).
+- **Audit Tools**: `tooling/run-aar.js` for architectural acceptance testing.
+- Test cases for routing and boundary attacks.
+
+### Changed
+- Name transition from "Self-Improving" to **Adaptive Agent OS** (Self Optimizing ≠ Self Modifying).
+- Enforced hard cap of **30 Skills** to prevent Skill Inflation.
+- Frozen Baseline achieved: `v8.1.3-agent-os-production`.
+
+---
+
+## [8.0.0] — 2026-07 — Agent Knowledge System
+
+### Philosophy shift
+- **V7:** Skill Repository — human selects skill, AI executes
+- **V8:** Agent Knowledge System — AI retrieves context, selects capability, executes workflow, verifies
+
+### Added
+- `rules/` — Agent behavior policies (global, coding, safety)
+- `workflows/` — Reusable execution pipelines (YAML, with inputs/outputs per step)
+- `examples/` — Few-shot knowledge (good/, bad/)
+- `learnings/` — Evidence-based learning lifecycle (draft/, validated/, deprecated/)
+- `registry/` — Generated AI retrieval index (skills-index.yml)
+- `docs/ARCHITECTURE.md` — Agent request flow diagram
+- `docs/VERSIONING.md` — Semantic versioning policy
+- `docs/schemas/` — Schema definitions for all knowledge objects
+- `docs/decisions/` — Architecture Decision Records (ADRs)
+- `.agentsignore` — AI boundary file (what agents should NOT load)
+- `tooling/` — Dev automation (generate-registry.js, validate-skills.js)
+- `tests/agent-evaluation/` — Agent behavior test harness
+
+### Changed
+- SKILL.md schema upgraded to V8: added `type`, `intent`, `triggers`, `complexity`, `workflow`, `verification`, `related_skills`
+- `skills.json` demoted to **generated compatibility manifest** (source of truth = SKILL.md)
+- Workflows extracted from individual skills → shared reusable templates
+
+### Removed
+- Embedded workflows inside SKILL.md body (moved to workflows/)
+- Old migration scripts (migrate-v*.js, patch*.py, add_lang.*, etc.)
+- Duplicate documentation (CLAUDE.md, old docs/)
+- Experimental packages (packages/edaos-sdk)
+- framework/, knowledge/, specs/, templates/ directories
+
+### Migration
+- V7.5.1 tagged at git: `v7.5.1`
+- V7 skills preserved in git history; migration is additive schema upgrade
+
+---
+
+## [7.5.1] — 2026-07 — Final V7 Release
+
+- Bumped all skill versions to 7.5.1
+- Added qk-fe-api-integration skill
+- Added qk-performance-tuner (global config)
+- Stabilized frontmatter schema across all 22 skills
+
+## [7.5.0] — 2026-07
+
+- Major skills refactor with EDAOS runtime adapter
+- Added MCP server integration
+- Added qk-bug-resolution workflow contracts
+
+## [7.0.0] — 2026
+
+- V7 release: 22 skills, YAML frontmatter, token budget system

package/.agents/README.md

@@ -1,74 +1,52 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.5.0
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.7
 
-> **V7.5.0 "Anti-Slop & Zero-Trust Architecture"**
+> **v8.1.7 "Agent Engineering OS + Design Intelligence"**
 
-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)**.
+Hệ sinh thái AI Developer Skill OS đã lột xác hoàn toàn. Từ một bộ "công cụ phân tán" (Toolbox) ở V7, phiên bản V8.1.7 được thiết kế như một **Hệ điều hành khép kín (Agent Engineering OS)**, sở hữu năng lực giám sát, bảo vệ ranh giới quyết định (Decision Boundaries) và được trang bị thêm tầng **Design Intelligence**.
 
 ---
 
-## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V7 Kernel)
+## 🏗️ Triết Lý Hoạt Động Cốt Lõi (V8 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.
+### 1. Decision Boundary (Ranh giới Thẩm quyền)
+Không còn tình trạng một Skill ôm đồm mọi việc. Mọi Skill (Kỹ năng) hiện tại bị quản lý bởi các trường `owns`, `does_not_own`, `conflicts_with`, `delegates_to`. Thợ code UI (`qk-ui-builder`) không được phép tự ra quyết định kiến trúc, và ngược lại.
 
-### 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`).
+### 2. Design Intelligence Layer
+Khắc phục điểm yếu "mù thẩm mỹ" của AI. Agent giờ đây không chỉ biết code mà còn có Gu Thẩm Mỹ (Design Taste). Dựa trên yêu cầu của bạn, hệ thống tự động tra cứu **Knowledge Graph** để chọn đúng Theme (Fintech, Healthcare, SaaS...), Typography và Visual Patterns trước khi giao việc cho UI Builder.
 
-### 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`).
+### 3. Khế Ước Đi Đầu (Contract-First & Zero-Trust)
+- **Frontend / UI**: Mọi sửa đổi phải tuân thủ Design System (được `qk-design-system-engineering` kiểm duyệt).
+- **Backend / API**: Phải viết OpenAPI/Swagger contract trước (`qk-api-lifecycle`).
+- **Data**: Cấm AI tự đoán cấu trúc DB, mọi truy vấn phải có Schema (`qk-data-lifecycle`).
 
 ---
 
-## 🧩 Danh sách 22 Master Skills
+## 🧩 Danh sách 30 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-access-policy`
-- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-fe-api-integration`, `qk-data-lifecycle`, `qk-ui-builder`, `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`, `qk-db-optimizer`
+Các kỹ năng được quản lý bằng **Capability Graph** và được đánh giá liên tục thông qua Evaluation Suite. Bao gồm 7 lĩnh vực:
+1. **Core & Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-project-memory`, `qk-help`
+2. **Product & Architecture:** `qk-product-specification`, `qk-project-bootstrap`, `qk-frontend-architecture`
+3. **Frontend & UI:** `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-builder`, `qk-fe-api-integration`, `qk-ui-audit`
+4. **Backend & Data:** `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-access-policy`
+5. **Engineering & Delivery:** `qk-feature-delivery`, `qk-bug-resolution`, `qk-engineering-standard`, `qk-system-evolution`, `qk-docs`
+6. **Quality & Testing:** `qk-test-engineering`, `qk-validation-gate`, `qk-web-quality-gate`, `qk-project-health`
+7. **Security, DevOps & Analytics:** `qk-security-audit`, `qk-db-optimizer`, `qk-devops-platform`, `qk-production-release`, `qk-agent-observability`, `qk-ai-builder`
 
 ---
 
 ## 💻 Cách Cài Đặt (Installation)
 
-### Cách 1: NPM Global (Khuyên dùng cho nhiều máy)
+### Cách 1: NXP (Không cần cài global) - MỚI
 ```bash
-npm i -g ai-developer-skill-os
+npx ai-developer-skill-os init
 ```
 
-### Cách 2: NXP (Không cần cài global)
+### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
 ```bash
-npx ai-developer-skill-os init --ide=antigravity --scope=2
-```
-
-### Cách 3: NPM Scripts (Trong dự án)
-```bash
-# Antigravity Global — 1 lần cài, mọi dự án dùng chung
-npm run install:antigravity
-
-# Antigravity Local — cài riêng cho dự án này
-npm run install:antigravity:local
-
-# Các IDE khác
-npm run install:cursor        # Global Cursor
-npm run install:windsurf      # Global Windsurf
-npm run install:claude        # Global Claude Code
-npm run install:kilo          # Global Kilo Code
-npm run install:multi         # Multi-IDE
+npm i -g ai-developer-skill-os
 ```
 
-## 📦 Tham số cho `init`
-
-| Tham số | Giá trị | Mô tả |
-|---------|---------|-------|
-| `--ide` | `antigravity`, `cursor`, `windsurf`, `claude`, `kilo`, `multi-ide` | IDE/AI Assistant |
-| `--scope` | `1` = Local, `2` = Global | Phạm vi cài đặt |
-
-### Ví dụ thực tế
-
+### Chạy bằng tham số (Command Line Arguments)
 ```bash
 # Cài Antigravity Global (toàn máy)
 npx ai-developer-skill-os init --ide=antigravity --scope=2
@@ -78,23 +56,31 @@ npx ai-developer-skill-os init --ide=antigravity --scope=1
 
 # Cài Cursor Local
 npx ai-developer-skill-os init --ide=cursor --scope=1
-
-# Cài Multi-IDE (tạo CLAUDE.md + .qk-ai-skill-os)
-npx ai-developer-skill-os init --ide=multi-ide --scope=2
 ```
 
-## 🧪 Testing
+## 📦 Các IDE/AI Assistant Được Hỗ Trợ
+- (1) Cursor
+- (2) Windsurf
+- (3) Cline / Roo Code
+- (4) Antigravity / Gemini
+- (5) Codex
+- (6) Kilo Code
 
-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ộ 22 file Kỹ năng trước khi xuất bản:
+---
+
+## 🧪 Đánh Giá Tự Động (Agent Evaluation)
+
+Hệ thống đi kèm một bộ Runner nội bộ để kiểm toán **Routing Intelligence**. Bất kỳ cập nhật nào vào hệ thống Kỹ năng đều phải vượt qua bài kiểm tra hóc búa (Bypass Security, Boundary Attacks, Ambiguous Prompts):
 
 ```bash
-npm test
+npm run test:agent
+npm run test:graph
+npm run test:registry
 ```
 
-## 🚀 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:
+## 🚀 Hướng Dẫn Sử Dụng
+Sau khi cài đặt thành công, hãy gõ lệnh:
 ```bash
 ./qk-help
 ```
-
+để kích hoạt AI Orchestrator và khám phá sức mạnh của hệ điều hành!

package/.agents/skills/qk-code-review/SKILL.md

@@ -0,0 +1,189 @@
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-code-review
+version: 8.0.0
+status: stable
+description: "Elite AI/Code Review System: Kiểm toán, Review code và cấu hình AI với tư duy Architect, áp dụng 4-Phase Review."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: utility
+
+intent:
+  - code-review
+  - quality-assurance
+  - architecture-review
+  - ai-config-audit
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "1-15"
+    has_behavior_change: false
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "review code"
+  - "code review"
+  - "kiểm tra code"
+  - "đánh giá code"
+  - "review skin"
+  - "review rule"
+  - "review ai"
+
+selection:
+  priority: high
+  confidence_threshold: 0.85
+
+# ── V8: References ─────────────────────────────────────────
+workflow: code-review
+
+rules:
+  - global
+
+tools:
+  - filesystem
+
+related_skills:
+  - qk-validation-gate
+  - qk-engineering-standard
+  - qk-project-health
+
+knowledge_scope:
+  owns:
+    - code-review-standards
+    - ai-configuration-review
+    - feedback-delivery
+  references:
+    - architecture
+    - security-best-practices
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: review
+
+# ── V8: Knowledge links ────────────────────────────────────
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: high
+latency: medium
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [source-code, rules, workflows]
+
+token_budget:
+  max_files_read: 10
+  max_lines_per_read: 300
+  max_shell_commands: 2
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-code-review — Elite Review System
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+Biến quá trình Code Review từ "bắt bẻ" (gatekeeping) thành "chia sẻ tri thức" (knowledge sharing) thông qua phản hồi mang tính xây dựng, phân tích có hệ thống và hợp tác cải tiến.
+
+---
+
+## Preconditions
+
+- [ ] Xác định rõ đối tượng cần review: Mã nguồn phần mềm (React, Java, etc.) hay Cấu hình AI (Skin, Rules, Workflows).
+- [ ] Cung cấp ngữ cảnh hoặc mục tiêu của đoạn code/cấu hình cần review.
+
+```
+On missing precondition → EXIT: BLOCKED
+Report: "Missing: Vui lòng cung cấp ngữ cảnh hoặc chỉ định rõ file cần review."
+```
+
+---
+
+## Dynamic Context Loading (Tải Ngữ Cảnh Động)
+
+> **BẮT BUỘC:** Trước khi bắt đầu review, Agent phải sử dụng tool `view_file` để nạp các bí kíp tương ứng từ thư mục `references/` nhằm đảm bảo chất lượng review sâu sát nhất.
+
+- **Nếu review AI Config (Skin, Rule, Workflow):**
+  - Mở đọc: `references/ai/v8-schema-validation.md` và `references/ai/ai-anti-patterns.md`.
+- **Nếu review Code Phần mềm (VD: React, Java, Go, v.v.):**
+  - Nhận diện ngôn ngữ/framework.
+  - Mở đọc file tương ứng: `references/languages/[tên-ngôn-ngữ].md` (VD: `react.md`, `java.md`).
+- **Nếu review ở mức tổng quát hoặc PR lớn (Cross-cutting):**
+  - Đọc thêm: `references/cross-cutting/architecture-review-guide.md`, hoặc các file về security/performance nếu phù hợp.
+
+---
+
+## 4-Phase Review Process
+
+Là một AI Architect, quá trình review phải tuân thủ nghiêm ngặt 4 giai đoạn sau:
+
+### Phase 1: Context Gathering & Loading (Thu thập & Nạp Ngữ Cảnh)
+- Đọc file mô tả (PR, Issue) hoặc yêu cầu của người dùng.
+- **Thực thi Dynamic Context Loading** (đọc các file reference cần thiết như đã định nghĩa ở trên).
+
+### Phase 2: High-Level Review (Kiến trúc & Chuẩn mực)
+- **Đối với AI Config:** Kiểm tra cấu trúc V8 (Identity, Intent, Complexity, Triggers). 
+- **Đối với Code Phần mềm:** Kiểm tra SOLID, Coupling/Cohesion, Performance, Security (Tham chiếu theo `cross-cutting` guides).
+
+### Phase 3: Deep-dive & Logic Review (Phân tích chi tiết)
+- **Đối với AI Config:** Kiểm tra rủi ro "ảo giác" (hallucination), token abuse, side-effects, stop_early.
+- **Đối với Code Phần mềm:** Rà soát edge cases, lỗi logic chuyên sâu theo từng ngôn ngữ (Tham chiếu theo `languages` guides).
+
+### Phase 4: Summary & Decision (Tổng hợp & Quyết định)
+- Đưa ra báo cáo theo `Output Format`.
+- Gắn nhãn `Severity Tags` rõ ràng.
+
+---
+
+## Feedback Principles (Nguyên tắc Phản hồi)
+
+- **Collaborative Language (Ngôn từ hợp tác)**: Thay vì ra lệnh ("Sửa cái này thành X", "Bỏ dòng này đi"), hãy dùng câu hỏi gợi mở ("Nếu chúng ta dùng X ở đây thì có tối ưu hiệu năng hơn không?", "Có vẻ logic này bị lặp, chúng ta extract nó ra hàm riêng được không?").
+- **Differentiate Severity (Phân biệt mức độ)**: Bắt buộc sử dụng các nhãn sau để phân loại mức độ phản hồi:
+  - 🔴 `[blocking]` - Lỗi nghiêm trọng (VD: Security flaw, thiếu token_budget). Bắt buộc phải sửa.
+  - 🟡 `[important]` - Lỗi quan trọng (VD: Performance leak, trigger quá rộng). Nên sửa hoặc cần thảo luận.
+  - 🟢 `[nit]` - Cải thiện nhỏ (VD: Lỗi chính tả, format, naming). Không bắt buộc.
+  - 💡 `[suggestion]` - Cách tiếp cận hoặc thư viện thay thế để tham khảo.
+  - 📚 `[learning]` - Giải thích nguyên lý (Why) để chia sẻ kiến thức, không yêu cầu hành động.
+  - 🎉 `[praise]` - Lời khen cho đoạn code / logic thiết kế tốt.
+
+---
+
+## Output Format
+
+```markdown
+## qk-code-review Report
+─────────────────────────────────────────────────
+**Target:** [Tên file / Chức năng]
+**Status:** SUCCESS | BLOCKED | FAILED | PARTIAL
+
+### 📊 Executive Summary
+[1-2 câu tóm tắt chất lượng tổng thể của mã nguồn/cấu hình. VD: "Kiến trúc rõ ràng, nhưng tiềm ẩn rủi ro lặp vô hạn ở dòng 45."]
+
+### 🔍 Findings & Recommendations
+
+[Nhóm các findings theo mức độ nghiêm trọng giảm dần. LUÔN đính kèm snippet / file line nếu có thể]
+
+- 🔴 `[blocking]`: [Vấn đề nghiêm trọng]
+  - *Location*: `file.ts:L45`
+  - *Feedback*: [Câu hỏi/Gợi ý sửa chữa]
+  
+- 🟡 `[important]`: [Vấn đề quan trọng]
+- 💡 `[suggestion]`: [Gợi ý cải thiện]
+- 🟢 `[nit]`: [Góp ý nhỏ]
+- 🎉 `[praise]`: [Khen ngợi]
+
+### 🛠️ Suggested Fixes (Optional)
+[Cung cấp Code diff hoặc YAML chuẩn xác để user dễ dàng copy & paste. TUYỆT ĐỐI KHÔNG tự sửa file nếu user chưa yêu cầu]
+
+### ✅ Verdict
+- [ ] Approve (Có thể merge/deploy ngay)
+- [ ] Changes Requested (Cần sửa các mục `[blocking]`)
+- [ ] Comment (Chỉ là gợi ý, quyền quyết định ở user)
+```

package/.agents/skills/qk-code-review/references/ai/ai-anti-patterns.md

@@ -0,0 +1,28 @@
+# AI Agent Anti-Patterns
+
+Khi review các cấu hình AI (Skills, Rules, Workflows), hãy lưu ý các "Code Smells" hoặc Anti-patterns phổ biến sau đây:
+
+## 1. Mất kiểm soát Token (Token Abuse)
+- **Dấu hiệu**: Không định nghĩa `token_budget`, hoặc định nghĩa `max_files_read: 50`, `max_lines_per_read: 1000`.
+- **Rủi ro**: Agent sẽ đọc lướt quá nhiều file, làm cạn kiệt context window, dẫn đến "ảo giác" (hallucination) và tốn kém chi phí.
+- **Cách khắc phục**: Ép buộc một giới hạn cứng hợp lý (VD: `max_files_read: 3`, `max_lines_per_read: 150`). Bắt buộc agent dùng `grep` thay vì `read_file` toàn bộ.
+
+## 2. Phạm vi quá rộng (Scope Creep)
+- **Dấu hiệu**: Phần `Scope` hoặc `Intent` bao gồm quá nhiều chức năng không liên quan (VD: Vừa viết code, vừa test, vừa deploy, vừa viết docs).
+- **Rủi ro**: Agent mất tập trung, không biết ưu tiên tác vụ nào, thường xuyên bỏ dở công việc giữa chừng.
+- **Cách khắc phục**: Áp dụng nguyên tắc Single Responsibility. Tách thành nhiều skill nhỏ và dùng Orchestrator hoặc Workflow để phối hợp. Yêu cầu làm rõ mục `This skill does NOT`.
+
+## 3. Lạm dụng quyền thực thi (Unsafe Side-Effects)
+- **Dấu hiệu**: Cấu hình `side_effects: run_commands` nhưng không có Verification Gate hoặc không bắt buộc user approval.
+- **Rủi ro**: Có thể vô tình xóa file (`rm -rf`), chạy mã độc, hoặc làm hỏng môi trường phát triển của User.
+- **Cách khắc phục**: Đánh giá Risk level (High/Medium). Nếu có `run_commands`, phải ép buộc chạy ở môi trường giả lập (sandbox) hoặc chỉ sinh ra script để user tự chạy (Dry-run mode).
+
+## 4. Thiếu điều kiện tiền quyết (Missing Preconditions)
+- **Dấu hiệu**: Bỏ trống phần `Preconditions`, agent lao vào thực thi ngay lập tức.
+- **Rủi ro**: Chạy sai ngữ cảnh, sửa bậy bạ vào mã nguồn khi chưa đủ thông tin, tốn token vô ích.
+- **Cách khắc phục**: Bắt buộc phải có `EXIT: BLOCKED` nếu thiếu thông tin đầu vào quan trọng (ví dụ: thiếu file config, thiếu đường dẫn dự án).
+
+## 5. Prompt mang tính "Bức ép" (Aggressive Prompts)
+- **Dấu hiệu**: Dùng nhiều từ in hoa "MUST", "DO NOT", "NEVER" nhưng thiếu giải thích nguyên lý (Why).
+- **Rủi ro**: LLM (Large Language Model) thường bị over-constrained (bị kìm kẹp quá mức), dẫn đến việc từ chối trả lời (refusal) hoặc phản hồi cứng nhắc, mất đi khả năng sáng tạo.
+- **Cách khắc phục**: Chuyển từ "Cấm làm X" sang "Chỉ làm X khi Y, vì Z". Cung cấp `examples` cụ thể thay vì cấm đoán suông.

package/.agents/skills/qk-code-review/references/ai/v8-schema-validation.md

@@ -0,0 +1,65 @@
+# V8 Schema Validation Guide
+
+Tài liệu này dùng để đối chiếu khi review các file `SKILL.md` hoặc các file cấu hình AI khác trong dự án. Đảm bảo mọi cấu hình tuân thủ chặt chẽ định dạng và kiến trúc của V8 Skin.
+
+## 1. Frontmatter (YAML Metadata) Bắt buộc
+
+Mọi file `SKILL.md` **phải** bắt đầu bằng khối YAML chứa các thông tin sau:
+
+```yaml
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-[tên-skill]          # Bắt buộc có tiền tố qk-
+version: [X.Y.Z]              # Phiên bản semantic
+status: [stable/beta/draft]
+description: "[Mô tả ngắn gọn bằng tiếng Việt]"
+platforms: [danh sách platform hỗ trợ]
+
+# ── V8: Classification ─────────────────────────────────────
+type: [utility/capability/orchestrator]
+intent:
+  - [mục-đích-chính]
+
+complexity:
+  level: [low/medium/high/critical]
+  criteria:
+    files_affected: "[range]"
+    # ... các criteria khác
+
+triggers:                     # Rất quan trọng, bắt buộc có
+  - "[từ khóa 1]"
+  - "[từ khóa 2]"
+
+# ── V7 Runtime ─────────────────────────────────────────────
+# Phần này cấu hình cách Agent thực thi
+side_effects: [read_only/edit_files/run_commands]
+produces: [...]
+consumes: [...]
+
+token_budget:                 # Bắt buộc để tránh cạn kiệt Token
+  max_files_read: [số]
+  max_lines_per_read: [số]
+  max_shell_commands: [số]
+  stop_early: [true/false]
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+```
+
+## 2. Các phần Body (Markdown) Bắt buộc
+
+1. **Title & Language Rule**: Ngay sau frontmatter, phải có tiêu đề và rule ngôn ngữ chuẩn:
+   ```markdown
+   > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+   ```
+2. **Preconditions**: Định nghĩa rõ điều kiện tiên quyết để skill này có thể chạy. Phải mô tả hành động (thường là `EXIT: BLOCKED`) nếu thiếu thông tin.
+3. **Scope (What it does / What it does NOT)**: Phải rõ ràng giới hạn của skill. Đặc biệt phần `Does NOT` để ngăn scope creep.
+4. **Output Format**: Format chuẩn mà AI sẽ phản hồi lại cho user sau khi thực thi.
+
+## 3. Checklist khi Review
+
+- [ ] Tiền tố tên có đúng chuẩn (`qk-`) không?
+- [ ] Triggers có bao phủ đủ các cách gọi thông dụng không? Có bị trùng lặp với skill khác không?
+- [ ] `token_budget` có được cấu hình hợp lý so với `complexity` không? (Ví dụ: complexity low nhưng lại cho đọc 50 files là sai).
+- [ ] Nếu `side_effects` là `run_commands` hoặc `edit_files`, phần Preconditions đã đủ chặt chẽ chưa?
+- [ ] Format đầu ra (Output format) có chuẩn mực và chuyên nghiệp không?