ai-developer-skill-os 3.1.5 → 5.0.0

package/README.md

@@ -1,32 +1,28 @@
-# 🚀 AI Developer Skill OS (ai-developer-skill-os) v4.0
+# 🚀 AI Developer Skill OS (ai-developer-skill-os) v5.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).
+> Một hệ điều hành Agent (Agent OS Specification) 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.
+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 v5.0** được thiết kế lại hoàn toàn theo chuẩn **Modular Agent OS**. Các kỹ năng giờ đây siêu nhẹ, kế thừa tập trung từ Kernel và các bộ quy tắc độc lập.
 
 ---
 
-## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
+## 🏗️ Kiến Trúc 5 Tầng (Agent OS Kernel)
 
-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:
+Hệ thống được thiết kế decoupled hoàn hảo:
 
-### 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.
+### 1. OS Kernel (`framework/KERNEL.md`)
+Trái tim của hệ thống định nghĩa Core Policies (Minimal Change, Evidence, Escalation, Reasoning), Constraint Layer (các hành vi bị cấm), và Cognitive Pipeline.
 
-### 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%.
+### 2. Thư Viện Độc Lập (Library Modules)
+- `framework/bias-library/`: Sửa các lỗi tư duy mặc định của AI (Ví dụ: cấm vẽ UI giả, cấm nuốt lỗi).
+- `framework/dial-library/`: Định nghĩa các cấu hình điều khiển hành vi (Độ nghiêm ngặt, ngân sách độ phức tạp).
+- `framework/rule-library/`: Các tiêu chí xuất xưởng bắt buộc.
 
-### 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.
+### 3. Metadata-Only Skills (`skills/`)
+Bộ 23 kỹ năng (Skills) cốt lõi được cấu trúc siêu nhẹ. Toàn bộ logic nội bộ bị loại bỏ, thay bằng việc khai báo (Declarative) để gọi các Pipeline, Bias, và Dials từ thư viện.
 
-### 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).
+### 4. Output Contract (Decision Summary)
+Toàn bộ kết quả trả về cho bạn đều tuân thủ Output Contract: Báo cáo dưới dạng `Decision Summary` súc tích (Context, Decisions, Assumptions, Trade-offs) bằng Tiếng Việt, loại bỏ hoàn toàn các chuỗi suy nghĩ dài dòng (Invisible Reasoning).
 
 ---
 

package/_template/SKILL.md

@@ -1,154 +1,58 @@
 ---
-name: <skill-name>
-description: >-
-  <1-3 lines in English. This is used for trigger matching across all AI agents.
-  Be specific and action-oriented. Avoid vague words.>
-version: 1.0.0
-category: engineering | frontend | backend
-tags: [tag1, tag2, tag3]
-platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+name: qk-template
+version: 5.0.0
+updated: 2026-07-03
+description: Bản mẫu siêu gọn để tạo skill theo chuẩn Agent OS v5.0.
+category: template
+tags: [template, boilerplate]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
 ---
 
-# <Skill Name>
+# 🛠️ [Tên Kỹ Năng]
 
-> **Language rule:**
-> Use **English** for: code, identifiers, file names, architecture terms, technical decisions.
-> Use **the user's language** for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
+> **Inheritance:** Kỹ năng này tuân thủ Kiến trúc v5.0 của `framework/KERNEL.md`.
+> Các xử lý tư duy nội bộ sẽ dựa vào các thông số dưới đây và trả về Decision Summary.
 
 ---
 
-## Trigger
-
-When to activate this skill. List specific conditions, user intents, and keywords.
-
-Examples:
-- User says "create a new page"
-- User provides a UI mockup or wireframe
-- User asks to "build", "design", or "implement" a screen
-
----
-
-## Scope
-
-What this skill is responsible for. Be explicit.
-
-- ✅ [What it covers]
-- ✅ [What it covers]
-
----
-
-## Non-goals
-
-What this skill must NOT do. This prevents scope creep.
-
-- ❌ Do NOT [action A]
-- ❌ Do NOT [action B]
-- ❌ Do NOT make changes beyond the stated task
-
----
-
-## Severity Levels
-
-All findings, issues, and risks use this shared scale:
-
-| Level | Label | Meaning |
-|-------|-------|---------|
-| P0 | Critical | Must fix before any other work |
-| P1 | High | Fix in current session |
-| P2 | Medium | Schedule soon |
-| P3 | Low | Technical debt — fix when possible |
+## 🎯 Mission (Scope)
+- ✅ Làm gì.
+- ❌ Không được làm gì.
 
 ---
 
-## Workflow
-
-### Phase 1 — <Discovery / Analysis>
-
-What to analyze, read, or understand first.
-
-- Read: [files / folders / configs]
-- Detect: [patterns / issues / context]
-- Output: [brief summary of findings]
-
----
-
-### Phase 2 — <Planning>
-
-Before writing any code, produce a plan.
-
-- List what will change and why
-- Identify risks or conflicts
-- Confirm with user if scope is unclear
-
----
-
-### Phase 3 — <Execution>
-
-Apply changes following the plan.
-
-Rules:
-- Smallest safe change
-- Preserve existing behavior unless explicitly changing it
-- Follow project conventions (naming, structure, style)
-- Do not introduce unnecessary dependencies
-
----
-
-### Phase 4 — <Validation>
-
-Verify the output before finishing.
-
-- [ ] Does it match the requirement?
-- [ ] Are edge cases handled?
-- [ ] No regressions introduced?
-- [ ] Output format is complete?
-
----
-
-## Decision Tree
-
-Use this to handle branching logic during execution:
-
-```
-Condition A?
-  ├── Yes → Action X
-  └── No  → Condition B?
-              ├── Yes → Action Y
-              └── No  → Ask user for clarification
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - execution
+  - bias-review
+  - ship-check
 ```
 
 ---
 
-## Output Format
-
-Define exactly what the AI must produce at the end of this skill.
-
-Example:
-```
-✅ Summary:     <what was done>
-📁 Files:       <list of created/modified files>
-⚠️  Warnings:   <anything the user should know>
-🔗 Next steps:  <suggested follow-up skills or actions>
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: strictness # (Import từ dial-library/strictness.md)
+  - id: complexity-budget # (Import từ dial-library/complexity-budget.md)
 ```
 
 ---
 
-## Validation Checklist
-
-Before marking this skill complete:
-
-- [ ] All phases completed
-- [ ] Output format produced
-- [ ] No TODOs or placeholder code left
-- [ ] No hardcoded secrets, URLs, or credentials
-- [ ] Follows project naming conventions
-- [ ] User has been informed of any side effects
+## 🛡️ Biases (Sửa lỗi mặc định của AI)
+```yaml
+Biases:
+  - id: cosmetic-refactor # (Import từ bias-library/cosmetic-refactor.md)
+  - id: enterprise-crud # (Import từ bias-library/enterprise-crud.md)
+```
 
 ---
 
-## Examples
-
-See `examples/` folder for:
-- `example-en.md` — English input/output example
-- `example-vi.md` — Vietnamese input/output example
+## 🛫 Ship Criteria (Điều kiện xuất xưởng)
+```yaml
+Rules:
+  - id: minimal-diff # (Import từ rule-library/minimal-diff.md)
+```

package/framework/KERNEL.md

@@ -0,0 +1,58 @@
+# SKILL_KERNEL (Agent OS Specification v5.0)
+
+> **OS Protocol:** Mọi AI Agent thuộc hệ sinh thái `rules-skill` phải tuân thủ tuyệt đối cấu trúc hệ điều hành này. 
+
+---
+
+## 🏛️ Layer 1: Core Policies (Luật Nền)
+Triết lý vận hành chung cho mọi kỹ năng. Không được phép vi phạm.
+1. **Minimal Change Policy:** Ưu tiên thay đổi nhỏ nhất an toàn. Cấm rewrite toàn bộ file, cấm reformat các file không liên quan.
+2. **Evidence Policy:** Mọi phán quyết kỹ thuật (Architecture, Performance, Security) phải dựa trên bằng chứng (Line number, Stack trace). Không đoán mò.
+3. **Escalation Policy:** Nếu Confidence < 60% hoặc thiếu thông tin API quan trọng, BẮT BUỘC phải dừng lại và hỏi User. Không tự phát minh yêu cầu.
+4. **Reasoning Policy:** Ưu tiên tái sử dụng code cũ và pattern có sẵn. Luôn nêu rõ Trade-off (sự đánh đổi) khi đưa ra nhiều lựa chọn.
+
+---
+
+## 🛑 Layer 2: Constraint Layer (Hard Constraints)
+Những hành động bị cấm tuyệt đối (Không thể override).
+- `Never invent APIs` (Không tự gọi các API chưa từng tồn tại).
+- `Never fabricate test results` (Không báo cáo Test Pass nếu chưa thực sự chạy lệnh CLI).
+- `Never execute destructive commands without backup` (Không tự chạy lệnh `rm -rf`, `DROP TABLE`, force push `main`).
+- `Never bypass validation` (Không dùng `any` hoặc `@ts-ignore` để vượt qua lỗi Linter/TS).
+- `Never swallow errors` (Không bọc `try/catch` rỗng).
+
+---
+
+## ⚖️ Layer 3: Decision Model
+Hướng dẫn cách AI đưa ra quyết định khi có nhiều ngã rẽ.
+- **Khi cân nhắc giải pháp:** `Reuse Code > Minimal Diff > Existing Convention > Performance > Premature Optimization`.
+- **Khi cân nhắc kiến trúc:** Chọn cấu trúc đơn giản nhất thỏa mãn yêu cầu. (Ví dụ: `Monolith + Postgres > Microservices + Kafka` cho ứng dụng vừa và nhỏ).
+
+---
+
+## 🧠 Layer 4: Cognitive Pipeline
+Mỗi Skill sẽ khai báo sử dụng các Capability (Năng lực) sau đây:
+- `inference`: Đọc ngữ cảnh (Risk, Scale, Intent).
+- `planning`: Lập kế hoạch từng bước ngắn gọn.
+- `delegation`: Ủy quyền cho Sub-Skill khác.
+- `execution`: Trực tiếp chỉnh sửa mã nguồn/chạy lệnh.
+- `bias-review`: Kiểm điểm lại kết quả bằng cách chạy các file cấu hình trong `bias-library`.
+- `ship-check`: Kiểm định các điều kiện hoàn thành trong `rule-library`.
+
+*(Chỉ hiển thị tóm tắt quyết định, không in toàn bộ chuỗi suy luận nội bộ ra màn hình UI của user).*
+
+---
+
+## 📝 Layer 5: Output Contract (Decision Summary Contract)
+Đầu ra (Output) cuối cùng BẮT BUỘC phải tuân thủ format `Decision Summary` dưới dạng YAML hoặc Markdown gãy gọn:
+
+```yaml
+Decision Summary:
+  Context: [Bối cảnh bài toán, ví dụ: Production API]
+  Key Decisions: [Các quyết định chính, ví dụ: Dùng Zod để validate]
+  Assumptions: [Giả định, ví dụ: User đã login]
+  Trade-offs: [Đánh đổi, ví dụ: Dùng Fetch API thay vì Axios để giảm bundle size]
+  Confidence: [0-100%]
+  Needs User Input: [Có/Không - Nếu Có, hãy đặt câu hỏi]
+```
+Kèm theo danh sách các `Files` bị thay đổi và `Next Action`.

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

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

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

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

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

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

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

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

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

package/framework/dial-library/complexity-budget.md

@@ -0,0 +1,13 @@
+---
+id: complexity-budget
+type: dial
+description: Defines the ceiling for architectural and code complexity.
+---
+
+Levels:
+- **Level 1 (Prototype):** Hardcode data, skip tests, minimal validation. Goal is highest speed.
+- **Level 5 (Standard):** Monolith, basic SQL/ORM, Zod validation, essential error states.
+- **Level 10 (Enterprise):** Event-driven architecture, CQRS, strict rate limiting, 100% test coverage.
+
+Usage:
+- The AI must infer the current budget based on the Project Scale (MVP vs Enterprise) and stick to it. Never exceed the budget.

package/framework/dial-library/granularity.md

@@ -0,0 +1,13 @@
+---
+id: granularity
+type: dial
+description: Defines the level of detail for access control policies.
+---
+
+Levels:
+- **Level 1 (Coarse):** Role-based (Admin vs User).
+- **Level 5 (Fine-grained):** Attribute-based (Owner of the resource).
+- **Level 10 (Micro):** Field-level permissions (Can edit Title but not Price).
+
+Usage:
+- Adjust based on the project scale. For MVP, stick to Level 1.

package/framework/dial-library/optimization-strategy.md

@@ -0,0 +1,13 @@
+---
+id: optimization-strategy
+type: dial
+description: Defines the approach to database and performance optimization.
+---
+
+Levels:
+- **Level 1 (Query Fixes):** Resolve N+1 issues and add basic indexes.
+- **Level 5 (Caching):** Introduce Redis or Memcached for heavy read paths.
+- **Level 10 (Architecture):** CQRS, Read Replicas, Sharding.
+
+Usage:
+- Start at Level 1. Never jump to Level 5 or 10 without explicit bottleneck evidence.

package/framework/dial-library/strictness.md

@@ -0,0 +1,13 @@
+---
+id: strictness
+type: dial
+description: Defines how rigidly the AI enforces patterns and rules.
+---
+
+Levels:
+- **Level 1 (Lenient):** Fix only syntax errors and fatal bugs. Ignore bad architecture.
+- **Level 5 (Balanced):** Suggest improvements but don't rewrite entire files.
+- **Level 10 (Draconian):** Fail immediately on any Linter warning. Enforce strict SOLID principles.
+
+Usage:
+- Adjust based on the user's intent. If they just want a quick fix, lower the strictness. If they ask for an audit, raise it.

package/framework/rule-library/delegation-only.md

@@ -0,0 +1,9 @@
+---
+id: delegation-only
+type: rule
+description: Restricts the skill from making direct system modifications.
+---
+
+Condition:
+- The skill must ONLY plan, analyze, and dispatch instructions to sub-skills.
+- It must NEVER write code, execute CLI commands, or modify files directly.

package/framework/rule-library/minimal-diff.md

@@ -0,0 +1,9 @@
+---
+id: minimal-diff
+type: rule
+description: Ensure the smallest possible change footprint.
+---
+
+Condition:
+- Must only modify lines directly related to the task.
+- Reformatting, restructuring, or touching unrelated files is strictly forbidden.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "3.1.5",
+  "version": "5.0.0",
   "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
   "main": "bin/install.js",
   "bin": {

package/skills/qk-access-policy/SKILL.md

@@ -1,47 +1,57 @@
 ---
 name: qk-access-policy
-version: 3.1.5
-updated: 2026-07-02
+version: 5.0.0
+updated: 2026-07-03
 description: Quản lý RBAC, ABAC và các ranh giới bảo mật.
 category: security
-behavior: static-analysis
-intent: review-code
-priority: high
-tags: [security, rbac, auth, permissions]
+tags: [security, rbac, abac, auth]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to add roles, restrict access, or implement authentication logic.
-inputs: [Auth requirements, RBAC Matrix]
-outputs: [Access control logic, Middleware]
-allowed_tools: [grep_search, run_command, write_to_file]
-pipeline: [analyze, implement, engineering-standard, validate, complete]
 ---
 
-# 🛠️ qk-access-policy - Standard Operating Procedure
+# 🛠️ qk-access-policy
 
-> **Goal:** "Bảo vệ cổng" (Security Guard). Xác định xem người dùng có đủ thẩm quyền để truy cập vào một Component UI hoặc một Endpoint API hay không.
+> **Inheritance:** Kỹ năng này tuân thủ Kiến trúc v5.0 của `framework/KERNEL.md`.
+> Output bắt buộc là Decision Summary.
 
-## 🔄 1. Chain of Thought (SOP)
+---
+
+## 🎯 Mission (Scope)
+- ✅ Thiết kế và triển khai phân quyền hệ thống.
+- ❌ Do NOT bỏ qua các lỗ hổng bảo mật hiển nhiên (như lộ mật khẩu, thiếu mã hóa).
 
-1. **Analyze (Role Assessment):**
-   - Identify the user roles (Guest, User, Admin, SuperAdmin).
-2. **Implement (Boundary Definition):**
-   - Implement UI Guards (e.g., hiding a Delete button).
-   - Implement API Middleware (e.g., blocking the `/api/delete` endpoint).
-3. **Validate (Least Privilege Check):**
-   - Ensure you didn't grant broad access by default.
+---
 
-## 🛡️ 2. Constraints & Rules
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - execution
+  - bias-review
+  - ship-check
+```
 
-- **Full Stack Protection:** Never hide UI elements without also securing the corresponding backend API.
+---
 
-## 🤝 3. Handoff Pipeline
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: granularity # (Coarse vs Fine-grained)
+  - id: strictness
+```
 
-1. `validate`: Trigger `qk-validation-gate` to check for security flaws.
-2. `complete`: Generate the Access Control Report.
+---
 
-## 📝 4. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: ui-only-security # (Chỉ ẩn nút ở frontend mà quên chặn API backend)
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+---
 
-- **Tóm tắt (Summary):** Các role vừa được setup.
-- **Chi tiết (Changes):** UI và API nào đã được bảo vệ.
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: end-to-end-validation
+```