@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,167 @@
1
+ # Session Memory — [Feature Name]
2
+
3
+ > **File**: `.v-flow/features/NNN-feature-name/_session.md`
4
+ > **Mục đích**: Working memory của feature trong một phiên làm việc — tạm thời, không phải Source of Truth.
5
+ > **Cập nhật bởi**: Mỗi Agent khi chuyển phase hoặc ra quyết định quan trọng.
6
+ > **Đọc bởi**: Mọi Agent khi bắt đầu làm việc với feature này (đọc sau spec.md, trước context.md).
7
+
8
+ ---
9
+
10
+ ## 📋 Tóm Tắt Nhanh (Quick Status)
11
+
12
+ > Agent điền khi bắt đầu mỗi phase
13
+
14
+ ```
15
+ Phase hiện tại : [phase]
16
+ Bắt đầu lúc : [datetime]
17
+ Agent đang làm : [agent name]
18
+ Spec version : [vX.Y]
19
+ Validation : [PASS | PASS_WITH_CONCERNS | FAIL | pending]
20
+ Tasks done : [N/total]
21
+ ```
22
+
23
+ ---
24
+
25
+ ## 🧠 Context Quan Trọng (Key Decisions Made)
26
+
27
+ > Ghi lại các quyết định đã được người dùng confirm — để Agent sau không hỏi lại
28
+
29
+ | # | Quyết định | Lý do | Ai confirm | Khi nào |
30
+ |---|-----------|-------|------------|---------|
31
+ | 1 | | | | |
32
+
33
+ ---
34
+
35
+ ## ❓ Câu Hỏi Đang Mở (Open Questions)
36
+
37
+ > Agent ghi câu hỏi vào đây thay vì tự đoán — người dùng trả lời
38
+
39
+ - [ ] [Câu hỏi 1] → *Đang chờ trả lời*
40
+ - [x] [Câu hỏi 2] → *Trả lời: ...*
41
+
42
+ ---
43
+
44
+ ## ⚡ Execution Trace (Phase-by-Phase Log)
45
+
46
+ > Tự động append bởi mỗi Agent khi hoàn thành phase
47
+
48
+ ### [S.1] Specify — [YYYY-MM-DD]
49
+ - **Agent**: BA Agent
50
+ - **Input**: [mô tả yêu cầu đầu vào]
51
+ - **Output**: `spec.md v1.0`
52
+ - **Module cards used**: [module] v[X.Y], [module] v[X.Y] ← version lúc chạy gate
53
+ - **Biz verification**: [passed | passed_with_warnings | failed | skipped] — [modules đã verify]
54
+ - **Highlights**: [điều gì đặc biệt/khác thường trong spec này?]
55
+ - **Prototype suggestion**: [yes — N ambiguity points | no]
56
+ - **Human checkpoint**: [approved by / pending]
57
+
58
+ ### [S.1.5] Prototype — [YYYY-MM-DD] *(optional — skip nếu không chạy)*
59
+ - **Agent**: Prototype Agent
60
+ - **Branch**: [LOGIC | UI | skipped]
61
+ - **Question**: [câu hỏi prototype trả lời]
62
+ - **REQ refs**: [REQ-xxx, REQ-xxx]
63
+ - **Verdict**: [VALIDATED | REJECTED | INCONCLUSIVE | skipped]
64
+ - **Prototype location**: `.v-flow/features/NNN/prototype/`
65
+ - **Key findings**: [tóm tắt 1-2 câu]
66
+ - **Spec impact**: [no change | update needed | new REQ added]
67
+ - **Routing**: [→ /v.plan + /v.test | → /v.specify | → awaiting stakeholder | skipped]
68
+
69
+ ### [B.0a] Plan — [YYYY-MM-DD]
70
+ - **Agent**: Plan Agent
71
+ - **Output**: `plan.md`, `tasks.md` ([N] tasks)
72
+ - **Key decisions**:
73
+ - [Quyết định kiến trúc quan trọng]
74
+ - **Risks flagged**:
75
+ - [Risk 1]
76
+ - **Human checkpoint**: [approved by / pending]
77
+
78
+ ### [B.0b] Test — [YYYY-MM-DD]
79
+ - **Agent**: Test Agent
80
+ - **Output**: `test-cases.md` ([N] test cases)
81
+ - **Coverage gaps noted**: [nếu có]
82
+ - **Human checkpoint**: [approved by / pending]
83
+
84
+ ### [R.0] Master Check — [YYYY-MM-DD]
85
+ - **Agent**: Master Check Agent
86
+ - **Verdict**: [PASS | PASS_WITH_CONCERNS | FAIL]
87
+ - **Critical issues**: [N]
88
+ - **Major issues**: [N]
89
+ - **Concerns to watch**: [list concerns nếu PASS_WITH_CONCERNS]
90
+ - **Routing decision**: [implement | re_specify | re_plan | re_test]
91
+ - **Route reason**: [lý do routing]
92
+
93
+ ### [B.1] Implement — [YYYY-MM-DD]
94
+ - **Agent**: Implement Agent
95
+ - **Tasks completed**: [N/total]
96
+ - **Concerns addressed**:
97
+ - [W-001] → [cách giải quyết]
98
+ - **Deviations from plan**: [nếu có, và lý do]
99
+ - **Tests passing**: [N/N]
100
+
101
+ ### [R.1] Review — [YYYY-MM-DD]
102
+ - **Agent**: Review Agent
103
+ - **Verdict**: [APPROVED | APPROVED_WITH_NOTES | CHANGES_REQUIRED]
104
+ - **Issues found**: [N] (≥3 required)
105
+ - **Routing decision**: [deploy | fix_and_re_review]
106
+
107
+ ---
108
+
109
+ ## 🔄 Live Progress (Streaming)
110
+
111
+ > Agent cập nhật section này **TRONG LÚC** đang làm việc — không đợi xong mới ghi.
112
+ > Lấy cảm hứng từ LangGraph streaming modes (values, updates, tokens).
113
+
114
+ ```
115
+ ## 🔄 [Agent Name] đang chạy — [Phase]
116
+
117
+ **Started**: [HH:MM] | **Elapsed**: [N phút]
118
+
119
+ ### Task Progress
120
+ - `[x]` T-001 Setup migration (2 phút)
121
+ - `[x]` T-002 Implement JWT (3 phút)
122
+ - `[/]` T-003 Login endpoint ← **ĐANG LÀM** (3 phút)
123
+ > Đang viết unit test cho edge case: expired token
124
+ - `[ ]` T-004 Refresh endpoint
125
+ - `[ ]` T-005 E2E test
126
+
127
+ **Tests**: 12/18 passing | **Coverage**: 67%
128
+
129
+ ### ⚠️ Alerts (Log trong lúc làm)
130
+ - T-003 phức tạp hơn plan dự kiến → có thể +15 phút
131
+ - Found edge case not in spec → ghi vào Open Questions
132
+ ```
133
+
134
+ > Sau khi agent hoàn thành, section này được clear và nội dung chuyển vào Execution Trace.
135
+
136
+ ---
137
+
138
+ ## ⚠️ Spec Change Log
139
+
140
+ > Ghi nhận thay đổi spec trong lúc pipeline đang chạy (Double-texting detection)
141
+
142
+ <!-- Append khi spec thay đổi -->
143
+
144
+ ---
145
+
146
+ ## 🚦 Concerns Tracker (Từ Master Check)
147
+
148
+ > Carry-forward từ validation-report.md — agent phải giải quyết khi implement
149
+
150
+ | ID | Mô tả | Trạng thái | Giải quyết bằng cách |
151
+ |----|-------|-----------|---------------------|
152
+ | W-001 | | `[ ] open` / `[x] resolved` | |
153
+
154
+ ---
155
+
156
+ ## 🔗 Links (Quick Reference)
157
+
158
+ - Spec: `.v-flow/features/NNN/spec.md`
159
+ - State: `.v-flow/features/NNN/.flow-state.yaml`
160
+ - Plan: `.v-flow/features/NNN/plan.md`
161
+ - Tasks: `.v-flow/features/NNN/tasks.md`
162
+ - Tests: `.v-flow/features/NNN/test-cases.md`
163
+ - Validation: `.v-flow/features/NNN/validation-report.md`
164
+
165
+ ---
166
+
167
+ *Session file — không phải Source of Truth. Spec.md mới là Single Source of Truth.*
@@ -0,0 +1,75 @@
1
+ # Spec Review Log — [Feature Name]
2
+
3
+ > **Mục đích**: Track lịch sử từng round của Dual BA loop
4
+ > **Điều kiện dừng**: 0 Critical + 0 Major (CONVERGED) hoặc Round ≥ 4 (ESCALATE)
5
+
6
+ ---
7
+
8
+ ## Thông tin chung
9
+
10
+ | Thuộc tính | Giá trị |
11
+ |-----------|---------|
12
+ | **Feature** | [NNN-ten-feature] |
13
+ | **BA Agent** | BA Agent |
14
+ | **BA Critic** | BA Critic Agent |
15
+ | **Max Rounds** | 4 |
16
+ | **Exit Criteria** | No Critical + No Major |
17
+ | **Bắt đầu** | YYYY-MM-DD |
18
+ | **Trạng thái** | 🔄 In Progress / ✅ CONVERGED / 🛑 ESCALATED |
19
+
20
+ ---
21
+
22
+ <!-- Thêm mỗi Round bên dưới theo template sau -->
23
+
24
+ ## Round [N] — [YYYY-MM-DD]
25
+
26
+ **Spec Version đầu round**: v[X.Y]
27
+ **Reviewer**: BA Critic Agent *(fresh context — không đọc round trước)*
28
+
29
+ ### Issues Found
30
+
31
+ | ID | Mức | Mô tả ngắn | Requirement liên quan |
32
+ |----|-----|------------|----------------------|
33
+ | R[N]-C001 | 🔴 Critical | [Mô tả vấn đề] | REQ-Exx |
34
+ | R[N]-M001 | 🟠 Major | [Mô tả vấn đề] | REQ-Uxx |
35
+ | R[N]-m001 | 🟡 Minor | [Mô tả vấn đề] | REQ-Sxx |
36
+
37
+ ### Thống kê Round [N]
38
+
39
+ | Mức | Số lượng |
40
+ |-----|---------|
41
+ | 🔴 Critical | 0 |
42
+ | 🟠 Major | 0 |
43
+ | 🟡 Minor | 0 |
44
+ | **Tổng** | **0** |
45
+
46
+ ### Verdict Round [N]
47
+
48
+ > ✅ **CONVERGED** — 0 Critical + 0 Major. Sẵn sàng chạy `/v.plan`
49
+ > ⚠️ **ITERATE** — Còn [N] Critical/Major. BA Agent cần cập nhật spec
50
+ > 🛑 **ESCALATE** — Đã đạt max_rounds = 4. Cần human review trước khi tiếp tục
51
+
52
+ ### BA Agent Response *(chỉ điền nếu ITERATE)*
53
+
54
+ **Spec Version mới**: v[X.Y+1]
55
+
56
+ | Issue ID | Hành động | Ghi chú |
57
+ |----------|-----------|---------|
58
+ | R[N]-C001 | ✅ Đã sửa | [Mô tả cách sửa] |
59
+ | R[N]-M001 | ✅ Đã sửa | [Mô tả cách sửa] |
60
+ | R[N]-m001 | ⏭️ Bỏ qua | [Lý do không sửa] |
61
+
62
+ ---
63
+
64
+ ## Convergence Summary *(cập nhật sau mỗi round)*
65
+
66
+ | Round | Spec Version | Critical | Major | Minor | Delta | Verdict |
67
+ |-------|-------------|---------|-------|-------|-------|---------|
68
+ | 1 | v1.0 | - | - | - | - | - |
69
+ | 2 | - | - | - | - | - | - |
70
+ | 3 | - | - | - | - | - | - |
71
+ | 4 | - | - | - | - | - | - |
72
+
73
+ **Kết quả cuối**: -
74
+ **Spec Version Final**: -
75
+ **Bước tiếp theo**: -
@@ -0,0 +1,229 @@
1
+ # Template: Specification (Đặc tả kỹ thuật)
2
+
3
+ > 📌 **Single Source of Truth** — Spec thắng khi có conflict với plan/tasks/tests.
4
+ > Được tạo bởi **BA Agent** từ yêu cầu đầu vào
5
+ > Feature: [TÊN FEATURE]
6
+
7
+ ## 1. Tổng quan
8
+
9
+ ### 1.1 Mô tả ngắn gọn
10
+ <!-- 1-2 câu mô tả feature này làm gì -->
11
+
12
+ ### 1.2 Động lực (Motivation)
13
+ <!-- Tại sao cần feature này? Giải quyết vấn đề gì? -->
14
+
15
+ ### 1.3 Actors (Đối tượng liên quan)
16
+ <!-- Ai sử dụng feature? Vai trò của họ? -->
17
+
18
+ | Actor | Mô tả | Quyền hạn |
19
+ |-------|-------|----------|
20
+ | | | |
21
+
22
+ ---
23
+
24
+ ## 2. Đặc tả Use Case chi tiết (Use Case Specification)
25
+
26
+ > Mỗi use case mô tả **một mục tiêu hoàn chỉnh** của một actor.
27
+ > Đánh mã `UC-01`, `UC-02`... để Plan / Test / Requirements tham chiếu.
28
+ > **Lặp lại block dưới đây cho mỗi use case** của feature.
29
+ > Mỗi UC có **Workflow (sơ đồ luồng)** trực quan hoá Main Flow + ngoại lệ; cuối mục có **Sequence Diagram tổng thể** thể hiện tương tác kỹ thuật của cả feature.
30
+
31
+ ### UC-01: [Tên use case — động từ + đối tượng]
32
+
33
+ | Thuộc tính | Nội dung |
34
+ |-----------|----------|
35
+ | **Mã** | UC-01 |
36
+ | **Mô tả tính năng** | <!-- 1-3 câu: use case này cho phép actor làm gì, đạt mục tiêu gì --> |
37
+ | **Tác nhân chính** | [Actor khởi tạo use case] |
38
+ | **Tác nhân phụ** | [Hệ thống ngoài / actor hỗ trợ — để trống nếu không có] |
39
+ | **Độ ưu tiên** | Cao / Trung bình / Thấp |
40
+ | **Tần suất sử dụng** | [VD: hàng ngày / mỗi lần đăng nhập / hiếm] |
41
+
42
+ **Điều kiện trước (Preconditions)** — phải đúng TRƯỚC khi use case bắt đầu:
43
+ - [ ] [VD: Actor đã đăng nhập và có quyền X]
44
+ - [ ] [VD: Tồn tại ít nhất 1 bản ghi trong danh sách]
45
+
46
+ **Điều kiện sau (Postconditions)** — đảm bảo SAU khi use case kết thúc thành công:
47
+ - [ ] [VD: Bản ghi mới được lưu và hiển thị trong danh sách]
48
+ - [ ] [VD: Audit log được ghi lại]
49
+
50
+ **Luồng sự kiện chính (Main Flow)** — happy path, mô tả hành động của tác nhân & phản ứng của hệ thống:
51
+
52
+ | # | Hành động của tác nhân | Phản ứng của hệ thống |
53
+ |---|------------------------|------------------------|
54
+ | 1 | [Actor làm gì] | [Hệ thống đáp lại thế nào] |
55
+ | 2 | | |
56
+ | 3 | | |
57
+
58
+ **Luồng ngoại lệ & thay thế (Exceptions / Alternative Flows)**:
59
+
60
+ | Mã | Tại bước | Điều kiện kích hoạt | Xử lý của hệ thống |
61
+ |----|----------|---------------------|---------------------|
62
+ | UC-01-E1 | B2 | [VD: Email sai định dạng] | [VD: Hiển thị lỗi inline, giữ nguyên dữ liệu form] |
63
+ | UC-01-A1 | B3 | [VD: Actor chọn "Lưu nháp"] | [VD: Lưu trạng thái draft, bỏ qua validate đầy đủ] |
64
+
65
+ **Workflow (sơ đồ luồng)** — trực quan hoá Main Flow + điểm rẽ nhánh + ngoại lệ trong **một** use case này:
66
+
67
+ ```mermaid
68
+ flowchart TD
69
+ Start([Bắt đầu — preconditions đạt]) --> S1[B1: Hành động của actor]
70
+ S1 --> D1{Điều kiện hợp lệ?}
71
+ D1 -->|Không| E1[UC-01-E1: Xử lý lỗi → quay lại]
72
+ E1 --> S1
73
+ D1 -->|Có| S2[B2: Hệ thống xử lý]
74
+ S2 --> D2{Kết quả?}
75
+ D2 -->|Lỗi| E2[UC-01-E2: Thông báo lỗi]
76
+ D2 -->|Thành công| Done([Kết thúc — postconditions đạt])
77
+ ```
78
+
79
+ > Quy ước: chữ nhật = bước `Bn` (khớp số ở bảng Main Flow), hình thoi = điểm rẽ nhánh/quyết định, node lỗi map đúng **mã ngoại lệ** ở bảng Exceptions (`UC-01-Ex`). Một flowchart cho mỗi UC; chi tiết validate/lỗi vẫn nằm ở bảng, flowchart chỉ làm rõ luồng.
80
+
81
+ **Yêu cầu đặc biệt (Special Requirements / NFR)** — phi chức năng gắn với use case này:
82
+ - **Hiệu năng**: [VD: Phản hồi < 2s với 95% request]
83
+ - **Bảo mật / Phân quyền**: [VD: Chỉ role Admin được thực hiện]
84
+ - **Khả dụng / UX**: [VD: Hỗ trợ điều hướng bàn phím, screen reader]
85
+ - **Tuân thủ / Audit**: [VD: Ghi log mọi thao tác ghi dữ liệu]
86
+
87
+ **Mô tả màn hình (Screen / UI)**:
88
+
89
+ | Màn hình | Mục đích | Thành phần chính | Trạng thái & điều hướng |
90
+ |----------|----------|------------------|--------------------------|
91
+ | [Tên màn hình] | [Dùng để làm gì] | [Các field, nút, bảng, thông báo...] | [Empty / Loading / Error / Success → đi đâu tiếp] |
92
+
93
+ **🖼️ UI Intent (contract giao diện)** — điền khi UC có giao diện. Đây là *carrier của contract UI* mà Plan / Prototype / Implement / Review bám theo:
94
+
95
+ | Thuộc tính | Nội dung |
96
+ |-----------|----------|
97
+ | **Mockup nguồn** | [`docs/PYC-xxx.pdf#p4` \| `figma:<link>` \| (không có)] — *con trỏ do BA ghi, KHÔNG trích ảnh* |
98
+ | **Ảnh đã ingest** | `ui/mockups/UC-NN-*.png` — *prototype `--from-mockup` dựng / hoặc human đặt vào (để trống ở spec)* |
99
+ | **Kế thừa trang** | [`/route` hiện có cần đồng bộ phong cách \| (màn hình mới)] |
100
+ | **Bố cục (layout)** | [mô tả vùng theo ý đồ mockup: header / body / footer / sidebar...] |
101
+ | **Mức ràng buộc** | `Định hướng` (khớp layout/thành phần/luồng) \| `Bắt buộc` (pixel) — *mặc định: Định hướng* |
102
+ | **Render đã chốt** | `ui/approved/UC-NN.*` — Prototype S.1.5 `--from-mockup` dựng qua `DESIGN.md` (để trống nếu chưa dựng) |
103
+
104
+ > ⚠️ Mockup quản **cấu trúc** (layout / thành phần / luồng). Style **bắt buộc** lấy từ `DESIGN.md` — KHÔNG copy màu/spacing/font trực tiếp từ ảnh.
105
+
106
+ ---
107
+
108
+ ### UC-02: [Tên use case]
109
+
110
+ <!-- Lặp lại đầy đủ cấu trúc như UC-01 cho mỗi use case còn lại -->
111
+
112
+ ---
113
+
114
+ ### Sequence Diagram — Tương tác tổng thể (feature)
115
+
116
+ > **Một** sequence diagram end-to-end cho **cả feature** — thể hiện tương tác **User – FE – BE – External/Partner** theo thời gian (KHÔNG đưa Database object).
117
+ > Vẽ **luồng thành công (happy path)** làm chính; nhánh phụ / secondary use-case dùng `alt` / `opt`. Validate & xử lý lỗi chi tiết để ở **Workflow từng UC** + bảng Exceptions — **không lặp lại** ở đây.
118
+ > Quy ước (theo skill `ba-sequence-spec`): alias participant **ASCII** (`User`/`FE`/`BE`/`Partner`), mỗi message **1 dòng có đánh số**, không dùng `'` `"` hay `\n`.
119
+
120
+ ```mermaid
121
+ sequenceDiagram
122
+ participant User
123
+ participant FE as Frontend
124
+ participant BE as Backend
125
+ participant Ext as External
126
+
127
+ User->>FE: 1. [Hành động khởi tạo — UC-01]
128
+ FE->>BE: 2. [Gọi API chính, vd POST /api/...]
129
+ BE->>Ext: 3. [Tương tác hệ thống ngoài — bỏ nếu không có]
130
+ Ext-->>BE: 4. [Kết quả từ hệ thống ngoài]
131
+ BE-->>FE: 5. [Trả kết quả]
132
+ alt [Trường hợp chính — thành công]
133
+ FE-->>User: 6. [Hiển thị kết quả / điều hướng]
134
+ else [Nhánh phụ — UC-02 / điều kiện khác]
135
+ FE-->>User: 6'. [Phản hồi nhánh phụ]
136
+ end
137
+ ```
138
+
139
+ > 🔗 **Mapping:** mỗi nhánh chính của diagram ứng với một use-case (UC-01, UC-02...); chi tiết từng bước nằm ở **Workflow** của UC tương ứng. Đặc tả API (Request/Response/Error/Status) thuộc `plan.md` (§4 API Design / Data Contracts), không lặp ở spec.
140
+
141
+ ---
142
+
143
+ ## 3. Requirements (Yêu cầu — Ký pháp EARS)
144
+
145
+ ### 3.1 Yêu cầu phổ quát (Ubiquitous)
146
+ <!-- Hệ thống phải <action> -->
147
+ - **REQ-U01**: Hệ thống phải [yêu cầu]
148
+ - **REQ-U02**: ...
149
+
150
+ ### 3.2 Yêu cầu theo sự kiện (Event-driven)
151
+ <!-- Khi <trigger>, hệ thống phải <action> -->
152
+ - **REQ-E01**: Khi [sự kiện], hệ thống phải [hành động]
153
+ - **REQ-E02**: ...
154
+
155
+ ### 3.3 Yêu cầu theo trạng thái (State-driven)
156
+ <!-- Trong khi <state>, hệ thống phải <action> -->
157
+ - **REQ-S01**: Trong khi [trạng thái], hệ thống phải [hành động]
158
+ - **REQ-S02**: ...
159
+
160
+ ### 3.4 Yêu cầu có điều kiện (Optional)
161
+ <!-- Nếu <condition>, hệ thống phải <action> -->
162
+ - **REQ-O01**: Nếu [điều kiện], hệ thống phải [hành động]
163
+ - **REQ-O02**: ...
164
+
165
+ ---
166
+
167
+ ## 4. Acceptance Criteria (Tiêu chí chấp nhận)
168
+
169
+ > Mỗi tiêu chí có **mã `AC-NN`** (đánh số toàn spec) để task `Done khi` tham chiếu chính xác, và Master Check / validator cross-check coverage (**mọi AC phải có ≥1 task**). Mỗi REQ cần ≥1 AC.
170
+
171
+ | Mã | Use Case | Requirement | Tiêu chí | Cách kiểm tra |
172
+ |----|----------|------------|---------|---------------|
173
+ | AC-01 | UC-01 | REQ-U01 | [Tiêu chí cụ thể] | [Cách verify] |
174
+ | AC-02 | UC-01 | REQ-E01 | | |
175
+
176
+ ---
177
+
178
+ ## 5. Ràng buộc & Giả định
179
+
180
+ ### 5.1 Ràng buộc (Constraints)
181
+ - [ ] [Ràng buộc kỹ thuật, business...]
182
+
183
+ ### 5.2 Giả định (Assumptions)
184
+ - [ ] [Các giả định đang áp dụng]
185
+
186
+ ### 5.3 Ngoài phạm vi (Out of Scope)
187
+ - [ ] [Những gì KHÔNG thuộc feature này]
188
+
189
+ ---
190
+
191
+ ## 6. Rủi ro & Phụ thuộc
192
+
193
+ | Rủi ro / Phụ thuộc | Mức độ | Giải pháp |
194
+ |--------------------|--------|----------|
195
+ | | Cao/Trung/Thấp | |
196
+
197
+ ---
198
+
199
+ ## 7. Status (Single Source of Truth Tracker)
200
+
201
+ > ⚠️ Mọi Agent đọc file này PHẢI kiểm tra Status trước khi hành động.
202
+ > Khi spec thay đổi, **BA Agent** phải bump `Spec Version` và reset trạng thái các artifact
203
+
204
+ | Thông tin | Giá trị |
205
+ |-----------|--------|
206
+ | **Spec Version** | v1.0 |
207
+ | **Trạng thái** | `Draft` / `Reviewed` / `Approved` |
208
+ | **Người approve** | [Tên] |
209
+ | **Ngày approve** | [YYYY-MM-DD] |
210
+
211
+ ### Artifact Sync Status
212
+
213
+ > Sau khi spec thay đổi, cập nhật bảng này. ❌ = cần sync lại, ✅ = đã sync, N/A = chưa tạo
214
+
215
+ | Artifact | Synced to Spec | Trạng thái | Ghi chú |
216
+ |----------|---------------|------------|--------|
217
+ | `ui/mockups/` | v0.0 | N/A | Ảnh mockup — prototype/human đặt (nếu có UI) |
218
+ | `ui/approved/` | v0.0 | N/A | Render đã chốt — Prototype `--from-mockup` (nếu có UI) |
219
+ | `plan.md` | v0.0 | N/A | Chưa tạo |
220
+ | `tasks.md` | v0.0 | N/A | Chưa tạo |
221
+ | `test-cases.md` | v0.0 | N/A | Chưa tạo |
222
+ | `validation-report.md` | v0.0 | N/A | Chưa tạo |
223
+
224
+ ### Changelog
225
+
226
+ | Version | Ngày | Thay đổi | Người thực hiện |
227
+ |---------|------|----------|------------------|
228
+ | v1.0 | [YYYY-MM-DD] | Tạo mới | BA Agent |
229
+
@@ -0,0 +1,101 @@
1
+ # Template: Sprint Status — Bảng theo dõi Sprint
2
+
3
+ > Được tạo bởi **Sprint Planning Agent**
4
+ > Sprint: [N]
5
+ > Ngày bắt đầu: [YYYY-MM-DD]
6
+ > Ngày dự kiến kết thúc: [YYYY-MM-DD]
7
+
8
+ ---
9
+
10
+ ## Sprint Goal
11
+
12
+ > [1-2 câu mô tả mục tiêu sprint]
13
+
14
+ ---
15
+
16
+ ## 1. Sprint Backlog
17
+
18
+ ### Feature: [NNN-feature-name]
19
+
20
+ | Task ID | Mô tả | Priority | Estimation | Status | Assignee |
21
+ |---------|--------|:--------:|:----------:|:------:|----------|
22
+ | T-001 | [mô tả] | Must | [N]h | [ ] / [/] / [x] | [AI/Human] |
23
+ | T-002 | [mô tả] | Should | [N]h | [ ] | [AI/Human] |
24
+ | T-003 | [mô tả] | Nice | [N]h | [ ] | [AI/Human] |
25
+
26
+ ### Feature: [NNN-feature-name-2] *(nếu multi-feature sprint)*
27
+
28
+ | Task ID | Mô tả | Priority | Estimation | Status | Assignee |
29
+ |---------|--------|:--------:|:----------:|:------:|----------|
30
+ | T-001 | [mô tả] | Must | [N]h | [ ] | [AI/Human] |
31
+
32
+ ---
33
+
34
+ ## 2. Capacity Planning
35
+
36
+ | Metric | Giá trị |
37
+ |--------|--------|
38
+ | Tổng tasks | [N] |
39
+ | Must-have tasks | [N] |
40
+ | Should-have tasks | [N] |
41
+ | Nice-to-have tasks | [N] |
42
+ | Ước tính tổng | [N] giờ |
43
+ | Capacity khả dụng | [N] giờ |
44
+ | Utilization | [XX]% |
45
+
46
+ ---
47
+
48
+ ## 3. Cross-Feature Dependencies
49
+
50
+ ```mermaid
51
+ graph LR
52
+ F001[001-login] -->|auth API| F002[002-dashboard]
53
+ F002 -->|user data| F003[003-profile]
54
+ ```
55
+
56
+ | Dependency | From | To | Status | Blocker? |
57
+ |-----------|------|-----|:------:|:--------:|
58
+ | Auth API | 001-login | 002-dashboard | ✅ / ❌ | ⚠️ / ✅ |
59
+
60
+ ---
61
+
62
+ ## 4. Daily Progress
63
+
64
+ ### Day [N] — [YYYY-MM-DD]
65
+
66
+ | Feature | Tasks Done | Total | Progress | Blockers |
67
+ |---------|:----------:|:-----:|:--------:|----------|
68
+ | 001 | [N] | [N] | [XX]% | [none / mô tả] |
69
+ | 002 | [N] | [N] | [XX]% | [none / mô tả] |
70
+
71
+ ---
72
+
73
+ ## 5. Sprint Risks
74
+
75
+ | Risk | Probability | Impact | Mitigation |
76
+ |------|:-----------:|:------:|-----------|
77
+ | [mô tả risk] | High/Med/Low | High/Med/Low | [plan] |
78
+
79
+ ---
80
+
81
+ ## 6. Sprint Summary *(điền khi kết thúc sprint)*
82
+
83
+ | Metric | Planned | Actual |
84
+ |--------|:-------:|:------:|
85
+ | Tasks completed | [N] | [N] |
86
+ | Story points | [N] | [N] |
87
+ | Velocity | — | [N] pts/sprint |
88
+ | Carry-over tasks | — | [N] |
89
+
90
+ ### Sprint Health
91
+
92
+ | Indicator | Status |
93
+ |-----------|:------:|
94
+ | Goal achieved | ✅ / ❌ |
95
+ | All Must-have done | ✅ / ❌ |
96
+ | No critical blockers | ✅ / ❌ |
97
+ | Team satisfaction | [1-5]/5 |
98
+
99
+ ---
100
+
101
+ > **Bước tiếp theo**: `/v.retrospective --sprint [N]`