ai-developer-skill-os 9.3.0 → 10.1.0

package/.agents/workflows/spec-driven-development.yml

@@ -1,87 +1,109 @@
-name: spec-driven-development
-version: 8.0.0
-description: "Workflow phát triển dựa trên đặc tả (Specification-Driven Development)."
-
-owner:
-  type: engineering
-  maintained_by: qk-team
-
-verification_profile: spec-driven
-
-triggers:
-  - "write a spec"
-  - "viết đặc tả"
-  - "spec this out"
-  - "design before implementing"
-  - "technical spec for"
-
-ide_binding:
-  slash_command: "/spec"
-  aliases: ["/spec-driven"]
-
-steps:
-  - id: clarify_requirement
-    name: "Clarify Requirements"
-    purpose: "Làm rõ yêu cầu từ ý tưởng ban đầu"
-    required: true
-    inputs:
-      - user_idea
-    outputs:
-      - clarified_requirement
-    actions:
-      - "Hỏi các câu hỏi làm rõ scope và constraints"
-      - "Xác định rõ outcome mong muốn"
-
-  - id: create_spec
-    name: "Create Specification"
-    purpose: "Viết tài liệu đặc tả kỹ thuật"
-    required: true
-    inputs:
-      - clarified_requirement
-    outputs:
-      - technical_spec
-    actions:
-      - "Thiết kế API contracts, data models"
-      - "Xác định UI/UX heuristics"
-      - "Spec phải quy định rõ boundary validation (R-SEC-04)"
-      - "Xác định edge cases"
-
-  - id: create_plan
-    name: "Create Plan"
-    purpose: "Lên kế hoạch triển khai"
-    required: true
-    inputs:
-      - technical_spec
-    outputs:
-      - implementation_plan
-    actions:
-      - "Chia nhỏ spec thành các task cụ thể"
-      - "Đánh giá rủi ro và thứ tự ưu tiên"
-
-  - id: implement
-    name: "Implement"
-    purpose: "Triển khai mã nguồn"
-    required: true
-    inputs:
-      - implementation_plan
-      - technical_spec
-    outputs:
-      - source_code
-    actions:
-      - "Code theo đúng spec"
-
-  - id: verify
-    name: "Verify Implementation"
-    purpose: "Kiểm tra mã nguồn với đặc tả"
-    required: true
-    inputs:
-      - source_code
-      - technical_spec
-    outputs:
-      - verification_result
-    actions:
-      - "Đối chiếu kết quả code với acceptance criteria"
-
-escalation:
-  max_retries: 2
-  on_failure: "Báo cáo lệch spec và xin chỉ thị"
+name: spec-driven-development
+version: 9.3.0
+description: "Workflow phát triển sản phẩm dựa trên đặc tả kỹ thuật (Specification-Driven Development): Idea → Requirements → Acceptance Criteria (BDD) → Technical Spec → Plan → Verify."
+
+owner:
+  type: engineering
+  maintained_by: qk-team
+
+verification_profile: spec-driven
+
+triggers:
+  - "write a spec"
+  - "viết đặc tả"
+  - "spec this out"
+  - "acceptance criteria"
+  - "prd"
+  - "technical spec"
+  - "user story"
+  - "design before implementing"
+
+ide_binding:
+  slash_command: "/spec"
+  aliases: ["/grill-me", "/prd", "/spec-driven"]
+
+steps:
+  - id: clarify_requirements
+    name: "Làm rõ yêu cầu & Bóc tách ý tưởng"
+    purpose: "Biến ý tưởng thô sơ thành mục tiêu sản phẩm rõ ràng, không mơ hồ"
+    required: true
+    inputs:
+      - user_idea
+      - dev_profile
+    outputs:
+      - problem_statement    # Vấn đề cần giải quyết
+      - target_actors        # Ai sử dụng tính năng này
+      - scope_boundary       # In-scope vs Out-of-scope rõ ràng
+    actions:
+      - "Gợi ý người dùng chạy lệnh slash /grill-me để phỏng vấn sâu nếu yêu cầu còn nhiều giả định chưa rõ"
+      - "Xác định rõ vấn đề cốt lõi (Core Problem) và giá trị kinh doanh (Value)"
+      - "Vạch rõ ranh giới: Làm gì (In-scope) và KHÔNG làm gì (Out-of-scope)"
+    exit_on_fail: BLOCKED
+
+  - id: acceptance_criteria
+    name: "Xây dựng Acceptance Criteria (BDD)"
+    purpose: "Định nghĩa định lượng tiêu chí hoàn thành theo chuẩn Given / When / Then"
+    required: true
+    inputs:
+      - problem_statement
+      - target_actors
+      - scope_boundary
+    outputs:
+      - criteria_matrix      # Bảng Given / When / Then cho từng use-case
+      - edge_cases           # Kịch bản biên, lỗi, rớt mạng, mất quyền
+    actions:
+      - "Viết kịch bản theo chuẩn BDD (Given / When / Then) cho từng User Story"
+      - "Liệt kê ít nhất 3 edge cases (dữ liệu rỗng, timeout, quyền truy cập không hợp lệ)"
+      - "Xác định rõ HTTP status code mong đợi cho từng kịch bản lỗi"
+
+  - id: technical_specification
+    name: "Thiết kế Đặc tả Kỹ thuật (Technical Spec)"
+    purpose: "Xác định kiến trúc hệ thống, API contracts, và Data schema trước khi code"
+    required: true
+    inputs:
+      - criteria_matrix
+      - edge_cases
+    outputs:
+      - data_models          # Entities, Interfaces, DB Schema migrations
+      - api_contracts        # Endpoint, Method, Request/Response JSON schemas
+      - architecture_diagram # Sơ đồ luồng ASCII Unicode Box Drawing
+    actions:
+      - "Vẽ sơ đồ luồng dữ liệu (Data Flow) bằng Unicode/ASCII Box Drawing (chuẩn GEMINI.md)"
+      - "Thiết kế Type contracts (TypeScript interfaces / Pydantic models / Protobuf)"
+      - "Xác định rõ các điểm chốt chặn bảo mật (Boundary Validation R-SEC-04)"
+      - "Đảm bảo contract giữa Frontend và Backend đồng bộ 100%"
+
+  - id: create_plan
+    name: "Lập Kế hoạch Triển khai (Implementation Plan)"
+    purpose: "Phân rã spec thành các task cụ thể và kích hoạt phê duyệt tương tác"
+    required: true
+    inputs:
+      - technical_specification
+    outputs:
+      - implementation_plan  # File implementation_plan.md
+    actions:
+      - "Phân chia task theo thứ tự an toàn: Types/Schema → Business Logic/Service → UI/Route → Tests"
+      - "Ước lượng rủi ro và blast radius cho từng file"
+      - "Trên Antigravity IDE: Tạo implementation_plan.md kèm RequestFeedback: true để kích hoạt Modal phê duyệt"
+    human_checkpoint:
+      condition: "Task có độ phức tạp medium/high (≥ 2 files hoặc sửa schema DB)"
+      message: "Bản đặc tả và kế hoạch kỹ thuật đã sẵn sàng. Xác nhận để chuyển sang bước thực thi."
+
+  - id: verify_compliance
+    name: "Kiểm định Tuân thủ Đặc tả"
+    purpose: "Đối chiếu mã nguồn sau khi code với 100% Acceptance Criteria ban đầu"
+    required: true
+    inputs:
+      - source_code
+      - criteria_matrix
+    outputs:
+      - compliance_report    # Pass rate, tiêu chí chưa đạt (nếu có)
+    actions:
+      - "Kiểm tra từng tiêu chí Given/When/Then — đánh dấu ✅ hoặc ❌"
+      - "Chạy automated tests nếu có để chứng minh tiêu chí đã đạt"
+      - "Không cho phép đóng task nếu còn bất kỳ acceptance criterion nào chưa thỏa mãn"
+    exit_on_fail: PARTIAL
+
+escalation:
+  max_retries: 2
+  on_failure: "Báo cáo độ lệch so với spec, chỉ ra blocker và yêu cầu chỉ thị từ Tech Lead / User"

package/CHANGELOG.md

@@ -5,6 +5,60 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ---
 
+## [10.1.0] — 2026-09-15 — AI Developer Skill OS v10.1: 11 Super-Skills, API-to-Data Discovery & Prompt Compiler v11.1
+
+### Added
+- **`qk-api-data-discovery` (Super-Skill thứ 11)**: Kỹ nghệ Khám phá API & Hợp đồng Dữ liệu thực nghiệm (API Discovery → Real Evidence → Schema Discovery → Data Contract → Bronze Medallion Assessment).
+  - Tôn chỉ vàng: *"Never infer an API contract from endpoint names alone. Observe the real API response first, preserve raw evidence, then derive the schema and standardized collection from observed evidence."*
+  - Mô hình 2 Pha với **Checkpoint STOP**: Pha A (Khám phá & xuất báo cáo Checkpoint `docs/api-discovery/<collection>-analysis.md`) → Dừng lại chờ người dùng quyết định → Pha B (Triển khai đúng Option được chọn).
+  - Quy tắc Handoff Contract: Báo cáo checkpoint chứa 3 tầng thông tin độc lập (FACT, ANALYSIS, DECISION OPTIONS) để chuyển giao quyền kiểm soát cho người dùng.
+- **`qk-prompt-compiler` v11.1**: Tích hợp Control Plane & Behavioral Gate với 4 chốt chặn kiểm soát: Risk Gate (`Complexity ≠ Risk`), Change Budget Gate (1–5 files, 0 deps), Scope Expansion Gate (chặn lan tầng), và Evidence Gate (`CLAIM LEVEL <= EVIDENCE LEVEL`).
+- **Nâng cấp Antigravity Cockpit**: Hỗ trợ 14 Senior Developer Roles, Interactive Planning Mode tự động (`RequestFeedback: true`), Dual-Stream Reporting và Unicode Box Drawing Diagrams.
+
+### Changed
+- **Quy hoạch 11 Core Super-Skills**: Đồng bộ hóa toàn bộ registry O(1), routing table và tài liệu hướng dẫn về chuẩn 11 Super-Skills tập trung, xóa bỏ hoàn toàn phân mảnh.
+- **Test Suite v10+**: Nâng cấp test suite tự động nhận diện các phiên bản Super-Skills v10+ và v11+, đạt 10/10 test cases passed (<1s).
+
+---
+
+## [9.3.1] — 2026-09-14 — EDAOS v9.3: SSOT Trigger Discipline, Full-Body Execution & Complete Documentation
+
+### Added
+- **Complete v9.3 Documentation Sync**: Updated `README.md` and `CHANGELOG.md` with comprehensive architectural documentation, active skill breakdown, and governance notes.
+- **SSOT 2-Clause Trigger Standard**: Implemented Anthropic 2-clause standard across all 29 active skills (`qk-*`). Clause 1 defines primary responsibility; Clause 2 defines explicit trigger intents including colloquial Vietnamese triggers ("kể cả khi chỉ nói...").
+- **Closed-Loop 4-Tier Body Architecture**: Completed full execution body across all 29 active skills (Preconditions, In/Out-of-Scope boundaries, Step-by-step pipeline, Role-aware Prompt Templates & Command argument specs).
+- **Direct Terminal Visual Rendering**: Enforced Unicode/ASCII Box Drawing for architectural diagrams, sequence flows, and decision trees directly in terminal output (GEMINI.md).
+- **Vitest Isolation Engine**: Added isolated `vitest.config.js` ignoring external IDE worktrees (`.kilo/`) for fast (<1s) 10/10 test suite execution.
+
+### Changed
+- **Boundary Disambiguation**: Resolved trigger overlaps between paired skills:
+  - `qk-project-audit` (pre-code gap analysis & feasibility) vs `qk-project-health` (code smells & technical debt audit of running codebase).
+  - `qk-ui-audit` (visual consistency & 57-check anti-slop) vs `qk-web-quality-gate` (WCAG a11y, performance, lighthouse).
+  - `qk-access-policy` (RBAC/ABAC & auth middleware) vs `qk-security-audit` (OWASP scan & vulnerability detection).
+- **Skill Restructuring & Governance**:
+  - Archived `qk-frontend-architecture` and `qk-agent-observability` with deprecation paths.
+  - Relocated `qk-engineering-standard` to Behavior Policy Rule (`.agents/rules/coding.md`).
+  - Relocated `qk-validation-gate` to Eval Pipeline Engine (`evals/runner.js`).
+  - Preserved 3 legacy v9.1 skills (`qk-fe-api-integration`, `qk-help`, `qk-system-evolution`) for zero-breaking backward compatibility.
+
+---
+
+## [9.2.0] — 2026-09-11 — EDAOS v9.2: Role-Aware Execution & Semantic Naming
+
+### Added
+- **DEV_PROFILE.md**: Project-level role and stack context file automatically loaded at session start.
+- **Role Behavior Matrix**: Added 6 developer profiles (`fe`, `be`, `fullstack`, `data`, `ai-engineer`, `devops`) with focus, depth, and skip guidance.
+- **Role-Aware Prompt Templates**: Integrated role-specific templates in key skills.
+
+### Changed
+- Renamed `qk-fe-api-integration` → `qk-api-consumer`.
+- Renamed `qk-system-evolution` → `qk-upgrade`.
+- Renamed `qk-project-analyst` → `qk-project-audit`.
+- Renamed workflows: `skill-evolution.yml` → `skin-governance.yml`, `research.yml` → `context-discovery.yml`.
+- Deprecated and removed legacy `qk-help` in favor of `qk-orchestrator`.
+
+---
+
 ## [9.0.0] — 2026-08 — EDAOS v9.0: Universal Project Knowledge V1 & Dual-Mode Memory Architecture
 
 ### Added

package/README.md

@@ -1,184 +1,125 @@
-# AI Developer Skill OS v9.2.0
-
-> **v9.2.0 "EDAOS v9.2 — Role-Aware Execution & Semantic Naming"**
-
-Phiên bản **v9.2.0** tập trung vào 3 nâng cấp cốt lõi:
-1. **Role-Aware Execution** — AI tự động điều chỉnh chiều sâu phân tích theo role khai báo trong `DEV_PROFILE.md`
-2. **Semantic Naming** — Đổi tên skills, workflows theo đúng mục đích thực tế, loại bỏ tên trừu tượng
-3. **Prompt Templates theo Role** — Mỗi skill có examples cụ thể cho từng role (fe/be/fullstack/data/ai-engineer/devops)
-
----
-
-## Bắt đầu nhanh
-
-### Bước 1 — Khai báo role và stack một lần
-
-Tạo file `.agents/DEV_PROFILE.md` trong dự án:
-
-```yaml
-role: fullstack          # fe | be | fullstack | data | ai-engineer | devops
-stack:
-  frontend:  Next.js 14 + TypeScript
-  backend:   tRPC + Prisma
-  database:  PostgreSQL
-  css:       Tailwind CSS
-ai_style: concise        # concise | detailed | teaching
-```
-
-AI sẽ đọc file này trước mọi yêu cầu — không cần nhắc lại stack mỗi lần.
-
-### Bước 2 — Gọi skill
-
-```bash
-# Cú pháp command
-./qk-feature-delivery
-./qk-bug-resolution
-./qk-api-lifecycle --fw=fastapi
-
-# Hoặc ngôn ngữ tự nhiên — AI tự route đúng skill
-"fix bug login crash"
-"viết api tạo đơn hàng"
-"refactor file UserService.ts quá dài"
-```
-
-### Cài đặt
-
-```bash
-# NPX (không cần cài global)
-npx ai-developer-skill-os init
-
-# NPM global
-npm i -g ai-developer-skill-os
-
-# Với tham số IDE
-npx ai-developer-skill-os init --ide=cursor --scope=1
-npx ai-developer-skill-os init --ide=windsurf --scope=1
-npx ai-developer-skill-os init --ide=antigravity --scope=2
-```
-
-**IDE được hỗ trợ:** Cursor · Windsurf · Cline / Roo Code · Antigravity · Kilo Code · Codex
-
----
-
-## Kiến trúc v9.2
-
-```
-.agents/
-├── DEV_PROFILE.md        ← Khai báo role + stack (đọc đầu mỗi session)
-├── AGENTS.md             ← Entry point: routing table + role behavior matrix
-├── skills/               ← 33 capabilities — mỗi skill có SKILL.md
-├── workflows/            ← 10 execution pipelines
-├── rules/                ← 8 behavior policies
-├── registry/             ← Generated indexes (không sửa tay)
-├── knowledge/            ← Design intelligence + domain patterns
-└── blueprints/           ← Project scaffold templates
-```
-
-### Role Behavior Matrix
-
-| Role | AI tập trung vào | AI bỏ qua |
-|---|---|---|
-| `fe` | Component arch, state, a11y, bundle size | DB schema, backend arch |
-| `be` | API contract, business logic, DB perf, security | CSS, UI layout |
-| `fullstack` | FE+BE end-to-end, type-safe contract | Over-engineering |
-| `data` | Idempotency, data quality, lineage, SLA | Application ORM, UI |
-| `ai-engineer` | Prompt eng, RAG arch, eval pipeline, hallucination | Standard CRUD |
-| `devops` | CI/CD, IaC, observability, rollback | Business logic, UI |
-
----
-
-## 33 Skills (v9.2.0)
-
-### Core & Orchestration
-| Skill | Mô tả |
-|---|---|
-| `qk-orchestrator` | Route yêu cầu đến đúng skill, kiểm tra preconditions |
-| `qk-context-loader` | Load context, vẽ dependency graph trước khi code |
-| `qk-project-memory` | Lưu/tra cứu project knowledge (Architecture, Convention, Pattern, Hard Bug) |
-| `qk-project-bootstrap` | Khởi tạo dự án mới với Blueprint Plugins (RAG/Coding/Workflow) |
-
-### Product & Architecture
-| Skill | Mô tả |
-|---|---|
-| `qk-product-specification` | Idea → Requirement → Acceptance Criteria → Technical Spec |
-| `qk-frontend-architecture` | Quyết định kiến trúc FE: component strategy, state, routing |
-| `qk-project-audit` | Gap Analysis, Feasibility, Risk Assessment — báo cáo trước khi code |
-
-### Frontend & UI
-| Skill | Mô tả |
-|---|---|
-| `qk-ui-builder` | Build/edit/audit/redesign UI từ Figma/ảnh/design reference |
-| `qk-ui-system-builder` | Build Design System và token library từ DESIGN.md |
-| `qk-design-system-engineering` | Quản trị design system: tokens, component variants, governance |
-| `qk-api-consumer` | Consume API (REST/GraphQL/tRPC), manage state, bind vào UI |
-| `qk-ui-audit` | Audit UI với 57-check Anti-Slop checklist |
-| `qk-web-quality-gate` | A11y, SEO, Web Performance, Security, UX Heuristics |
-
-### Backend & Data
-| Skill | Mô tả |
-|---|---|
-| `qk-api-lifecycle` | Design + implement API với Zero-Trust — contract trước, code sau |
-| `qk-data-lifecycle` | Schema management + safe migrations (freeze → compat → cleanup) |
-| `qk-data-engineer` | Data pipelines: dbt, Spark, Airflow, Delta Lake — idempotency first |
-| `qk-access-policy` | RBAC/ABAC — định nghĩa role matrix trước, implement middleware sau |
-| `qk-db-optimizer` | Evidence-based DB optimization: EXPLAIN → analyze → index |
-
-### Engineering & Delivery
-| Skill | Mô tả |
-|---|---|
-| `qk-feature-delivery` | End-to-end feature: Requirements → Context → Design → Implement |
-| `qk-bug-resolution` | Closed-loop bug fix: Observe → Hypothesis → Evidence → Fix |
-| `qk-refactor` | Tái cấu trúc code không đổi behavior — extract, simplify, decouple |
-| `qk-upgrade` | Nâng cấp library/framework an toàn — incremental, rollback bắt buộc |
-| `qk-docs` | Viết/cập nhật docs chính xác tuyệt đối — match code thực tế |
-
-### Quality & Testing
-| Skill | Mô tả |
-|---|---|
-| `qk-test-engineering` | Test strategy: pyramid, coverage, regression, mock |
-| `qk-validation-gate` | Quality gate: linters, tests, scorecard.yaml (0–100) |
-| `qk-project-health` | Audit: Code Smells, Tech Debt, Architecture (0–100 score) |
-| `qk-code-review` | 4-Phase elite code review với Architect mindset |
-| `qk-engineering-standard` | Enforce SOLID, DRY, Clean Code với ngưỡng metric cụ thể |
-
-### Security, DevOps & AI
-| Skill | Mô tả |
-|---|---|
-| `qk-security-audit` | OWASP, dependency risk, secret detection, permission model |
-| `qk-devops-platform` | CI/CD strategy, deployment architecture, environment management |
-| `qk-production-release` | 8-gate mandatory checklist trước khi deploy production |
-| `qk-ai-builder` | Governed AI Agent & RAG pipeline design — eval pipeline included |
-| `qk-agent-observability` | Monitor AI skin routing decisions, failure patterns |
-
----
-
-## Changelog
-
-### v9.2.0 (2026-09-11)
-- **Thêm:** `DEV_PROFILE.md` — role + stack context file, AI đọc đầu mỗi session
-- **Thêm:** Role Behavior Matrix trong `AGENTS.md` — 6 roles với focus/depth/skip
-- **Thêm:** Prompt templates theo role trong 7 key skills
-- **Đổi tên:** `qk-fe-api-integration` → `qk-api-consumer` (rõ hơn, không FE-only)
-- **Đổi tên:** `qk-system-evolution` → `qk-upgrade` (đúng mục đích thực tế)
-- **Đổi tên:** `qk-project-analyst` → `qk-project-audit` (rõ output là audit report)
-- **Đổi tên workflow:** `skill-evolution.yml` → `skin-governance.yml`
-- **Đổi tên workflow:** `research.yml` → `context-discovery.yml`
-- **Xóa:** `qk-help` (deprecated từ v8.0, superseded bởi `qk-orchestrator`)
-- **Xóa:** `.ai-local/` Self-Init Protocol khỏi tất cả SKILL.md (giảm token overhead)
-- **Fix:** Compact routing table trong `AGENTS.md` — không cần đọc `skills-index.yml`
-
-### v9.1.x (2026-08-03)
-- O(1) registry engine, Universal Project Knowledge V1
-
-### v9.0.0 (2026-07-01)
-- V9 schema migration, manifest-first architecture
-
----
-
-## Đánh giá tự động
-
-```bash
-npm run test:agent      # Routing intelligence tests
-npm run test:graph      # Capability graph validation
-npm run test:registry   # Registry consistency check
-```
+# AI Developer Skill OS v10.1.0 — Lean Core Edition
+
+> **v10.1.0 "Lean Core Revolution & API-to-Data Discovery Integration"**
+
+Phiên bản **v10.1.0** giải quyết triệt để vấn đề phân mảnh quá mức (extreme fragmentation) từ 37 thư mục vi kỹ năng (micro-skills) xuống còn **11 Core Super-Skills** mạnh mẽ, không làm mất bất kỳ tính năng chuyên sâu nào, đồng thời tích hợp toàn diện cỗ máy biên dịch Prompt Compiler v11.1 và Discovery Engine cho Antigravity IDE.
+
+---
+
+## Điểm Nổi Bật Của v10.1.0
+
+1. **Quy Hoạch 11 Core Super-Skills**: Hợp nhất logic toàn diện từ 37 thư mục cũ vào 11 khối năng lực domain chuyên sâu:
+   - `qk-orchestrator`: Điều phối, nạp ngữ cảnh kiến trúc (Context Graph) và khởi tạo dự án (Bootstrap).
+   - `qk-prompt-compiler`: Biên dịch & chuẩn hóa prompt (Control Plane, Prompt Delta, 4 Cổng Kiểm Soát).
+   - `qk-product-spec`: Phân tích yêu cầu, PRD, BDD/Gherkin acceptance criteria và Gap Analysis/Khả thi.
+   - `qk-feature-delivery`: Phát triển tính năng end-to-end, tích hợp API client, state management và giao tiếp FE-BE.
+   - `qk-bug-resolution`: Chẩn đoán và xử lý bug bằng chu trình khép kín 5 bước (Observe → Hypothesize → Evidence → Fix → Verify).
+   - `qk-ui-engineer`: Xây dựng UI chuẩn Design Tokens, tối ưu hoá tương tác, responsive và kiểm toán 57 tiêu chí Anti-Slop.
+   - `qk-backend-data`: Thiết kế REST/tRPC API, Schema & Migration an toàn, phân quyền RBAC/ABAC, tối ưu EXPLAIN database và Data Pipeline (ETL/dbt).
+   - `qk-api-data-discovery`: Khám phá API, thu thập Real Evidence, Schema Discovery, đánh giá tầng Bronze Medallion và Checkpoint Handoff Contract.
+   - `qk-code-review`: Kiểm toán mã nguồn kiến trúc, chấm điểm sức khỏe Codebase Health Score (0–100), bảo mật OWASP Top 10 và chất lượng Web (WCAG 2.1 AA, Core Web Vitals).
+   - `qk-code-cleaner`: Tái cấu trúc sạch sẽ (SOLID, giải phóng God files >300L), nâng cấp thư viện an toàn (có Rollback plan) và kỹ nghệ kiểm thử tự động (Test Pyramid).
+   - `qk-devops-release`: Vận hành Platform (Docker, CI/CD GitHub Actions), cổng kiểm soát phát hành 8-Gate Production, đồng bộ tài liệu (README/OpenAPI), bộ nhớ dự án (`.ai-local/`, `/learn`) và kiến trúc AI/RAG.
+2. **Hỗ Trợ Toàn Diện 14 Senior Roles**: Fullstack, Backend, Frontend, Data Engineer, Data Analyst, Data Architect, Data Scientist, DevOps, QA, Product Manager, Business Analyst, UI/UX Designer, AI/ML Engineer, Business Manager.
+3. **Antigravity Cockpit Optimization**:
+   - **Interactive Planning Mode**: Tự động kích hoạt modal và nút **[Proceed]** trên Antigravity trước khi thay đổi mã nguồn lớn (complexity ≥ Medium).
+   - **Artifact Dual-Stream Reporting**: Tránh spam hàng trăm dòng vào cửa sổ Chat; xuất báo cáo chi tiết vào file Artifact (`review_report.md`, `health_scorecard.md`) và in bản Tóm tắt điều hành 15–25 dòng vào chat.
+   - **Dynamic Workspace Path Links**: Toàn bộ đường dẫn file được định dạng theo chuẩn `file:///<workspace-root>/...` dùng forward slash, click mở ngay lập tức trong editor.
+   - **Ascii / Unicode Diagram Rendering**: Vẽ sơ đồ kiến trúc và luồng dữ liệu trực tiếp trong terminal bằng Unicode Box Drawing.
+
+---
+
+## Cấu Trúc Hệ Thống
+
+```
+.agents/
+├── DEV_PROFILE.md        ← Khai báo role + stack của bạn (AI đọc đầu mỗi session)
+├── AGENTS.md             ← Entry point: Quick Routing Table 9 Super-Skills + 14 Roles Matrix
+├── GEMINI.md             ← Quy chuẩn cockpit riêng cho Antigravity IDE
+├── skills/               ← 11 Core Super-Skills (mỗi skill có SKILL.md độc lập)
+│   ├── qk-orchestrator/
+│   ├── qk-prompt-compiler/
+│   ├── qk-product-spec/
+│   ├── qk-feature-delivery/
+│   ├── qk-bug-resolution/
+│   ├── qk-ui-engineer/
+│   ├── qk-backend-data/
+│   ├── qk-api-data-discovery/
+│   ├── qk-code-review/
+│   ├── qk-code-cleaner/
+│   └── qk-devops-release/
+├── workflows/            ← 10 execution pipelines liên kết trực tiếp
+├── rules/                ← Behavior policies (global, coding, safety, security...)
+└── registry/             ← Index O(1) sinh tự động (index.yaml, graph.json)
+```
+
+---
+
+## Bắt Đầu Nhanh
+
+### Bước 1 — Khai báo role và stack một lần
+
+Tạo hoặc chỉnh sửa `.agents/DEV_PROFILE.md` trong dự án của bạn:
+
+```yaml
+role: fullstack          # fe | be | fullstack | data | ai-engineer | devops | qa | pm | ba...
+stack:
+  frontend:  Next.js 15 + TypeScript
+  backend:   Node.js + Fastify / NestJS
+  database:  PostgreSQL + Prisma
+  css:       Tailwind CSS
+ai_style: concise        # concise | detailed | teaching
+```
+
+### Bước 2 — Gọi Super-Skill
+
+```bash
+# Kích hoạt bằng lệnh trực tiếp:
+./qk-orchestrator              # Điều phối, nạp ngữ cảnh dự án
+./qk-prompt-compiler           # Biên dịch & chuẩn hóa prompt (hiển thị trước khi code)
+./qk-product-spec              # Viết PRD, user stories, acceptance criteria
+./qk-feature-delivery          # Phát triển tính năng mới end-to-end
+./qk-bug-resolution            # Sửa bug và điều tra nguyên nhân gốc
+./qk-ui-engineer               # Thiết kế UI, tokens, audit anti-slop
+./qk-backend-data              # Viết API, schema migration, tối ưu DB, pipeline
+./qk-api-data-discovery        # Khám phá API, Schema Discovery, Data Contract & Bronze
+./qk-code-review               # Review code, health score (0-100), OWASP, WCAG
+./qk-code-cleaner              # Refactor God files, nâng cấp library, viết test
+./qk-devops-release            # Docker, CI/CD, 8-gate release, docs, RAG
+
+# Hoặc dùng ngôn ngữ tự nhiên — AI tự động nhận diện:
+"biên dịch lại prompt cho task này"        → qk-prompt-compiler
+"fix bug crash màn hình checkout"         → qk-bug-resolution
+"thiết kế api đặt hàng và migration db"   → qk-backend-data
+"phân tích postman và lấy schema bronze"  → qk-api-data-discovery
+"review bảo mật và đo nợ kỹ thuật dự án"  → qk-code-review
+"tách file UserService.ts bị quá dài"     → qk-code-cleaner
+"chuẩn bị release lên production"         → qk-devops-release
+```
+
+---
+
+## Danh Mục 11 Core Super-Skills
+
+| Super-Skill | Phụ Đề Dev (Nhiệm vụ cốt lõi) | Phạm vi & Năng lực thực chiến | Các kỹ năng cũ đã hợp nhất |
+|---|---|---|---|
+| `qk-orchestrator` | **Điều hướng & Context** | Điều phối tổng thể, nạp context đồ thị phụ thuộc (Context Graph), khởi tạo cấu hình dự án (Bootstrap) | `qk-orchestrator`, `qk-context-loader`, `qk-project-bootstrap`, `qk-help` |
+| `qk-prompt-compiler` | **Biên Dịch & Chuẩn Hóa Prompt** | Bộ biên dịch câu lệnh thô (Raw Request) thành Execution Prompt 9 thành phần kỹ thuật, công khai minh bạch trước khi thực thi | *Mới* (tích hợp [PROMPT_RULES.md](./PROMPT_RULES.md)) |
+| `qk-product-spec` | **Viết Spec & PRD** | Đặc tả sản phẩm, phân tích PRD, Acceptance Criteria (BDD/Gherkin), Gap Analysis và Đánh giá tính khả thi | `qk-product-specification`, `qk-project-audit` |
+| `qk-feature-delivery` | **Build Feature mới** | Phát triển tính năng mới trọn gói, tích hợp API Client, xử lý loading/error states, quản lý State | `qk-feature-delivery`, `qk-api-consumer`, `qk-fe-api-integration` |
+| `qk-bug-resolution` | **Debug & Fix Bug** | Chẩn đoán và dập lỗi theo chu trình khép kín 5 bước, loại bỏ giả định mù quáng | `qk-bug-resolution` |
+| `qk-ui-engineer` | **Build UI & Component** | Xây dựng UI component chuẩn Design Tokens, tương tác micro-animations, kiểm toán 57 tiêu chí Anti-Slop | `qk-ui-builder`, `qk-design-system-engineering`, `qk-ui-system-builder`, `qk-ui-audit`, `qk-frontend-architecture` |
+| `qk-backend-data` | **API & Database** | Kiến trúc REST/tRPC API, Database Schema & Migration an toàn, phân quyền RBAC/ABAC, tối ưu EXPLAIN query, Data Pipeline (ETL/dbt) | `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-access-policy`, `qk-db-optimizer`, `qk-data-engineer` |
+| `qk-api-data-discovery` | **Khám Phá API & Data Contract** | Phân tích Postman, thu thập Real Evidence, khám phá Schema & Data Dictionary, đánh giá tầng Bronze Medallion, Checkpoint dừng trước khi code | *Mới* (API-to-Data Engine & Contract Discovery) |
+| `qk-code-review` | **Review Code & Audit** | Đánh giá mã nguồn kiến trúc, đo lường chỉ số nợ kỹ thuật (Health Score 0–100), quét bảo mật OWASP Top 10, kiểm toán chất lượng Web WCAG AA | `qk-code-review`, `qk-project-health`, `qk-security-audit`, `qk-web-quality-gate`, `qk-validation-gate` |
+| `qk-code-cleaner` | **Refactor & Viết Test** | Tái cấu trúc sạch (SOLID, phân tách God files >300L), nâng cấp thư viện tiệm tiến (kèm Rollback plan), kỹ nghệ kiểm thử tự động (Test Pyramid) | `qk-refactor`, `qk-upgrade`, `qk-system-evolution`, `qk-test-engineering`, `qk-engineering-standard` |
+| `qk-devops-release` | **DevOps, CI/CD & Deploy** | Nền tảng CI/CD (Docker, GitHub Actions), cổng kiểm soát phát hành 8-Gate Release, đồng bộ tài liệu (README, OpenAPI), bộ nhớ dự án (`.ai-local/`), AI/RAG Pipeline | `qk-devops-platform`, `qk-production-release`, `qk-docs`, `qk-project-memory`, `qk-ai-builder`, `qk-agent-observability` |
+
+---
+
+## Công Cụ & Scripts Quản Trị
+
+```bash
+# Tái tạo runtime registry O(1) từ 11 Super-Skills:
+node tooling/build-registry.js
+```