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.
- package/.agents/AGENTS.md +13 -0
- package/.agents/LICENSE +21 -21
- package/.agents/docs/ARCHITECTURE.md +56 -120
- package/.agents/docs/GOVERNANCE.md +3 -3
- package/.agents/docs/SPEC.md +137 -60
- package/.agents/docs/VERSIONING.md +25 -57
- package/.agents/docs/adr/0005-v10-platform-consolidation.md +50 -0
- package/.agents/docs/schemas/learning.schema.yml +22 -57
- package/.agents/docs/schemas/skill.schema.yml +116 -161
- package/.agents/docs/schemas/workflow.schema.yml +51 -26
- package/.agents/docs/skill-classification.md +1 -1
- package/.agents/registry/graph.json +171 -77
- package/.agents/registry/index.yaml +68 -35
- package/.agents/rules/coding.md +1 -1
- package/.agents/rules/command-safety.md +1 -1
- package/.agents/rules/global.md +1 -1
- package/.agents/rules/prompt-compiler.md +1 -1
- package/.agents/rules/safety.md +1 -1
- package/.agents/rules/security.md +1 -1
- package/.agents/rules/skill-quality.md +18 -3
- package/.agents/skills/_template/SKILL.md +238 -88
- package/.agents/skills/qk-api-data-discovery/SKILL.md +176 -190
- package/.agents/skills/qk-api-data-discovery/references/bronze-record-format.md +47 -0
- package/.agents/skills/qk-api-data-discovery/references/data-contract-yaml.md +72 -0
- package/.agents/skills/qk-api-data-discovery/references/discovery-report-template.md +110 -0
- package/.agents/skills/qk-backend-data/SKILL.md +150 -1
- package/.agents/skills/qk-bug-resolution/SKILL.md +153 -1
- package/.agents/skills/qk-bug-resolution/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-code-cleaner/SKILL.md +150 -1
- package/.agents/skills/qk-code-review/SKILL.md +195 -1
- package/.agents/skills/qk-code-review/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-code-review/references/ai/{v8-schema-validation.md → schema-validation.md} +2 -2
- package/.agents/skills/qk-code-review/references/cross-cutting/async-concurrency-patterns.md +515 -515
- package/.agents/skills/qk-code-review/references/cross-cutting/error-handling-principles.md +492 -492
- package/.agents/skills/qk-code-review/references/cross-cutting/n-plus-one-queries.md +309 -309
- package/.agents/skills/qk-code-review/references/cross-cutting/sql-injection-prevention.md +307 -307
- package/.agents/skills/qk-code-review/references/cross-cutting/xss-prevention.md +263 -263
- package/.agents/skills/qk-code-review/references/languages/angular.md +768 -768
- package/.agents/skills/qk-code-review/references/languages/c.md +890 -890
- package/.agents/skills/qk-code-review/references/languages/cpp.md +893 -893
- package/.agents/skills/qk-code-review/references/languages/css-less-sass.md +661 -661
- package/.agents/skills/qk-code-review/references/languages/django.md +985 -985
- package/.agents/skills/qk-code-review/references/languages/fastapi.md +580 -580
- package/.agents/skills/qk-code-review/references/languages/go.md +993 -993
- package/.agents/skills/qk-code-review/references/languages/java.md +409 -409
- package/.agents/skills/qk-code-review/references/languages/java8.md +586 -586
- package/.agents/skills/qk-code-review/references/languages/kotlin.md +1018 -1018
- package/.agents/skills/qk-code-review/references/languages/nestjs.md +593 -593
- package/.agents/skills/qk-code-review/references/languages/php.md +684 -684
- package/.agents/skills/qk-code-review/references/languages/python.md +1073 -1073
- package/.agents/skills/qk-code-review/references/languages/qt.md +757 -757
- package/.agents/skills/qk-code-review/references/languages/react.md +871 -871
- package/.agents/skills/qk-code-review/references/languages/ruby.md +964 -964
- package/.agents/skills/qk-code-review/references/languages/rust.md +846 -846
- package/.agents/skills/qk-code-review/references/languages/svelte.md +1064 -1064
- package/.agents/skills/qk-code-review/references/languages/swift.md +936 -936
- package/.agents/skills/qk-code-review/references/languages/typescript.md +1016 -1016
- package/.agents/skills/qk-code-review/references/languages/vue.md +924 -924
- package/.agents/skills/qk-code-review/references/languages/zig.md +440 -440
- package/.agents/skills/qk-devops-release/SKILL.md +150 -1
- package/.agents/skills/qk-feature-delivery/SKILL.md +153 -1
- package/.agents/skills/qk-feature-delivery/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-orchestrator/SKILL.md +187 -2
- package/.agents/skills/qk-orchestrator/evals/scorecard.yaml +1 -1
- package/.agents/skills/qk-orchestrator/references/routing-table.md +1 -1
- package/.agents/skills/qk-product-spec/SKILL.md +150 -1
- package/.agents/skills/qk-prompt-compiler/SKILL.md +188 -65
- package/.agents/skills/qk-ui-engineer/SKILL.md +150 -1
- package/.agents/workflows/_schema.yml +146 -146
- package/.agents/workflows/bug-resolution.yml +155 -121
- package/.agents/workflows/code-review.yml +127 -93
- package/.agents/workflows/context-discovery.yml +128 -94
- package/.agents/workflows/documentation.yml +124 -90
- package/.agents/workflows/feature-delivery.yml +158 -124
- package/.agents/workflows/production-release.yml +207 -173
- package/.agents/workflows/prompt-compilation.yml +126 -0
- package/.agents/workflows/refactor.yml +136 -102
- package/.agents/workflows/security-audit.yml +149 -115
- package/.agents/workflows/shared/quality-gate.yml +3 -1
- package/.agents/workflows/skin-governance.yml +149 -115
- package/.agents/workflows/spec-driven-development.yml +78 -71
- package/CHANGELOG.md +61 -0
- package/README.md +3 -3
- package/bin/install.js +38 -51
- package/package.json +68 -74
- package/tooling/build-registry.js +226 -208
- package/tooling/run-aar.js +55 -126
- package/tooling/sync-versions.js +2 -2
- package/tooling/validate-graph.js +100 -87
- package/tooling/validate-skills.js +32 -14
- package/.agents/docs/decisions/ADR-001-v8-migration.md +0 -58
- package/.agents/docs/decisions/ADR-002-workflow-separation.md +0 -50
- package/.agents/docs/decisions/ADR-003-registry-generated.md +0 -54
- package/.agents/docs/decisions/ADR-008-skill-boundary-review.md +0 -27
- package/.agents/registry/capability-graph.yml +0 -390
- package/.agents/registry/skills-index.yml +0 -305
- package/.agents/skills/_template/capability.yaml +0 -34
- package/.agents/skills/_template/evals/scorecard.yaml +0 -19
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: qk-devops-release
|
|
3
|
-
version: 10.
|
|
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.
|
|
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,9 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: qk-orchestrator
|
|
3
|
-
version: 10.
|
|
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] |
|
|
@@ -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
|
+
|