ai-developer-skill-os 10.1.0 → 10.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/.agents/AGENTS.md +13 -0
  2. package/.agents/LICENSE +21 -21
  3. package/.agents/docs/ARCHITECTURE.md +56 -120
  4. package/.agents/docs/GOVERNANCE.md +3 -3
  5. package/.agents/docs/SPEC.md +137 -60
  6. package/.agents/docs/VERSIONING.md +25 -57
  7. package/.agents/docs/adr/0005-v10-platform-consolidation.md +50 -0
  8. package/.agents/docs/schemas/learning.schema.yml +22 -57
  9. package/.agents/docs/schemas/skill.schema.yml +116 -161
  10. package/.agents/docs/schemas/workflow.schema.yml +51 -26
  11. package/.agents/docs/skill-classification.md +1 -1
  12. package/.agents/registry/graph.json +171 -77
  13. package/.agents/registry/index.yaml +68 -35
  14. package/.agents/rules/coding.md +1 -1
  15. package/.agents/rules/command-safety.md +1 -1
  16. package/.agents/rules/global.md +1 -1
  17. package/.agents/rules/prompt-compiler.md +1 -1
  18. package/.agents/rules/safety.md +1 -1
  19. package/.agents/rules/security.md +1 -1
  20. package/.agents/rules/skill-quality.md +18 -3
  21. package/.agents/skills/_template/SKILL.md +238 -88
  22. package/.agents/skills/qk-api-data-discovery/SKILL.md +176 -190
  23. package/.agents/skills/qk-api-data-discovery/references/bronze-record-format.md +47 -0
  24. package/.agents/skills/qk-api-data-discovery/references/data-contract-yaml.md +72 -0
  25. package/.agents/skills/qk-api-data-discovery/references/discovery-report-template.md +110 -0
  26. package/.agents/skills/qk-backend-data/SKILL.md +150 -1
  27. package/.agents/skills/qk-bug-resolution/SKILL.md +153 -1
  28. package/.agents/skills/qk-bug-resolution/evals/scorecard.yaml +1 -1
  29. package/.agents/skills/qk-code-cleaner/SKILL.md +150 -1
  30. package/.agents/skills/qk-code-review/SKILL.md +195 -1
  31. package/.agents/skills/qk-code-review/evals/scorecard.yaml +1 -1
  32. package/.agents/skills/qk-code-review/references/ai/{v8-schema-validation.md → schema-validation.md} +2 -2
  33. package/.agents/skills/qk-code-review/references/cross-cutting/async-concurrency-patterns.md +515 -515
  34. package/.agents/skills/qk-code-review/references/cross-cutting/error-handling-principles.md +492 -492
  35. package/.agents/skills/qk-code-review/references/cross-cutting/n-plus-one-queries.md +309 -309
  36. package/.agents/skills/qk-code-review/references/cross-cutting/sql-injection-prevention.md +307 -307
  37. package/.agents/skills/qk-code-review/references/cross-cutting/xss-prevention.md +263 -263
  38. package/.agents/skills/qk-code-review/references/languages/angular.md +768 -768
  39. package/.agents/skills/qk-code-review/references/languages/c.md +890 -890
  40. package/.agents/skills/qk-code-review/references/languages/cpp.md +893 -893
  41. package/.agents/skills/qk-code-review/references/languages/css-less-sass.md +661 -661
  42. package/.agents/skills/qk-code-review/references/languages/django.md +985 -985
  43. package/.agents/skills/qk-code-review/references/languages/fastapi.md +580 -580
  44. package/.agents/skills/qk-code-review/references/languages/go.md +993 -993
  45. package/.agents/skills/qk-code-review/references/languages/java.md +409 -409
  46. package/.agents/skills/qk-code-review/references/languages/java8.md +586 -586
  47. package/.agents/skills/qk-code-review/references/languages/kotlin.md +1018 -1018
  48. package/.agents/skills/qk-code-review/references/languages/nestjs.md +593 -593
  49. package/.agents/skills/qk-code-review/references/languages/php.md +684 -684
  50. package/.agents/skills/qk-code-review/references/languages/python.md +1073 -1073
  51. package/.agents/skills/qk-code-review/references/languages/qt.md +757 -757
  52. package/.agents/skills/qk-code-review/references/languages/react.md +871 -871
  53. package/.agents/skills/qk-code-review/references/languages/ruby.md +964 -964
  54. package/.agents/skills/qk-code-review/references/languages/rust.md +846 -846
  55. package/.agents/skills/qk-code-review/references/languages/svelte.md +1064 -1064
  56. package/.agents/skills/qk-code-review/references/languages/swift.md +936 -936
  57. package/.agents/skills/qk-code-review/references/languages/typescript.md +1016 -1016
  58. package/.agents/skills/qk-code-review/references/languages/vue.md +924 -924
  59. package/.agents/skills/qk-code-review/references/languages/zig.md +440 -440
  60. package/.agents/skills/qk-devops-release/SKILL.md +150 -1
  61. package/.agents/skills/qk-feature-delivery/SKILL.md +153 -1
  62. package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
  63. package/.agents/skills/qk-orchestrator/SKILL.md +187 -2
  64. package/.agents/skills/qk-orchestrator/evals/scorecard.yaml +1 -1
  65. package/.agents/skills/qk-orchestrator/references/routing-table.md +1 -1
  66. package/.agents/skills/qk-product-spec/SKILL.md +150 -1
  67. package/.agents/skills/qk-prompt-compiler/SKILL.md +188 -65
  68. package/.agents/skills/qk-ui-engineer/SKILL.md +150 -1
  69. package/.agents/workflows/_schema.yml +146 -146
  70. package/.agents/workflows/bug-resolution.yml +155 -121
  71. package/.agents/workflows/code-review.yml +127 -93
  72. package/.agents/workflows/context-discovery.yml +128 -94
  73. package/.agents/workflows/documentation.yml +124 -90
  74. package/.agents/workflows/feature-delivery.yml +158 -124
  75. package/.agents/workflows/production-release.yml +207 -173
  76. package/.agents/workflows/prompt-compilation.yml +126 -0
  77. package/.agents/workflows/refactor.yml +136 -102
  78. package/.agents/workflows/security-audit.yml +149 -115
  79. package/.agents/workflows/shared/quality-gate.yml +3 -1
  80. package/.agents/workflows/skin-governance.yml +149 -115
  81. package/.agents/workflows/spec-driven-development.yml +78 -71
  82. package/CHANGELOG.md +61 -0
  83. package/README.md +3 -3
  84. package/bin/install.js +38 -51
  85. package/package.json +68 -74
  86. package/tooling/build-registry.js +226 -208
  87. package/tooling/run-aar.js +55 -126
  88. package/tooling/sync-versions.js +2 -2
  89. package/tooling/validate-graph.js +100 -87
  90. package/tooling/validate-skills.js +32 -14
  91. package/.agents/docs/decisions/ADR-001-v8-migration.md +0 -58
  92. package/.agents/docs/decisions/ADR-002-workflow-separation.md +0 -50
  93. package/.agents/docs/decisions/ADR-003-registry-generated.md +0 -54
  94. package/.agents/docs/decisions/ADR-008-skill-boundary-review.md +0 -27
  95. package/.agents/registry/capability-graph.yml +0 -390
  96. package/.agents/registry/skills-index.yml +0 -305
  97. package/.agents/skills/_template/capability.yaml +0 -34
  98. package/.agents/skills/_template/evals/scorecard.yaml +0 -19
@@ -1,9 +1,11 @@
1
1
  ---
2
2
  name: qk-devops-release
3
- version: 10.1.0
3
+ version: 10.2.0
4
4
  status: stable
5
5
  subtitle: "DevOps, CI/CD & Deploy"
6
6
  description: "Vận hành Nền tảng, Tự động hóa CI/CD, Cổng kiểm soát phát hành 8-Gate Production, Đồng bộ tài liệu kỹ thuật, Bộ nhớ dự án (.ai-local/) và Kỹ nghệ AI/RAG. Dùng khi: ci/cd, deployment, pipeline, docker, dockerfile, devops, github actions, deploy production, release checklist, go live, rollout, viết docs, readme, swagger, lưu context, project memory, /learn, build ai, rag pipeline, prompt engineering — TUYỆT ĐỐI KHÔNG dùng khi debug lỗi logic ứng dụng (dùng qk-bug-resolution)."
7
+ platforms: [antigravity, claude, opencode]
8
+ runtime_version: 1
7
9
  tools:
8
10
  - filesystem
9
11
  - terminal
@@ -42,6 +44,83 @@ triggers:
42
44
 
43
45
  ---
44
46
 
47
+ ## Memory Workflow
48
+
49
+ ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
50
+ - 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:
51
+ - **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.
52
+ - **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.
53
+
54
+ ---
55
+
56
+ ### Pre-flight Retrieve (Trước khi thực thi)
57
+ - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
58
+ bắt buộc tra cứu:
59
+ - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
60
+
61
+ - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
62
+ - Architecture
63
+ - Hard Bug
64
+ - Convention
65
+ - Pattern
66
+ - Tech Debt Pattern
67
+
68
+ - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
69
+ Không được xem Memory là Source of Truth.
70
+ 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.
71
+
72
+ ---
73
+
74
+ ### Learning Flow (AI tự học có kiểm soát)
75
+ - 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:
76
+ - Hard Bug có khả năng tái diễn.
77
+ - Pattern làm việc lặp lại trong dự án.
78
+ - Convention hoặc quy tắc kiến trúc mới.
79
+ - Quyết định Architecture quan trọng.
80
+ - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
81
+
82
+ - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
83
+ - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
84
+ - AI không được tự động Promote Candidate Memory thành Project Knowledge.
85
+
86
+ ---
87
+
88
+ ### Post-flight Harvest (Đề xuất → Phê duyệt)
89
+ Sau khi hoàn thành task:
90
+ - AI đánh giá các Candidate Memory đã tạo.
91
+ - Nếu phát hiện tri thức có giá trị tái sử dụng:
92
+ - Đề xuất người dùng xem xét.
93
+ - Gửi yêu cầu phê duyệt thông qua:
94
+ - `/learn`
95
+ - `qk-project-memory`
96
+ - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
97
+
98
+ ```
99
+ .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
100
+ ```
101
+
102
+ - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
103
+ - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
104
+
105
+ ---
106
+
107
+ ### Ignore (Không đưa vào Memory)
108
+ Không lưu:
109
+ - Trace log của một session đơn lẻ.
110
+ - Temporary debugging data.
111
+ - Output của một lần chạy test/scan.
112
+ - Report health tạm thời của một đợt kiểm tra.
113
+ - Lỗi nhỏ chỉ xảy ra một lần.
114
+ - Thông tin không có khả năng tái sử dụng.
115
+
116
+ ---
117
+
118
+ ### Golden Rule
119
+ > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
120
+ > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
121
+
122
+ ---
123
+
45
124
  ## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
46
125
 
47
126
  > **Core Principle:** Right-size infrastructure. Do not design a Kubernetes cluster for a static site. Automation must be dependable, reproducible, and guarded by strict safety gates.
@@ -143,3 +222,73 @@ Tình trạng 8 Cổng An Toàn (Truth-First):
143
222
  • Gate 7 (SemVer): [Bump vX.Y.Z]
144
223
  • Gate 8 (Changelog): [Sẵn sàng Release Notes]
145
224
  ```
225
+
226
+ ---
227
+
228
+ ## 7. Mô Hình Độ Tin Cậy (Confidence Model)
229
+
230
+ | Level | Condition | Action |
231
+ |-------|-----------|--------|
232
+ | HIGH | Direct evidence available | Proceed |
233
+ | MEDIUM | Some assumptions needed | Note assumptions |
234
+ | LOW | Insufficient evidence | EXIT: BLOCKED |
235
+
236
+ ---
237
+
238
+ ## 8. Thoái Ra Mã (Exit Codes)
239
+
240
+ | Code | Meaning | When |
241
+ |------|---------|------|
242
+ | SUCCESS | Task completed and verified | All acceptance criteria met |
243
+ | PARTIAL | Task done with minor gaps | Some checks skipped |
244
+ | BLOCKED | Missing precondition or info | Ask user |
245
+ | FAILED | Task failed after max retries | Report error |
246
+
247
+ ---
248
+
249
+ ## 9. Bằng Chứng Định Dạng (Evidence Format)
250
+
251
+ ```
252
+ [SEVERITY] path/to/file.ts:LINE
253
+ Reason: [why this matters]
254
+ Confidence: [HIGH|MEDIUM|LOW]
255
+ Fix: [suggestion]
256
+ ```
257
+
258
+ ---
259
+
260
+ ## Platform-Specific Instructions
261
+
262
+ ### Antigravity (Google Gemini)
263
+ - Uses `.agents/AGENTS.md` as entry point
264
+ - Supports Cockpit integration
265
+ - Rewrite absolute paths for global mode
266
+ - `GEMINI.md` copied for global installs
267
+
268
+ ### Claude Code (Anthropic)
269
+ - Reads `.claude/CLAUDE.md` automatically
270
+ - Large context window (~200K tokens)
271
+ - Can handle full skill files without trimming
272
+ - Uses native tool format (Read, Write, Edit, Bash)
273
+
274
+ ### OpenCode (Open Source)
275
+ - Reads `.opencode/config.yaml`
276
+ - Context window ~128K tokens
277
+ - Keep skill files lean when possible
278
+ - Supports custom tool format
279
+
280
+ ---
281
+
282
+ ## Compliance
283
+
284
+ | Check | Status |
285
+ |-------|--------|
286
+ | Runtime Standard | 11/11 |
287
+ | Frontmatter Complete | ✅ |
288
+ | Platforms Field | ✅ |
289
+ | References Valid | ✅ |
290
+ | Decision Trees | PASS |
291
+ | Thresholds Defined | PASS |
292
+ | schema_version | 10.2.0 |
293
+ | runtime_version | 1 |
294
+ | platforms | [antigravity, claude, opencode] |
@@ -1,9 +1,11 @@
1
1
  ---
2
2
  name: qk-feature-delivery
3
- version: 10.1.0
3
+ version: 10.2.0
4
4
  status: stable
5
5
  subtitle: "Build Feature mới"
6
6
  description: "Phát triển tính năng mới end-to-end: Thiết lập Contract kiểu dữ liệu, tích hợp gọi API, xử lý trọn vẹn 4 trạng thái UI (Loading/Success/Empty/Error) và tuân thủ YAGNI/SOLID. Dùng khi: add feature, phát triển tính năng mới, tạo mới, build new, thêm chức năng, tích hợp api, fetch data, consume api, bind data, state management — TUYỆT ĐỐI KHÔNG dùng cho việc fix bug (dùng qk-bug-resolution) hoặc dọn dẹp code cũ (dùng qk-code-cleaner)."
7
+ platforms: [antigravity, claude, opencode]
8
+ runtime_version: 1
7
9
  tools:
8
10
  - filesystem
9
11
  - terminal
@@ -30,6 +32,86 @@ triggers:
30
32
 
31
33
  ---
32
34
 
35
+ ## Memory Workflow
36
+
37
+ ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
38
+ - 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:
39
+ - **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.
40
+ - **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.
41
+
42
+ ---
43
+
44
+ ### Pre-flight Retrieve (Trước khi thực thi)
45
+ - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
46
+ bắt buộc tra cứu:
47
+ - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
48
+
49
+ - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
50
+ - Architecture
51
+ - Hard Bug
52
+ - Convention
53
+ - Pattern
54
+ - Tech Debt Pattern
55
+ - 👉 *Domain Focus:* Architecture / Pattern / Convention liên quan đến luồng tính năng hiện tại.
56
+
57
+ - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
58
+ Không được xem Memory là Source of Truth.
59
+ 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.
60
+
61
+ ---
62
+
63
+ ### Learning Flow (AI tự học có kiểm soát)
64
+ - 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:
65
+ - Hard Bug có khả năng tái diễn.
66
+ - Pattern làm việc lặp lại trong dự án.
67
+ - Convention hoặc quy tắc kiến trúc mới.
68
+ - Quyết định Architecture quan trọng.
69
+ - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
70
+ - 👉 *Domain Harvest:* Quyết định Architecture hoặc Pattern mới hình thành khi làm feature.
71
+
72
+ - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
73
+ - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
74
+ - AI không được tự động Promote Candidate Memory thành Project Knowledge.
75
+
76
+ ---
77
+
78
+ ### Post-flight Harvest (Đề xuất → Phê duyệt)
79
+ Sau khi hoàn thành task:
80
+ - AI đánh giá các Candidate Memory đã tạo.
81
+ - Nếu phát hiện tri thức có giá trị tái sử dụng:
82
+ - Đề xuất người dùng xem xét.
83
+ - Gửi yêu cầu phê duyệt thông qua:
84
+ - `/learn`
85
+ - `qk-project-memory`
86
+ - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
87
+
88
+ ```
89
+ .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
90
+ ```
91
+
92
+ - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
93
+ - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
94
+
95
+ ---
96
+
97
+ ### Ignore (Không đưa vào Memory)
98
+ Không lưu:
99
+ - Trace log của một session đơn lẻ.
100
+ - Temporary debugging data.
101
+ - Output của một lần chạy test/scan.
102
+ - Report health tạm thời của một đợt kiểm tra.
103
+ - Lỗi nhỏ chỉ xảy ra một lần.
104
+ - Thông tin không có khả năng tái sử dụng.
105
+ - 👉 *Domain Ignore:* Dữ liệu mock phục vụ thử nghiệm tính năng ban đầu.
106
+
107
+ ---
108
+
109
+ ### Golden Rule
110
+ > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
111
+ > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
112
+
113
+ ---
114
+
33
115
  ## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
34
116
 
35
117
  > **Core Principle:** YAGNI (You Aren't Gonna Need It). Build the simplest, cleanest solution that fully satisfies today's requirement. Do not write tomorrow's abstractions today.
@@ -181,3 +263,73 @@ Kiểm chứng thực tế (Verify Before Claim):
181
263
  • YAGNI: ✅ Giữ giải pháp tối giản, không sinh abstraction thừa
182
264
  • Zero Hack: ✅ Không dùng any, @ts-ignore, hay silent catch
183
265
  ```
266
+
267
+ ---
268
+
269
+ ## 8. Mô Hình Độ Tin Cậy (Confidence Model)
270
+
271
+ | Level | Condition | Action |
272
+ |-------|-----------|--------|
273
+ | HIGH | Direct evidence available | Proceed |
274
+ | MEDIUM | Some assumptions needed | Note assumptions |
275
+ | LOW | Insufficient evidence | EXIT: BLOCKED |
276
+
277
+ ---
278
+
279
+ ## 9. Thoái Ra Mã (Exit Codes)
280
+
281
+ | Code | Meaning | When |
282
+ |------|---------|------|
283
+ | SUCCESS | Task completed and verified | All acceptance criteria met |
284
+ | PARTIAL | Task done with minor gaps | Some checks skipped |
285
+ | BLOCKED | Missing precondition or info | Ask user |
286
+ | FAILED | Task failed after max retries | Report error |
287
+
288
+ ---
289
+
290
+ ## 10. Bằng Chứng Định Dạng (Evidence Format)
291
+
292
+ ```
293
+ [SEVERITY] path/to/file.ts:LINE
294
+ Reason: [why this matters]
295
+ Confidence: [HIGH|MEDIUM|LOW]
296
+ Fix: [suggestion]
297
+ ```
298
+
299
+ ---
300
+
301
+ ## Platform-Specific Instructions
302
+
303
+ ### Antigravity (Google Gemini)
304
+ - Uses `.agents/AGENTS.md` as entry point
305
+ - Supports Cockpit integration
306
+ - Rewrite absolute paths for global mode
307
+ - `GEMINI.md` copied for global installs
308
+
309
+ ### Claude Code (Anthropic)
310
+ - Reads `.claude/CLAUDE.md` automatically
311
+ - Large context window (~200K tokens)
312
+ - Can handle full skill files without trimming
313
+ - Uses native tool format (Read, Write, Edit, Bash)
314
+
315
+ ### OpenCode (Open Source)
316
+ - Reads `.opencode/config.yaml`
317
+ - Context window ~128K tokens
318
+ - Keep skill files lean when possible
319
+ - Supports custom tool format
320
+
321
+ ---
322
+
323
+ ## Compliance
324
+
325
+ | Check | Status |
326
+ |-------|--------|
327
+ | Runtime Standard | 11/11 |
328
+ | Frontmatter Complete | ✅ |
329
+ | Platforms Field | ✅ |
330
+ | References Valid | ✅ |
331
+ | Decision Trees | PASS |
332
+ | Thresholds Defined | PASS |
333
+ | schema_version | 10.2.0 |
334
+ | runtime_version | 1 |
335
+ | platforms | [antigravity, claude, opencode] |
@@ -1,6 +1,6 @@
1
1
  name: qk-feature-delivery-eval
2
2
  description: Đánh giá quy trình phát triển tính năng mới (End-to-End)
3
- version: 9.1.0
3
+ version: 10.2.0
4
4
  threshold: 85 # Tính năng mới phải đáp ứng các tiêu chuẩn khắt khe trước khi hoàn thành
5
5
 
6
6
  metrics:
@@ -1,9 +1,11 @@
1
1
  ---
2
2
  name: qk-orchestrator
3
- version: 10.1.0
3
+ version: 10.2.0
4
4
  status: stable
5
5
  subtitle: "Điều hướng & Context"
6
6
  description: "Cổng điều phối trung tâm: Nạp kiến trúc dự án (Context Graph), tự động khởi tạo hồ sơ (Bootstrap DEV_PROFILE.md) và định tuyến chính xác đến 1 trong 9 Super-Skills. Dùng khi: help, list skills, chọn skill gì, route task, load context, tìm hiểu codebase, giải thích kiến trúc dự án, setup dev profile, bootstrap dự án mới — TUYỆT ĐỐI KHÔNG trực tiếp code hay sửa file dự án."
7
+ platforms: [antigravity, claude, opencode]
8
+ runtime_version: 1
7
9
  tools:
8
10
  - filesystem
9
11
  - terminal
@@ -32,6 +34,86 @@ triggers:
32
34
 
33
35
  ---
34
36
 
37
+ ## Memory Workflow
38
+
39
+ ### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
40
+ - 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:
41
+ - **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.
42
+ - **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.
43
+
44
+ ---
45
+
46
+ ### Pre-flight Retrieve (Trước khi thực thi)
47
+ - Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
48
+ bắt buộc tra cứu:
49
+ - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
50
+
51
+ - Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
52
+ - Architecture
53
+ - Hard Bug
54
+ - Convention
55
+ - Pattern
56
+ - Tech Debt Pattern
57
+ - 👉 *Domain Focus:* Architecture / Convention (vd: bảng điều hướng kỹ năng, ràng buộc ranh giới rõ ràng).
58
+
59
+ - Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
60
+ Không được xem Memory là Source of Truth.
61
+ 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.
62
+
63
+ ---
64
+
65
+ ### Learning Flow (AI tự học có kiểm soát)
66
+ - 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:
67
+ - Hard Bug có khả năng tái diễn.
68
+ - Pattern làm việc lặp lại trong dự án.
69
+ - Convention hoặc quy tắc kiến trúc mới.
70
+ - Quyết định Architecture quan trọng.
71
+ - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
72
+ - 👉 *Domain Harvest:* Quy luật phân phối routing hiệu quả mới.
73
+
74
+ - Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
75
+ - Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
76
+ - AI không được tự động Promote Candidate Memory thành Project Knowledge.
77
+
78
+ ---
79
+
80
+ ### Post-flight Harvest (Đề xuất → Phê duyệt)
81
+ Sau khi hoàn thành task:
82
+ - AI đánh giá các Candidate Memory đã tạo.
83
+ - Nếu phát hiện tri thức có giá trị tái sử dụng:
84
+ - Đề xuất người dùng xem xét.
85
+ - Gửi yêu cầu phê duyệt thông qua:
86
+ - `/learn`
87
+ - `qk-project-memory`
88
+ - Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
89
+
90
+ ```
91
+ .ai-local/candidates/ ──(Approve)──> .ai-local/knowledge/index.yaml
92
+ ```
93
+
94
+ - Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
95
+ - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
96
+
97
+ ---
98
+
99
+ ### Ignore (Không đưa vào Memory)
100
+ Không lưu:
101
+ - Trace log của một session đơn lẻ.
102
+ - Temporary debugging data.
103
+ - Output của một lần chạy test/scan.
104
+ - Report health tạm thời của một đợt kiểm tra.
105
+ - Lỗi nhỏ chỉ xảy ra một lần.
106
+ - Thông tin không có khả năng tái sử dụng.
107
+ - 👉 *Domain Ignore:* Trình tự gọi lệnh tạm thời của một prompt user.
108
+
109
+ ---
110
+
111
+ ### Golden Rule
112
+ > **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
113
+ > **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
114
+
115
+ ---
116
+
35
117
  ## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
36
118
 
37
119
  > **Core Principle:** The dispatcher routes; it does not implement. Load just enough context to make precise technical decisions without overwhelming the conversation window.
@@ -105,4 +187,107 @@ Bản đồ kiến trúc nhanh:
105
187
 
106
188
  ⚡ Chuyển giao thực thi:
107
189
  Đang kích hoạt [<Super-Skill>](file:///<workspace-root>/.agents/skills/<super-skill>/SKILL.md) để xử lý yêu cầu.
108
- ```
190
+ ```
191
+
192
+ ---
193
+
194
+ ## 6. Mô Hình Độ Tin Cậy (Confidence Model)
195
+
196
+ | Level | Condition | Action |
197
+ |-------|-----------|--------|
198
+ | HIGH | Intent keyword matches exactly one skill in routing table | Route directly |
199
+ | MEDIUM | Multiple possible skills match | Route to most likely, note ambiguity |
200
+ | LOW | Request is too vague or conflicts with DEV_PROFILE.md role | EXIT: BLOCKED |
201
+
202
+ ---
203
+
204
+ ## 7. Mức Độ Nghiêm Trọng (Severity)
205
+
206
+ | Level | Definition | Example |
207
+ |-------|-----------|---------|
208
+ | CRITICAL | Routing to wrong skill causing data loss or security issue | Sending auth task to qk-ui-engineer |
209
+ | HIGH | Missing routing target or precondition not verified | No matching skill, DESIGN.md missing |
210
+ | MEDIUM | Ambiguous intent requiring user clarification | Multiple skills match equally |
211
+ | LOW | Minor routing inefficiency | Could route to a more specific skill |
212
+
213
+ ---
214
+
215
+ ## 8. Bằng Chứng Định Dạng (Evidence Format)
216
+
217
+ ```
218
+ [SEVERITY] context: [intent/trigger]
219
+ Routing: [source → target-skill]
220
+ Confidence: [HIGH|MEDIUM|LOW]
221
+ Manifest: [package.json | tsconfig.json | ... verified]
222
+ ```
223
+
224
+ **Example:**
225
+ ```
226
+ [HIGH] context: "fix login bug"
227
+ Routing: user → qk-orchestrator → qk-bug-resolution
228
+ Confidence: HIGH
229
+ Manifest: package.json verified (React 18)
230
+ ```
231
+
232
+ ---
233
+
234
+ ## 9. Chính Sách Retry
235
+
236
+ ```
237
+ Routing ambiguous
238
+ └─ Ask clarifying question
239
+ ├─ User clarifies → Retry routing
240
+ └─ 2nd clarification still ambiguous
241
+ └─ EXIT: BLOCKED — request more specific description
242
+ ```
243
+
244
+ Max retries: 2. After 2nd ambiguous match → EXIT: BLOCKED.
245
+
246
+ ---
247
+
248
+ ## 10. Thoái Ra Mã (Exit Codes)
249
+
250
+ | Code | Meaning | When |
251
+ |------|---------|------|
252
+ | SUCCESS | Skill routed, preconditions verified, delegation in progress | Normal flow |
253
+ | PARTIAL | Routed with MEDIUM confidence — ambiguity noted | Multiple skills match |
254
+ | BLOCKED | Cannot classify intent or precondition missing | Vague request or missing DESIGN.md |
255
+ | FAILED | No skill matches and cannot escalate | Unknown domain request |
256
+
257
+ ---
258
+
259
+ ## Platform-Specific Instructions
260
+
261
+ ### Antigravity (Google Gemini)
262
+ - Uses `.agents/AGENTS.md` as entry point
263
+ - Supports Cockpit integration
264
+ - Rewrite absolute paths for global mode
265
+ - `GEMINI.md` copied for global installs
266
+
267
+ ### Claude Code (Anthropic)
268
+ - Reads `.claude/CLAUDE.md` automatically
269
+ - Large context window (~200K tokens)
270
+ - Can handle full skill files without trimming
271
+ - Uses native tool format (Read, Write, Edit, Bash)
272
+
273
+ ### OpenCode (Open Source)
274
+ - Reads `.opencode/config.yaml`
275
+ - Context window ~128K tokens
276
+ - Keep skill files lean when possible
277
+ - Supports custom tool format
278
+
279
+ ---
280
+
281
+ ## Compliance
282
+
283
+ | Check | Status |
284
+ |-------|--------|
285
+ | Runtime Standard | 11/11 |
286
+ | Frontmatter Complete | ✅ |
287
+ | Platforms Field | ✅ |
288
+ | References Valid | ✅ |
289
+ | Decision Trees | PASS |
290
+ | Thresholds Defined | PASS |
291
+ | schema_version | 10.2.0 |
292
+ | runtime_version | 1 |
293
+ | platforms | [antigravity, claude, opencode] |
@@ -1,6 +1,6 @@
1
1
  name: qk-orchestrator-eval
2
2
  description: Đánh giá khả năng điều phối và định tuyến tác vụ (Task Routing)
3
- version: 9.1.0
3
+ version: 10.2.0
4
4
  threshold: 85 # Đóng vai trò kiểm soát luồng, yêu cầu độ chính xác cao
5
5
 
6
6
  metrics:
@@ -83,4 +83,4 @@ When 2+ skills match:
83
83
  | "refactor" + API | `qk-refactor` if code quality focus, `qk-api-lifecycle` if contract change |
84
84
  | "add feature" + DB | Route `qk-feature-delivery` with `qk-data-lifecycle` in pipeline |
85
85
  | "optimize" without context | Ask: "DB performance or code quality?" |
86
-
86
+