ai-developer-skill-os 7.5.0 → 8.1.4

package/.agents/workflows/skill-evolution.yml

@@ -0,0 +1,65 @@
+name: skill-evolution
+description: "Workflow vòng lặp tiến hóa và tối ưu hóa skill (Skill Evolution)."
+version: 1.0.0
+
+steps:
+  - id: observe_usage
+    name: "Observe Usage"
+    purpose: "Theo dõi cách skill được sử dụng"
+    required: true
+    inputs: [skill_logs]
+    outputs: [usage_metrics]
+    actions:
+      - "Thống kê trigger rate và token usage"
+
+  - id: measure_success
+    name: "Measure Success"
+    purpose: "Đánh giá tỷ lệ thành công"
+    required: true
+    inputs: [usage_metrics, execution_results]
+    outputs: [success_rate]
+    actions:
+      - "Xác định các lần exit SUCCESS vs FAILED/PARTIAL"
+
+  - id: detect_failure
+    name: "Detect Failure Patterns"
+    purpose: "Phát hiện lý do thất bại"
+    required: true
+    inputs: [execution_results]
+    outputs: [failure_patterns]
+    actions:
+      - "Phân tích log lỗi, hallucination, out of budget"
+
+  - id: improve_skill
+    name: "Improve Skill"
+    purpose: "Đề xuất tối ưu skill"
+    required: true
+    inputs: [failure_patterns, skill_body]
+    outputs: [improved_skill_proposal]
+    actions:
+      - "Giảm noise trong instruction"
+      - "Cập nhật examples và learnings"
+      - "Tinh chỉnh token budget"
+
+  - id: validate_improvement
+    name: "Validate Improvement"
+    purpose: "Xác thực bản nâng cấp"
+    required: true
+    inputs: [improved_skill_proposal]
+    outputs: [validation_result]
+    actions:
+      - "Chạy qua validate-skills.js"
+      - "Kiểm tra schema compliance"
+
+  - id: promote
+    name: "Promote Skill"
+    purpose: "Đưa bản cải tiến vào sử dụng"
+    required: true
+    inputs: [validation_result]
+    outputs: [stable_skill]
+    actions:
+      - "Chuyển status thành stable"
+
+escalation:
+  max_retries: 1
+  on_failure: "Hủy bỏ bản cải tiến nếu validation thất bại"

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

@@ -0,0 +1,57 @@
+name: spec-driven-development
+description: "Workflow phát triển dựa trên đặc tả (Specification-Driven Development)."
+version: 1.0.0
+
+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"
+      - "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ị"

package/CHANGELOG.md

@@ -1,69 +1,91 @@
-# 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/`.
+# 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.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/README.md

@@ -1,81 +1,86 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v7.0.0
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v8.1.4
 
-> **V7.0.0 "Anti-Slop & Zero-Trust Architecture"**
+> **v8.1.4 "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.4 đượ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-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`, `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)
 
-Sử dụng npm:
+### 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
 ```
 
-### Antigravity (Global)
-Cài 1 lần, áp dụng cho mọi dự án trên máy:
+### Cách 2: NPM Global (Khuyên dùng cho cá nhân)
 ```bash
-npm run install:antigravity
+npm i -g ai-developer-skill-os
 ```
 
-### Antigravity (Local — per project)
-Cài riêng cho dự án hiện tại, override global:
+### Chạy bằng tham số (Command Line Arguments)
 ```bash
-npm run install:antigravity:local
-```
+# Cài Antigravity Global (toàn máy)
+npx ai-developer-skill-os init --ide=antigravity --scope=2
 
-### Các IDE khác
-```bash
-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 (CLAUDE.md + .qk-ai-skill-os)
-```
+# Cài Antigravity Local (chỉ dự án này)
+npx ai-developer-skill-os init --ide=antigravity --scope=1
 
-Hoặc khởi tạo thông qua `npx`:
-```bash
-npx ai-developer-skill-os init
+# Cài Cursor Local
+npx ai-developer-skill-os init --ide=cursor --scope=1
 ```
 
-## 🧪 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
+
+---
+
+## 🧪 Đánh Giá Tự Động (Agent Evaluation)
 
-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:
+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!