ai-developer-skill-os 9.3.1 → 10.1.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 +60 -40
- package/.agents/DEV_PROFILE.md +36 -2
- package/.agents/registry/graph.json +95 -342
- package/.agents/registry/index.yaml +61 -237
- package/.agents/rules/coding.md +30 -12
- package/.agents/rules/command-safety.md +19 -8
- package/.agents/rules/global.md +234 -28
- package/.agents/rules/prompt-compiler.md +170 -0
- package/.agents/skills/qk-api-data-discovery/SKILL.md +470 -0
- package/.agents/skills/qk-backend-data/SKILL.md +190 -0
- package/.agents/skills/qk-bug-resolution/SKILL.md +176 -248
- package/.agents/skills/qk-code-cleaner/SKILL.md +250 -0
- package/.agents/skills/qk-code-review/SKILL.md +126 -247
- package/.agents/skills/qk-devops-release/SKILL.md +145 -0
- package/.agents/skills/qk-feature-delivery/SKILL.md +179 -247
- package/.agents/skills/qk-orchestrator/SKILL.md +100 -151
- package/.agents/skills/qk-product-spec/SKILL.md +113 -0
- package/.agents/skills/qk-prompt-compiler/SKILL.md +321 -0
- package/.agents/skills/qk-ui-engineer/SKILL.md +137 -0
- package/.agents/workflows/feature-delivery.yml +1 -1
- package/.agents/workflows/production-release.yml +1 -1
- package/.agents/workflows/spec-driven-development.yml +109 -87
- package/CHANGELOG.md +16 -0
- package/README.md +125 -205
- package/bin/install.js +337 -329
- package/package.json +2 -2
- package/.agents/README.md +0 -90
- package/.agents/docs/CHI_TIET_SKILLS.md +0 -126
- package/.agents/docs/HUONG_DAN_SU_DUNG.md +0 -120
- package/.agents/docs/MIGRATION-CLEANUP-V8.1.3.md +0 -36
- package/.agents/docs/MIGRATION-STATUS.md +0 -35
- package/.agents/docs/MIGRATION-V8.md +0 -10
- package/.agents/docs/ROADMAP-V8.2.md +0 -78
- package/.agents/docs/V8-CERTIFICATION.md +0 -27
- package/.agents/skills/qk-access-policy/SKILL.md +0 -206
- package/.agents/skills/qk-access-policy/capability.yaml +0 -23
- package/.agents/skills/qk-access-policy/evals/scorecard.yaml +0 -36
- package/.agents/skills/qk-agent-observability/SKILL.md +0 -108
- package/.agents/skills/qk-agent-observability/capability.yaml +0 -29
- package/.agents/skills/qk-agent-observability/evals/scorecard.yaml +0 -29
- package/.agents/skills/qk-agent-observability/references/scorecard.yaml +0 -80
- package/.agents/skills/qk-ai-builder/SKILL.md +0 -254
- package/.agents/skills/qk-ai-builder/capability.yaml +0 -23
- package/.agents/skills/qk-ai-builder/evals/scorecard.yaml +0 -30
- package/.agents/skills/qk-api-consumer/SKILL.md +0 -256
- package/.agents/skills/qk-api-consumer/capability.yaml +0 -21
- package/.agents/skills/qk-api-consumer/evals/scorecard.yaml +0 -29
- package/.agents/skills/qk-api-lifecycle/SKILL.md +0 -251
- package/.agents/skills/qk-api-lifecycle/capability.yaml +0 -23
- package/.agents/skills/qk-api-lifecycle/evals/scorecard.yaml +0 -29
- package/.agents/skills/qk-bug-resolution/capability.yaml +0 -25
- package/.agents/skills/qk-code-review/capability.yaml +0 -23
- package/.agents/skills/qk-context-loader/SKILL.md +0 -198
- package/.agents/skills/qk-context-loader/capability.yaml +0 -23
- package/.agents/skills/qk-context-loader/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-data-engineer/SKILL.md +0 -253
- package/.agents/skills/qk-data-lifecycle/SKILL.md +0 -197
- package/.agents/skills/qk-data-lifecycle/capability.yaml +0 -23
- package/.agents/skills/qk-data-lifecycle/evals/scorecard.yaml +0 -29
- package/.agents/skills/qk-db-optimizer/SKILL.md +0 -210
- package/.agents/skills/qk-db-optimizer/capability.yaml +0 -22
- package/.agents/skills/qk-db-optimizer/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-design-system-engineering/SKILL.md +0 -193
- package/.agents/skills/qk-design-system-engineering/capability.yaml +0 -25
- package/.agents/skills/qk-design-system-engineering/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-devops-platform/SKILL.md +0 -198
- package/.agents/skills/qk-devops-platform/capability.yaml +0 -29
- package/.agents/skills/qk-devops-platform/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-docs/SKILL.md +0 -193
- package/.agents/skills/qk-docs/capability.yaml +0 -23
- package/.agents/skills/qk-docs/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-engineering-standard/SKILL.md +0 -89
- package/.agents/skills/qk-engineering-standard/capability.yaml +0 -23
- package/.agents/skills/qk-engineering-standard/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-engineering-standard/references/anti-patterns.md +0 -121
- package/.agents/skills/qk-engineering-standard/rules/backend.md +0 -122
- package/.agents/skills/qk-engineering-standard/rules/database.md +0 -3
- package/.agents/skills/qk-engineering-standard/rules/frontend.md +0 -152
- package/.agents/skills/qk-engineering-standard/rules/security.md +0 -3
- package/.agents/skills/qk-engineering-standard/rules/testing.md +0 -3
- package/.agents/skills/qk-fe-api-integration/SKILL.md +0 -704
- package/.agents/skills/qk-fe-api-integration/capability.yaml +0 -21
- package/.agents/skills/qk-fe-api-integration/evals/scorecard.yaml +0 -29
- package/.agents/skills/qk-feature-delivery/capability.yaml +0 -24
- package/.agents/skills/qk-frontend-architecture/SKILL.md +0 -127
- package/.agents/skills/qk-frontend-architecture/capability.yaml +0 -28
- package/.agents/skills/qk-frontend-architecture/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-help/SKILL.md +0 -107
- package/.agents/skills/qk-help/capability.yaml +0 -20
- package/.agents/skills/qk-help/evals/scorecard.yaml +0 -13
- package/.agents/skills/qk-orchestrator/capability.yaml +0 -22
- package/.agents/skills/qk-product-specification/SKILL.md +0 -187
- package/.agents/skills/qk-product-specification/capability.yaml +0 -27
- package/.agents/skills/qk-product-specification/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-production-release/SKILL.md +0 -188
- package/.agents/skills/qk-production-release/capability.yaml +0 -27
- package/.agents/skills/qk-production-release/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-project-audit/SKILL.md +0 -174
- package/.agents/skills/qk-project-bootstrap/SKILL.md +0 -372
- package/.agents/skills/qk-project-bootstrap/capability.yaml +0 -23
- package/.agents/skills/qk-project-bootstrap/evals/scorecard.yaml +0 -28
- package/.agents/skills/qk-project-health/SKILL.md +0 -202
- package/.agents/skills/qk-project-health/capability.yaml +0 -23
- package/.agents/skills/qk-project-health/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-project-memory/SKILL.md +0 -303
- package/.agents/skills/qk-project-memory/capability.yaml +0 -23
- package/.agents/skills/qk-project-memory/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-refactor/SKILL.md +0 -243
- package/.agents/skills/qk-refactor/capability.yaml +0 -26
- package/.agents/skills/qk-refactor/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-security-audit/SKILL.md +0 -280
- package/.agents/skills/qk-security-audit/capability.yaml +0 -29
- package/.agents/skills/qk-security-audit/evals/scorecard.yaml +0 -27
- package/.agents/skills/qk-system-evolution/SKILL.md +0 -625
- package/.agents/skills/qk-system-evolution/capability.yaml +0 -24
- package/.agents/skills/qk-system-evolution/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-test-engineering/SKILL.md +0 -215
- package/.agents/skills/qk-test-engineering/capability.yaml +0 -28
- package/.agents/skills/qk-test-engineering/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-ui-audit/SKILL.md +0 -175
- package/.agents/skills/qk-ui-audit/capability.yaml +0 -23
- package/.agents/skills/qk-ui-audit/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-ui-audit/references/anti-slop-checklist.md +0 -136
- package/.agents/skills/qk-ui-builder/SKILL.md +0 -521
- package/.agents/skills/qk-ui-builder/capability.yaml +0 -29
- package/.agents/skills/qk-ui-builder/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-ui-builder/references/anti-patterns.md +0 -295
- package/.agents/skills/qk-ui-builder/references/color.md +0 -115
- package/.agents/skills/qk-ui-builder/references/component-cookbook.md +0 -458
- package/.agents/skills/qk-ui-builder/references/copy.md +0 -250
- package/.agents/skills/qk-ui-builder/references/interaction-and-states.md +0 -115
- package/.agents/skills/qk-ui-builder/references/layout-and-space.md +0 -111
- package/.agents/skills/qk-ui-builder/references/macrostructures/01-bento-grid.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/02-long-document.md +0 -50
- package/.agents/skills/qk-ui-builder/references/macrostructures/03-marquee-hero.md +0 -51
- package/.agents/skills/qk-ui-builder/references/macrostructures/04-stat-led.md +0 -49
- package/.agents/skills/qk-ui-builder/references/macrostructures/05-workbench.md +0 -44
- package/.agents/skills/qk-ui-builder/references/macrostructures/06-conversational-faq.md +0 -50
- package/.agents/skills/qk-ui-builder/references/macrostructures/07-manifesto.md +0 -51
- package/.agents/skills/qk-ui-builder/references/macrostructures/08-photographic.md +0 -50
- package/.agents/skills/qk-ui-builder/references/macrostructures/09-quote-led.md +0 -50
- package/.agents/skills/qk-ui-builder/references/macrostructures/11-catalogue.md +0 -49
- package/.agents/skills/qk-ui-builder/references/macrostructures/12-letter.md +0 -49
- package/.agents/skills/qk-ui-builder/references/macrostructures/13-index-first.md +0 -49
- package/.agents/skills/qk-ui-builder/references/macrostructures/14-narrative-workflow.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/15-split-studio.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/16-feature-stack.md +0 -51
- package/.agents/skills/qk-ui-builder/references/macrostructures/17-type-specimen.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/18-portfolio-grid.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/19-map-diagram.md +0 -50
- package/.agents/skills/qk-ui-builder/references/macrostructures/20-ecosystem-index.md +0 -48
- package/.agents/skills/qk-ui-builder/references/macrostructures/21-component-playground.md +0 -45
- package/.agents/skills/qk-ui-builder/references/macrostructures.md +0 -38
- package/.agents/skills/qk-ui-builder/references/motion.md +0 -95
- package/.agents/skills/qk-ui-builder/references/responsive.md +0 -115
- package/.agents/skills/qk-ui-builder/references/slop-test.md +0 -135
- package/.agents/skills/qk-ui-builder/references/structure.md +0 -280
- package/.agents/skills/qk-ui-builder/references/themes/atmospheric.md +0 -53
- package/.agents/skills/qk-ui-builder/references/themes/carnival.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/cobalt.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/editorial.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/garden.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/hum.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/lumen.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/midnight.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/modern-minimal.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/playful.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/specimen.md +0 -52
- package/.agents/skills/qk-ui-builder/references/themes/terminal.md +0 -52
- package/.agents/skills/qk-ui-builder/references/typography.md +0 -129
- package/.agents/skills/qk-ui-system-builder/SKILL.md +0 -183
- package/.agents/skills/qk-ui-system-builder/capability.yaml +0 -25
- package/.agents/skills/qk-ui-system-builder/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-upgrade/SKILL.md +0 -301
- package/.agents/skills/qk-upgrade/capability.yaml +0 -24
- package/.agents/skills/qk-upgrade/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-validation-gate/SKILL.md +0 -88
- package/.agents/skills/qk-validation-gate/capability.yaml +0 -23
- package/.agents/skills/qk-validation-gate/evals/scorecard.yaml +0 -26
- package/.agents/skills/qk-web-quality-gate/SKILL.md +0 -197
- package/.agents/skills/qk-web-quality-gate/capability.yaml +0 -24
- package/.agents/skills/qk-web-quality-gate/evals/scorecard.yaml +0 -26
- package/.agents/workflows/research.yml +0 -75
- package/.agents/workflows/skill-evolution.yml +0 -97
- package/tooling/fix-refactor.js +0 -8
package/.agents/rules/global.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
version:
|
|
2
|
+
version: 10.1.0
|
|
3
3
|
description: "Agent behavior policies applied globally across all capabilities."
|
|
4
4
|
domain: rules
|
|
5
5
|
applies_to: all
|
|
@@ -11,7 +11,7 @@ applies_to: all
|
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
## R-G-01: Decision Before Action
|
|
14
|
+
## R-G-01: Decision Before Action & Review Loop
|
|
15
15
|
|
|
16
16
|
**MUST** create a plan before executing any task with complexity ≥ medium.
|
|
17
17
|
|
|
@@ -24,22 +24,31 @@ If medium/high: outline steps first
|
|
|
24
24
|
↓
|
|
25
25
|
Execute step by step
|
|
26
26
|
↓
|
|
27
|
-
|
|
27
|
+
Post-Implementation Self-Review (Requirements, Diff & Scope)
|
|
28
|
+
↓
|
|
29
|
+
Verify with actual evidence
|
|
30
|
+
↓
|
|
31
|
+
Conclude
|
|
28
32
|
```
|
|
29
33
|
|
|
30
|
-
**Violation:** Starting to write code before understanding the full scope.
|
|
34
|
+
**Violation:** Starting to write code before understanding the full scope, or claiming completion without self-review.
|
|
31
35
|
|
|
32
36
|
---
|
|
33
37
|
|
|
34
|
-
## R-G-02: Evidence Before Conclusion
|
|
38
|
+
## R-G-02: Evidence Before Conclusion & Causal Chain
|
|
35
39
|
|
|
36
|
-
**MUST**
|
|
40
|
+
**MUST** establish concrete evidence and prove the causal link before stating a finding or applying a fix:
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
REQUEST ──► SCOPE ──► TARGETED INSPECTION ──► EVIDENCE ──► ROOT CAUSE ──► MINIMAL FIX ──► VERIFY ──► ANALYZE RESULT ──► STATUS
|
|
44
|
+
```
|
|
37
45
|
|
|
38
|
-
- Do NOT
|
|
39
|
-
- Do NOT
|
|
40
|
-
- Do NOT
|
|
46
|
+
- Do NOT jump from Evidence directly to a fix without proving why that evidence points to the root cause.
|
|
47
|
+
- Do NOT guess root cause without inspecting the relevant code.
|
|
48
|
+
- Do NOT assume a bug is fixed without verification evidence.
|
|
49
|
+
- Do NOT report "done" without executing checks and analyzing results.
|
|
41
50
|
|
|
42
|
-
**Minimum evidence:** File path + line number + quoted code.
|
|
51
|
+
**Minimum evidence:** File path + line number + quoted code + explicit explanation of why it causes the issue.
|
|
43
52
|
|
|
44
53
|
---
|
|
45
54
|
|
|
@@ -53,18 +62,17 @@ Verify each step before next
|
|
|
53
62
|
|
|
54
63
|
---
|
|
55
64
|
|
|
56
|
-
## R-G-04: Token Budget Discipline
|
|
65
|
+
## R-G-04: Token Budget & Retrieval Discipline
|
|
57
66
|
|
|
58
|
-
**MUST** respect the
|
|
67
|
+
**MUST** respect the token budget and retrieval efficiency:
|
|
59
68
|
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
- Stop reading when sufficient evidence is found (`stop_early: true`).
|
|
69
|
+
- Use targeted search tools available in the current environment for pattern discovery.
|
|
70
|
+
- Read only the minimum relevant sections and stop retrieval when sufficient evidence has been established.
|
|
63
71
|
- Never read: `node_modules/`, `dist/`, `.git/`, binary files.
|
|
64
72
|
|
|
65
73
|
---
|
|
66
74
|
|
|
67
|
-
## R-G-05: Retrieval Path
|
|
75
|
+
## R-G-05: Retrieval Path
|
|
68
76
|
|
|
69
77
|
When starting a task, follow this sequence:
|
|
70
78
|
|
|
@@ -79,9 +87,8 @@ When starting a task, follow this sequence:
|
|
|
79
87
|
```
|
|
80
88
|
|
|
81
89
|
**Do NOT:**
|
|
82
|
-
-
|
|
83
|
-
-
|
|
84
|
-
- Scan entire repository before starting
|
|
90
|
+
- Load all skills at once.
|
|
91
|
+
- Scan entire repository before starting.
|
|
85
92
|
|
|
86
93
|
---
|
|
87
94
|
|
|
@@ -111,7 +118,7 @@ Never silently terminate. Always report exit code and reason.
|
|
|
111
118
|
|
|
112
119
|
## R-G-08: No Silent Errors
|
|
113
120
|
|
|
114
|
-
**NEVER** use
|
|
121
|
+
**NEVER** use `!` (non-null assertion), empty `try/catch {}` (suppressing errors silently), or blind type casting (`as any`) to hide errors. Optional chaining (`?.`) is allowed and recommended for safe navigation of nullable/optional properties.
|
|
115
122
|
|
|
116
123
|
Fix root cause. If root cause is unclear → report as `BLOCKED` with evidence.
|
|
117
124
|
|
|
@@ -130,9 +137,9 @@ Deprecated skills **MUST NOT** be selected. If a user asks for a deprecated skil
|
|
|
130
137
|
Agent **MUST NOT** execute when selection confidence < threshold.
|
|
131
138
|
|
|
132
139
|
Agent **SHOULD**:
|
|
133
|
-
1. Ask clarification
|
|
134
|
-
2. Present top 2-3 candidate skills with brief descriptions
|
|
135
|
-
3. Explain what information is missing
|
|
140
|
+
1. Ask clarification.
|
|
141
|
+
2. Present top 2-3 candidate skills with brief descriptions.
|
|
142
|
+
3. Explain what information is missing.
|
|
136
143
|
|
|
137
144
|
---
|
|
138
145
|
|
|
@@ -140,11 +147,8 @@ Agent **SHOULD**:
|
|
|
140
147
|
|
|
141
148
|
Every SKILL.md `description` field **MUST** satisfy both:
|
|
142
149
|
|
|
143
|
-
**(a) What it does** — concrete action the skill performs
|
|
144
|
-
**(b) When to use** — trigger context, keywords, situations
|
|
145
|
-
|
|
146
|
-
**Bad:** `"Xử lý dữ liệu."`
|
|
147
|
-
**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."`
|
|
150
|
+
**(a) What it does** — concrete action the skill performs
|
|
151
|
+
**(b) When to use** — trigger context, keywords, situations
|
|
148
152
|
|
|
149
153
|
Description phải đủ mạnh để AI **không under-trigger** (bỏ qua skill khi lẽ ra nên dùng).
|
|
150
154
|
|
|
@@ -160,3 +164,205 @@ Nếu gần chạm 500 dòng:
|
|
|
160
164
|
- Layer 1 (frontmatter) luôn trong context
|
|
161
165
|
- Layer 2 (SKILL.md body) nạp khi skill active
|
|
162
166
|
- Layer 3 (references/, scripts/, assets/) nạp on-demand
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## R-G-13: Laser Focus & Anti-Sprawl
|
|
171
|
+
|
|
172
|
+
Agent **BẮT BUỘC** khóa chặt phạm vi thực thi theo 3 nguyên tắc thép:
|
|
173
|
+
|
|
174
|
+
### 13.1. Scope Lock & No Unrelated Changes
|
|
175
|
+
- **Chỉ giải quyết đúng yêu cầu hiện tại:** Không tự mở rộng phạm vi sang refactor, bug fixing, optimization, redesign hoặc cleanup không liên quan.
|
|
176
|
+
- **Cấm sửa lan man:** Không sửa các file không liên quan chỉ vì phát hiện chúng "có thể cải thiện".
|
|
177
|
+
- **Ghi nhận thay vì tự tiện:** Nếu phát hiện vấn đề ngoài phạm vi, **CHỈ GHI NHẬN VÀ BÁO CÁO** trong phần ghi chú, tuyệt đối không tự ý sửa.
|
|
178
|
+
- **Câu hỏi phán xét:** Mọi thay đổi phải trả lời được câu hỏi: *"Thay đổi này có cần thiết trực tiếp cho yêu cầu hiện tại không?"*. Nếu câu trả lời là "KHÔNG" ➔ **TUYỆT ĐỐI KHÔNG THỰC HIỆN**.
|
|
179
|
+
|
|
180
|
+
### 13.2. File Creation Control (Kiểm Soát Sinh File)
|
|
181
|
+
- **Không tạo file chỉ để làm kiến trúc trông đẹp hơn.**
|
|
182
|
+
- Trước khi tạo file mới, **BẮT BUỘC** kiểm tra repository để xác định:
|
|
183
|
+
1. Có file/component/service/hook hiện tại nào có thể tái sử dụng được không?
|
|
184
|
+
2. Có pattern tương tự trong project hay không?
|
|
185
|
+
3. File mới có thực sự cần thiết cho tính năng hay không?
|
|
186
|
+
- **Ưu tiên chỉnh sửa và tái sử dụng cấu trúc hiện có:** Chỉ tạo file mới khi có lý do kỹ thuật rõ ràng và file đó có trách nhiệm riêng biệt (Single Responsibility). Cấm tạo các abstraction trung gian chỉ để "đúng pattern".
|
|
187
|
+
|
|
188
|
+
### 13.3. Repository Inspection Rule (Quét Có Mục Đích)
|
|
189
|
+
- Trước khi triển khai, chỉ quét những file và thư mục **có khả năng liên quan trực tiếp**.
|
|
190
|
+
- Tuyệt đối **KHÔNG**:
|
|
191
|
+
- Quét và phân tích toàn bộ repository một cách không cần thiết.
|
|
192
|
+
- Đọc hàng loạt file không liên quan.
|
|
193
|
+
- Biến việc "khảo sát codebase" thành một nhiệm vụ cleanup toàn dự án.
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## R-G-14: Zero-Faked Pass & Root-Cause Verification
|
|
198
|
+
|
|
199
|
+
Agent MUST treat **PASS as a verified conclusion, never as a target**.
|
|
200
|
+
|
|
201
|
+
### 14.1. Root-Cause Gate
|
|
202
|
+
|
|
203
|
+
Before applying a fix, Agent MUST establish:
|
|
204
|
+
1. What is the observed problem?
|
|
205
|
+
2. Where does it occur?
|
|
206
|
+
3. What code path causes it?
|
|
207
|
+
4. What is the root cause?
|
|
208
|
+
5. Why will the proposed change remove the root cause?
|
|
209
|
+
|
|
210
|
+
Do NOT apply speculative fixes.
|
|
211
|
+
|
|
212
|
+
If root cause cannot be established with sufficient evidence:
|
|
213
|
+
```text
|
|
214
|
+
BLOCKED
|
|
215
|
+
Reason: Root cause cannot be established from available evidence.
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### 14.2. Minimal Correct Fix
|
|
219
|
+
|
|
220
|
+
The fix MUST:
|
|
221
|
+
- Address the identified root cause.
|
|
222
|
+
- Be the smallest change that correctly resolves the problem.
|
|
223
|
+
- Preserve unrelated behavior.
|
|
224
|
+
- Avoid introducing unnecessary abstractions or files.
|
|
225
|
+
- Avoid workaround code whose only purpose is to make verification pass.
|
|
226
|
+
|
|
227
|
+
### 14.3. Post-Implementation Review Gate — REVIEW TRƯỚC KHI PASS
|
|
228
|
+
|
|
229
|
+
Agent **MUST NOT** declare a task complete immediately after implementation.
|
|
230
|
+
|
|
231
|
+
Sau khi hoàn thành thay đổi, Agent **BẮT BUỘC** thực hiện một vòng self-review độc lập trước khi chạy verification và kết luận:
|
|
232
|
+
|
|
233
|
+
```text
|
|
234
|
+
REQUEST ──► PLAN ──► TARGETED INSPECTION ──► EVIDENCE ──► ROOT CAUSE ──► IMPLEMENT
|
|
235
|
+
│
|
|
236
|
+
▼
|
|
237
|
+
🔍 POST-IMPLEMENTATION REVIEW
|
|
238
|
+
├── 1. Requirement Review: Đã đáp ứng đúng yêu cầu ban đầu? Có thiếu edge case nào không?
|
|
239
|
+
├── 2. Implementation Review: Code có giải quyết triệt để root cause? Có logic/file thừa không?
|
|
240
|
+
├── 3. Scope Review (Diff Check): Những file nào đã sửa? Có accidental hay unrelated changes không?
|
|
241
|
+
├── 4. Quality Review: Có vi phạm as any, @ts-ignore, silent catch, hay dirty workaround không?
|
|
242
|
+
└── 5. Verification Review: Đã xác định đúng lệnh test/build thực tế cần chạy chưa?
|
|
243
|
+
│
|
|
244
|
+
├── Nếu Review phát hiện lỗi ──► STOP ──► RE-ANALYZE ──► MINIMAL FIX ──► REVIEW AGAIN
|
|
245
|
+
│
|
|
246
|
+
▼
|
|
247
|
+
14.4. VERIFICATION GATE (Chạy lệnh thực tế) ──► 14.5. FAILURE RE-ANALYSIS (nếu fail)
|
|
248
|
+
│
|
|
249
|
+
▼
|
|
250
|
+
14.6. ANTI-FAKE-PASS ──► 14.7. EVIDENCE-BASED STATUS ──► 14.8. TRUTH-FIRST REPORTING
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
#### Final Gate Condition:
|
|
254
|
+
Chỉ được kết luận `SUCCESS` khi:
|
|
255
|
+
- Requirement đã được đối chiếu đầy đủ.
|
|
256
|
+
- Implementation đã được self-review độc lập.
|
|
257
|
+
- Scope / Diff đã được kiểm tra (0 unrelated changes).
|
|
258
|
+
- Root cause đã được xử lý đúng.
|
|
259
|
+
- Verification thực tế đạt yêu cầu (có output lệnh thực tế).
|
|
260
|
+
- Không có bất kỳ workaround nào để ép PASS.
|
|
261
|
+
|
|
262
|
+
> **Implementation complete ≠ Task complete.**
|
|
263
|
+
> **Task complete = Implementation + Review + Verification + Evidence.**
|
|
264
|
+
|
|
265
|
+
### 14.4. Verification Gate
|
|
266
|
+
|
|
267
|
+
After applying the fix and completing self-review, Agent MUST run the most relevant available verification:
|
|
268
|
+
- Unit tests
|
|
269
|
+
- Integration tests
|
|
270
|
+
- Type-check
|
|
271
|
+
- Lint
|
|
272
|
+
- Build
|
|
273
|
+
- Relevant runtime/manual verification
|
|
274
|
+
|
|
275
|
+
Only verification actually executed may be reported as evidence.
|
|
276
|
+
|
|
277
|
+
### 14.5. Failure Re-Analysis
|
|
278
|
+
|
|
279
|
+
If verification FAILS:
|
|
280
|
+
```text
|
|
281
|
+
FAIL
|
|
282
|
+
↓
|
|
283
|
+
STOP
|
|
284
|
+
↓
|
|
285
|
+
Read actual failure
|
|
286
|
+
↓
|
|
287
|
+
Re-analyze root cause
|
|
288
|
+
↓
|
|
289
|
+
Determine whether previous diagnosis was incomplete/wrong
|
|
290
|
+
↓
|
|
291
|
+
Apply corrected minimal fix
|
|
292
|
+
↓
|
|
293
|
+
Review again
|
|
294
|
+
↓
|
|
295
|
+
Verify again
|
|
296
|
+
```
|
|
297
|
+
Do NOT repeatedly modify code blindly until the check becomes green.
|
|
298
|
+
|
|
299
|
+
### 14.6. Anti-Fake-Pass
|
|
300
|
+
|
|
301
|
+
Agent MUST NOT make a verification pass by:
|
|
302
|
+
- Adding `as any`
|
|
303
|
+
- Adding `@ts-ignore`
|
|
304
|
+
- Adding `@ts-expect-error` to suppress a newly introduced error
|
|
305
|
+
- Disabling lint/type-check/test rules
|
|
306
|
+
- Skipping or deleting failing tests
|
|
307
|
+
- Weakening assertions without justification
|
|
308
|
+
- Hardcoding fake outputs
|
|
309
|
+
- Returning fake/mock data in production code
|
|
310
|
+
- Swallowing exceptions (`catch (e) {}` rỗng)
|
|
311
|
+
- Changing expected results merely to match incorrect behavior
|
|
312
|
+
- Modifying configuration solely to hide failures
|
|
313
|
+
|
|
314
|
+
### 14.7. Evidence-Based Status
|
|
315
|
+
|
|
316
|
+
Agent MUST distinguish:
|
|
317
|
+
|
|
318
|
+
| Status | Requirement |
|
|
319
|
+
|---|---|
|
|
320
|
+
| `SUCCESS` | Correct fix + self-reviewed + relevant verification passed |
|
|
321
|
+
| `BLOCKED` | Root cause/precondition cannot be established or required verification cannot proceed |
|
|
322
|
+
| `FAILED` | Correct execution attempted but task could not be completed |
|
|
323
|
+
| `PARTIAL` | Some scoped work completed, but required verification or implementation remains incomplete |
|
|
324
|
+
|
|
325
|
+
Never convert `BLOCKED`, `FAILED`, or `PARTIAL` into `SUCCESS` merely because the code was modified.
|
|
326
|
+
|
|
327
|
+
### 14.8. Truth-First Reporting
|
|
328
|
+
|
|
329
|
+
Never claim:
|
|
330
|
+
- "100% fixed"
|
|
331
|
+
- "All tests pass"
|
|
332
|
+
- "Build passes"
|
|
333
|
+
- "No issues"
|
|
334
|
+
- "Verified"
|
|
335
|
+
|
|
336
|
+
unless the corresponding verification was actually executed and passed.
|
|
337
|
+
|
|
338
|
+
If verification cannot be executed:
|
|
339
|
+
```text
|
|
340
|
+
Status: NOT VERIFIED
|
|
341
|
+
Reason: <concrete reason>
|
|
342
|
+
```
|
|
343
|
+
Do not infer PASS from code inspection alone.
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## R-G-15: Prompt Interpretation & Control Plane Gate (Risk Gate, Change Budget, Scope Expansion & Evidence Gate)
|
|
348
|
+
|
|
349
|
+
**MUST** translate raw or concise user requests into an explicit, reviewable **Compiled Execution Prompt**, expose **Prompt Delta**, and enforce 4 control gates before and during execution.
|
|
350
|
+
|
|
351
|
+
```text
|
|
352
|
+
RAW REQUEST ──► COMPILE & DELTA ──► RISK & BUDGET GATE ──► DECIDE MODE (AUTO/CONFIRM/ASK) ──► EXECUTE ──► SCOPE EXPANSION GATE? ──► EVIDENCE GATE ──► REPORT
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### 15.1. Core Maxim
|
|
356
|
+
> `AI MUST NEVER INCREASE THE USER'S INTENDED SCOPE SILENTLY.`
|
|
357
|
+
> *(The AI may increase implementation detail, but must never silently increase business scope, behavioral scope, architectural scope, security scope, data scope, or change budget).*
|
|
358
|
+
|
|
359
|
+
### 15.2. Mandatory Gates
|
|
360
|
+
1. **Risk Gate (`Complexity ≠ Risk`):** Đánh giá độc lập Complexity (`L0–L4`) và Risk (`R0–R4`). Nếu `Risk >= R2` hoặc `Complexity >= L3` hoặc đụng đến Auth/DB/Production → BẮT BUỘC chọn chế độ `CONFIRM`.
|
|
361
|
+
2. **Change Budget Gate:** Khóa giới hạn thay đổi (Kỳ vọng 1–3 files, tối đa 5 files; 0 new dependencies; không đổi API/DB trừ khi được yêu cầu).
|
|
362
|
+
3. **Scope Expansion Gate:** Trong khi code, nếu phát hiện phạm vi thực tế vượt Compiled Scope → **STOP EXPANSION NGAY LẬP TỨC**, báo cáo nguyên nhân và recompile để chờ người dùng duyệt (`CONFIRM`).
|
|
363
|
+
4. **Evidence Gate:** `CLAIM LEVEL <= EVIDENCE LEVEL`. Không được khẳng định pass khi chỉ đọc code. Phải phân biệt rõ `VERIFIED`, `PARTIALLY VERIFIED`, và `UNVERIFIED`.
|
|
364
|
+
|
|
365
|
+
- **Reference:** Detailed policies in [PROMPT_RULES.md](./PROMPT_RULES.md) and [.agents/rules/prompt-compiler.md](.agents/rules/prompt-compiler.md).
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
---
|
|
2
|
+
version: 11.1.0
|
|
3
|
+
description: "Quy tắc Prompt Compiler v11.1 Control Plane: Cổng kiểm soát hành vi, Risk Gate R0-R4, Change Budget, Scope Expansion Gate, Evidence Gate và Prompt Delta."
|
|
4
|
+
domain: rules
|
|
5
|
+
applies_to: all
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Prompt Compiler Rules v11.1 — Control Plane & Behavioral Gate
|
|
9
|
+
|
|
10
|
+
> **Câu hỏi domain này trả lời:** *Làm thế nào để kiểm soát hành vi của AI trước và trong khi code, ngăn chặn bành trướng phạm vi âm thầm, giới hạn ngân sách thay đổi và khóa mức độ khẳng định theo bằng chứng thực tế?*
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. Nguyên Tắc Cốt Lõi & Khẩu Hiệu Kiến Trúc (Core Maxims)
|
|
15
|
+
|
|
16
|
+
> 1. `AI MUST NEVER INCREASE THE USER'S INTENDED SCOPE SILENTLY.`
|
|
17
|
+
> *(AI tuyệt đối không bao giờ được âm thầm bành trướng phạm vi ý định của người dùng).*
|
|
18
|
+
>
|
|
19
|
+
> 2. `The AI may increase implementation detail, but must never silently increase business scope, behavioral scope, architectural scope, security scope, data scope, or change budget.`
|
|
20
|
+
> *(AI có thể đào sâu chi tiết triển khai kỹ thuật, nhưng cấm âm thầm tăng phạm vi nghiệp vụ, hành vi, kiến trúc, bảo mật, dữ liệu hoặc ngân sách thay đổi).*
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 2. Thứ Bậc Ngữ Cảnh Hóa Biên Dịch (Context-Aware Compilation Hierarchy)
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
SYSTEM / PLATFORM RULES
|
|
28
|
+
↓
|
|
29
|
+
PROJECT RULES
|
|
30
|
+
↓
|
|
31
|
+
GLOBAL RULES
|
|
32
|
+
↓
|
|
33
|
+
RELEVANT SKILL
|
|
34
|
+
↓
|
|
35
|
+
PROJECT CONTEXT / DEV_PROFILE.md
|
|
36
|
+
↓
|
|
37
|
+
EXISTING ARCHITECTURE & CODE
|
|
38
|
+
↓
|
|
39
|
+
USER REQUIREMENT ◄── [NGUỒN CHÍNH XÁC ĐỊNH MỤC TIÊU CỐT LÕI (WHAT)]
|
|
40
|
+
↓
|
|
41
|
+
AI INTERPRETATION
|
|
42
|
+
↓
|
|
43
|
+
EXECUTION PLAN ◄── [QUY CHUẨN KỸ THUẬT & RANH GIỚI BẢO VỆ (HOW & BOUNDARIES)]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
- **User Requirement:** Là nguồn sự thật tối thượng để xác định **Mục tiêu cần làm gì (WHAT)**.
|
|
47
|
+
- **Rules, Skills & Codebase:** Đóng vai trò là luật lệ, ranh giới và tiêu chuẩn kỹ thuật để quy định **Cách AI được phép thực hiện an toàn (HOW & BOUNDARIES)**.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Cổng Đánh Giá Rủi Ro Độc Lập (Risk Gate: Complexity ≠ Risk)
|
|
52
|
+
|
|
53
|
+
Một thay đổi 1 dòng trong file cấu hình Production (`L1`) có thể gây sập hệ thống (`R4`). Hai trục này phải được đánh giá riêng biệt:
|
|
54
|
+
|
|
55
|
+
### Trục Phức Tạp (Complexity)
|
|
56
|
+
- `L0 — Trivial`: Sửa typo, format markdown.
|
|
57
|
+
- `L1 — Simple`: Sửa 1 hàm nhỏ, tinh chỉnh CSS cục bộ 1 component.
|
|
58
|
+
- `L2 — Normal`: Bug logic thông thường, thêm 1 endpoint/hook trong module.
|
|
59
|
+
- `L3 — Complex`: Tính năng liên tầng (FE + BE), tái cấu trúc module.
|
|
60
|
+
- `L4 — High Architecture`: Thiết kế lại flow hoặc kiến trúc hệ thống.
|
|
61
|
+
|
|
62
|
+
### Trục Rủi Ro (Risk Levels)
|
|
63
|
+
- `R0 — Safe`: Thao tác chỉ đọc (Read-only), audit, tài liệu.
|
|
64
|
+
- `R1 — Low`: Thay đổi nhỏ, local UI, dễ rollback, không side-effect.
|
|
65
|
+
- `R2 — Medium`: Logic nghiệp vụ, hàm dùng chung, có nguy cơ hồi quy (regression).
|
|
66
|
+
- `R3 — High`: Sửa đổi liên tầng, API contract, database migration, CI/CD config.
|
|
67
|
+
- `R4 — Critical`: Destructive operation (DROP, TRUNCATE, DELETE), bảo mật/auth, production data.
|
|
68
|
+
|
|
69
|
+
### Ma Trận Quyết Định Chế Độ (Mode Matrix)
|
|
70
|
+
```text
|
|
71
|
+
IF Complexity >= L3 ──► Minimum CONFIRM
|
|
72
|
+
IF Risk >= R2 ──► Minimum CONFIRM
|
|
73
|
+
IF Risk >= R3 ──► CONFIRM + Explicit Risk Report
|
|
74
|
+
IF destructive / auth / production data ──► BẮT BUỘC CONFIRM (Chờ duyệt [Proceed])
|
|
75
|
+
IF thiếu thông tin / intent mơ hồ ──► BẮT BUỘC ASK (Hỏi lại, không đoán)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 4. Ngân Sách Thay Đổi (Change Budget Gate)
|
|
81
|
+
|
|
82
|
+
Khóa chặt quy mô can thiệp cho mỗi task:
|
|
83
|
+
- **Files Budget:** Dự kiến 1–3 files; Tối đa 5 files. Vượt quá 5 files = Vi phạm budget.
|
|
84
|
+
- **Dependencies Budget:** Mặc định = 0 new dependencies. Cấm tự ý `npm install` thêm package nếu chưa hỏi.
|
|
85
|
+
- **API Contract:** Không thay đổi (trừ khi task yêu cầu).
|
|
86
|
+
- **Database Schema:** Không thay đổi (trừ khi task yêu cầu).
|
|
87
|
+
- **Architecture:** Không tự tiện rewrite.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 5. Cổng Chặn Bành Trướng Phạm Vi (Scope Expansion Gate)
|
|
92
|
+
|
|
93
|
+
Khi đang thực hiện (in-flight execution), nếu AI phát hiện lỗi nằm xuyên tầng hoặc cần sửa ngoài phạm vi đã compile:
|
|
94
|
+
```text
|
|
95
|
+
STOP EXPANSION NGAY LẬP TỨC
|
|
96
|
+
↓
|
|
97
|
+
BÁO CÁO PHÁT SINH PHẠM VI (SCOPE EXPANSION REPORT):
|
|
98
|
+
- Scope ban đầu đã duyệt
|
|
99
|
+
- Phụ thuộc mới phát hiện
|
|
100
|
+
- Lý do kỹ thuật vì sao bắt buộc phải mở rộng
|
|
101
|
+
- Files bị ảnh hưởng & Mức tăng rủi ro (Risk escalation)
|
|
102
|
+
↓
|
|
103
|
+
RECOMPILE PROMPT & PROMPT DELTA MỚI
|
|
104
|
+
↓
|
|
105
|
+
CHỜ NGƯỜI DÙNG PHÊ DUYỆT (CONFIRM) MỚI ĐƯỢC LÀM TIẾP
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 6. Cổng Bằng Chứng Khẳng Định (Evidence Gate)
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
NGUYÊN TẮC:
|
|
114
|
+
CLAIM LEVEL <= EVIDENCE LEVEL
|
|
115
|
+
(Mức độ khẳng định của AI không được vượt quá mức độ bằng chứng thực tế thu thập được)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Phân cấp 3 trạng thái nghiệm thu:
|
|
119
|
+
1. **`VERIFIED`:** Đã chạy test/build thực tế trong terminal và PASS.
|
|
120
|
+
2. **`PARTIALLY VERIFIED`:** Static analysis / typecheck / lint PASS, chưa test luồng integration/browser thật.
|
|
121
|
+
3. **`UNVERIFIED`:** Chưa chạy test, chỉ review code tĩnh. **CẤM GHI PASS**, bắt buộc ghi: *"Trạng thái: NOT VERIFIED — Đã sửa logic tĩnh. Cần người dùng kiểm thử thủ công."*
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 7. Khung Hiển Thị Mặc Định (Default UI Block với Prompt Delta & Budget)
|
|
126
|
+
|
|
127
|
+
Khi nhận câu lệnh, AI bắt buộc render cấu trúc sau trước khi code:
|
|
128
|
+
|
|
129
|
+
````markdown
|
|
130
|
+
## 🧠 1. Tôi hiểu yêu cầu
|
|
131
|
+
[Tóm tắt 1-2 câu về mục tiêu thực sự bạn muốn đạt được]
|
|
132
|
+
|
|
133
|
+
## 📝 2. Prompt tôi sẽ dùng (Compiled Execution Prompt)
|
|
134
|
+
```text
|
|
135
|
+
Role: <vai trò chuyên trách trong 14 Roles>
|
|
136
|
+
Objective: <mục tiêu đo lường được, định nghĩa rõ "DONE = ?">
|
|
137
|
+
Context: <stack & module liên quan từ DEV_PROFILE.md và codebase>
|
|
138
|
+
Source of Truth: <thứ tự ưu tiên nguồn dữ liệu>
|
|
139
|
+
Scope:
|
|
140
|
+
- IN-SCOPE: <file/hàm được phép sửa>
|
|
141
|
+
- OUT-OF-SCOPE: <vùng cấm tuyệt đối>
|
|
142
|
+
Constraints: Minimal Safe Change, YAGNI, không phá vỡ API/DB hiện có, zero fake pass
|
|
143
|
+
Process: <các bước logic tối giản>
|
|
144
|
+
Acceptance Criteria:
|
|
145
|
+
- [ ] <Điều kiện kiểm chứng 1>
|
|
146
|
+
- [ ] <Điều kiện kiểm chứng 2>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## 🔍 3. Prompt Delta (Tôi đã diễn giải thêm)
|
|
150
|
+
|
|
151
|
+
### User đã yêu cầu:
|
|
152
|
+
- [Nguyên văn câu lệnh bạn đưa]
|
|
153
|
+
|
|
154
|
+
### AI suy luận từ context:
|
|
155
|
+
- [Những điểm kỹ thuật AI bổ sung dựa trên mã nguồn thực tế]
|
|
156
|
+
|
|
157
|
+
### AI KHÔNG tự giả định:
|
|
158
|
+
- [Những ranh giới AI tự khóa lại: không rewrite, không đổi DB, không sửa lan man]
|
|
159
|
+
|
|
160
|
+
## 📊 4. Đánh Giá Rủi Ro & Ngân Sách Thay Đổi (Risk & Budget)
|
|
161
|
+
- **Độ phức tạp / Rủi ro:** `L[0-4]` / `R[0-4]` — [Đánh giá ngắn]
|
|
162
|
+
- **Ngân sách file (Change Budget):** Tối đa [N] files (`path/to/file1`)
|
|
163
|
+
- **Dependencies mới:** 0 package
|
|
164
|
+
|
|
165
|
+
## 📋 5. Các bước thực hiện
|
|
166
|
+
1. [Khảo sát] → 2. [Thực thi tối thiểu] → 3. [Xác minh theo Evidence Gate]
|
|
167
|
+
|
|
168
|
+
## ⚡ 6. Execution Mode
|
|
169
|
+
**[ AUTO | CONFIRM | ASK ]** — [Lý do lựa chọn mode dựa trên ma trận Risk & Complexity]
|
|
170
|
+
````
|