ai-developer-skill-os 9.1.2 → 9.3.0

package/.agents/rules/coding.md

@@ -110,3 +110,26 @@ Ngoài R-C-01 đến R-C-08 ở trên, Agent **MUST** tuân thủ đầy đủ d
 - `references/anti-patterns.md` là phần **mở rộng chi tiết** của rule này, không thay thế các rule R-C-01–08.
 - Khi viết component UI, đối chiếu thêm với `references/component-cookbook.md` để đảm bảo đúng cấu trúc giải phẫu (Types → Hook → JSX).
 - Nếu 2 nguồn mâu thuẫn nhau, `coding.md` (rule cấp cao) được ưu tiên; báo cáo mâu thuẫn để cập nhật `anti-patterns.md`.
+
+---
+
+## R-C-10: Engineering Standards Checklist (Absorbed from qk-engineering-standard)
+
+> Áp dụng cho mọi skill có `side_effects: edit_files`. Đây là checklist tự động — không cần gọi skill riêng.
+
+Trước khi báo cáo task hoàn thành, **MUST** verify từng điểm:
+
+| # | Tiêu chí | Threshold |
+|---|---|---|
+| 1 | Function length | ≤ 40 lines |
+| 2 | File length | ≤ 300 lines |
+| 3 | Function params | ≤ 4 |
+| 4 | Nesting depth | ≤ 3 levels |
+| 5 | Cyclomatic complexity | ≤ 10 |
+| 6 | No magic numbers | Dùng named constants |
+| 7 | No silent errors | Không empty catch, không `!`, không `any` |
+| 8 | DRY | Extract khi logic lặp ≥ 2 lần |
+| 9 | Naming conventions | camelCase fn, PascalCase class, UPPER_SNAKE constant |
+| 10 | No `console.log` in production code | Dùng logger hoặc xóa trước commit |
+
+**Violation:** Nếu bất kỳ điểm nào không đạt → sửa trước khi report SUCCESS. Không report PARTIAL chỉ vì threshold bị vi phạm.

package/.agents/rules/global.md

@@ -1,5 +1,5 @@
 ---
-version: 8.0.0
+version: 9.2.0
 description: "Agent behavior policies applied globally across all capabilities."
 domain: rules
 applies_to: all
@@ -49,7 +49,7 @@ Verify each step before next
 
 - Do NOT refactor code outside the task scope.
 - Do NOT "improve" unrelated files while working.
-- Do NOT run commands with broad side effects (e.g., `rm -rf`, `git reset --hard`) without explicit user confirmation.
+- Do NOT run commands with broad side effects (`rm -rf`, `git reset --hard`) without explicit user confirmation.
 
 ---
 
@@ -57,26 +57,31 @@ Verify each step before next
 
 **MUST** respect the `token_budget` defined in each skill's frontmatter.
 
-- Read files in targeted chunks (`view_file[start:end]`), never entire large files.
+- Read files in targeted chunks, never entire large files.
 - Use `grep_search` for pattern discovery, not full-file reads.
 - Stop reading when sufficient evidence is found (`stop_early: true`).
 - Never read: `node_modules/`, `dist/`, `.git/`, binary files.
 
 ---
 
-## R-G-05: Retrieval Path (AI-Native)
+## R-G-05: Retrieval Path (Compact — v9.2)
 
-When starting a task, the agent MUST follow this retrieval sequence:
+When starting a task, follow this sequence:
 
 ```
-1. Read registry/skills-index.yml → identify candidate skills
-2. Read candidate SKILL.md(s) → confirm intent + preconditions
-3. Load referenced workflow → understand execution steps
-4. Load referenced rules (this file + coding.md if needed)
-5. Execute
+1. Read .agents/DEV_PROFILE.md     → get role + stack
+2. Match intent against routing table in .agents/AGENTS.md
+3. Read the matching SKILL.md      → confirm intent + preconditions
+4. Load referenced workflow YAML   → understand execution steps
+5. Load rules/global.md + coding.md (if edit_files task)
+6. Execute step by step
+7. Exit with: SUCCESS | BLOCKED | FAILED | PARTIAL
 ```
 
-Do NOT load all skills. Do NOT scan the entire repository.
+**Do NOT:**
+- Read `registry/skills-index.yml` to route — use the inline routing table in `.agents/AGENTS.md`
+- Load all skills at once
+- Scan entire repository before starting
 
 ---
 
@@ -100,6 +105,7 @@ Never silently terminate. Always report exit code and reason.
 - **Code, identifiers, filenames, YAML keys:** English only.
 - **Explanations, summaries, reports to user:** Vietnamese (match user's language).
 - **SKILL.md body headings:** English.
+- **Commit messages:** English (Conventional Commits format).
 
 ---
 
@@ -107,42 +113,50 @@ Never silently terminate. Always report exit code and reason.
 
 **NEVER** use `?.`, `!`, `try/catch {}` (empty catch), or type casting to suppress errors.
 
-Fix root cause. If root cause is unclear → report as BLOCKED with evidence.
+Fix root cause. If root cause is unclear → report as `BLOCKED` with evidence.
 
 ---
 
 ## R-G-09: Legacy Skill Handling
 
-Agent **MUST** prefer stable skills.
+Agent **MUST** prefer stable skills over experimental or deprecated ones.
 
-Legacy skills **MAY** be selected only when:
-1. No stable candidate exists
-2. User explicitly requests legacy behavior
-3. Migration incomplete
-
-Legacy skills **MUST NOT** outrank stable skills.
+Deprecated skills **MUST NOT** be selected. If a user asks for a deprecated skill, explain the replacement.
 
 ---
 
 ## R-G-10: Ambiguity Resolution
 
-Agent **MUST NOT** execute when:
-`selection confidence < threshold`
+Agent **MUST NOT** execute when selection confidence < threshold.
 
 Agent **SHOULD**:
 1. Ask clarification
-2. Present top candidates
-3. Explain missing information
+2. Present top 2-3 candidate skills with brief descriptions
+3. Explain what information is missing
 
 ---
 
-## R-G-11: Knowledge & Memory Discipline (V1 / AI Skin V9)
+## R-G-11: SKILL.md Description Standard (Anthropic-aligned)
+
+Every SKILL.md `description` field **MUST** satisfy both:
+
+**(a) What it does** — concrete action the skill performs
+**(b) When to use** — trigger context, keywords, situations
+
+**Bad:** `"Xử lý dữ liệu."`
+**Good:** `"Thiết kế và implement API endpoint mới (REST/GraphQL/tRPC). Dùng skill này khi user nhắc đến: viết api, tạo endpoint, thiết kế api, build api, route handler, controller — kể cả khi chỉ hỏi về request/response schema."`
+
+Description phải đủ mạnh để AI **không under-trigger** (bỏ qua skill khi lẽ ra nên dùng).
+
+---
 
-**MUST** govern project memory like source code: simple, reviewable, updatable, and always human-approved.
+## R-G-12: Progressive Disclosure — SKILL.md Size Limit
 
-- **Self-Init & Local Private Mode:** Always use `.ai-local/` (Private Mode, gitignored) as the sole storage for learned knowledge and memory. If `.ai-local/` does not exist in the project root, the agent **MUST** automatically create the folder structure (`.ai-local/knowledge/`, `.ai-local/candidates/`) and add `.ai-local/` to the project's `.gitignore` file immediately before proceeding. Shared Mode (`.agents/knowledge/index.yaml`) is explicitly disabled and prohibited for dynamic project memory.
-- **Navigator ONLY:** Memory reduces discovery time; it is NOT a replacement for checking live source code.
-- **Strict Content Bounds:** Only store 4 categories in `knowledge/index.yaml`: `Architecture`, `Convention`, `Pattern`, and `Hard Bug`. Discard routine typos, trivial CSS, and standard CRUD.
-- **Zero-Overwrite & Portable:** Mark outdated facts as `status: Archived` (never overwrite history). Always use workspace-relative paths (`src/...`) and AST symbol names instead of hardcoded disk paths or rigid line numbers.
-- **No Silent Mutate:** Never edit memory files automatically without proposing to the developer and receiving affirmative confirmation via `/learn` or explicit instructions.
+SKILL.md body (không tính frontmatter) **MUST** be < 500 lines.
 
+Nếu gần chạm 500 dòng:
+- Tách phần chi tiết ra `references/*.md`
+- Ghi rõ trong SKILL.md: *"Khi cần X → đọc `references/X.md`"*
+- Layer 1 (frontmatter) luôn trong context
+- Layer 2 (SKILL.md body) nạp khi skill active
+- Layer 3 (references/, scripts/, assets/) nạp on-demand

package/.agents/skills/_template/SKILL.md

@@ -1,7 +1,7 @@
----
+---
 # ── Identity ───────────────────────────────────────────────
 name: qk-[skill-name]
-version: 9.1.0
+version: 9.2.0
 status: stable
 description: "[Một câu — skill này làm gì và dành cho ai]"
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
@@ -86,378 +86,3 @@ exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 # qk-[skill-name] — [Short Title]
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
----
-
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
-## Preconditions
-
-- [ ] [Required condition 1]
-- [ ] [Required condition 2]
-
-```
-On missing precondition → EXIT: BLOCKED
-Report: "Missing: [what is needed]"
-```
-
----
-
-## Scope
-
-**This skill does:**
-- ✅ [What it does — be specific]
-- ✅ [Another thing it does]
-
-**This skill does NOT:**
-- ❌ [Explicit exclusion 1]
-- ❌ [Explicit exclusion 2 — avoid scope creep]
-
----
-
-## Output Format
-
-```markdown
-## [Skill Name] Result
-
-**Status:** SUCCESS | BLOCKED | FAILED | PARTIAL
-**Exit:** [exit_code]
-
-### Summary
-[1-2 sentences]
-
-### Details
-[Main output content]
-
-### Verification
-[What was verified and how]
-```
-