@longph2102/v-flow 1.5.0

package/skills/plan/architecture-designer/gotchas.md

@@ -0,0 +1,45 @@
+# Gotchas — Architecture Designer
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **Over-engineering** — Tạo abstraction layer cho feature đơn giản.
+   - **Signal**: Interface với chỉ 1 implementation, Factory cho 1 class.
+   - **Fix**: YAGNI — design cho REQ hiện tại, không cho REQ tương lai.
+
+2. ❌ **Ignore No-Go Zones** — Thiết kế modify legacy code mà không kiểm tra context.md.
+   - **Hậu quả**: Implement Agent bị block ở B.1, phải quay lại redesign.
+   - **Fix**: Check TRƯỚC khi design — tạo adapter nếu cần interact No-Go Zone.
+
+3. ❌ **Vague file paths** — "tạo component ở src/somewhere".
+   - **Hậu quả**: Implement Agent tự quyết path → inconsistent structure.
+   - **Fix**: Mỗi file path PHẢI chính xác: `src/features/auth/data/auth_repository.dart`.
+
+4. ❌ **Missing error architecture** — Design chỉ có happy path.
+   - **Hậu quả**: Error handling ad-hoc, inconsistent response format.
+   - **Fix**: Plan PHẢI có Error Architecture section (types, flow, response format).
+
+5. ❌ **Coupling quá chặt** — Component A import trực tiếp B, B import trực tiếp C.
+   - **Fix**: Dependency injection, interface tại boundary.
+
+6. ❌ **Circular dependency** — A → B → A hoặc A → B → C → A.
+   - **Signal**: Import từ sibling module, shared mutable state.
+   - **Fix**: Extract shared logic sang _shared module hoặc event-based communication.
+
+7. ❌ **Design không align constitution** — Plan nói Repository pattern nhưng constitution nói Active Record.
+   - **Check**: Đọc constitution trước khi design. Design PHẢI confirm pattern alignment.
+
+8. ❌ **Thiếu REQ traceability** — Component tồn tại mà không trace về REQ nào.
+   - **Rule**: Mỗi component trong plan PHẢI reference ≥1 REQ-xxx.
+
+---
+
+## Edge Cases
+
+- ✅ Feature chỉ có 1-2 REQ → Plan đơn giản là OK. Không cần 8 sections nếu feature nhỏ.
+- ✅ Constitution chưa có → Cảnh báo human, dùng industry best practices, ghi `[⚠️ No constitution]`.
+- ✅ Greenfield (không có context.md) → Skip No-Go Zone checks, design tự do hơn.

package/skills/plan/task-breakdown/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: task-breakdown
+description: "Hướng dẫn Plan Agent chia tasks từ plan.md. Agent PHẢI đọc skill này sau khi hoàn thành architecture design. Đảm bảo mọi task trace về REQ-xxx và có annotations đúng."
+trigger: "Khi Plan Agent tạo tasks.md từ plan.md"
+phase: "B.0a"
+used_by:
+  - /v.plan
+hooks:
+  pre_breakdown: "Load plan.md + spec.md → extract REQ-xxx list và component list"
+  post_breakdown: "Verify: mỗi REQ có task, mỗi task có REQ, annotations đúng"
+---
+
+# Task Breakdown — Chia Tasks Có Traceability
+
+> ⚠️ Đây là **Skill bắt buộc** cho Plan Agent khi tạo tasks.md.
+> Mỗi task PHẢI trace về REQ-xxx. Task không có REQ = task thừa.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi chia tasks.
+> → Xem `examples/good/` cho mẫu tasks.md chuẩn — và `examples/bad/` cho anti-pattern (đối chứng).
+> → Xem `config.json` để customize (max_task_size, annotation_rules).
+
+---
+
+## Khi nào KHÔNG cần task breakdown chi tiết
+
+- Quick Fix (`/v.quickfix`) — 1-2 tasks trực tiếp từ spec
+- Hotfix (`/v.hotfix`) — 1 task focus fix, 1 task test
+- Task đã rõ ràng (chỉ 1-2 REQ, 1 component)
+
+> **Lite profile**: `quickfix`/`hotfix` → được bỏ Dependency Graph / Execution Schedule nếu chỉ 1–2 task; nhưng mỗi task VẪN cần Type + `Done khi` (AC) + block TDD.
+
+---
+
+## Task Annotations — Hệ Thống Nhãn
+
+> 💡 Annotations giúp Implement Agent biết THỨ TỰ và CÁCH implement.
+
+| Annotation | Ý nghĩa | Ví dụ khi dùng |
+|-----------|---------|-----------------|
+| `[ENTRYPOINT]` | Bắt đầu từ task này | Task đầu tiên, không dependency |
+| `[PARALLEL]` | Có thể làm song song với task khác | 2 tasks không share code |
+| `[GATE]` | DỪNG chờ human review | Task modify sensitive area |
+| `[CRITICAL]` | Ưu tiên cao nhất | Core business logic |
+| `[RISKY]` | Cần test kỹ hơn | Touch legacy code, complex logic |
+| `[DEPENDS: T-xxx]` | Chỉ start khi T-xxx xong | Data model trước, API sau |
+| `[SPIKE]` | Điều tra/POC — chưa biết cách làm; output là quyết định, time-boxed | Đo benchmark 2 lib trước khi chọn |
+| `[CLARIFY]` | Còn mơ hồ — Implement Agent hỏi human trước khi code | Spec thiếu business rule, edge case chưa rõ |
+
+### Quy tắc annotation
+
+1. Mỗi task list PHẢI có đúng 1 `[ENTRYPOINT]` (validator enforce — không 0, không >1)
+2. `[GATE]` tasks phải DỪNG — Implement Agent chờ human approve
+3. `[DEPENDS]` tạo DAG — KHÔNG được có circular dependency (validator detect cycle + dangling ref)
+4. `[PARALLEL]` chỉ khi tasks THỰC SỰ independent (không share state)
+5. `[CLARIFY]` khi còn điểm mơ hồ — kèm **Câu hỏi mở**; thà hỏi còn hơn đoán sai
+6. `[SPIKE]` khi cách làm chưa rõ — điều tra TRƯỚC, kết quả feed lại plan; đứng trước task phụ thuộc nó. Liên kết với mã rủi ro plan §7 (vd `Risk: R-01`)
+
+> Mẫu `[SPIKE]` + `[CLARIFY]` + chia milestone: `examples/good/spike-clarify-tasks.md`.
+
+---
+
+## Task Type — Loại thay đổi (gắn kèm annotations)
+
+> Annotations nói **THỨ TỰ**; Task Type nói task đụng **BỀ MẶT nào** → quyết định chi tiết bắt buộc trong body.
+
+| Type | Bề mặt | Body task PHẢI có |
+|------|--------|-------------------|
+| `[UI]` | Màn hình, component | Màn hình, widget/component, trạng thái, token `DESIGN.md` |
+| `[API]` | Endpoint | Method+path, field request/response thêm/đổi |
+| `[DB]` | Schema, migration | Bảng (new/alter), cột (tên/kiểu/null/default), **DDL up+down (câu lệnh thật)**, rollback |
+| `[LOGIC]` | Service, use case | Hàm/class, hiện trạng → mong muốn |
+| `[REFACTOR]` | Cấu trúc (behavior giữ nguyên) | Phạm vi, đảm bảo test cũ vẫn pass |
+| `[TEST]` | Test | Loại test, kịch bản |
+
+> 1 task có thể có nhiều type nếu cùng 1 component (vd `[API]` + `[DB]`); nếu tách được nên tách để dễ review.
+
+---
+
+## Đặc Thù Và Quy Ước
+
+### 1. Task Granularity vs Specificity
+
+> ⚠️ **Granularity ≠ Specificity**. Granularity = **KÍCH THƯỚC** task (≈ 1 component). Specificity = **ĐỘ CHI TIẾT bên trong** task (vị trí symbol, hiện trạng → mong muốn). Task đúng kích thước NHƯNG vẫn phải chi tiết bên trong — đây là chỗ hay bị bỏ sót khiến dev phải hỏi lại.
+
+**Granularity — kích thước:**
+- Quá lớn (❌): "T-001: Implement login feature" → quá rộng, không biết khi nào xong.
+- Quá nhỏ (❌): "T-001: Create file login.dart" → micromanage từng file.
+- Vừa đúng (✅): "T-001: Implement LoginUseCase — validate credentials, call repository" → 1 component, 1-2 REQs.
+- **Rule of thumb**: 1 task ≈ 1 component ≈ 1-3 REQs ≈ 1 TDD cycle.
+
+**Specificity — task SỬA code có sẵn** (granularity component, nhưng body PHẢI cụ thể):
+- Vị trí (symbol): hàm / class / widget / endpoint
+- Hiện trạng → Mong muốn
+- ❌ "T-0X: Update ProductScreen" → dev không biết sửa gì.
+- ✅ "T-0X: `ProductScreen.build()` — hiện render list phẳng → thêm `FilterBar` + cột `Trạng thái` (badge); filter theo status."
+
+### 2. Dependency Graph
+
+Tasks phải có dependency rõ ràng:
+```
+T-001 [ENTRYPOINT] [CRITICAL]: Data models
+T-002 [DEPENDS: T-001]: Repository implementation
+T-003 [DEPENDS: T-001] [PARALLEL]: API service (parallel với T-002)
+T-004 [DEPENDS: T-002, T-003]: Use case layer
+T-005 [DEPENDS: T-004]: UI/Presentation
+T-006 [DEPENDS: T-005] [GATE]: Integration test + human review
+```
+
+**Contract-first** (khi có cả `[UI]` và `[API]`): task chốt **data model + API contract** đứng sớm (entrypoint hoặc dependency chung); FE và BE đều `[DEPENDS]` vào nó rồi mới `[PARALLEL]`. Không để FE/BE chạy song song khi contract chưa đóng băng → tránh đoán field lệch nhau.
+
+### 3. REQ ↔ Task Traceability
+
+```markdown
+Mỗi task PHẢI có:
+  **Gắn với**: REQ-xxx, REQ-yyy    ← trace ngược về spec
+  **Component**: LoginUseCase       ← trace về plan
+  **Test cases**: TC-xxx, TC-yyy    ← trace về test-cases.md (sau B.0b)
+```
+
+### 4. Complexity Tiers (thay cho ước tính giờ)
+
+> Executor là AI agent → "mất bao nhiêu giờ" không còn ý nghĩa. Gắn mỗi task một tier S/M/L để biết task nào cần tách / cần soi kỹ.
+
+| Tier | Nghĩa | Dấu hiệu điển hình |
+|:----:|-------|--------------------|
+| **S** | Nhỏ, đường đi rõ | Data model/entity, 1 endpoint đơn giản, 1 widget thuần — ~1 TDD cycle |
+| **M** | Vừa | Use case có validation + error, repository + mapping, UI nhiều trạng thái — 2–3 TDD cycle |
+| **L** | Lớn | Logic nhiều edge case, tích hợp 3rd-party, đụng nhiều file liên quan |
+
+- Task mức **L** → cân nhắc tách nhỏ. Không tách được → gắn `[RISKY]` + nêu lý do.
+- **Sizing tổng** (quyết định chia milestone): quy đổi **S=1, M=2, L=4** điểm → Σ. Tổng **> ~24 điểm** (hoặc **> 20 task**) → đề xuất tách thành nhiều phase/milestone thay vì 1 feature khổng lồ.
+
+### 5. Calibration từ lịch sử
+
+Trước khi chia task cho feature mới, đọc `task-history.log` (+ `plan-history.log`) của feature tương tự để hiệu chỉnh:
+- Feature cùng loại thường ~bao nhiêu task? phân bố Complexity (S/M/L) ra sao?
+- Rủi ro / `[RISKY]` nào hay lặp lại → chủ động gắn `[SPIKE]`/`[RISKY]` sớm.
+- Sau khi xong, ghi 1 dòng vào `task-history.log` (format ở `config.json` → `memory`) để feature sau calibrate tiếp.
+
+> 📒 Log này là **plaintext do agent tự ghi/đọc** (không có CLI enforce). Consumer chính là `/v.retrospective` — Retrospective Agent đọc `plan-history.log`/`task-history.log` để rút xu hướng giữa các feature.
+
+---
+
+## Task Template
+
+> Dùng **đúng một** schema này — trùng với `.v-flow/templates/tasks-template.md` (nguồn chuẩn). Task ID `T-NNN`, Complexity S/M/L (không ghi giờ).
+>
+> **3 trường test/done bổ sung nhau** (không thay thế nhau): `Done khi` = bám **AC-NN spec §4** (ghi rõ mã AC, định nghĩa "xong" nghiệp vụ) · `Test liên quan: TC-xx` = **test chính thức** ở `test-cases.md` (Test Agent tạo B.0b) · `TDD` = checklist **Red→Green** ngay trong task. Implement chạy theo TDD → mỗi task `[LOGIC]`/`[UI]`/`[API]`/`[DB]` nên có block `TDD`.
+
+```markdown
+#### T-NNN: {Tên task cụ thể} `[TYPE]` `[ANNOTATIONS]`
+- **Mô tả**: {Mục tiêu — 1 câu}
+- **Files**: `path/to/file.ext`
+- **Vị trí (symbol)**: `Class.method()` / `Widget` / `METHOD /path`  ← task SỬA
+- **Thay đổi cụ thể**:
+  - Hiện trạng: {behavior hiện tại — bỏ trống nếu tạo mới}
+  - Mong muốn: {kết quả sau khi xong}
+  - Các bước: 1) … 2) …
+- {Block theo Type — [UI]: màn hình/component/trạng thái/token · [API]: endpoint+field · [DB]: bảng+cột+migration+rollback}
+- **Dependency**: T-{M} (hoặc Không)
+- **REQ / UC mapping**: REQ-{xxx} (UC-{xx})
+- **Done khi**: đáp ứng **AC-NN** tương ứng trong spec §4 (ghi rõ mã, không chỉ "test pass")
+- **Test liên quan**: TC-{xx}
+- **TDD** (Red→Green) — viết test TRƯỚC, rồi code cho pass:
+  - [ ] Test: {kịch bản 1 — chạy fail trước khi có code}
+  - [ ] Test: {kịch bản 2}
+  - [ ] Impl: {code tối thiểu để các test trên pass}
+- **Complexity**: S / M / L
+- **Câu hỏi mở** (chỉ khi `[CLARIFY]`): {điều cần làm rõ}
+- **Trạng thái**: [ ]
+```
+
+**Checklist "done" gợi ý** (bám theo Acceptance Criteria của REQ trong spec, không chỉ "tests pass"):
+- [ ] Unit tests written + pass (TDD Red → Green)
+- [ ] Đáp ứng AC cụ thể của REQ liên quan
+- [ ] Code follows constitution naming/patterns
+- [ ] No-Go Zones not violated
+- [ ] _session.md updated
+
+---
+
+## Self-Review — soi lại danh sách task bằng "mắt mới" (bắt buộc)
+
+> 💡 Chia xong → đọc lại tasks.md đối chiếu plan + spec, bắt gap ngữ nghĩa TRƯỚC khi giao Implement Agent. Checklist tự chạy (không subagent); KHÔNG đẩy validator sang semantics.
+
+1. **Phủ AC/REQ 2 chiều**: mỗi `AC-NN` & `REQ-xxx` của spec được ≥1 task phủ (thiếu = gap); **và** mỗi task trace ngược về ≥1 REQ (task không REQ = task thừa → bỏ).
+2. **Quét placeholder**: không còn task mơ hồ kiểu "Update X"/"xử lý sau" — task SỬA phải có `Vị trí` + `Hiện trạng → Mong muốn`.
+3. **Nhất quán ký hiệu giữa các task**: cùng một symbol gọi cùng một tên qua mọi task. `clearLayers()` ở T-003 nhưng `clearFullLayers()` ở T-007 = bug; `users` ở task này mà `user` ở task kia = bug.
+4. **DAG hợp lệ**: đúng 1 `[ENTRYPOINT]`; `[DEPENDS]` không vòng lặp, không trỏ task không tồn tại; task `[PARALLEL]` thật sự không share file/state.
+5. **Mỗi code task có block TDD + `Done khi` (AC-NN)**: không task `[LOGIC]/[UI]/[API]/[DB]` nào thiếu Red→Green hoặc thiếu mã AC cụ thể.
+
+Thấy lỗi → sửa tại chỗ. Đây là tầng bắt sớm; validator lint cấu trúc, Master Check soi ngữ nghĩa sâu hơn ở hạ nguồn.
+
+---
+
+## V-Flow Integration Points
+
+- **plan.md** (B.0a) → Input: component list, file structure
+- **spec.md** (S.1) → Input: REQ-xxx list cho traceability
+- **test-cases.md** (B.0b) → Test Agent sẽ map TC → TASK
+- **_session.md** → Ghi task dependency rationale
+- **Implement Agent** → Consumer: follow task order + annotations
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho lỗi phổ biến khi chia tasks — cập nhật liên tục.

package/skills/plan/task-breakdown/config.json

@@ -0,0 +1,26 @@
+{
+  "setup_questions": [
+    {
+      "id": "split_above_complexity",
+      "question": "Tách task khi vượt mức complexity nào?",
+      "options": ["M", "L"],
+      "default": "L",
+      "description": "Task vượt mức này sẽ được suggest split thành nhiều task nhỏ hơn. Dùng tier S/M/L thay cho ước tính giờ."
+    },
+    {
+      "id": "require_gate_for_legacy",
+      "question": "Bắt buộc [GATE] cho task modify legacy code?",
+      "type": "boolean",
+      "default": true
+    }
+  ],
+  "hooks": {
+    "pre_breakdown": "Load plan.md → extract component list + REQ mapping",
+    "post_breakdown": "Verify: mỗi REQ có task, no circular DEPENDS, exactly 1 ENTRYPOINT"
+  },
+  "memory": {
+    "file": "task-history.log",
+    "format": "[date] | [feature] | [total_tasks] | [entry_points] | [gates] | [parallel_groups]",
+    "purpose": "Track task planning patterns — dùng cho /v.retrospective"
+  }
+}

package/skills/plan/task-breakdown/examples/bad/vague-tasks.md

@@ -0,0 +1,77 @@
+# Ví dụ XẤU — Tasks mơ hồ (KHÔNG làm theo)
+
+> ⚠️ Đây là **anti-pattern**. Đối chiếu với `examples/good/tasks-login-feature.md`.
+> Mỗi khối minh họa một lỗi trong `gotchas.md` hoặc thiếu trường bắt buộc trong schema.
+
+---
+
+## ❌ 1. Task quá lớn + thiếu ENTRYPOINT
+
+```markdown
+#### T-001: Implement toàn bộ feature login `[LOGIC]`
+- **Mô tả**: làm hết login.
+```
+
+**Sai vì**: 1 task ôm cả feature → không biết khi nào xong, test khó viết; cả list không có `[ENTRYPOINT]`.
+**Sửa**: tách theo component (model → repo → usecase → UI), đúng 1 task `[ENTRYPOINT]`. Rule: 1 task ≈ 1 component ≈ 1–3 REQ ≈ 1 TDD cycle.
+
+---
+
+## ❌ 2. Thiếu trường bắt buộc (Done khi / Complexity / Type / TDD)
+
+```markdown
+#### T-002: Sửa màn product
+- **Files**: lib/ui/product_page.dart
+```
+
+**Sai vì**: không có Task Type, không Complexity, không `Done khi` (bám AC), không block TDD → validator cảnh báo, dev phải hỏi lại "xong là sao?".
+**Sửa**: gắn `[UI]` · `Complexity: M` · `Done khi: AC REQ-xxx spec §4` · block `TDD` (Red→Green).
+
+---
+
+## ❌ 3. Sửa code chung chung (thiếu Vị trí + Hiện trạng→Mong muốn)
+
+```markdown
+#### T-003: Update ProductScreen `[UI]`
+- **Mô tả**: cải thiện màn product.
+```
+
+**Sai vì**: "cải thiện" → không rõ sửa symbol nào, từ gì sang gì.
+**Sửa**: Vị trí `ProductScreen.build()` · Hiện trạng: render list phẳng → Mong muốn: thêm `FilterBar` + cột `Trạng thái` (badge), filter theo status.
+
+---
+
+## ❌ 4. Fake `[PARALLEL]` (2 task cùng sửa 1 file)
+
+```markdown
+#### T-004: Thêm filter `[UI]` `[PARALLEL]`
+- **Files**: lib/ui/product_page.dart
+#### T-005: Thêm cột trạng thái `[UI]` `[PARALLEL]`
+- **Files**: lib/ui/product_page.dart
+```
+
+**Sai vì**: hai task song song nhưng sửa **cùng** `product_page.dart` → xung đột.
+**Sửa**: gộp thành 1 task, hoặc cho 1 task `[DEPENDS]` task kia (tuần tự). Validator sẽ cảnh báo "Fake [PARALLEL]".
+
+---
+
+## ❌ 5. Circular dependency / thiếu REQ
+
+```markdown
+#### T-006: A `[DEPENDS: T-007]`   (không REQ)
+#### T-007: B `[DEPENDS: T-006]`   (không REQ)
+```
+
+**Sai vì**: T-006↔T-007 vòng lặp → không bao giờ chạy được; cả hai không trace REQ → task thừa.
+**Sửa**: tách logic chung sang T-000, cả hai `[DEPENDS: T-000]`; mỗi task gắn REQ-xxx.
+
+---
+
+## ❌ 6. "Done" = chỉ test pass
+
+```markdown
+- **Done khi**: tất cả test pass.
+```
+
+**Sai vì**: test pass ≠ đáp ứng nghiệp vụ; có thể test sai/thiếu.
+**Sửa**: `Done khi` bám **Acceptance Criteria** cụ thể trong spec §4 (vd: "nút submit disable khi form invalid + snackbar khi 401"). TDD là *cách* làm, AC là *đích*.

package/skills/plan/task-breakdown/examples/good/spike-clarify-tasks.md

@@ -0,0 +1,66 @@
+# Ví dụ — Tasks có `[SPIKE]` + `[CLARIFY]` + chia milestone
+
+> Minh hoạ 3 pattern ít được demo: **`[SPIKE]`** (điều tra, output = quyết định), **`[CLARIFY]`** (chặn đoán mò), và **chia milestone** khi sizing lớn. Schema task khớp `.v-flow/templates/tasks-template.md`.
+
+## Task Overview
+
+| Tổng tasks | `[SPIKE]` | `[CLARIFY]` | Sizing (Σ điểm) | Milestone |
+|:----------:|:---------:|:-----------:|:---------------:|:---------:|
+| 9 | 1 | 1 | 26 (>24 → tách) | M1, M2 |
+
+> Σ 26 điểm > 24 → tách **M1** (chốt nền + spike) và **M2** (tích hợp). Xem skill task-breakdown §4 (sizing).
+
+---
+
+## Milestone 1 — Nền tảng + điều tra
+
+#### T-001: SPIKE — chọn thư viện hàng đợi `[SPIKE]` `[ENTRYPOINT]`
+- **Mô tả**: Chưa rõ dùng BullMQ hay native SQS cho job retry — điều tra trước khi thiết kế.
+- **Files**: `docs/spikes/queue-choice.md` (output là **kết luận**, KHÔNG phải code production)
+- **Thay đổi cụ thể**:
+  - Mong muốn: benchmark 2 lib (throughput, retry, ops), chốt 1 + ghi lý do vào `_session.md`.
+  - Các bước: 1) POC 2 lib 2) đo p95 + chi phí vận hành 3) ra quyết định.
+- **Dependency**: Không
+- **REQ / UC mapping**: REQ-E03 (UC-02)
+- **Done khi**: có **quyết định** lib + lý do; nếu đổi hướng thiết kế → đề xuất quay lại `/v.plan` (AC-07, spec §4)
+- **Risk**: R-01 (plan §7) — chọn sai lib → rework tích hợp
+- **Complexity**: M (time-boxed 1 ngày)
+- **Trạng thái**: [ ]
+
+> `[SPIKE]`: output là **kết luận/quyết định**, time-boxed, đứng TRƯỚC task phụ thuộc nó. KHÔNG ép ra code production.
+
+#### T-002: Schema job table `[DB]` `[DEPENDS: T-001]`
+- **Mô tả**: Bảng lưu job + trạng thái retry.
+- **Files**: `migrations/20260602_create_jobs.sql`
+- **[DB]**: `jobs` NEW · cột `id, type, payload, status, attempts, created_at` · index `idx_jobs_status`
+- **DDL**: `CREATE TABLE jobs (...); CREATE INDEX idx_jobs_status ON jobs(status);` (up) / `DROP TABLE jobs;` (down)
+- **Dependency**: T-001
+- **REQ / UC mapping**: REQ-E03 (UC-02)
+- **Done khi**: bảng + index tồn tại, rollback chạy (AC-08, spec §4)
+- **TDD** (Red→Green):
+  - [ ] Test: cột + index tồn tại sau migration
+  - [ ] Impl: DDL
+- **Complexity**: S
+- **Trạng thái**: [ ]
+
+#### T-003: Business rule tính phí trễ hạn `[LOGIC]` `[CLARIFY]` `[DEPENDS: T-002]`
+- **Mô tả**: Tính phí khi job quá hạn — nhưng spec chưa rõ mốc tính.
+- **Files**: `src/billing/late_fee.ts`
+- **Thay đổi cụ thể**:
+  - Mong muốn: hàm `lateFee(job)` theo đúng business rule (chốt sau khi human trả lời).
+  - Các bước: (chỉ bắt đầu sau khi có câu trả lời).
+- **Dependency**: T-002
+- **REQ / UC mapping**: REQ-E04 (UC-02)
+- **Done khi**: khớp business rule đã chốt (AC-09, spec §4)
+- **Complexity**: M
+- **Câu hỏi mở**: Phí trễ tính theo **ngày lịch** hay **ngày làm việc**? Có trần tối đa không? → Implement Agent **DỪNG, hỏi human** trước khi code, KHÔNG tự đoán.
+- **Trạng thái**: [ ]
+
+> `[CLARIFY]`: kèm **Câu hỏi mở**; thà hỏi còn hơn giả định sai. Plan còn `[CLARIFY]` chưa coi là "ready" hoàn toàn.
+
+---
+
+## Milestone 2 — Tích hợp (sau khi M1 chốt spike + clarify)
+
+#### T-004 … T-009: (worker, API trigger, retry, observability, integration test `[GATE]`)
+> Lược — mỗi task vẫn đủ Type · Done khi (AC) · TDD · Complexity như schema chuẩn.

package/skills/plan/task-breakdown/examples/good/tasks-login-feature.md

@@ -0,0 +1,111 @@
+# Ví dụ — Tasks.md (User Login Feature)
+
+> Đây là mẫu output chuẩn cho Plan Agent khi chia tasks (schema khớp `.v-flow/templates/tasks-template.md`).
+
+---
+
+## Tasks — Feature 001: User Login
+
+#### T-001: Data Models & Entities `[LOGIC]` `[ENTRYPOINT]` `[CRITICAL]`
+- **Mô tả**: Tạo data models cho authentication flow — user entity, request/response DTOs.
+- **Files**: `lib/features/auth/domain/auth_models.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: AuthUser, LoginRequest, LoginResponse với serialization.
+  - Các bước: 1) Định nghĩa entity 2) DTO + fromJson/toJson 3) Unit test serialization.
+- **Dependency**: Không
+- **REQ / UC mapping**: REQ-E01, REQ-U01 (UC-01)
+- **Done khi**: serialize/deserialize round-trip đúng cho AuthUser + DTOs (AC-01, spec §4)
+- **Test liên quan**: TC-01
+- **TDD** (Red→Green):
+  - [ ] Test: `LoginResponse.fromJson` parse đúng `token` + `refreshToken`
+  - [ ] Test: `LoginRequest.toJson` ra đúng `{email, password}`
+  - [ ] Impl: entity + DTO + fromJson/toJson
+- **Complexity**: S
+- **Trạng thái**: [ ]
+
+#### T-002: Auth Repository Interface & Implementation `[LOGIC]` `[DEPENDS: T-001]`
+- **Mô tả**: Repository interface tại domain layer, implementation tại data layer.
+- **Files**: `lib/features/auth/domain/auth_repository.dart`, `lib/features/auth/data/auth_repository_impl.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: Interface defined trước implementation; map error types (InvalidCredentials, AccountLocked, NetworkError).
+  - Các bước: 1) Interface 2) Impl gọi API service (mock) 3) Unit test với mock.
+- **Dependency**: T-001
+- **REQ / UC mapping**: REQ-E01, REQ-E02 (UC-01)
+- **Done khi**: repository map đúng error types (InvalidCredentials/AccountLocked/NetworkError) (AC-02, spec §4)
+- **Test liên quan**: TC-02, TC-03
+- **TDD** (Red→Green):
+  - [ ] Test: API trả 401 → throw `InvalidCredentials`
+  - [ ] Test: API trả 423 → throw `AccountLocked`
+  - [ ] Impl: interface + impl gọi api service (mock) + map error
+- **Complexity**: M
+- **Trạng thái**: [ ]
+
+#### T-003: API Service `[API]` `[DEPENDS: T-001]` `[PARALLEL]`
+- **Mô tả**: HTTP client cho auth endpoints. Song song với T-002 (không share code).
+- **Files**: `lib/features/auth/data/auth_api_service.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: gọi `POST /api/auth/login`, parse response + error.
+  - Các bước: 1) Base URL từ config (không hardcode) 2) Timeout 10s (constitution §5.2) 3) Error parsing.
+- **[API]**: `POST /api/auth/login` · request `{email, password}` · response `{token, refreshToken}`
+- **Dependency**: T-001
+- **REQ / UC mapping**: REQ-E01 (UC-01)
+- **Done khi**: gọi đúng `POST /api/auth/login` + parse response/error (AC-03, spec §4)
+- **Test liên quan**: TC-04
+- **TDD** (Red→Green):
+  - [ ] Test: request hợp lệ → parse `{token, refreshToken}`
+  - [ ] Test: quá 10s → throw `NetworkError`
+  - [ ] Impl: http client + base URL từ config + timeout + parse
+- **Complexity**: S
+- **Trạng thái**: [ ]
+
+#### T-004: Login Use Case `[LOGIC]` `[CRITICAL]` `[DEPENDS: T-002, T-003]`
+- **Mô tả**: Core business logic — validate → authenticate → handle result + rate limiting.
+- **Files**: `lib/features/auth/domain/login_usecase.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: rate limiting block sau 5 attempts; mọi error type được handle.
+  - Các bước: 1) Validate input 2) Call repository 3) Đếm attempts + lockout.
+- **Dependency**: T-002, T-003
+- **REQ / UC mapping**: REQ-E01, REQ-E02, REQ-U01, REQ-O01 (UC-01)
+- **Done khi**: rate limiting chặn sau 5 lần sai + mọi error type được handle (AC-04, AC-05, spec §4)
+- **Test liên quan**: TC-01 → TC-05
+- **TDD** (Red→Green):
+  - [ ] Test: credential đúng → trả `AuthUser`
+  - [ ] Test: sai 5 lần → lockout; lần 6 bị chặn, KHÔNG gọi repository
+  - [ ] Impl: validate → call repo → đếm attempts + lockout
+- **Complexity**: M
+- **Trạng thái**: [ ]
+
+#### T-005: Login UI `[UI]` `[DEPENDS: T-004]`
+- **Mô tả**: Presentation layer — form UI, state management, error display.
+- **Files**: `lib/features/auth/presentation/login_screen.dart`, `login_bloc.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: loading/success/error state; validate email; thông báo lỗi không lộ credential.
+  - Các bước: 1) Form widget 2) Bloc states 3) Error mapping.
+- **[UI]**: Màn hình `LoginScreen` (UC-01) · component email/password field, submit button · trạng thái `loading/error-401` · token `input-default`, `button-primary`
+- **Dependency**: T-004
+- **REQ / UC mapping**: REQ-E01, REQ-E02, REQ-O01 (UC-01)
+- **Done khi**: hiển thị loading/success/error; thông báo lỗi KHÔNG lộ credential (AC-06, spec §4)
+- **Test liên quan**: TC-06, TC-07
+- **TDD** (Red→Green):
+  - [ ] Test: submit → state `loading` → success chuyển màn
+  - [ ] Test: 401 → hiển thị lỗi chung, không tiết lộ field nào sai
+  - [ ] Impl: form widget + bloc states + error mapping
+- **Complexity**: M
+- **Trạng thái**: [ ]
+
+#### T-006: Integration Test & Cleanup `[TEST]` `[GATE]` `[DEPENDS: T-005]`
+- **Mô tả**: End-to-end test flow. DỪNG chờ human review trước khi merge.
+- **Files**: `test/features/auth/login_integration_test.dart`
+- **Thay đổi cụ thể**:
+  - Mong muốn: E2E pass cho login success + failure flow.
+  - Các bước: 1) Test success 2) Test failure 3) Human review.
+- **Dependency**: T-005
+- **REQ / UC mapping**: All REQs (UC-01)
+- **Done khi**: E2E login success + failure pass; human review approved (AC-07, spec §4)
+- **Test liên quan**: TC-08
+- **TDD** (Red→Green):
+  - [ ] Test: happy path login → vào home
+  - [ ] Test: sai mật khẩu → ở lại màn + thông báo lỗi
+- **Gate condition**: Human review approved trước khi merge.
+- **Complexity**: S
+- **Trạng thái**: [ ]

package/skills/plan/task-breakdown/gotchas.md

@@ -0,0 +1,39 @@
+# Gotchas — Task Breakdown
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **Task quá lớn** — "Implement toàn bộ feature" = 1 task.
+   - **Hậu quả**: Implement Agent không biết khi nào xong, test khó viết.
+   - **Fix**: 1 task ≈ 1 component ≈ 1 TDD cycle.
+
+2. ❌ **Task quá nhỏ** — "Tạo file X.dart", "Import package Y".
+   - **Hậu quả**: 50 tasks → overwhelming, overhead tracking lớn hơn work.
+   - **Fix**: Group related micro-tasks vào 1 task có meaning.
+
+3. ❌ **Thiếu ENTRYPOINT** — Task list không có task nào đánh dấu bắt đầu.
+   - **Fix**: Luôn có ĐÚNG 1 task `[ENTRYPOINT]`.
+
+4. ❌ **Circular dependency** — T-001 depends T-002, T-002 depends T-001.
+   - **Fix**: Tách shared logic sang T-000, cả T-001 và T-002 depend T-000.
+
+5. ❌ **Fake PARALLEL** — 2 tasks đánh dấu parallel nhưng share cùng file.
+   - **Fix**: Track file paths — nếu 2 tasks modify cùng file → sequential.
+
+6. ❌ **Thiếu REQ traceability** — Task tồn tại nhưng không gắn REQ nào.
+   - **Rule**: Task không có REQ = task thừa. Hỏi: "Task này serve req nào?"
+
+7. ❌ **Quên task testing cuối** — Implement xong nhưng không có integration test task.
+   - **Fix**: Luôn có task cuối: "T-N: Integration test + cleanup" với `[GATE]` nếu cần.
+
+---
+
+## Edge Cases
+
+- ✅ Feature chỉ có 1 REQ → 2-3 tasks vẫn OK (setup, implement, test).
+- ✅ Feature cross-cutting (auth, logging) → Tách task _shared trước, feature task sau.
+- ✅ Legacy refactor → Mỗi task PHẢI check No-Go Zone, thêm `[RISKY]` nếu gần boundary.