@longph2102/v-flow 1.5.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 (247) hide show
  1. package/AGENTS.md +265 -0
  2. package/CHANGELOG.md +318 -0
  3. package/LICENSE +21 -0
  4. package/README.md +326 -0
  5. package/agents/ba-agent.md +437 -0
  6. package/agents/ba-critic-agent.md +156 -0
  7. package/agents/ba-to-ptyc-agent.md +112 -0
  8. package/agents/bugfix-analyst-agent.md +221 -0
  9. package/agents/constitute-agent.md +155 -0
  10. package/agents/help-agent.md +168 -0
  11. package/agents/implement-agent.md +220 -0
  12. package/agents/import-ba-docs-agent.md +164 -0
  13. package/agents/master-check-agent.md +228 -0
  14. package/agents/metrics-agent.md +180 -0
  15. package/agents/operations-agent.md +123 -0
  16. package/agents/plan-agent.md +218 -0
  17. package/agents/prototype-agent.md +191 -0
  18. package/agents/retrospective-agent.md +196 -0
  19. package/agents/review-agent.md +210 -0
  20. package/agents/sprint-agent.md +191 -0
  21. package/agents/status-agent.md +186 -0
  22. package/agents/sync-agent.md +201 -0
  23. package/agents/test-agent.md +166 -0
  24. package/agents/understand-agent.md +339 -0
  25. package/cli/commands/check.js +96 -0
  26. package/cli/commands/dev-quiz.js +107 -0
  27. package/cli/commands/doctor.js +348 -0
  28. package/cli/commands/feature.js +259 -0
  29. package/cli/commands/hooks.js +163 -0
  30. package/cli/commands/init.js +189 -0
  31. package/cli/commands/log.js +199 -0
  32. package/cli/commands/plugin.js +230 -0
  33. package/cli/commands/score-card.js +203 -0
  34. package/cli/commands/status.js +269 -0
  35. package/cli/commands/sync.js +59 -0
  36. package/cli/commands/upgrade.js +150 -0
  37. package/cli/commands/validate.js +1259 -0
  38. package/cli/commands/watch.js +151 -0
  39. package/cli/index.js +46 -0
  40. package/cli/lib/ac-test-gate.js +89 -0
  41. package/cli/lib/activity-log.js +209 -0
  42. package/cli/lib/cli-error.js +183 -0
  43. package/cli/lib/constitution-lint.js +561 -0
  44. package/cli/lib/dev-quiz-grade.js +127 -0
  45. package/cli/lib/governance.js +78 -0
  46. package/cli/lib/hook-targets.js +167 -0
  47. package/cli/lib/i18n.js +375 -0
  48. package/cli/lib/knowledge-oracle.js +379 -0
  49. package/cli/lib/logger.js +203 -0
  50. package/cli/lib/module-card-lint.js +304 -0
  51. package/cli/lib/module-card-score.js +223 -0
  52. package/cli/lib/plugins.js +481 -0
  53. package/cli/lib/scanner.js +692 -0
  54. package/cli/lib/sync-core.js +232 -0
  55. package/cli/lib/sync-targets.js +84 -0
  56. package/cli/lib/templates.js +268 -0
  57. package/cli/lib/yaml-parser.js +203 -0
  58. package/commands/v.ba-critic.md +101 -0
  59. package/commands/v.ba-to-ptyc.md +71 -0
  60. package/commands/v.bugfix.md +86 -0
  61. package/commands/v.check.md +131 -0
  62. package/commands/v.constitute.md +87 -0
  63. package/commands/v.constitution.md +84 -0
  64. package/commands/v.fork.md +127 -0
  65. package/commands/v.help.md +73 -0
  66. package/commands/v.hotfix.md +200 -0
  67. package/commands/v.implement.md +92 -0
  68. package/commands/v.import-ba-docs.md +222 -0
  69. package/commands/v.metrics.md +74 -0
  70. package/commands/v.operations.md +70 -0
  71. package/commands/v.plan.md +78 -0
  72. package/commands/v.prototype.md +121 -0
  73. package/commands/v.quickfix.md +169 -0
  74. package/commands/v.retrospective.md +80 -0
  75. package/commands/v.review.md +78 -0
  76. package/commands/v.rewind.md +127 -0
  77. package/commands/v.specify.md +118 -0
  78. package/commands/v.sprint.md +75 -0
  79. package/commands/v.status.md +62 -0
  80. package/commands/v.sync.md +81 -0
  81. package/commands/v.test.md +67 -0
  82. package/commands/v.understand.md +112 -0
  83. package/package.json +65 -0
  84. package/skills/_shared/constitution-reader/SKILL.md +109 -0
  85. package/skills/_shared/constitution-reader/config.json +52 -0
  86. package/skills/_shared/constitution-reader/examples/good/b1-phase-output.md +48 -0
  87. package/skills/_shared/constitution-reader/gotchas.md +46 -0
  88. package/skills/_shared/context-reader/SKILL.md +111 -0
  89. package/skills/_shared/context-reader/config.json +54 -0
  90. package/skills/_shared/context-reader/examples/good/legacy-nodejs-output.md +35 -0
  91. package/skills/_shared/context-reader/gotchas.md +49 -0
  92. package/skills/_shared/ears-notation/SKILL.md +63 -0
  93. package/skills/_shared/ears-notation/config.json +55 -0
  94. package/skills/_shared/ears-notation/examples/good/plan-test-interpretation.md +29 -0
  95. package/skills/_shared/ears-notation/gotchas.md +43 -0
  96. package/skills/check/cross-validator/SKILL.md +206 -0
  97. package/skills/check/cross-validator/config.json +33 -0
  98. package/skills/check/cross-validator/examples/good/validation-report-pass-with-concerns.md +105 -0
  99. package/skills/check/cross-validator/gotchas.md +43 -0
  100. package/skills/implement/constitution-enforcer/SKILL.md +134 -0
  101. package/skills/implement/constitution-enforcer/config.json +16 -0
  102. package/skills/implement/constitution-enforcer/examples/bad/vague-report.md +42 -0
  103. package/skills/implement/constitution-enforcer/examples/good/compliance-report.md +57 -0
  104. package/skills/implement/constitution-enforcer/gotchas.md +26 -0
  105. package/skills/implement/constitution-enforcer/scripts/check-constitution.sh +88 -0
  106. package/skills/implement/no-go-zone-guard/SKILL.md +173 -0
  107. package/skills/implement/no-go-zone-guard/config.json +28 -0
  108. package/skills/implement/no-go-zone-guard/examples/good/adapter-workaround.md +46 -0
  109. package/skills/implement/no-go-zone-guard/gotchas.md +27 -0
  110. package/skills/implement/no-go-zone-guard/scripts/check-nogo-zones.sh +148 -0
  111. package/skills/implement/no-go-zone-guard/scripts/nogo-precommit.sh +96 -0
  112. package/skills/implement/tdd-driver/SKILL.md +159 -0
  113. package/skills/implement/tdd-driver/config.json +33 -0
  114. package/skills/implement/tdd-driver/examples/good/tdd-cycle-product-repo.md +81 -0
  115. package/skills/implement/tdd-driver/gotchas.md +34 -0
  116. package/skills/metrics/metrics-collector/SKILL.md +133 -0
  117. package/skills/metrics/metrics-collector/config.json +16 -0
  118. package/skills/metrics/metrics-collector/examples/bad/incomplete-report.md +48 -0
  119. package/skills/metrics/metrics-collector/examples/good/full-metrics-report.md +101 -0
  120. package/skills/metrics/metrics-collector/gotchas.md +26 -0
  121. package/skills/operations/incident-runbook/SKILL.md +167 -0
  122. package/skills/operations/incident-runbook/config.json +21 -0
  123. package/skills/operations/incident-runbook/examples/bad/vague-incident-report.md +48 -0
  124. package/skills/operations/incident-runbook/examples/good/p1-hotfix-response.md +119 -0
  125. package/skills/operations/incident-runbook/gotchas.md +26 -0
  126. package/skills/plan/architecture-designer/SKILL.md +228 -0
  127. package/skills/plan/architecture-designer/config.json +32 -0
  128. package/skills/plan/architecture-designer/examples/bad/vague-plan.md +62 -0
  129. package/skills/plan/architecture-designer/examples/good/expand-contract-migration.md +56 -0
  130. package/skills/plan/architecture-designer/examples/good/plan-structure.md +58 -0
  131. package/skills/plan/architecture-designer/gotchas.md +45 -0
  132. package/skills/plan/task-breakdown/SKILL.md +208 -0
  133. package/skills/plan/task-breakdown/config.json +26 -0
  134. package/skills/plan/task-breakdown/examples/bad/vague-tasks.md +77 -0
  135. package/skills/plan/task-breakdown/examples/good/spike-clarify-tasks.md +66 -0
  136. package/skills/plan/task-breakdown/examples/good/tasks-login-feature.md +111 -0
  137. package/skills/plan/task-breakdown/gotchas.md +39 -0
  138. package/skills/prototype/LOGIC.md +240 -0
  139. package/skills/prototype/SKILL.md +185 -0
  140. package/skills/prototype/UI.md +407 -0
  141. package/skills/prototype/config.json +104 -0
  142. package/skills/prototype/examples/bad/prototype-notes.md +68 -0
  143. package/skills/prototype/examples/good/prototype-notes-ui.md +109 -0
  144. package/skills/prototype/examples/good/prototype-notes.md +67 -0
  145. package/skills/prototype/gotchas.md +128 -0
  146. package/skills/prototype/scripts/check-flow-state.ps1 +112 -0
  147. package/skills/prototype/scripts/check-flow-state.sh +104 -0
  148. package/skills/prototype/scripts/check-prototype-cleanup.ps1 +124 -0
  149. package/skills/prototype/scripts/check-prototype-cleanup.sh +109 -0
  150. package/skills/prototype/scripts/check-prototype-notes.ps1 +107 -0
  151. package/skills/prototype/scripts/check-prototype-notes.sh +102 -0
  152. package/skills/review/adversarial-reviewer/SKILL.md +137 -0
  153. package/skills/review/adversarial-reviewer/config.json +32 -0
  154. package/skills/review/adversarial-reviewer/examples/good/review-report-template.md +56 -0
  155. package/skills/review/adversarial-reviewer/gotchas.md +46 -0
  156. package/skills/review/adversarial-reviewer/scripts/quick-security-scan.sh +52 -0
  157. package/skills/specify/ba-bpmn-doc-gen/SKILL.md +108 -0
  158. package/skills/specify/ba-bpmn-doc-gen/reference/reference-bpmn-generation.md +528 -0
  159. package/skills/specify/ba-bpmn-doc-gen/reference/reference-drawio-flowchart.md +466 -0
  160. package/skills/specify/ba-critic/SKILL.md +172 -0
  161. package/skills/specify/ba-critic/config.json +32 -0
  162. package/skills/specify/ba-critic/examples/good/critic-report-round1.md +51 -0
  163. package/skills/specify/ba-critic/gotchas.md +40 -0
  164. package/skills/specify/ba-critic/scripts/check-spec-quality.sh +72 -0
  165. package/skills/specify/ba-doc-generator/SKILL.md +102 -0
  166. package/skills/specify/ba-doc-generator/references/template-clevel.md +84 -0
  167. package/skills/specify/ba-doc-generator/references/template-compliance.md +83 -0
  168. package/skills/specify/ba-doc-generator/references/template-dev.md +138 -0
  169. package/skills/specify/ba-doc-generator/references/template-partner.md +167 -0
  170. package/skills/specify/ba-doc-generator/references/template-pm.md +92 -0
  171. package/skills/specify/ba-doc-generator/references/template-review.md +114 -0
  172. package/skills/specify/ba-doc-generator/references/template-tester.md +108 -0
  173. package/skills/specify/ba-doc-generator/references/template-user.md +98 -0
  174. package/skills/specify/bugfix-analyst/SKILL.md +296 -0
  175. package/skills/specify/bugfix-analyst/config.json +41 -0
  176. package/skills/specify/bugfix-analyst/examples/bad/common-mistakes.md +71 -0
  177. package/skills/specify/bugfix-analyst/examples/good/email-validation-bugfix.md +53 -0
  178. package/skills/specify/bugfix-analyst/gotchas.md +51 -0
  179. package/skills/specify/ears-writer/SKILL.md +129 -0
  180. package/skills/specify/ears-writer/config.json +20 -0
  181. package/skills/specify/ears-writer/examples/bad/common-mistakes.md +17 -0
  182. package/skills/specify/ears-writer/examples/good/login-requirements.md +41 -0
  183. package/skills/specify/ears-writer/gotchas.md +43 -0
  184. package/skills/specify/ears-writer/scripts/check-ears-compliance.sh +51 -0
  185. package/skills/test/test-case-generator/SKILL.md +161 -0
  186. package/skills/test/test-case-generator/config.json +33 -0
  187. package/skills/test/test-case-generator/examples/good/test-cases-login.md +104 -0
  188. package/skills/test/test-case-generator/gotchas.md +43 -0
  189. package/skills/understand/ba-docs-scanner/SKILL.md +239 -0
  190. package/skills/understand/ba-docs-scanner/config.json +47 -0
  191. package/skills/understand/ba-docs-scanner/examples/good/work-order-br-extract.md +28 -0
  192. package/skills/understand/ba-docs-scanner/gotchas.md +44 -0
  193. package/skills/understand/ba-docs-scanner/merge-rules.md +47 -0
  194. package/skills/understand/codebase-scanner/SKILL.md +260 -0
  195. package/skills/understand/codebase-scanner/config.json +56 -0
  196. package/skills/understand/codebase-scanner/examples/good/menu-module-output.md +44 -0
  197. package/skills/understand/codebase-scanner/gotchas.md +42 -0
  198. package/skills/understand/codebase-scanner/scripts/scan-project-structure.sh +64 -0
  199. package/templates/DESIGN.md +456 -0
  200. package/templates/agent-command-template.yaml +240 -0
  201. package/templates/agent-config-template.md +170 -0
  202. package/templates/agent-definition-template.md +145 -0
  203. package/templates/agent-metrics-template.md +150 -0
  204. package/templates/api-contract-template.md +72 -0
  205. package/templates/bugfix-report-template.md +195 -0
  206. package/templates/bugfix-spec-template.md +134 -0
  207. package/templates/code-review-report-template.md +119 -0
  208. package/templates/constitution-template.md +234 -0
  209. package/templates/context-template.md +94 -0
  210. package/templates/data-model-template.md +95 -0
  211. package/templates/decision-log-template.md +92 -0
  212. package/templates/flow-state-template.yaml +208 -0
  213. package/templates/github/workflows/v-flow-validate.yml +30 -0
  214. package/templates/knowledge/adr-template.md +70 -0
  215. package/templates/knowledge/api-contract-template.md +140 -0
  216. package/templates/knowledge/domain-glossary.md +29 -0
  217. package/templates/knowledge/golden-tests-readme.md +115 -0
  218. package/templates/knowledge/lessons-learned.md +41 -0
  219. package/templates/knowledge/patterns.md +103 -0
  220. package/templates/module-card/SKILL.md +85 -0
  221. package/templates/module-card/api-specs.md +96 -0
  222. package/templates/module-card/business-quiz.md +119 -0
  223. package/templates/module-card/cross-service.md +125 -0
  224. package/templates/module-card/db.md +85 -0
  225. package/templates/module-card/dev-quiz.md +62 -0
  226. package/templates/module-card/permissions.md +83 -0
  227. package/templates/module-card/state-diagram.md +64 -0
  228. package/templates/module-card/tech-context.md +90 -0
  229. package/templates/module-card/ui-flows.md +91 -0
  230. package/templates/module-card/use-cases.md +142 -0
  231. package/templates/module-template.yaml +161 -0
  232. package/templates/operations-report-template.md +108 -0
  233. package/templates/plan-template.md +308 -0
  234. package/templates/prototype-notes-template.md +116 -0
  235. package/templates/ptyc/PTYC.template.docx +0 -0
  236. package/templates/ptyc/ptyc.meta.example.yaml +44 -0
  237. package/templates/retrospective-report-template.md +136 -0
  238. package/templates/security-review-template.md +84 -0
  239. package/templates/session-template.md +167 -0
  240. package/templates/spec-review-log-template.md +75 -0
  241. package/templates/spec-template.md +229 -0
  242. package/templates/sprint-status-template.md +101 -0
  243. package/templates/tasks-template.md +275 -0
  244. package/templates/test-cases-template.md +124 -0
  245. package/templates/ux-checklist-template.md +79 -0
  246. package/templates/validation-report-template.md +125 -0
  247. package/templates/vflow-config-template.yaml +22 -0
@@ -0,0 +1,33 @@
1
+ {
2
+ "_note": "setup_questions là PROMPT. Đáp án resolve persist vào .v-flow/config.yaml (xem .v-flow/templates/vflow-config-template.yaml). Skill đọc .v-flow/config.yaml trước, thiếu mới dùng default dưới đây.",
3
+ "answers_persisted_to": ".v-flow/config.yaml",
4
+ "setup_questions": [
5
+ {
6
+ "id": "test_framework",
7
+ "question": "Test framework nào đang dùng?",
8
+ "options": ["jest", "mocha", "vitest", "flutter_test", "pytest", "other"],
9
+ "default": "jest"
10
+ },
11
+ {
12
+ "id": "coverage_target",
13
+ "question": "Coverage target tối thiểu (%)?",
14
+ "type": "number",
15
+ "default": 80
16
+ },
17
+ {
18
+ "id": "test_location",
19
+ "question": "Test files đặt ở đâu?",
20
+ "options": ["colocated", "test/", "__tests__/", "spec/"],
21
+ "default": "test/"
22
+ }
23
+ ],
24
+ "hooks": {
25
+ "pre_implement": "Đọc test-cases.md → map TC-xxx cho TASK hiện tại",
26
+ "post_implement": "Chạy full test suite → verify không regression"
27
+ },
28
+ "memory": {
29
+ "file": "tdd-history.log",
30
+ "format": "[date] | [feature] | [task] | [tests_written] | [tests_passed] | [refactor_needed]",
31
+ "purpose": "Track TDD discipline — Agent đọc để biết patterns trước đó"
32
+ }
33
+ }
@@ -0,0 +1,81 @@
1
+ # Good Example — TDD Cycle cho T-003: Product Repository
2
+
3
+ ## Context
4
+ - Task: Tạo ProductRepository với parameterized SQL
5
+ - REQ: REQ-U01 (parameterized queries), REQ-E05 (soft delete)
6
+ - Test cases: TC-01 (parameterized), TC-09 (soft delete)
7
+
8
+ ## 🔴 RED — Viết test trước
9
+
10
+ ```javascript
11
+ // test/repositories/product.repo.test.js
12
+ const { ProductRepository } = require('../../repositories/product.repo');
13
+
14
+ describe('ProductRepository', () => {
15
+ let repo, mockPool;
16
+
17
+ beforeEach(() => {
18
+ mockPool = { query: jest.fn() };
19
+ repo = new ProductRepository(mockPool);
20
+ });
21
+
22
+ // TC-01: REQ-U01 — parameterized query
23
+ it('should_use_parameterized_query_when_finding_by_id', async () => {
24
+ mockPool.query.mockResolvedValue({ rows: [{ id: 1, name: 'Test' }] });
25
+
26
+ await repo.findById(1);
27
+
28
+ // Assert: query uses $1 parameter, NOT string concat
29
+ const [sql, params] = mockPool.query.mock.calls[0];
30
+ expect(sql).toContain('$1');
31
+ expect(sql).not.toMatch(/['"]?\s*\+/); // no string concat
32
+ expect(params).toEqual([1]);
33
+ });
34
+
35
+ // TC-09: REQ-E05 — soft delete
36
+ it('should_set_deleted_at_when_soft_deleting', async () => {
37
+ mockPool.query.mockResolvedValue({ rowCount: 1 });
38
+
39
+ await repo.softDelete(1);
40
+
41
+ const [sql] = mockPool.query.mock.calls[0];
42
+ expect(sql).toContain('deleted_at');
43
+ expect(sql).not.toContain('DELETE FROM');
44
+ });
45
+ });
46
+ ```
47
+
48
+ **Run → FAIL**: `ProductRepository is not defined` ✅ (expected)
49
+
50
+ ## 🟢 GREEN — Code tối thiểu
51
+
52
+ ```javascript
53
+ // repositories/product.repo.js
54
+ class ProductRepository {
55
+ constructor(pool) { this.pool = pool; }
56
+
57
+ async findById(id) {
58
+ const { rows } = await this.pool.query(
59
+ 'SELECT * FROM products WHERE id = $1 AND deleted_at IS NULL', [id]
60
+ );
61
+ return rows[0] || null;
62
+ }
63
+
64
+ async softDelete(id) {
65
+ const { rowCount } = await this.pool.query(
66
+ 'UPDATE products SET deleted_at = NOW() WHERE id = $1', [id]
67
+ );
68
+ return rowCount > 0;
69
+ }
70
+ }
71
+ module.exports = { ProductRepository };
72
+ ```
73
+
74
+ **Run → PASS** ✅
75
+
76
+ ## 🔵 REFACTOR — Clean theo constitution
77
+
78
+ - Extracted SQL strings to constants
79
+ - Added JSDoc comments
80
+ - Verified: all tests still pass ✅
81
+ - No-Go check: không đụng `db/pool.js` ✅
@@ -0,0 +1,34 @@
1
+ # Gotchas — TDD Driver
2
+
3
+ > Cập nhật liên tục khi Agent gặp edge case mới.
4
+ > Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
5
+
6
+ ---
7
+
8
+ ## Anti-Patterns
9
+
10
+ 1. ❌ **Implement trước, test sau** — Test sẽ bias theo code đã viết. "Green bar = proof" là ảo.
11
+ - **Hậu quả**: Test chỉ confirm code hoạt động, không confirm requirement.
12
+
13
+ 2. ❌ **Skip test vì "đơn giản"** — Bugs hay ẩn ở code đơn giản nhất.
14
+ - **VD**: Off-by-one, null check, empty array.
15
+
16
+ 3. ❌ **Test quá lớn** — 1 test cover 5 behaviors → khi fail, không biết cái nào sai.
17
+ - **Fix**: 1 test = 1 assertion = 1 behavior.
18
+
19
+ 4. ❌ **Mock quá nhiều** — Test full mocks → integration issues leak ra production.
20
+ - **Rule**: Mock external deps only. Business logic test real code.
21
+
22
+ 5. ❌ **Sửa test để pass** — Nếu test fail → fix CODE, KHÔNG fix test.
23
+ - **Exception**: Test implementation sai (sai mock setup, sai expected value) → fix test.
24
+
25
+ 6. ❌ **Quên concerns** — W-xxx carry-forward từ R.0 phải được resolve trong TDD cycle.
26
+ - **Check**: Đọc `_session.md` → search `W-` → resolve trong task assigned.
27
+
28
+ 7. ❌ **Test depend test khác** — Test 2 fail vì Test 1 setup shared state.
29
+ - **Fix**: Mỗi test PHẢI chạy standalone. Fresh state per test.
30
+
31
+ 8. ❌ **Test tên vô nghĩa** — `test1`, `testLogin` → khi fail, không biết test gì.
32
+ - **Fix**: `should_return_404_when_product_not_found`.
33
+
34
+ 9. ✅ **Nếu test PASS ngay ở RED** — Test SAI, không phải code ĐÚNG. Xem lại.
@@ -0,0 +1,133 @@
1
+ ---
2
+ name: metrics-collector
3
+ version: "1.0"
4
+ agent: metrics
5
+ phase: M.0
6
+ triggers:
7
+ - post_review
8
+ - manual_collection
9
+ dependencies:
10
+ - _shared/constitution-reader
11
+ input:
12
+ - .flow-state.yaml
13
+ - _session.md
14
+ - validation-report.md
15
+ - code-review-report.md (if exists)
16
+ - git log / timestamps
17
+ output:
18
+ - metrics-report.md
19
+ complexity: medium
20
+ ---
21
+
22
+ # Metrics Collector Skill
23
+
24
+ > **Purpose**: Thu thập và phân tích Agent performance metrics sau mỗi feature cycle.
25
+ > **Khi nào dùng**: Sau khi R.1 (Review) hoàn tất — chạy `/v.metrics`.
26
+
27
+ ## Quick Reference
28
+
29
+ ```
30
+ Input: .flow-state.yaml + _session.md + validation/review reports
31
+ Output: metrics-report.md
32
+ Agent: Metrics Agent
33
+ Phase: M.0 (post R.1)
34
+ ```
35
+
36
+ ## What This Skill Does
37
+
38
+ 1. **Collect Timeline Data** — Timestamps từ `.flow-state.yaml` phase_history
39
+ 2. **Count Iterations** — Bao nhiêu lần revision tại mỗi phase
40
+ 3. **Measure Quality** — First-pass approval rates, Master Check verdict
41
+ 4. **Analyze Bottlenecks** — Phase nào mất thời gian nhất
42
+ 5. **Generate Report** — Structured metrics-report.md
43
+
44
+ ## Metrics Categories
45
+
46
+ ### Per-Agent Metrics
47
+
48
+ | Metric | Source | Formula |
49
+ |--------|--------|---------|
50
+ | **First-pass approval rate** | `.flow-state.yaml` phase_history | phases_passed_first_try / total_phases |
51
+ | **Revision count** | `_session.md` execution trace | Count re-entries per phase |
52
+ | **Processing time** | `.flow-state.yaml` timestamps | exited_at - entered_at per phase |
53
+ | **Quality score** | `validation-report.md` | (PASS=100, WITH_CONCERNS=70, FAIL=0) |
54
+
55
+ ### Per-Pipeline Metrics
56
+
57
+ | Metric | Source | Formula |
58
+ |--------|--------|---------|
59
+ | **Total cycle time** | `.flow-state.yaml` | last_phase.exited_at - first_phase.entered_at |
60
+ | **Master Check pass rate** | `.flow-state.yaml` routing | PASS_count / total_check_count |
61
+ | **Rework rate** | Phase history | phases_with_rework / total_phases |
62
+ | **Concern resolution rate** | `_session.md` | concerns_resolved / concerns_raised |
63
+
64
+ ### Per-Feature Metrics
65
+
66
+ | Metric | Source | Formula |
67
+ |--------|--------|---------|
68
+ | **Requirements count** | `spec.md` | Count REQ-xxx |
69
+ | **Test coverage** | `test-cases.md` | tests_count / requirements_count |
70
+ | **Spec change count** | `.flow-state.yaml` spec_version | Version number (v1.0 → v1.2 = 2 changes) |
71
+
72
+ ## How to Use
73
+
74
+ ### Step 1: Gather Data Sources
75
+
76
+ ```markdown
77
+ Đọc các file sau từ feature directory:
78
+ 1. .flow-state.yaml → phase_history, artifacts, routing
79
+ 2. _session.md → execution trace, decisions, open questions
80
+ 3. validation-report.md → verdict, concerns
81
+ 4. spec.md → requirements count
82
+ 5. test-cases.md → test count
83
+ ```
84
+
85
+ ### Step 2: Calculate Metrics
86
+
87
+ ```markdown
88
+ Cho mỗi phase trong phase_history:
89
+ - Tính duration = exited_at - entered_at
90
+ - Đếm số lần phase xuất hiện (revision count)
91
+ - Kiểm tra verdict/approval status
92
+
93
+ Tổng hợp:
94
+ - Total cycle time
95
+ - Bottleneck phase (longest duration)
96
+ - First-pass vs revision phases
97
+ ```
98
+
99
+ ### Step 3: Generate Report
100
+
101
+ ```markdown
102
+ ## 📊 Metrics Report — [Feature Name]
103
+
104
+ ### Summary
105
+ | Metric | Value |
106
+ |--------|-------|
107
+ | Total cycle time | X days |
108
+ | Phases completed | Y/Z |
109
+ | First-pass rate | XX% |
110
+ | Rework rate | XX% |
111
+ | Requirements | N |
112
+ | Test cases | M |
113
+
114
+ ### Phase Timeline
115
+ | Phase | Duration | Revisions | Verdict |
116
+ |-------|----------|-----------|---------|
117
+ | S.1 | 2h | 0 | approved |
118
+ | B.0a | 1h | 0 | - |
119
+ | R.0 | 30m | 1 | PASS_WITH_CONCERNS |
120
+ | B.1 | 4h | 0 | - |
121
+ | R.1 | 1h | 0 | APPROVED |
122
+
123
+ ### Recommendations
124
+ 1. [Based on bottleneck analysis]
125
+ 2. [Based on rework patterns]
126
+ ```
127
+
128
+ ## Gotchas
129
+
130
+ 1. **Missing timestamps** — Nếu `.flow-state.yaml` không có đủ timestamps, ước tính từ git log
131
+ 2. **Manual phases** — Một số phases (e.g., human approval) không có agent metrics
132
+ 3. **Cross-feature comparison** — Chỉ so sánh features cùng project_type (greenfield vs legacy)
133
+ 4. **First feature bias** — Feature đầu tiên thường chậm hơn do setup overhead
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "metrics-collector",
3
+ "version": "1.0",
4
+ "description": "Collects and analyzes Agent performance metrics after each feature cycle",
5
+ "agent": "metrics",
6
+ "phase": ["M.0"],
7
+ "triggers": ["post_review", "manual"],
8
+ "dependencies": ["_shared/constitution-reader"],
9
+ "config": {
10
+ "metrics_categories": ["per_agent", "per_pipeline", "per_feature"],
11
+ "comparison_threshold": 5,
12
+ "report_format": "markdown",
13
+ "include_recommendations": true,
14
+ "benchmark_window": "last_5_features"
15
+ }
16
+ }
@@ -0,0 +1,48 @@
1
+ # Metrics Collector — Bad Example
2
+
3
+ > Ví dụ output THIẾU SÓT — không nên làm theo.
4
+
5
+ ## ❌ Bad Output — Quá sơ sài
6
+
7
+ ```markdown
8
+ ## Metrics Report
9
+
10
+ Feature completed in 6 hours.
11
+ All tests passed.
12
+ No major issues.
13
+ ```
14
+
15
+ ## Vấn đề
16
+
17
+ | # | Lỗi | Giải thích |
18
+ |---|------|-----------|
19
+ | 1 | Không có per-phase breakdown | Không biết phase nào bottleneck |
20
+ | 2 | Không có per-agent analysis | Không biết agent nào cần cải thiện |
21
+ | 3 | Không có benchmark comparison | "6 hours" có tốt hay không? |
22
+ | 4 | Không có trend data | Không biết đang cải thiện hay xuống |
23
+ | 5 | Không có recommendations | Metrics vô dụng nếu không actionable |
24
+ | 6 | Không track concerns | Concerns từ R.0 có resolved không? |
25
+
26
+ ## ❌ Bad Output — Chỉ liệt kê không phân tích
27
+
28
+ ```markdown
29
+ ## Metrics
30
+
31
+ - S.1: 1.5h
32
+ - B.0a: 45m
33
+ - B.0b: 30m
34
+ - R.0: 20m
35
+ - B.1: 2.5h
36
+ - R.1: 40m
37
+
38
+ Total: 6.5h
39
+ ```
40
+
41
+ ## Vấn đề
42
+
43
+ | # | Lỗi | Giải thích |
44
+ |---|------|-----------|
45
+ | 1 | Raw data không insight | Liệt kê số nhưng không phân tích |
46
+ | 2 | Thiếu context | Không biết revision count, verdict |
47
+ | 3 | Không có percentage | Không thấy proportions |
48
+ | 4 | Không actionable | Không biết cần làm gì tiếp |
@@ -0,0 +1,101 @@
1
+ # Metrics Collector — Good Example
2
+
3
+ > Ví dụ output chuẩn của Metrics Agent sau khi feature cycle hoàn tất.
4
+
5
+ ## Input Context
6
+
7
+ **Feature:** 005-user-notifications
8
+ **Pipeline:** S.1 → B.0a ∥ B.0b → R.0 → B.1 → R.1 → M.0
9
+ **Outcome:** Deployed successfully
10
+
11
+ ## Output — metrics-report.md
12
+
13
+ ```markdown
14
+ ## 📊 Metrics Report — 005-user-notifications
15
+
16
+ **Generated**: 2026-04-25 14:30
17
+ **Pipeline**: Full Flow (with Dual BA)
18
+ **Outcome**: ✅ Deployed
19
+
20
+ ### Summary
21
+
22
+ | Metric | Value | Benchmark | Status |
23
+ |--------|-------|-----------|--------|
24
+ | Total cycle time | 6.5 hours | 4-8 hours | ✅ Normal |
25
+ | Phases completed | 7/7 | 7/7 | ✅ Complete |
26
+ | First-pass rate | 71% (5/7) | >60% | ✅ Good |
27
+ | Rework rate | 29% (2/7) | <40% | ✅ Acceptable |
28
+ | Requirements | 8 (3U + 2E + 2S + 1O) | — | — |
29
+ | Test cases | 15 | — | 1.88 per REQ |
30
+ | Spec changes | 2 (v1.0 → v1.2) | <3 | ✅ Normal |
31
+
32
+ ### Phase Timeline
33
+
34
+ | Phase | Duration | Revisions | Verdict | Notes |
35
+ |-------|----------|-----------|---------|-------|
36
+ | S.1 Spec | 1.5h | 1 | approved v1.2 | Dual BA: 2 rounds to converge |
37
+ | B.0a Plan | 45m | 0 | approved | Clean architecture applied |
38
+ | B.0b Test | 30m | 0 | approved | 15 TCs (8 happy, 4 edge, 3 error) |
39
+ | R.0 Check | 20m | 1 | PASS_WITH_CONCERNS | [W-001] Missing pagination spec |
40
+ | B.1 Implement | 2.5h | 0 | — | TDD: all 15 tests pass |
41
+ | R.1 Review | 40m | 0 | APPROVED_WITH_NOTES | 4 issues (0 critical, 1 major, 3 minor) |
42
+ | M.0 Metrics | 15m | 0 | — | This report |
43
+
44
+ ### Per-Agent Analysis
45
+
46
+ | Agent | First-pass? | Quality | Insight |
47
+ |-------|:-----------:|---------|---------|
48
+ | BA Agent | ❌ (rev 1) | Good | Spec v1.0 thiếu error paths → v1.2 after BA Critic |
49
+ | Plan Agent | ✅ | Excellent | Components mapped 100% to REQs |
50
+ | Test Agent | ✅ | Good | Coverage 1.88 TC/REQ — above target |
51
+ | Master Check | ❌ (rev 1) | Good | Caught [W-001] → resolved in B.1 |
52
+ | Implement Agent | ✅ | Excellent | TDD discipline maintained |
53
+ | Review Agent | ✅ | Good | Found 1 major (missing index) |
54
+
55
+ ### Concern Resolution
56
+
57
+ | Concern | Source | Resolution | Verified |
58
+ |---------|--------|------------|:--------:|
59
+ | [W-001] Missing pagination | R.0 | Added pagination in B.1 (limit=20, offset) | ✅ R.1 |
60
+
61
+ ### Bottleneck Analysis
62
+
63
+ ```
64
+ Phase Duration Distribution:
65
+ S.1 ████████████████████ 1.5h (23%) ← Longest — Dual BA overhead
66
+ B.1 ██████████████████████████████████ 2.5h (38%) ← Expected — most work
67
+ B.0a ██████████ 45m (12%)
68
+ R.1 █████████ 40m (10%)
69
+ B.0b ██████ 30m (8%)
70
+ R.0 ████ 20m (5%)
71
+ M.0 ██ 15m (4%)
72
+ ```
73
+
74
+ **Bottleneck**: S.1 (23%) — Dual BA review added ~45m overhead.
75
+ **Action**: Consider using single BA for features with <5 requirements.
76
+
77
+ ### Recommendations
78
+
79
+ 1. **BA Agent**: Pre-define error paths in initial spec to reduce Dual BA rounds
80
+ 2. **Master Check**: Pagination should be in standard checklist for list APIs
81
+ 3. **Review Agent**: Database index check should be automated (add to constitution)
82
+ 4. **Overall**: Cycle time within normal range — no urgent improvements needed
83
+
84
+ ### Trend (last 3 features)
85
+
86
+ | Feature | Cycle Time | First-pass | Rework | REQs |
87
+ |---------|-----------|-----------|--------|------|
88
+ | 003-export | 4.0h | 83% | 17% | 5 |
89
+ | 004-dashboard | 7.5h | 57% | 43% | 12 |
90
+ | **005-notifications** | **6.5h** | **71%** | **29%** | **8** |
91
+ | **Average** | **6.0h** | **70%** | **30%** | **8.3** |
92
+ ```
93
+
94
+ ## Why This Is Good
95
+
96
+ 1. ✅ **Quantitative** — tất cả metrics đều có số liệu cụ thể
97
+ 2. ✅ **Benchmarked** — so sánh với benchmark biết normal hay không
98
+ 3. ✅ **Actionable** — recommendations cụ thể cho từng agent
99
+ 4. ✅ **Visual** — bar chart cho bottleneck analysis
100
+ 5. ✅ **Trending** — so sánh với features trước để thấy xu hướng
101
+ 6. ✅ **Concern tracking** — chứng minh concerns đã resolved
@@ -0,0 +1,26 @@
1
+ # Metrics Collector — Gotchas & Common Mistakes
2
+
3
+ ## ⚠️ Gotcha 1: Vanity Metrics
4
+
5
+ **Sai**: Focus vào "total features completed" — không phản ánh quality.
6
+ **Đúng**: Đo **first-pass approval rate** và **rework rate** — phản ánh thực sự Agent performance.
7
+
8
+ ## ⚠️ Gotcha 2: Missing Baseline
9
+
10
+ **Sai**: Report metrics mà không có benchmark.
11
+ **Đúng**: So sánh với 5 features gần nhất. Feature đầu tiên là baseline, không phải target.
12
+
13
+ ## ⚠️ Gotcha 3: Ignoring Context
14
+
15
+ **Sai**: So sánh cycle time giữa simple CRUD feature và complex integration feature.
16
+ **Đúng**: Normalize theo requirements count. Report requirements/hour thay vì absolute time.
17
+
18
+ ## ⚠️ Gotcha 4: Skipping Recommendations
19
+
20
+ **Sai**: Chỉ report numbers, không đề xuất action.
21
+ **Đúng**: Mỗi metrics report PHẢI có ≥2 actionable recommendations dựa trên bottleneck analysis.
22
+
23
+ ## ⚠️ Gotcha 5: Over-optimization
24
+
25
+ **Sai**: Mỗi feature đều thay đổi agent-config.md dựa trên metrics.
26
+ **Đúng**: Chỉ update agent config sau 5-10 features. Trends matter, not individual data points.
@@ -0,0 +1,167 @@
1
+ ---
2
+ name: incident-runbook
3
+ version: "1.0"
4
+ agent: operations
5
+ phase: O.0
6
+ triggers:
7
+ - production_incident
8
+ - hotfix_flow
9
+ - monitoring_alert
10
+ dependencies:
11
+ - _shared/context-reader
12
+ input:
13
+ - incident report / alert
14
+ - monitoring data (logs, metrics)
15
+ - context.md
16
+ - spec.md (related feature)
17
+ output:
18
+ - operations-report.md
19
+ - incident ticket (INC-XXX.md)
20
+ complexity: high
21
+ ---
22
+
23
+ # Incident Runbook Skill
24
+
25
+ > **Purpose**: Structured incident response procedure cho production issues.
26
+ > **Khi nào dùng**: Khi nhận alert/report từ production — chạy `/v.hotfix`.
27
+
28
+ ## Quick Reference
29
+
30
+ ```
31
+ Input: Incident report + monitoring data + context.md
32
+ Output: operations-report.md + INC-XXX.md
33
+ Agent: Operations Agent
34
+ Phase: O.0
35
+ ```
36
+
37
+ ## What This Skill Does
38
+
39
+ 1. **Triage** — Phân loại severity (P1/P2/P3/P4) và assign response SLA
40
+ 2. **Investigate** — Root Cause Analysis (RCA) có cấu trúc
41
+ 3. **Contain** — Immediate mitigation steps
42
+ 4. **Fix** — Route to appropriate pipeline (hotfix/quickfix/standard)
43
+ 5. **Learn** — Post-mortem và lessons learned
44
+
45
+ ## Severity Classification
46
+
47
+ | Level | Impact | Response SLA | Pipeline |
48
+ |-------|--------|-------------|----------|
49
+ | **P1** | Service down, data loss | < 15 min | `/v.hotfix` |
50
+ | **P2** | Major feature broken | < 1 hour | `/v.hotfix` |
51
+ | **P3** | Minor feature degraded | < 4 hours | `/v.quickfix` |
52
+ | **P4** | Cosmetic, performance | Next sprint | Standard flow |
53
+
54
+ ## Incident Response Steps
55
+
56
+ ### Step 1: Triage (< 5 min)
57
+
58
+ ```markdown
59
+ ## Incident Triage
60
+
61
+ **Alert Source**: [monitoring / user report / automated test]
62
+ **Timestamp**: [when detected]
63
+ **Impact Assessment**:
64
+ - Users affected: [all / segment / single]
65
+ - Feature affected: [feature name]
66
+ - Data integrity: [safe / at risk / compromised]
67
+
68
+ **Severity**: P[1-4]
69
+ **Response SLA**: [time]
70
+ ```
71
+
72
+ ### Step 2: Investigate (RCA)
73
+
74
+ ```markdown
75
+ ## Root Cause Analysis
76
+
77
+ ### What happened?
78
+ [Description của incident]
79
+
80
+ ### Timeline
81
+ | Time | Event |
82
+ |------|-------|
83
+ | T-0 | Description of the trigger event |
84
+ | T+5m | First alert |
85
+ | T+10m | Investigation started |
86
+
87
+ ### Root Cause
88
+ [Direct cause → Contributing factors → Systemic issues]
89
+
90
+ ### Blast Radius
91
+ - Files affected: [list]
92
+ - Modules affected: [list]
93
+ - No-Go Zones touched: [yes/no — CRITICAL if yes]
94
+ ```
95
+
96
+ ### Step 3: Contain
97
+
98
+ ```markdown
99
+ ## Immediate Mitigation
100
+
101
+ ### Actions Taken
102
+ 1. [Rollback / Feature flag / Rate limit / etc.]
103
+ 2. [Communication to users]
104
+ 3. [Monitoring enhanced]
105
+
106
+ ### Verification
107
+ - [How to verify the containment is effective]
108
+ - [Metrics to watch]
109
+ ```
110
+
111
+ ### Step 4: Fix (Route to Pipeline)
112
+
113
+ ```markdown
114
+ ## Fix Strategy
115
+
116
+ ### Route Decision
117
+ - P1/P2 → `/v.hotfix` — skip spec, direct implement → review → deploy
118
+ - P3 → `/v.quickfix` — minimal spec → implement → review
119
+ - P4 → Standard flow with backlog ticket
120
+
121
+ ### Fix Details
122
+ - Branch: hotfix/INC-XXX
123
+ - Files to change: [list]
124
+ - Test strategy: [unit test for fix + regression]
125
+ - Deploy strategy: [immediate / canary / next release]
126
+ ```
127
+
128
+ ### Step 5: Learn (Post-mortem)
129
+
130
+ ```markdown
131
+ ## Post-Mortem
132
+
133
+ ### What went well
134
+ 1. [Detection was fast]
135
+ 2. [Communication was clear]
136
+
137
+ ### What went wrong
138
+ 1. [Missing test coverage for edge case]
139
+ 2. [No monitoring for this metric]
140
+
141
+ ### Action Items
142
+ | # | Action | Owner | Due |
143
+ |---|--------|-------|-----|
144
+ | 1 | Add test for edge case X | Dev | Sprint N |
145
+ | 2 | Add monitoring alert for Y | SRE | Sprint N |
146
+ | 3 | Update context.md with new no-go zone | Tech Lead | Sprint N |
147
+
148
+ ### Knowledge Base Update
149
+ → File: .v-flow/knowledge/lessons-learned/INC-XXX.md
150
+ ```
151
+
152
+ ## Integration with V-Flow Pipeline
153
+
154
+ ```
155
+ Alert → O.0 (Triage + RCA) → Route Decision:
156
+ ├── P1/P2 → B.1 (Hotfix) → R.1 (Review) → Deploy → O.0 (Verify)
157
+ ├── P3 → S.1 (Quick Spec) → B.1 → R.1 → Deploy
158
+ └── P4 → Backlog → Standard Pipeline
159
+ ```
160
+
161
+ ## Gotchas
162
+
163
+ 1. **Đừng debug production trên production** — Reproduce locally trước khi fix
164
+ 2. **No-Go Zones** — Nếu root cause nằm trong no-go zone, PHẢI escalate tới Tech Lead
165
+ 3. **Hotfix ≠ Skip quality** — Hotfix vẫn cần test và review, chỉ skip spec
166
+ 4. **Communication** — Cập nhật stakeholders tại mỗi bước, không chỉ khi fix xong
167
+ 5. **Lessons learned** — Post-mortem PHẢI được ghi vào knowledge base, không chỉ chat/email
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "incident-runbook",
3
+ "version": "1.0",
4
+ "description": "Structured incident response procedure for production issues",
5
+ "agent": "operations",
6
+ "phase": ["O.0"],
7
+ "triggers": ["production_incident", "monitoring_alert", "hotfix_flow"],
8
+ "dependencies": ["_shared/context-reader"],
9
+ "config": {
10
+ "severity_levels": {
11
+ "P1": { "sla_minutes": 15, "route": "hotfix" },
12
+ "P2": { "sla_minutes": 60, "route": "hotfix" },
13
+ "P3": { "sla_minutes": 240, "route": "quickfix" },
14
+ "P4": { "sla_minutes": null, "route": "standard" }
15
+ },
16
+ "require_postmortem": true,
17
+ "incident_dir": ".v-flow/incidents",
18
+ "lessons_learned_dir": ".v-flow/knowledge/lessons-learned",
19
+ "report_format": "markdown"
20
+ }
21
+ }