ai-developer-skill-os 3.1.4 → 5.0.0

package/skills/qk-docs/SKILL.md

@@ -1,60 +1,56 @@
 ---
 name: qk-docs
-version: 3.1.4
-updated: 2026-07-02
-description: Write and maintain human-readable project documentation.
+version: 5.0.0
+updated: 2026-07-03
+description: Viết và duy trì tài liệu dự án để con người có thể dễ dàng đọc hiểu.
 category: documentation
-behavior: static-analysis
-intent: maintain
-priority: low
-tags: [docs, markdown, jsdoc, readme]
+tags: [documentation, readme, comments]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to write docs, update the README, or generate JSDoc comments.
-inputs: [Source code, Task context]
-outputs: [Markdown Documentation, JSDoc]
-allowed_tools: [read_file, write_to_file]
-pipeline: [analyze, implement, validate, complete]
 ---
 
-# 🛠️ qk-docs - Standard Operating Procedure
+# 🛠️ qk-docs
 
-> **Goal:** Đóng vai trò là "Technical Writer". Viết tài liệu (README, API Docs, Code Comments) rõ ràng, dễ hiểu cho con người.
+> **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)
+---
 
-1. **Analyze (Context Extraction):**
-   - Read the target source code to understand its Inputs, Outputs, and side effects.
-2. **Implement (Drafting):**
-   - Write Markdown or JSDoc comments.
-   - Structure: Description -> Parameters -> Returns -> Warnings/Notes.
-3. **Validate (Review Examples):**
-   - ALWAYS provide 1-2 real-world code examples demonstrating how to use the function/API.
-4. **Complete (Format):**
-   - Ensure proper Markdown syntax (bolding, code blocks with languages).
+## 🎯 Mission (Scope)
+- ✅ Dịch logic phức tạp thành giải thích tiếng Việt trong sáng cho con người.
+- ❌ Do NOT dịch nguyên xi các thuật ngữ chuyên ngành (Props, Hook, Cache).
 
-## 🛡️ 2. Constraints & Rules
+---
 
-- **Human Friendly:** Avoid overly academic language. Explain it as if explaining to a junior developer.
-- **Language Hybrid:** If writing Vietnamese documentation, keep technical keywords (props, state, endpoint, fetch) in English.
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - execution
+  - bias-review
+  - ship-check
+```
 
-## 🌳 3. Decision Tree
+---
 
-```text
-Is this an API Documentation?
-  ├── YES → Use standard REST/GraphQL documentation layout (Endpoint, Method, Body, Response).
-  └── NO → Is it a Component Documentation?
-             ├── YES → Document the Props interface and usage examples.
-             └── NO → Write standard JSDoc.
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: strictness
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `complete`: Generate the Docs and save them to the project files.
+---
 
-## 📝 5. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: hallucinated-tools # (Tự bịa ra các step hướng dẫn không tồn tại)
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+---
 
-- **Tóm tắt (Summary):** Tài liệu nào đã được tạo/cập nhật.
-- **Chi tiết (Changes):** Cấu trúc tài liệu.
-- **Xác thực (Verification):** Yêu cầu User đọc lướt qua tài liệu.
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: minimal-diff
+```

package/skills/qk-engineering-standard/SKILL.md

@@ -1,69 +1,57 @@
 ---
 name: qk-engineering-standard
-version: 3.1.4
-updated: 2026-07-02
-description: Enforce SOLID, DRY, Clean Code, and Naming conventions.
-category: standard
-behavior: static-analysis
-intent: review-code
-priority: critical
-tags: [clean-code, architecture, refactoring, solid]
+version: 5.0.0
+updated: 2026-07-03
+description: Ép buộc áp dụng SOLID, DRY, Clean Code, và các quy tắc đặt tên.
+category: conventions
+tags: [clean-code, solid, refactoring, conventions]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to review code, refactor code, or as part of the pipeline before validation.
-inputs: [Source Code, Target Directory]
-outputs: [Refactored Code, Code Review Report]
-allowed_tools: [grep_search, read_file, write_to_file]
-pipeline: [analyze, review, implement, validate, complete]
 ---
 
-# 🛠️ qk-engineering-standard - Standard Operating Procedure
+# 🛠️ qk-engineering-standard
 
-> **Goal:** Đóng vai trò là "Kiến trúc sư trưởng", rà soát và ép buộc mã nguồn phải tuân thủ chuẩn mực Clean Code, dễ đọc và dễ bảo trì.
+> **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)
-
-1. **Analyze (Context Review):**
-   - Scan the target file(s) and determine their role (UI, Logic, API, Config).
-2. **Review (Smell Detection):**
-   - Check for Naming violations (e.g., `temp`, `data`, `res` instead of `userData`).
-   - Check for Magic Numbers/Strings.
-   - Check for God Components (Files > 300 lines or > 3 responsibilities).
-3. **Implement (Refactoring):**
-   - Extract inline styles or raw strings into constants.
-   - Split large components into smaller, pure components.
-   - Separate UI rendering from Business Logic (Custom Hooks).
-4. **Verify (Validation):**
-   - Ensure the refactoring did NOT change the business logic or behavior of the app (Regression check).
+---
 
-## 🛡️ 3. Constraints & Rules
+## 🎯 Mission (Scope)
+- ✅ Refactor code để áp dụng Clean Architecture.
+- ❌ Do NOT thay đổi logic nghiệp vụ (business logic).
 
-- **Code is for Humans:** Write code that junior developers can easily understand. Avoid overly clever or obscure syntax.
-- **Scope Limit:** Do NOT refactor the entire project if the user only asked to review one file. Limit the scope to the current task context.
-- **Preserve Behavior:** Refactoring must strictly preserve backward compatibility.
+---
 
-## 🌳 3. Decision Tree
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - execution
+  - bias-review
+  - ship-check
+```
 
-```text
-Is the file larger than 300 lines?
-  ├── YES → Propose splitting the file into sub-components or moving logic to hooks.
-  └── NO → Continue normal inspection.
+---
 
-Does the React Component contain `fetch()` or heavy data mapping?
-  ├── YES → Extract the logic into a separate `use[Feature]Data.ts` hook.
-  └── NO → Pass.
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: strictness
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `validate`: Run static analysis (Linters, TypeScript compiler) to ensure the refactored code has no syntax errors.
-2. `complete`: Generate the review report.
+---
 
-## 📝 5. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: cosmetic-refactor
+  - id: premature-abstraction
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt. Cấu trúc báo cáo bao gồm:
+---
 
-- **Tóm tắt (Summary):** File nào vừa được Refactor / Review.
-- **Chi tiết (Changes):** Các thay đổi cụ thể về Tên biến, Cấu trúc.
-- **Nguyên nhân (Reasoning):** Giải thích tại sao code cũ là "Bad Practice" và code mới tốt hơn thế nào.
-- **Xác thực (Verification):** Đảm bảo code chạy không lỗi.
-- **Hành động tiếp (Next Action):** Bàn giao lại cho Pipeline.
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: minimal-diff
+```

package/skills/qk-feature-delivery/SKILL.md

@@ -1,73 +1,57 @@
 ---
 name: qk-feature-delivery
-version: 3.1.4
-updated: 2026-07-02
-description: Develop new features end-to-end (Frontend & Backend).
-category: engineering
-behavior: development
-intent: implement-feature
-priority: high
-tags: [feature, development, e2e, ui, api]
+version: 5.0.0
+updated: 2026-07-03
+description: Phát triển tính năng mới hoàn chỉnh từ Frontend đến Backend.
+category: fullstack
+tags: [feature, frontend, backend, implementation]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to create a new page, component, or endpoint.
-inputs: [Feature requirements, Design/Mockup (optional)]
-outputs: [Implemented code, Test cases]
-allowed_tools: [run_command, read_file, write_to_file, grep_search]
-pipeline: [analyze, implement, engineering-standard, validate, complete]
 ---
 
-# 🛠️ qk-feature-delivery - Standard Operating Procedure
+# 🛠️ qk-feature-delivery
 
-> **Goal:** Phát triển một tính năng mới hoàn chỉnh, từ giao diện (Frontend) đến API (Backend) và Cơ sở dữ liệu (nếu có).
+> **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)
-
-1. **Analyze (Requirements Gathering):**
-   - Read the user's requirements.
-   - Break down the feature into sub-tasks (e.g., Schema -> API -> UI Component -> Integration).
-2. **Plan (Architecture & Design):**
-   - Identify if you need to load specific knowledge files (e.g., `knowledge/frontend/react.md`).
-   - Define data interfaces (TypeScript Types/Interfaces) first.
-3. **Execute (Implementation):**
-   - Build the backend/API mock first (if applicable).
-   - Build the UI component and bind the data.
-4. **Verify (Validation):**
-   - Check if the UI is responsive.
-   - Ensure the API handles edge cases (empty states, loading, error).
-
-## 🛡️ 3. Constraints & Rules
+---
 
-- **Contract First:** Always define the Type/Interface contract before writing the implementation logic.
-- **Component Reusability:** Do not create a new Button or Input if a Shared Component already exists in `src/components/shared/`.
-- **DRY (Don't Repeat Yourself):** Extract inline styles or duplicate logic into hooks/utilities.
+## 🎯 Mission (Scope)
+- ✅ Code tính năng end-to-end (API, DB, UI).
+- ❌ Do NOT dùng lại các thư viện quá cũ hoặc deprecated.
 
-## 🌳 3. Decision Tree
+---
 
-```text
-Does the feature require Backend API changes?
-  ├── YES → Start with Database Schema/Types -> API Route -> UI Integration.
-  └── NO → Is it a purely visual UI component?
-             ├── YES → Load UI/Design tokens and implement.
-             └── NO (Stateful) → Load `knowledge/frontend/react.md` to design the State Management strategy.
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - execution
+  - bias-review
+  - ship-check
 ```
 
-## 🤝 4. Handoff Pipeline
-
-After implementing the feature, map to the pipeline:
+---
 
-1. `engineering-standard`: Ensure naming conventions and file size limits are respected.
-2. `validate`: Run tests and format the code.
-3. `complete`: Output the final report.
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: complexity-budget
+```
 
-## 📝 5. Output Format
+---
 
-Vui lòng báo cáo lại bằng Tiếng Việt với cấu trúc tương tự `templates/bug-report.md` nhưng thay đổi tiêu đề thành:
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: enterprise-crud
+  - id: missing-ui-states
+```
 
-### 🚀 Báo Cáo Triển Khai Tính Năng (Feature Report)
+---
 
-- **Tóm tắt (Summary):** Tính năng gì đã được làm.
-- **Chi tiết (Changes):** Liệt kê các file tạo mới / chỉnh sửa.
-- **Kiến trúc (Reasoning):** Giải thích quyết định thiết kế State/API.
-- **Xác thực (Verification):** Các bước để user test thử.
-- **Rủi ro (Risks):** Có làm chậm hệ thống hay bundle size không.
-- **Hành động tiếp (Next Action):** ...
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: end-to-end-validation
+```

package/skills/qk-help/SKILL.md

@@ -1,44 +1,52 @@
 ---
 name: qk-help
-version: 3.1.4
-updated: 2026-07-02
-description: Display the list of available skills and pro-tips.
-category: utilities
-behavior: static-analysis
-intent: review-code
-priority: low
-tags: [help, manual, list, tutorial]
+version: 5.0.0
+updated: 2026-07-03
+description: Hiển thị danh sách các kỹ năng hiện có và các mẹo sử dụng.
+category: utility
+tags: [help, menu, list]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User types 'help', asks for a list of skills, or doesn't know how to use the agent.
-inputs: [Help query]
-outputs: [List of skills, Tips]
-allowed_tools: [read_file, list_dir]
-pipeline: [analyze, complete]
 ---
 
-# 🛠️ qk-help - Standard Operating Procedure
+# 🛠️ qk-help
 
-> **Goal:** Bản đồ hướng dẫn sử dụng Agent Skills. Giúp User tra cứu nhanh lệnh.
+> **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)
+- ✅ Trình bày bảng hướng dẫn sử dụng nhanh gọn, dễ đọc.
+- ❌ Do NOT đưa ra những tường chữ dài dòng.
 
-1. **Analyze (Scan):**
-   - Read the skills directory to list all available tools.
-2. **Complete (Format):**
-   - Format the skills into a neat Markdown table.
+---
 
-## 🛡️ 2. Constraints & Rules
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - execution # Bỏ qua Inference và Planning vì đây là skill cung cấp thông tin.
+  - ship-check
+```
 
-- **Keep it short:** Do not print the entire content of `SKILL.md`. Only print the Name and Description from the metadata.
+---
 
-## 🤝 3. Handoff Pipeline
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: strictness
+```
 
-1. `complete`: Output the Help table.
+---
 
-## 📝 4. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases: []
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt dạng Bảng (Table).
+---
 
-- **Cột 1:** Tên Skill
-- **Cột 2:** Mô tả ngắn (Tiếng Việt)
-- **Cột 3:** Lệnh kích hoạt (Ví dụ: `@qk-bug-resolution`)
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: delegation-only
+```

package/skills/qk-orchestrator/SKILL.md

@@ -1,60 +1,58 @@
 ---
 name: qk-orchestrator
-version: 3.1.4
-updated: 2026-07-02
-description: Route user requests, parse intents, and delegate to the correct sub-skills.
-category: orchestration
-behavior: static-analysis
-intent: review-code
-priority: critical
-tags: [router, orchestrator, delegation, ai-manager]
+version: 5.0.0
+updated: 2026-07-03
+description: Điều hướng yêu cầu của người dùng, phân tích ý định và ủy quyền cho các sub-skills phù hợp.
+category: core
+tags: [orchestrator, routing, dispatch, core]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: Triggered initially when the user provides a vague or complex multi-step request.
-inputs: [User intent, Raw Context]
-outputs: [Workflow routing, Sub-skill delegation]
-allowed_tools: [grep_search, read_file]
-pipeline: [analyze, plan, delegate]
 ---
 
-# 🛠️ qk-orchestrator - Standard Operating Procedure
+# 🛠️ qk-orchestrator
 
-> **Goal:** "Tổng tư lệnh" (Master Orchestrator). Phân tích ý đồ của người dùng và điều phối các kỹ năng (Skills) khác để giải quyết vấn đề thay vì làm mọi thứ một cách thủ cô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)
+---
 
-1. **Analyze (Intent Parsing):**
-   - Read the user's request. Determine the goal: Is it a Bug Fix, a New Feature, a Refactor, or just a Question?
-2. **Plan (Context Gathering & Skill Selection):**
-   - Determine which specific files are needed.
-   - Select the most appropriate Skill (e.g., `qk-feature-delivery` for new UI, `qk-bug-resolution` for fixing errors).
-3. **Delegate (Handoff):**
-   - Handoff the gathered context to the selected Skill.
+## 🎯 Mission (Scope)
+- ✅ Phân tích yêu cầu và điều phối cho đúng Skill con.
+- ❌ Do NOT tự tay viết code hoặc thực hiện thay đổi hệ thống.
 
-## 🛡️ 2. Constraints & Rules
+---
 
-- **Delegation First:** Do not write source code directly while acting as the Orchestrator. Delegate to the correct specialized Skill.
-- **Ambiguity Check:** If the user's intent is unclear, give them 2-3 Skill suggestions to choose from.
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - delegation # <-- Core capability
+  - bias-review
+  - ship-check
+```
 
-## 🌳 3. Decision Tree
+---
 
-```text
-Is the task a massive project (e.g., "Build an Admin Dashboard")?
-  ├── YES → Break it down:
-  │       1. `qk-project-bootstrap` (Setup)
-  │       2. `qk-data-lifecycle` (DB Schema)
-  │       3. `qk-api-lifecycle` (Endpoints)
-  │       4. `qk-feature-delivery` (UI).
-  └── NO → Delegate to the single most appropriate skill.
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: autonomy # (Tự động quyết định hay chờ lệnh)
+  - id: strictness
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `delegate`: Call the target Skill.
+---
 
-## 📝 5. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: hallucinated-tools # (Tự bịa ra các tool/skill không tồn tại)
+  - id: absent-delegation # (Tự nhảy vào code thay vì giao việc)
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+---
 
-- **Tóm tắt (Summary):** Đã phân tích xong yêu cầu của User.
-- **Quyết định điều phối (Reasoning):** Giao việc cho Skill nào.
-- **Hành động tiếp (Next Action):** Tự động chuyển vai trò sang Skill được chọn.
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: delegation-only
+```

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

@@ -1,60 +1,55 @@
 ---
 name: qk-policy-engine
-version: 3.1.4
-updated: 2026-07-02
-description: Policy evaluation engine to ensure actions are authorized and safe.
+version: 5.0.0
+updated: 2026-07-03
+description: Hệ thống đánh giá chính sách để đảm bảo các hành động an toàn và được ủy quyền.
 category: security
-behavior: static-analysis
-intent: review-code
-priority: high
-tags: [security, policy, guardrails, authorization]
+tags: [security, policy, safety, guardrails]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
-trigger: User asks to perform a high-risk destructive action (e.g., DROP table, mass delete).
-inputs: [Requested Action, Context]
-outputs: [Approval/Denial, Policy violations]
-allowed_tools: [read_file]
-pipeline: [analyze, evaluate, complete]
 ---
 
-# 🛠️ qk-policy-engine - Standard Operating Procedure
+# 🛠️ qk-policy-engine
 
-> **Goal:** Đóng vai trò là "Bộ quy tắc thép" (Policy Enforcer). Ngăn chặn các lệnh sai lầm có thể phá hoại hệ thố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)
+---
 
-1. **Analyze (Risk Assessment):**
-   - Classify the user's request (Low, Medium, High risk).
-   - High Risk: Dropping databases, deleting multiple files, force-pushing to `main`.
-2. **Evaluate (Policy Check):**
-   - Load security policies (from `.agents/AGENTS.md` or `.cursorrules`).
-   - Check if the action violates any safety constraints.
-3. **Complete (Decision):**
-   - Approve (Allow execution) or Deny (Block execution) with explicit reasons.
+## 🎯 Mission (Scope)
+- ✅ Đóng vai trò Guardrails, ngăn chặn các hành vi phá hoại trước khi chúng diễn ra.
+- ❌ Do NOT đồng ý thực thi lệnh nguy hiểm (drop table, rm -rf) trừ khi có sự xác nhận mạnh mẽ.
 
-## 🛡️ 2. Constraints & Rules
+---
 
-- **Deny by Default:** If an action is highly destructive and no backup plan exists, DENY it.
-- **Override:** Only allow skipping the policy if the user explicitly passes an `--override` flag in their prompt.
+## ⚙️ Capabilities (Cognitive Pipeline)
+```yaml
+Pipeline:
+  - inference
+  - planning
+  - bias-review
+  - ship-check
+```
 
-## 🌳 3. Decision Tree
+---
 
-```text
-Does the action involve deleting data or resources in Production?
-  ├── YES → Has the user provided a backup confirmation?
-  │       ├── YES → Approve.
-  │       └── NO → DENY and request backup confirmation.
-  └── NO → Approve.
+## 🎛️ Dials (Hành vi)
+```yaml
+Dials:
+  - id: strictness
 ```
 
-## 🤝 4. Handoff Pipeline
-
-1. `complete`: Generate the Policy Decision Report.
+---
 
-## 📝 5. Output Format
+## 🛡️ Biases (Sửa lỗi mặc định)
+```yaml
+Biases:
+  - id: swallow-errors
+```
 
-Vui lòng trả kết quả bằng Tiếng Việt.
+---
 
-- **Tóm tắt (Summary):** Mức độ rủi ro (Risk Level).
-- **Phán quyết (Decision):** ✅ APPROVED hoặc ❌ DENIED.
-- **Nguyên nhân (Reasoning):** Vi phạm chính sách nào (nếu bị Deny).
-- **Hành động tiếp (Next Action):** ...
+## 🛫 Ship Criteria
+```yaml
+Rules:
+  - id: delegation-only
+```