ai-developer-skill-os 2.1.1 → 3.1.0

package/.agents/AGENTS.md

@@ -0,0 +1,81 @@
+# Global Agent Policies
+
+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/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to the **AI Developer Skill OS** project will be documented
 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).
 
+## [3.0.1] - 2026-07-02
+
+### Changed
+- Updated skills.json version từ 1.0.1 → 3.0.1 để phản án version skills chính
+- Thay đổi status các skill từ `planned` → `ready` 
+- Cập nhật `qk-bug-fix` → `qk-bug-resolution` với version 3.0.0
+
+### Added
+- Thêm `knowledge/backend/nodejs.md` - tài liệu kiến trúc backend Node.js
+- Thêm categories registry cho dễ phân loại skills
+
+### Fixed
+- Sửa lỗi `qk-projects-bootstrap` → `qk-project-bootstrap` typo trong categories
+
 ## [1.0.1] - 2026-07-01
 ### Fixed
 - Standardized Language rule across all 23 SKILL.md files for consistency.

package/README.md

@@ -1,130 +1,84 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os)
-
-> 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 (Cursor, Windsurf, Cline, v.v.).
-
-Thay vì cung cấp các "công cụ rời rạc" (Toolbox), dự án này xây dựng một hệ thống **22 Siêu Kỹ Năng (Master Skills)**, biến Agent của bạn thành một **Senior 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.
-
----
-
-## 🏗️ Kiến Trúc Khối (The 7-Layer Architecture)
-
-Hệ thống được thiết kế hoàn hảo với 7 phân lớp, hoạt động khép kín theo chuỗi End-to-End:
-
-### 0. Foundation Layer (Nền Tảng Cốt Lõi)
-- `qk-orchestrator`: Bộ điều hướng yêu cầu người dùng, chọn Workflow.
-- `qk-context-loader`: Bộ nạp ngữ cảnh, tìm file liên quan, chống tràn token.
-- `qk-policy-engine`: Động cơ kiểm tra tính hợp lệ của Request trước khi chạy.
-- `qk-access-policy`: Ranh giới bảo mật, phân quyền và RBAC.
-- `qk-project-memory`: Bộ nhớ cấu trúc dự án (Architecture, UI Patterns, Conventions).
-- `qk-engineering-standard`: Bộ luật thiết kế (Frontend, Backend, Security, Testing rules).
-- `qk-project-bootstrap`: Trình khởi tạo dự án từ con số 0.
-
-### 1. UI System Layer (Hệ Thống Giao Diện)
-- `qk-ui-system-builder`: Quản lý Design System, Component Library.
-- `qk-design-to-code`: Chuyển đổi Figma/Screenshot sang mã nguồn.
-- `qk-ui-audit`: Kiểm toán tính nhất quán, Responsive, Accessibility.
-
-### 2. Development Layer (Phát Triển E2E)
-- `qk-feature-delivery`: Phân tích, code, test hoàn thiện một tính năng từ A-Z.
-- `qk-api-lifecycle`: Vòng đời API (Spec, Service, Type, Test, Docs).
-- `qk-data-lifecycle`: Vòng đời dữ liệu (Schema, Migration, Query Tuning).
-
-### 3. Quality Assurance Layer (Đảm Bảo Chất Lượng)
-- `qk-project-health`: Audit tình trạng dự án, Tech Debt, Code Smell.
-- `qk-bug-resolution`: Tái hiện lỗi, tìm Root Cause, Fix và chống Regression.
-- `qk-validation-gate`: Cổng chặn an toàn (Lint, Test, Security) trước khi hoàn tất.
-
-### 4. Evolution Layer (Tiến Hóa Hệ Thống)
-- `qk-system-evolution`: Nâng cấp phiên bản, Impact Analysis, Dry-run.
-
-### 5. Operation Layer (Vận Hành)
-- `qk-production-release`: CI/CD, Build, Deploy, Observability.
-
-### 6. AI Builder Layer
-- `qk-ai-builder`: Thiết kế các hệ thống AI App, Agent, RAG.
-
-### 7. Knowledge Layer (Tri Thức & Tài Liệu)
-- `qk-docs`: Viết tài liệu cho con người (README, Changelog, Developer Guide).
-- `qk-documentation-system`: Máy học nội bộ (Chuyển đổi Pattern thành luật nạp vào Memory).
-- `qk-help`: Trợ lý tra cứu hướng dẫn kỹ năng.
-
----
-
-## 🔄 Luồng Vận Hành Khép Kín (Workflow)
-
-Khi bạn ra lệnh: `"Thêm tính năng đăng nhập"`:
-```text
-User Request 
-   ↓
-qk-orchestrator (Phân tích, chọn qk-feature-delivery)
-   ↓
-qk-context-loader (Load code liên quan Auth)
-   ↓
-qk-policy-engine & qk-access-policy (Check quyền)
-   ↓
-qk-engineering-standard (Rút luật Backend/Security)
-   ↓
-[THỰC THI BỞI qk-feature-delivery]
-   ↓
-qk-validation-gate (Test, Lint)
-   ↓
-qk-docs (Cập nhật API doc, Changelog)
-   ↓
-qk-documentation-system (Lưu các Pattern mới vào Memory)
-```
-
----
-
-## 💡 Ví Dụ Thực Tế (Common Examples)
-
-Dưới đây là một số ví dụ sử dụng các kỹ năng phổ biến và mạnh mẽ nhất trong quá trình code hàng ngày của bạn:
-
-### 1. `qk-orchestrator` (Trợ lý điều phối trung tâm)
-Nếu bạn không biết nên dùng skill nào, hãy gọi Orchestrator. Nó sẽ tự động phân tích và kích hoạt đúng các skill bên dưới.
-```bash
-./qk-orchestrator "Tôi muốn tạo một trang Dashboard hiển thị doanh thu bằng React"
-```
-
-### 2. `qk-feature-delivery` (Phát triển tính năng E2E)
-Dùng khi bạn muốn xây dựng trọn vẹn một tính năng từ DB, API đến UI và Test.
-```bash
-./qk-feature-delivery "Tạo luồng thanh toán giỏ hàng (Cart Checkout), lưu vào bảng orders và gọi API thanh toán Stripe"
-```
-
-### 3. `qk-bug-resolution` (Chẩn đoán và diệt Bug triệt để)
-Tuyệt đối không dùng prompt thường để sửa lỗi. Dùng kỹ năng này để ép AI tìm Root Cause và viết Regression Test.
-```bash
-./qk-bug-resolution "API /users/profile đang trả về 500 khi user chưa có avatar, stack trace như sau..."
-```
-
-### 4. `qk-ui-system-builder` (Chuẩn hóa giao diện)
-Dùng khi thiết kế các component dùng chung (Button, Card, Form) để đảm bảo không bị rác CSS.
-```bash
-./qk-ui-system-builder "Tạo một Data Table Component có hỗ trợ phân trang và filter, sử dụng Design Token hiện tại"
-```
-
-### 5. `qk-api-lifecycle` (Thiết kế và Code API)
-Dành cho Backend Engineer, đi từ spec đến code, type và test.
-```bash
-./qk-api-lifecycle "Thiết kế API cập nhật mật khẩu, yêu cầu validate JWT token và mã hóa bcrypt"
-```
-
----
-
-## 💻 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ộ 22 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 liên quan đến Frontend"
-```
+# 🚀 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, 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 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.
+
+---
+
+## ✨ Tính năng chính
+- **23 Skills chuẩn Enterprise** cho Frontend, Backend, Engineering
+- **Kiến trúc 5 tầng** giúp tối ưu Context Window
+- **Pipeline tự động**: analyze → implement → validate → complete
+- **Decision Tree** cho từng skill, đưa ra quyết định chuẩn xác
+- **Knowledge RAG on-demand** - chỉ tải kiến thức khi cần thiế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
+```
+
+## 🚀 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/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.

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

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

@@ -0,0 +1,25 @@
+# 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/knowledge/backend/nodejs.md

@@ -0,0 +1,52 @@
+---
+id: nodejs-knowledge-base
+domain: backend
+tags: [nodejs, express, api, middleware]
+priority: high
+---
+
+# Node.js Backend Knowledge Base
+
+## Architecture Patterns
+- **Controller Layer:** Handle HTTP requests/responses, input validation, delegate to Service
+- **Service Layer:** Business logic, data transformation, transaction management  
+- **Repository Layer:** Direct database queries, ORM interactions
+- **Middleware:** Auth guards, logging, rate limiting, error handling
+
+## Express Best Practices
+```ts
+// Controller pattern - thin, delegates to service
+export async function createUser(req: Request, res: Response) {
+  const result = await userService.create(req.body);
+  res.status(201).json(result);
+}
+
+// Service pattern - business logic
+export async function create(userData: UserDto) {
+  // Validation
+  const validated = userSchema.parse(userData);
+  // Transaction
+  return db.user.create({ data: validated });
+}
+
+// Middleware pattern - reusable
+export const requireAuth = (req: Request, res: Response, next: NextFunction) => {
+  const user = verifyToken(req.headers.authorization);
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+  req.user = user;
+  next();
+};
+```
+
+## Error Handling
+- Never throw raw Errors. Use custom error classes.
+- Always catch async errors in middleware.
+- Return consistent error format: `{ error: string, code?: string }`
+
+## Security Checklist
+- Use helmet middleware for security headers
+- Validate all inputs with Zod/Joi
+- Never commit .env files
+- Use parameterized queries to prevent SQL injection
+- Rate limit public endpoints
+- Log security events (failed logins, permission denied)

package/knowledge/frontend/react.md

@@ -0,0 +1,81 @@
+---
+id: react-knowledge-base
+domain: frontend
+tags: [react, hooks, components, state]
+priority: high
+---
+
+# React Knowledge Base
+
+## State Management Rules
+- Use `useState` for strictly local UI state (e.g., dropdown toggle).
+- Use `useContext` or global stores (Zustand/Redux) when prop drilling exceeds 3 levels.
+- Never store derived data in state. Compute it on the fly during render.
+- Never store API responses in Redux if a Server State tool (React Query/SWR) is available.
+- For forms: Use React Hook Form + Zod for validation, NOT useState for each field.
+
+## Hooks Best Practices
+- **useEffect:** Avoid using `useEffect` for data transformation or syncing state. Only use it for actual side effects (subscriptions, API calls, manual DOM mutations).
+- **useMemo / useCallback:** Only use when passing props to heavily memoized child components or when the computation is extremely expensive. Do not use them blindly.
+- **Custom Hooks:** Extract complex logic out of UI components into custom hooks. Prefix them with `use` (e.g., `useUserAuth`).
+- **Custom Hook Pattern:**
+  ```ts
+  // useApi.ts - Generic API hook
+  export function useApi<T>(url: string) {
+    const [data, setData] = useState<T | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    
+    useEffect(() => {
+      fetchData();
+    }, [url]);
+  }
+  ```
+
+## Component Boundaries
+- Follow Single Responsibility Principle. A component should either handle logic (Container) or handle rendering UI (Presentational), ideally not both if it's complex.
+- Keep files under 300 lines. If a file is larger, break it down.
+- **Component Hierarchy:**
+  - `components/shared/` - Reusable, no business logic
+  - `features/<domain>/components/` - Feature-specific components
+  - `layouts/` - Page layouts and wrappers
+
+## Performance Gotchas
+- Stale Closures: Always include all reactive variables in the dependency array of `useEffect` or `useCallback`.
+- Keys in Lists: Always use unique IDs for `key` props. Never use array indices unless the list is completely static.
+- **Re-render Detection:**
+  ```ts
+  // Use console.log inside component to detect renders
+  // Wrap child in React.memo if unnecessary re-renders occur
+  export const MemoizedChild = React.memo(ChildComponent);
+  ```
+
+## Error Handling Patterns
+```ts
+// API Error Boundary
+class ErrorBoundary extends React.Component {
+  state = { hasError: false };
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+}
+
+// Hook error handling
+const { data, error, isLoading } = useQuery(['key'], fetchFn);
+if (error) return <ErrorMessage error={error} />;
+if (isLoading) return <LoadingSpinner />;
+```
+
+## Testing Patterns
+```tsx
+// Component test with React Testing Library
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('handles user interaction', async () => {
+  render(<LoginForm />);
+  const button = screen.getByRole('button', { name: /login/i });
+  await userEvent.click(button);
+  await waitFor(() => expect(mockSubmit).toHaveBeenCalled());
+});
+```