ai-developer-skill-os 7.5.0 → 8.1.4

package/docs/GOVERNANCE.md

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

package/docs/HUONG_DAN_SU_DUNG.md

@@ -1,120 +0,0 @@
-# Hướng Dẫn Sử Dụng — AI Developer Skill OS
-
-**Tác giả:** Quang Khánh  
-**Phiên bản:** v7.5.0 (Anti-Slop & Zero-Trust Architecture)
-
-Chào mừng bạn đến với **AI Developer Skill OS**, hệ điều hành kỹ năng (Skill Framework) biến các trợ lý AI (Gemini, Antigravity, Claude Code, Cursor, Windsurf) từ một "cỗ máy sinh code" thành một **Senior Software Engineer / Chief Architect** thực thụ với khả năng tự học, tự kiểm toán và tự viết tài liệu.
-
----
-
-## 1. Cơ chế hoạt động (Tại sao lại cần Skin/Skill này?)
-
-Thông thường, khi bạn yêu cầu AI "Làm cho tôi tính năng X", AI sẽ nhảy ngay vào viết code. Điều này ở các dự án lớn thường dẫn đến: phá vỡ kiến trúc, tạo ra code rác, và không tuân thủ các component dùng chung.
-
-Với hệ điều hành 22 Master Skills này:
-1. Bạn đưa ra yêu cầu thông qua **`qk-orchestrator`**.
-2. Hệ thống sẽ tự động gọi **`qk-context-loader`** để gom đúng file (tránh tràn ngữ cảnh).
-3. Kế tiếp, **`qk-engineering-standard`** sẽ gắn các "luật thép" (rules) của dự án vào ngữ cảnh.
-4. AI kích hoạt kỹ năng thực thi E2E như **`qk-feature-delivery`** để code và test trọn vẹn.
-5. Cuối cùng, **`qk-validation-gate`** chặn lại kiểm tra lỗi, trước khi giao cho **`qk-docs`** tự động cập nhật tài liệu.
-
----
-
-## 2. Hướng dẫn cài đặt qua NPM (Khuyên dùng)
-
-Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn có thể cài vào bất kỳ dự án nào cực kỳ nhanh chóng.
-
-Mở terminal tại gốc dự án của bạn và chạy lệnh cài đặt tương ứng với công cụ AI bạn đang dùng:
-
-```bash
-npx ai-developer-skill-os init
-```
-
-Quá trình cài đặt sẽ hỏi bạn 2 câu quan trọng:
-
-**Câu 1: Bạn đang dùng IDE nào?**
-Hệ thống sẽ tự động tạo file cấu hình tương ứng (ví dụ `.cursorrules`, `.windsurfrules`, `.clinerules`) và bơm sẵn System Prompt vào để AI tự nhận diện các skill.
-
-**Câu 2: Phạm vi cài đặt?**
-- **(1) Local:** Cài vào thư mục `skills/` (hoặc `.agents/` cho Gemini) ngay trong dự án. Thích hợp cho làm việc nhóm.
-- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Chỉ cài 1 lần, áp dụng cho mọi dự án.
-
-> 💡 **Tính năng Tự động Dọn dẹp (Auto-Cleanup):** Mỗi khi cài đặt lại, hệ thống sẽ tự động quét và xóa sạch các kỹ năng phiên bản cũ để tối ưu dung lượng và tránh xung đột cho máy tính của bạn. Mọi thứ hoàn toàn tự động!
-
-### Cấu hình thủ công (Dành cho IDE / CLI cụ thể)
-
-#### Cho Gemini IDE / Antigravity
-**Không cần cấu hình gì thêm!** Hệ thống tự nhận diện các file trong `.agents/` hoặc thư mục cấu hình toàn cục.
-
-#### Cho Cursor / Windsurf (AI Code Editors)
-Tạo file `.cursorrules` hoặc `.windsurfrules` ở gốc dự án:
-```md
-# AI Developer Skill OS by Quang Khánh
-
-When answering or generating code, you MUST act as an expert engineer using the skills defined in `./skills.json`.
-Bất cứ khi nào người dùng gõ lệnh `./qk-[tên-skill]`, bạn BẮT BUỘC phải đọc file `SKILL.md` tương ứng trong thư mục `./skills/` trước khi thực hiện.
-Speak to me in Vietnamese, but write all code in English.
-```
-
-#### Cho Claude Code / Kilo Code (CLI Agents)
-Tạo file `CLAUDE.md` (hoặc `KILO.md`) ở gốc dự án và dán đoạn sau vào:
-```md
-# System Instructions
-Bạn đang chạy bằng **AI Developer Skill OS** (Tác giả: Quang Khánh).
-
-Vui lòng tìm đọc danh sách kỹ năng tại file `./skills.json`.
-ĐẶC BIỆT LƯU Ý: Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng `./qk-[tên-skill]`, bạn BẮT BUỘC phải gọi và đọc nội dung file `SKILL.md` tương ứng trong thư mục `./skills/` trước khi phân tích hoặc viết code.
-```
-
----
-
-## 3. Cách kiểm tra cài đặt thành công
-
-Để biết AI của bạn đã thực sự "nhập môn" bộ AI-OS này chưa, hãy mở khung chat AI trong dự án và gõ cú pháp lệnh:
-> **`./qk-help`** Hãy liệt kê cho tôi các khối kỹ năng của hệ thống.
-
-✅ **Thành công:** Nếu AI trả lời bằng tiếng Việt, liệt kê đúng mô hình 7 Lớp (Foundation, UI, Development, Quality, Evolution, Operation, AI, Knowledge).
-❌ **Thất bại:** Nếu AI trả lời chung chung, bạn cần kiểm tra lại đường dẫn file cấu hình ở bước trên.
-
----
-
-## 4. Cách gọi lệnh Skill chuyên nghiệp (Usage)
-
-AI sẽ tự động nhận diện skill qua ngữ cảnh, nhưng cách chuyên nghiệp và tiết kiệm thời gian nhất là bạn sử dụng cú pháp: **`./qk-[tên-skill]`**
-
-Dưới đây là các câu lệnh (prompt) mẫu cực kỳ hiệu quả mà bạn nên dùng:
-
-### 🎯 Ví dụ 1: Giao phó tổng thể (Orchestrator)
-> **`./qk-orchestrator`** Tôi muốn thêm tính năng Đăng nhập bằng Google. Hãy lên kế hoạch và gọi các skill cần thiết để thực hiện từ A-Z.
-
-### 🎯 Ví dụ 2: Phát triển Tính năng E2E (Feature Delivery)
-> **`./qk-feature-delivery`** Hãy tạo màn hình Dashboard thống kê doanh thu. Lưu ý cập nhật Database, tạo API và dùng UI Component có sẵn.
-
-### 🎯 Ví dụ 3: Fix lỗi cứng đầu (Bug Resolution)
-> **`./qk-bug-resolution`** Code đang bị crash với lỗi `Hydration error`. Hãy tìm Root Cause, sửa an toàn và đảm bảo viết Regression Test để chống hồi quy.
-
-### 🎯 Ví dụ 4: Xây dựng Giao diện (UI System Builder)
-> **`./qk-ui-system-builder`** Hãy tạo cho tôi một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token của dự án. Không viết inline CSS rác.
-
-### 🎯 Ví dụ 5: Audit & Tối ưu (Project Health)
-> **`./qk-project-health`** Hãy kiểm tra nhanh cho tôi thư mục `src/components/` xem có bị Code Smell hoặc vi phạm Architecture không.
-
----
-
-## 💡 5. Mẹo & Workflow Thực Chiến (Best Practices)
-
-Để khai thác tối đa sức mạnh của 22 kỹ năng, bí quyết là **tin tưởng vào chuỗi Handoff tự động** của hệ thống thay vì phải gọi từng lệnh nhỏ lẻ.
-
-### 🌟 Bắt đầu một tính năng hoàn toàn mới
-Thay vì bảo AI tạo từng file, hãy yêu cầu một lần:
-* `> Hãy dùng ./qk-feature-delivery để tạo chức năng Giỏ hàng (Cart).`
-Hệ thống sẽ tự động đi từ DB -> API -> UI và đẩy sang `qk-validation-gate` để kiểm tra lỗi.
-
-### 🌟 Khi dự án bắt đầu lộn xộn
-* `> Hãy chạy ./qk-project-health để kiểm tra toàn bộ nợ kỹ thuật (Tech Debt). Sau đó hãy dùng ./qk-docs để cập nhật lại cấu trúc thư mục mới nhất vào README.`
-
-### 🌟 Chống "Phá Code" (Safe Refactor)
-Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
-* `> Hãy dùng ./qk-system-evolution để phân tích tầm ảnh hưởng (Impact Analysis) nếu tôi cập nhật Next.js lên phiên bản 15.`
-
-👉 Chúc bạn tận hưởng cảm giác code như một Chief Architect thực thụ!

package/docs/SPEC.md

@@ -1,87 +0,0 @@
-# AI Developer Skill OS - Specification (v7.5)
-
-This document defines the strict contract and schema for all `SKILL.md` files in the AI Developer Skill OS. Every active skill MUST comply with this specification. The frontmatter is frozen to ensure cross-platform compatibility and deterministic agent behavior.
-
-## 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]
-category: [core|frontend|backend|fullstack|security|qa|maintenance|devops|utilities]
-version: X.Y.Z
-description: "[One sentence — what this skill does]"
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
-
-# Orchestrator routing metadata
-cost: [low|medium|high]
-latency: [fast|medium|slow]
-risk: [low|medium|high]
-side_effects: [edit_files|run_commands|read_only|none]
-produces: [report|code|schema|plan|tokens]
-consumes: [context-graph|design-md|stack-trace|json-payload|none]
-
-token_budget:
-  max_files_read: 3
-  max_lines_per_read: 150
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-```
-
-### Field Definitions
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | YES | Skill identifier, must start with `qk-` |
-| `category` | enum | YES | Primary domain: `core`, `frontend`, `backend`, `fullstack`, `security`, `qa`, `maintenance`, `devops`, `utilities` |
-| `version` | semver | YES | Semantic version of this skill |
-| `description` | string | YES | One-sentence summary of the skill's purpose |
-| `platforms` | array | YES | Supported AI platforms. Valid values: `antigravity`, `claude-code`, `cursor`, `windsurf`, `kilo-code` |
-| `execution_mode` | string | YES | Must be `deterministic` for all v7.5 skills |
-| `cost` | enum | YES | Token/compute cost: `low`, `medium`, `high` |
-| `latency` | enum | YES | Expected execution speed: `fast`, `medium`, `slow` |
-| `risk` | enum | YES | Risk level of side effects: `low`, `medium`, `high` |
-| `side_effects` | enum | YES | What the skill modifies: `edit_files`, `run_commands`, `read_only`, `none` |
-| `produces` | array | YES | Output artifacts: `report`, `code`, `schema`, `plan`, `tokens` |
-| `consumes` | array | YES | Required inputs: `context-graph`, `design-md`, `stack-trace`, `json-payload`, `none` |
-| `token_budget.max_files_read` | int | YES | Maximum files to read before stopping |
-| `token_budget.max_lines_per_read` | int | YES | Maximum lines per file read operation |
-| `token_budget.max_shell_commands` | int | YES | Maximum shell commands allowed |
-| `token_budget.stop_early` | bool | YES | Whether to stop when confidence threshold is reached |
-| `exit_codes` | array | YES | Valid exit codes for this skill |
-
-## 2. Skill Body Structure (Markdown)
-
-The body of the `SKILL.md` file MUST contain the following sections in order:
-
-1. **Header:** Skill title and language rule
-2. **Preconditions:** Checklist of required inputs/state before execution
-3. **Scope:** What the skill explicitly does (✅) and does not do (❌)
-4. **Priority Order:** P1–P4 checks with skip thresholds for token budget management
-5. **Workflow:** Phased execution steps with explicit decision trees and exit conditions
-6. **Confidence Model:** HIGH/MEDIUM/LOW confidence levels with actions
-7. **Severity:** CRITICAL/HIGH/MEDIUM/LOW severity definitions with examples
-8. **Evidence Format:** Mandatory template for all findings
-9. **Retry Policy:** Retry logic with maximum attempt limits
-10. **Escalation Rules:** Structured BLOCKED response format
-11. **Handoff Contract:** JSON schema for `Consumes` and `Produces`
-12. **Output Format:** Mandatory output template
-13. **Exit Codes:** Table mapping codes to meanings
-
-## 3. Naming Conventions
-
-- Skill files: `skills/qk-[skill-name]/SKILL.md`
-- Registry entry: `qk-[skill-name]`
-- All code, identifiers, and file names: English only
-- Explanations and reports: Vietnamese (match user language)
-
-## 4. Compliance Enforcement
-
-- All skills MUST pass `npm run lint` (which validates frontmatter against this spec)
-- The `## Compliance` table at the bottom of each `SKILL.md` is deprecated and MUST be removed
-- CI pipeline enforces schema compliance automatically

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

@@ -1,19 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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.

package/docs/adr/0004-progressive-evidence.md

@@ -1,19 +0,0 @@
-# 4. Progressive Evidence Collection
-
-Date: 2026-07-02
-
-## Status
-Accepted
-
-## Context
-AI Agents frequently fall into "hallucination loops" or "over-exploration loops", running commands like `ls`, `tree`, or reading entire project directories just to find one file. This burns through context windows rapidly and leads to poor reasoning.
-
-## Decision
-We implemented a strict **Progressive Evidence Collection** pipeline inside the OS Kernel (`AGENTS.md`):
-- **Context Budget:** Agents must start by reading 1 file, then 3 files, then a directory. They must never read the whole project unless explicitly required.
-- **Sufficient Confidence:** Agents must stop collecting evidence the moment they reach an 80% confidence threshold to proceed. 
-- **Evidence Priority:** User input > Existing context > Source code > Types > Logs > Runtime > External knowledge.
-
-## Consequences
-- **Positive:** Drastically reduced unnecessary `run_command` usage. Agents act much more like senior developers who pinpoint issues via stack traces instead of blindly searching the filesystem.
-- **Negative:** Requires rigorous enforcement in the Kernel to prevent agents from falling back to old habits.

package/docs/skill-classification.md

@@ -1,25 +0,0 @@
-# Skill Classifications (Intent-Based Policies)
-
-Skills are classified into behavioral groups that define their **Primary Objective** and **Preferred Evidence Strategy**.
-
-*Note: Actual verification depth is NOT determined by the skill itself, but must strictly follow the **Risk-based Verification Policy** defined in `AGENTS.md`.*
-
-## 1. Static Analysis Skills
-*e.g., Code Review, Project Health, Architecture, Documentation*
-- **Primary Goal:** Audit, analyze, or document without altering system behavior.
-- **Preferred Behavior:** Prefer static analysis (`read_file`, `grep_search`). Do not execute code or run test suites unless explicitly requested to validate the audit.
-
-## 2. Development Skills
-*e.g., Feature Delivery, Refactor, Bug Resolution*
-- **Primary Goal:** Modify existing behavior or implement new features safely.
-- **Preferred Behavior:** Apply localized changes. Gather targeted evidence. Avoid speculative full-project validation; verify only what is affected.
-
-## 3. Validation Skills
-*e.g., Validation Gate, CI Check, Release*
-- **Primary Goal:** Ensure code quality, security, and build stability before release.
-- **Preferred Behavior:** Exhaustive scanning. Running automated checks and full builds is encouraged to satisfy the validation gate.
-
-## 4. Maintenance Skills
-*e.g., System Evolution, Dependency Update*
-- **Primary Goal:** Upgrade system foundations safely with a rollback strategy.
-- **Preferred Behavior:** Inspect changelogs and compatibility carefully before updating. Run full system verifications post-update to ensure stability.

package/fix_seeds.js

@@ -1,22 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml'); // Note: might not be installed
-
-const skillsDir = 'd:\\ai-code-skin-mcp\\rules-skill\\skills';
-const seeds = ['qk-bug-resolution', 'qk-feature-delivery', 'qk-access-policy', 'qk-engineering-standard', 'qk-context-loader', 'qk-orchestrator'];
-
-seeds.forEach(seed => {
-  const specPath = path.join(skillsDir, seed, 'BEHAVIOR_SPEC.md');
-  const skillPath = path.join(skillsDir, seed, 'SKILL.md');
-  if (fs.existsSync(specPath)) {
-    const raw = fs.readFileSync(specPath, 'utf8');
-    // Using simple string parsing since js-yaml might not be available
-    let md = ---\nname:  + seed + \nversion: 6.0.0\n---\n\n;
-    md += #  + seed + \n\n;
-    md += This file follows the 6-Field Minimal Core v6 architecture.\n\n;
-    md += raw;
-    fs.writeFileSync(skillPath, md);
-    fs.unlinkSync(specPath);
-    console.log('Fixed', seed);
-  }
-});

package/framework/KERNEL.md

@@ -1,83 +0,0 @@
-# 📘 Behavior Specification Format (BSF) - Kernel v6.0
-
-> **Rule-Skins v6 is a Behavior Specification Format.**
-> BSF không phải thư viện prompt, không phải agent framework. 
-> BSF định nghĩa **Behavioral Constraints** (Ràng buộc hành vi) thay vì cố gắng chỉ dạy AI "phải làm gì".
-
----
-
-## 🧭 1. Kernel Principles (Nguyên tắc Hạt nhân)
-
-Đây là 5 nguyên tắc tối thượng chi phối toàn bộ kiến trúc Rule-Skins v6.
-
-1. **Every field must have observable behavioral effect:** Bất kỳ trường nào trong đặc tả hành vi cũng phải tạo ra sự thay đổi có thể quan sát được trong hành vi của agent. Nếu không, nó là nhiễu (noise) và phải bị xóa.
-2. **Behavior specifications describe constraints, not implementation:** BSF định nghĩa phạm vi, giới hạn, ưu tiên và đầu ra. Cách suy luận và lên kế hoạch được nhường lại cho LLM tự tối ưu.
-3. **Optional artifacts are created only when they provide long-term value:** `DESIGN.md`, `RATIONALE.md` hay thư mục `specs/` chỉ được tạo ra khi độ phức tạp của hành vi đòi hỏi. Đừng tạo các file/thư mục rỗng.
-4. **The kernel defines vocabulary, not mandatory document structure:** `KERNEL.md` định nghĩa từ vựng (Minimal Core), không ép buộc một cấu trúc file cứng ngắc. Skill nào cần trường nào thì dùng trường đó.
-5. **Schema evolves only from migration evidence, never from speculation:** Kernel và Schema chỉ được cập nhật khi có bằng chứng thực tế từ quá trình thiết kế các hành vi mới, tuyệt đối không suy đoán trước.
-
----
-
-## 💎 2. Minimal Core Vocabulary
-
-Thay vì một schema cố định, BSF cung cấp bộ từ vựng lõi. Mỗi `BEHAVIOR_SPEC.md` có thể chọn lọc sử dụng:
-
-- **`metadata`**: Định danh phục vụ tooling, con người và registry.
-- **`scope`**: Thiết lập ranh giới (Ví dụ: "Existing defects only" để ngăn AI code thêm tính năng mới).
-- **`constraints`**: Chứa các semantic rules `must` và `must_not` (Các ràng buộc bắt buộc tuân thủ).
-- **`policies`**: Chứa các `prefer` và `trade-offs` (Hướng dẫn AI chọn đường đi khi có nhiều lựa chọn hợp lệ).
-- **`escalation`**: Kích hoạt điều kiện "Dừng và Hỏi" hoặc "Từ chối".
-- **`output`**: Quy định định dạng artifact phải trả về.
-
----
-
-## 🛡️ 3. OS-Level Invariants (Luật Bất biến)
-
-Dưới đây là các ràng buộc áp dụng cho mọi skill mà không cần khai báo lại:
-
-```yaml
-OS_Invariants:
-  Security:
-    never:
-      - guess_passwords
-      - hardcode_secrets
-      - bypass_auth
-  UX_Interaction:
-    never:
-      - expose_internal_contract
-      - expose_internal_policy
-      - expose_internal_reasoning
-      - quote_yaml_sections
-    must:
-      - communicate_like_senior_engineer
-      - ask_only_necessary_questions
-      - explain_decisions_in_user_language
-```
-
----
-
-## 📁 4. Kiến trúc Thư mục (v6)
-
-```text
-rules-skill/
-├── framework/
-│   ├── KERNEL.md (Bộ luật lõi)
-│   └── behavior-patterns.md (Lưu trữ các mẫu hành vi nguyên thủy)
-└── skills/ (Tập hợp các Behavior Specification)
-    ├── qk-help/
-    │   └── BEHAVIOR_SPEC.md (Skill đơn giản chỉ cần 1 file)
-    └── qk-bug-resolution/
-        ├── BEHAVIOR_SPEC.md
-        ├── RATIONALE.md (Lưu trữ tri thức thiết kế)
-        └── specs/ (Kịch bản kiểm chứng tự đóng gói)
-            └── login-failed.yaml
-```
-
----
-
-## 🚀 5. Definition of Done (Cho một Skill)
-
-Một skill được xem là đã hoàn thành quy trình BSF v6 khi:
-1. Có `BEHAVIOR_SPEC.md` với các trường có tác động hành vi rõ rệt.
-2. Nếu phức tạp, có thêm `RATIONALE.md` giải thích lý do thiết kế.
-3. Nếu cần test, có các file `.yaml` chứa kịch bản và kỳ vọng khép kín trong `specs/`.

package/framework/bias-library/cosmetic-refactor.md

@@ -1,21 +0,0 @@
----
-id: cosmetic-refactor
-type: bias
-description: LLM frequently rename variables or restructures code purely for aesthetic reasons without architectural improvement.
----
-
-Detection:
-- Did I only rename variables (e.g. `data` to `userData`)?
-- Did I fail to split God Objects or reduce coupling?
-
-Risk:
-- High noise in Git diffs.
-- Low return on investment (ROI).
-- Potential regression for zero architectural gain.
-
-Correction:
-- Reject cosmetic-only changes.
-- Focus strictly on decoupling, dependency injection, or SOLID violations.
-
-Evidence:
-- Explain explicitly why the new structure scales better or is more decoupled.

package/framework/bias-library/enterprise-crud.md

@@ -1,21 +0,0 @@
----
-id: enterprise-crud
-type: bias
-description: LLM suggests overly complex architectures (Kafka, Redis, Microservices) for simple CRUD operations.
----
-
-Detection:
-- Did I introduce message queues, caching layers, or gRPC for a simple REST API?
-- Did I split a simple app into multiple microservices?
-
-Risk:
-- Severe over-engineering.
-- Unnecessary infrastructure costs.
-- Reduced maintainability for small teams.
-
-Correction:
-- Default to Monolith + PostgreSQL.
-- Only introduce caching or queues if a specific bottleneck is identified by evidence.
-
-Evidence:
-- Must provide exact metrics or requirements that justify the complex architecture.

package/framework/bias-library/fake-ui-slop.md

@@ -1,20 +0,0 @@
----
-id: fake-ui-slop
-type: bias
-description: LLM draws fake charts, images, or dashboard UI elements using generic div blocks instead of integrating real assets.
----
-
-Detection:
-- Did I use `<div class="bg-blue-500 w-full h-32">Fake Chart</div>`?
-- Did I forget to add placeholders for real images?
-
-Risk:
-- Unprofessional UI design.
-- Technical debt for the frontend developer.
-
-Correction:
-- Insert a comment like `<!-- TODO: Insert real image -->`.
-- Use high-quality placeholder services (e.g., picsum).
-
-Evidence:
-- Highlight the exact placeholder used.

package/framework/bias-library/hallucinated-tools.md

@@ -1,20 +0,0 @@
----
-id: hallucinated-tools
-type: bias
-description: LLM invents APIs, tools, or shell commands that do not exist in the current environment.
----
-
-Detection:
-- Did I attempt to call a CLI tool without verifying it is installed?
-- Did I invent a non-existent method on a standard library?
-
-Risk:
-- Execution failure.
-- Broken workflows.
-
-Correction:
-- Verify tools and APIs before using them.
-- Stick to standard, known commands.
-
-Evidence:
-- Provide documentation or link to the specific tool usage.

package/framework/bias-library/missing-ui-states.md

@@ -1,19 +0,0 @@
----
-id: missing-ui-states
-type: bias
-description: LLM writes frontend components assuming the "happy path" only, ignoring Loading, Error, and Empty states.
----
-
-Detection:
-- Did I write a fetch component without a loading spinner?
-- Did I forget to handle the case where the data array is empty?
-
-Risk:
-- Poor user experience.
-- UI crashes on undefined data.
-
-Correction:
-- Always implement Loading, Error, and Empty states for any asynchronous UI component.
-
-Evidence:
-- Point to the conditional rendering logic.

package/framework/bias-library/over-indexing.md

@@ -1,20 +0,0 @@
----
-id: over-indexing
-type: bias
-description: LLM recommends adding database indexes to every column to "improve performance", ignoring write penalties.
----
-
-Detection:
-- Did I suggest indexing a column with low cardinality (e.g., boolean status)?
-- Did I suggest indexing multiple columns without analyzing query patterns?
-
-Risk:
-- Slower INSERT/UPDATE operations.
-- Increased database storage costs.
-
-Correction:
-- Only recommend indexes for Foreign Keys or heavily filtered/sorted columns.
-- Suggest resolving N+1 queries first.
-
-Evidence:
-- Provide the exact slow query that justifies the index.

package/framework/bias-library/swallow-errors.md

@@ -1,19 +0,0 @@
----
-id: swallow-errors
-type: bias
-description: LLM wraps code in a try/catch block but leaves the catch block empty or just logs to console, effectively hiding fatal errors.
----
-
-Detection:
-- Did I write `catch (e) { console.error(e) }` without throwing or returning an error state?
-- Did I fail to surface the error to the UI?
-
-Risk:
-- Silent failures.
-- Extremely difficult debugging.
-
-Correction:
-- Always handle the error gracefully (e.g., return a unified error object or show a toast notification).
-
-Evidence:
-- Point to the specific error handling logic.

package/framework/bias-library/ui-only-security.md

@@ -1,17 +0,0 @@
----
-id: ui-only-security
-type: bias
-description: LLM hides a button on the UI for unauthorized users but forgets to secure the backend API endpoint.
----
-
-Detection:
-- Did I add a role check in the React component but not in the Node.js controller?
-
-Risk:
-- Critical security vulnerability (users can bypass UI and hit the API directly).
-
-Correction:
-- Security must always be enforced at the Backend/API layer first. UI hiding is just for UX.
-
-Evidence:
-- Point to the backend middleware or controller where the permission is checked.