ai-developer-skill-os 3.0.0 → 3.1.1

package/.agents/AGENTS.md

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

package/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI / Spec Compliance & Registry Validation
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**'
+      - 'skills.json'
+      - 'docs/SPEC.md'
+      - 'bin/install.js'
+  push:
+    branches: [ main ]
+    paths:
+      - 'skills/**'
+      - 'skills.json'
+      - 'docs/SPEC.md'
+      - 'bin/install.js'
+
+jobs:
+  lint-and-validate:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Validate Skills Registry vs Filesystem
+        run: npm run test:registry
+
+      - name: Validate SKILL.md Spec Compliance
+        run: npm run test
+
+  snapshot:
+    runs-on: windows-latest
+    needs: lint-and-validate
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Generate Registry Snapshot
+        run: node bin/install.js --ide=7 --scope=2

package/CHANGELOG.md

@@ -1,36 +1,53 @@
-# 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).
-
-## [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 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).
+
+## [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/README.md

@@ -1,77 +1,97 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v3.0
-
-> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini).
-
-Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v3.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
-
----
-
-## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
-
-Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
-
-### 1. Global Policy (`.agents/AGENTS.md`)
-Chứa các bộ luật thép toàn cục (Agent-wide rules):
-- **Language Policy:** Suy luận kỹ thuật bằng Tiếng Anh, giao tiếp với người dùng bằng Tiếng Việt.
-- **Execution Principles:** `Read before Write`, `Verify before Complete`.
-- **Engineering Policy:** Trị bệnh tận gốc (Fix root cause), giữ nguyên chuẩn cũ.
-
-### 2. Core Templates (`templates/`)
-Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.
-
-### 3. Skill Definition (`skills/`)
-Bộ 20+ kỹ năng (Skills) cốt lõi được cấu trúc siêu chuẩn xác với **Metadata 12 trường** (Version, Category, Pipeline, Allowed Tools...). Toàn bộ SOP (Standard Operating Procedure), Decision Tree và Constraints được viết 100% bằng Tiếng Anh để tối ưu hóa khả năng hiểu kỹ thuật của AI.
-
-### 4. Knowledge Library (`knowledge/`)
-Tri thức chuyên sâu được tách rời hoàn toàn khỏi Prompt. Ví dụ: Kiến thức về React (`knowledge/frontend/react.md`) chỉ được gọi (On-demand RAG) khi AI thực sự làm việc với React.
-
-### 5. Output Format (Vietnamese Report)
-Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Policy: Báo cáo bằng Tiếng Việt, chia mục rõ ràng (Summary, Changes, Root Cause, Risks, Next Actions).
-
----
-
-## 🧩 Danh sách 20+ Master Skills
-
-Các skill được chia thành các nhóm (Category) rõ ràng:
-- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
-- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
-- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
-- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
-- **Docs & Utils:** `qk-docs`, `qk-documentation-system`, `qk-project-memory`, `qk-help`
-
----
-
-## 🔄 Luồng Handoff Pipeline Khép Kín
-
-Bất cứ một tính năng hay lỗi nào cũng được đi qua một đường ống khép kín (Abstract Pipeline):
-```text
-analyze 
-  ↓
-implement 
-  ↓
-engineering-standard (Ép chuẩn Code, Naming, SOLID)
-  ↓
-validate (Chạy Linter, Tests, Security Check)
-  ↓
-complete (Tạo báo cáo bằng tiếng Việt)
-```
-
----
-
-## 💻 Cách Cài Đặt (Installation)
-
-Sử dụng npm:
-```bash
-npm i -g ai-developer-skill-os
-```
-Hoặc sử dụng qua `npx`:
-```bash
-npx ai-developer-skill-os init
-```
-
-## 🚀 Tra Cứu (Help)
-
-Để tra cứu danh sách toàn bộ 20+ Kỹ năng và các mẹo sử dụng, hãy gọi:
-```bash
-./qk-help "Hiển thị tất cả các skill"
-```
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v4.0
+
+> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini, Kilo).
+
+Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v4.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
+
+---
+
+## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
+
+Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
+
+### 1. OS Kernel (`.agents/AGENTS.md`)
+The core of the system is a lightweight, heavily optimized OS Kernel that dictates agent behavior across all tasks.
+- **Intent-Based Policies:** Skills are classified into 4 groups (Static Analysis, Development, Validation, Maintenance) rather than micromanaged with individual exceptions.
+- **Progressive Evidence Collection:** Agents collect context incrementally (1 file → 3 files) and stop at a 80% Confidence Threshold, eliminating "hallucination loops".
+- **Risk-based Verification:** Tests and builds are only run based on the risk level of the change, strictly guided by the Cost and Escalation policies.
+
+### 2. Core Templates (`templates/`)
+Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.
+
+### 3. Skill Definition (`skills/`)
+Bộ 20+ kỹ năng (Skills) cốt lõi được cấu trúc siêu chuẩn xác với **Metadata 12 trường** (Version, Category, Pipeline, Allowed Tools...). Toàn bộ SOP (Standard Operating Procedure), Decision Tree và Constraints được viết 100% bằng Tiếng Anh để tối ưu hóa khả năng hiểu kỹ thuật của AI.
+
+### 4. Knowledge Library (`knowledge/`)
+Tri thức chuyên sâu được tách rời hoàn toàn khỏi Prompt. Ví dụ: Kiến thức về React (`knowledge/frontend/react.md`) chỉ được gọi (On-demand RAG) khi AI thực sự làm việc với React.
+
+### 5. Output Format (Vietnamese Report)
+Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Policy: Báo cáo bằng Tiếng Việt, chia mục rõ ràng (Summary, Changes, Root Cause, Risks, Next Actions).
+
+---
+
+## 🧩 Danh sách 20+ Master Skills
+
+Các skill được chia thành các nhóm (Category) rõ ràng:
+- **Orchestration:** `qk-orchestrator`, `qk-context-loader`, `qk-policy-engine`, `qk-access-policy`
+- **Engineering / Dev:** `qk-feature-delivery`, `qk-api-lifecycle`, `qk-data-lifecycle`, `qk-design-to-code`, `qk-ui-system-builder`
+- **Validation & Standards:** `qk-validation-gate`, `qk-engineering-standard`, `qk-ui-audit`, `qk-project-health`, `qk-bug-resolution`
+- **Ops & AI:** `qk-system-evolution`, `qk-production-release`, `qk-ai-builder`, `qk-project-bootstrap`
+- **Docs & Utils:** `qk-docs`, `qk-documentation-system`, `qk-project-memory`, `qk-help`
+
+---
+
+## 🔄 Luồng Handoff Pipeline Khép Kín
+
+Bất cứ một tính năng hay lỗi nào cũng được đi qua một đường ống khép kín (Abstract Pipeline):
+```text
+analyze 
+  ↓
+implement 
+  ↓
+engineering-standard (Ép chuẩn Code, Naming, SOLID)
+  ↓
+validate (Chạy Linter, Tests, Security Check)
+  ↓
+complete (Tạo báo cáo bằng tiếng Việt)
+```
+
+---
+
+## 💻 Cách Cài Đặt (Installation)
+
+Sử dụng npm:
+```bash
+npm i -g ai-developer-skill-os
+```
+Hoặc sử dụng qua `npx`:
+```bash
+npx ai-developer-skill-os init
+```
+
+## 🧪 Testing
+
+This project includes a full test suite to ensure registry integrity and SKILL.md spec compliance:
+
+```bash
+npm test
+```
+
+CI runs automatically on every PR via GitHub Actions, enforcing:
+- Registry matches filesystem
+- All SKILL.md frontmatters comply with `docs/SPEC.md`
+- Install script idempotency
+
+## 🗑️ Cách Gỡ Cài Đặt (Uninstallation)
+
+Nếu bạn đã cài đặt thông qua npm global, bạn có thể gỡ bỏ bằng lệnh:
+```bash
+npm uninstall -g ai-developer-skill-os
+```
+
+## 🚀 Tra Cứu (Help)
+
+Để tra cứu danh sách toàn bộ 20+ Kỹ năng và các mẹo sử dụng, hãy gọi:
+```bash
+./qk-help "Hiển thị tất cả các skill"
+```

package/bin/install.js

@@ -237,8 +237,20 @@ Nếu người dùng sử dụng tham số (argument), bạn BẮT BUỘC phải
         }
 
         if (fs.existsSync(ruleFilePath)) {
-          fs.appendFileSync(ruleFilePath, "\n\n" + writeContent);
-          console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFilePath}`);
+          const existingContent = fs.readFileSync(ruleFilePath, 'utf8');
+          const marker = isGemini ? '<RULE[ai_skill_os]>' : '[Role]\nYou are an elite AI Software Engineer.';
+          const markerIndex = existingContent.indexOf(marker);
+          if (markerIndex !== -1) {
+            const before = existingContent.substring(0, markerIndex);
+            const after = existingContent.substring(markerIndex).split('\n').slice(isGemini ? 2 : 1).join('\n');
+            const lastMarkerEnd = after.indexOf(isGemini ? '</RULE[ai_skill_os]>' : '[Trigger Mechanism]');
+            const actualAfter = lastMarkerEnd !== -1 ? after.substring(lastMarkerEnd + (isGemini ? 19 : 18)).trimStart() : after;
+            fs.writeFileSync(ruleFilePath, before + writeContent.trimStart() + (actualAfter ? '\n' + actualAfter : '') + '\n');
+            console.log(`✅ Đã CẬP NHẬT cấu hình tự động trong file: ${ruleFilePath}`);
+          } else {
+            fs.appendFileSync(ruleFilePath, "\n\n" + writeContent);
+            console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFilePath}`);
+          }
         } else {
           fs.writeFileSync(ruleFilePath, writeContent);
           console.log(`✅ Đã TẠO MỚI file cấu hình: ${ruleFilePath}`);

package/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 v5.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.

package/docs/SPEC.md

@@ -0,0 +1,37 @@
+# AI Developer Skill OS - Specification (v4)
+
+This document defines the strict contract and schema for developing Custom Skills in the AI Developer Skill OS. The metadata frontmatter is frozen to ensure cross-platform compatibility (Cursor, Claude Code, Windsurf, Gemini).
+
+## 1. Frontmatter Contract (YAML)
+
+Every `SKILL.md` must begin with this exact YAML structure. Do not add, remove, or rename fields.
+
+```yaml
+---
+name: qk-[skill-name]
+version: X.Y.Z
+updated: YYYY-MM-DD
+description: Brief summary of what this skill accomplishes.
+behavior: static-analysis | development | validation | maintenance
+intent: review-code | fix-bug | implement-feature | validate | maintain
+priority: low | medium | high | critical
+tags: [tag1, tag2]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: Natural language phrase that activates this skill.
+inputs: [Required inputs]
+outputs: [Expected outputs]
+allowed_tools: [Tool1, Tool2]
+pipeline: [analyze, plan, implement, validate, complete]
+---
+```
+
+## 2. Skill Body Structure (Markdown)
+
+The body of the `SKILL.md` file MUST contain the following sections:
+
+1. **Goal:** The core objective of the skill.
+2. **Chain of Thought (SOP):** The exact step-by-step reasoning the agent must follow.
+3. **Constraints & Rules:** Hard boundaries and limits for this specific skill.
+4. **Handoff Pipeline (Optional):** How this skill transitions to the next phase (e.g. passing to validation).
+
+*Note: Skill documents MUST NOT declare Verification Levels or override Tool Efficiency policies. Those are exclusively managed by the Global Kernel (`AGENTS.md`).*

package/docs/adr/0001-intent-based-architecture.md

@@ -0,0 +1,19 @@
+# 1. Intent-Based Architecture
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+As the framework grew from 5 to 20+ skills, managing individual tool permissions and specific verification overrides within each `SKILL.md` became a maintenance nightmare (violating DRY). Agents were also suffering from "context bloat" because they had to read sprawling, repetitive rules across different skills.
+
+## Decision
+We transitioned from a "Rule-Based" architecture to an "Intent-Based" architecture. 
+- Skills no longer define their own verification exceptions or tool usage logic. 
+- Instead, skills declare their `behavior` and `intent` via frozen YAML metadata. 
+- The OS Kernel (`AGENTS.md`) intercepts these intents and automatically applies the correct global routing and execution constraints based on the categorized behavior.
+
+## Consequences
+- **Positive:** Massive reduction in skill file size. Easier to scale to 100+ skills. Centralized logic in the Kernel. Agent routing is drastically improved due to clear `intent` mapping.
+- **Negative:** Less granular control over unique outliers, but this enforces better standardization.

package/docs/adr/0002-kernel-freeze.md

@@ -0,0 +1,21 @@
+# 2. Kernel Freeze
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+The Global Policy file (`AGENTS.md`), which acts as the OS Kernel, was continuously expanding. Policies like Language, Decision, Engineering, Output, Tool Efficiency, Context Budget, and Escapation were all piled into a single document, threatening to balloon past 1,000 lines. A bloated kernel leads to Agent Hallucinations (due to context window pressure) and conflicting priorities.
+
+## Decision
+We officially "Freeze" the Kernel (`AGENTS.md`) at v4.0.0. The file is strictly rewritten to under 100 lines using absolute Rules (MUST/MUST NOT) and Guidelines (Prefer/Avoid). 
+Moving forward, no new policies will be added to the Kernel. All future expansions must occur at the higher layers:
+- New Capabilities
+- New Skills
+- New Knowledge documents
+- New Templates
+
+## Consequences
+- **Positive:** The baseline ruleset is locked, highly token-efficient, and easily digestible by any LLM. The framework achieves enterprise stability.
+- **Negative:** Feature requests that require global policy shifts will be rejected by default unless they fundamentally rewrite the OS paradigm.

package/docs/adr/0003-risk-based-verification.md

@@ -0,0 +1,20 @@
+# 3. Risk-based Verification
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+Previously, Verification Levels were hardcoded into the Skill Classification (e.g., Development skills automatically forced Level 2 Verification, meaning test suites were run regardless of the actual change). This caused conflicting behavior. For example, fixing a typo in a comment using the `qk-bug-resolution` skill would still trigger a test run, wasting time and resources. 
+
+## Decision
+We completely decoupled Verification Levels from Skill Classifications. 
+Skills now only define their "Preferred Evidence Strategy". The actual depth of verification is determined strictly by the **Risk-based Verification Policy** in the Kernel (`AGENTS.md`).
+- Level 0 (Low Risk): Comments, typos (Static Analysis only).
+- Level 2 (Medium Risk): Logic changes (Targeted tests).
+- Level 3 (High Risk): Auth, DB (Full validation).
+
+## Consequences
+- **Positive:** Agents no longer blindly run tests for trivial changes. Verification scales with the danger of the code being modified, vastly improving speed and token efficiency.
+- **Negative:** Agents must use logic to evaluate the "Risk" of their own changes before deciding whether to run a test.