@educa-corp/sdd-framework 0.1.0

package/steps/review-fanout.md

@@ -0,0 +1,159 @@
+# Review Fan-Out toàn diện + Hội tụ về độ đầy đủ
+
+**Vì sao có cái này:** Một lượt review đơn không bao giờ liệt kê hết mọi vấn đề cùng lúc — model
+dừng ở mức "đủ" findings, nên mỗi vòng review sau lại lòi ra vấn đề *mới*
+(đập chuột chũi). Quy trình này ép review **hội tụ trong một lần chạy lệnh**:
+fan out song song theo các chiều review, rồi lặp một critic độ-đầy-đủ cho tới khi một
+vòng không sinh thêm gì mới, *trước khi* ghi file findings.
+
+Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
+- **DIMENSIONS** — danh sách các chiều review để fan out
+  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+- **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
+- **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
+- **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
+
+> **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
+> quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
+> sub-agent. Chạy các check của lệnh trực tiếp trên section đã giới hạn và trả về findings.
+
+---
+
+## Phase 1 — Quét dimension song song
+
+**Bao nhiêu sub-agent:** *số lượng* agent không phải là đòn bẩy độ đầy đủ — bề rộng được
+cố định bởi taxonomy DIMENSION (thêm agent vào cùng một dimension chỉ tìm lại cùng vấn đề),
+còn *độ sâu* thuộc về vòng lặp critic ở Phase 2.
+
+**Nếu `GRANULARITY = per-uc`:** **bỏ qua bảng ngưỡng dưới đây**, luôn dùng độ mịn **DIMENSION × phạm vi UC** (kể cả PRD nhỏ) — đảm bảo quét sâu, không bỏ sót ngay lần đầu. (Cái giá: nhiều agent hơn cho PRD nhỏ — chấp nhận để lần đầu đầy đủ.)
+
+**Nếu `GRANULARITY = auto`** (mặc định): chọn **độ mịn fan-out** theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
+
+| Kích thước target | Độ mịn | Số agent |
+|-------------|-------------|-------------|
+| ≤ 3 UC **và** ≤ 300 dòng | một agent cho mỗi DIMENSION trên cả file | = số dimension |
+| > 3 UC **hoặc** > 300 dòng | một agent cho mỗi **DIMENSION × phạm vi UC** (các UC + một phạm vi PRD-global), gom batch để vừa giới hạn agent | `dimensions × (UCs + 1)`, có cap (xem dưới) |
+
+Độ mịn lớn hơn giữ context của mỗi sub-agent nhỏ và quét nó vét cạn trên một
+UC duy nhất — chính là điều ngăn bỏ sót trên các PRD lớn.
+
+> **Các section global (không thuộc UC) — bắt buộc ở chế độ `DIMENSION × UC`.** Mỗi agent per-UC chỉ
+> thấy một UC, nên các section toàn-PRD không thuộc UC nào (scope, success metric,
+> problem statement, terminology, glossary, changelog) sẽ không được quét. Khi nào
+> fan out theo UC, cũng phải thêm một phạm vi **"PRD-global"** (các section không thuộc UC, finding nhận
+> `uc_id: ""`) bên cạnh danh sách UC. Nên số agent tự nhiên là `dimensions × (UCs + 1)`.
+> (Không cần ở chế độ whole-file — ở đó mỗi agent đã thấy các section global rồi.)
+
+### Agent cap — gom batch các UC khi fan-out quá rộng
+
+`dimensions × (UCs + 1)` có thể bùng nổ trên PRD lớn (vd 6 check × (8 UC + 1) = 54
+agent). Giới hạn mỗi wave ở **`AGENT_CAP = 12`** agent và gom batch các phạm vi UC cho vừa:
+
+1. Dựng danh sách phạm vi = `[UC1, UC2, …, UCn, PRD-global]` (độ dài `UCs + 1`).
+   - **Nếu `CHANGED_SCOPE` được truyền (review delta):** danh sách phạm vi = `[các UC trong CHANGED_SCOPE] + [PRD-global]` (chỉ các UC đã đổi + global), KHÔNG phải tất cả UC. Số agent tụt theo đó.
+2. Tính số-phạm-vi-mỗi-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - Nếu `groups ≥ UCs + 1` → không cần batch, chạy một agent cho mỗi `DIMENSION × scope`.
+   - Else chia danh sách phạm vi thành `groups` bucket liền kề kích thước xấp xỉ bằng nhau
+     (giữ `PRD-global` ở bucket riêng nếu vừa; nếu không thì gắn vào bucket cuối).
+     Mỗi agent khi đó xử lý **một DIMENSION trên một bucket UC**.
+3. Kích thước wave kết quả = `dimensions × groups ≤ AGENT_CAP`.
+
+Một agent đã batch review nhiều UC cùng lúc — vẫn giới hạn chặt hơn nhiều so với cả
+file, nên độ phủ vẫn cao. `AGENT_CAP` là núm chỉnh duy nhất; tăng nếu host cho phép
+concurrency nhiều hơn, giảm để tiết kiệm token. Chế độ whole-file (≤ 3 UC) không bao giờ chạm cap.
+
+Spawn các sub-agent đã chọn bằng Agent tool (gửi trong một message duy nhất để chúng
+chạy đồng thời). Mỗi sub-agent nhận một **context window mới** và quét phạm vi của nó
+chỉ qua **một** dimension duy nhất — độ phủ sâu hơn một session phải tung hứng mọi
+dimension cùng lúc (tránh lost-in-the-middle).
+
+Template prompt cho sub-agent (điền vào các ngoặc):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Gom mảng findings của mọi sub-agent vào một danh sách hợp nhất `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Vòng lặp hội tụ critic độ-đầy-đủ
+
+Đây là bước chống đập-chuột-chũi. Lặp cho tới khi **hai vòng liên tiếp thêm 0 finding
+mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
+
+> **Lưu ý delta:** kể cả khi `CHANGED_SCOPE` giới hạn Phase 1 vào các UC đã đổi, completeness-critic ở Phase 2 **vẫn đọc TOÀN bộ doc** — đây là lưới an toàn bắt các vấn đề mà một fix ở UC đã đổi có thể làm lộ ra ở chỗ khác.
+
+1. Spawn một sub-agent **completeness-critic** bằng Agent tool. Cho nó:
+   - toàn bộ target file (`{target_file}`),
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
+   Prompt nó:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
+   content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
+   names/owners, error branches) written INSIDE an acceptance criterion or a scope line
+   instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
+   (same content, converged); a term definition crammed into In/Out Scope. For these, the
+   suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
+   outcome + BR ref) — NOT to delete it, and NOT to add more detail.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Thêm bất kỳ finding thực sự mới (chưa có trong `ALL_FINDINGS`) vào danh sách.
+3. Nếu vòng này trả 0 finding mới → tăng bộ đếm dry-round; ngược lại reset về 0.
+4. Dừng khi bộ đếm dry-round đạt 2, hoặc sau tổng cộng 3 vòng.
+
+Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
+
+---
+
+## Phase 3 — Dedup, giải quyết xung đột, merge
+
+Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
+trao đổi hay điều hoà giữa chúng — mọi xử lý trùng/xung đột diễn ra **ở đây trong
+orchestrator**, nơi thấy toàn bộ tập findings.
+
+1. **Khử trùng lặp** `ALL_FINDINGS`: hai finding là trùng nếu cùng nhắm tới cùng
+   `section` + `uc_id` và mô tả cùng một vấn đề gốc. Giữ cái có `suggestion`
+   phong phú hơn; nếu khác nhau về severity, giữ severity **cao hơn**.
+2. **Giải quyết xung đột** — nhóm các finding còn lại theo `section` + `uc_id` và kiểm tra
+   mâu thuẫn (hai finding có `suggestion` không thể cùng áp dụng, hoặc đề xuất sửa ngược nhau cho cùng một chỗ):
+   - Nếu hai đề xuất có thể **merge** thành một bản sửa mạch lạc → merge thành một finding duy nhất.
+   - Nếu chúng **loại trừ lẫn nhau** → phát ra **một** finding nêu cả hai phương án
+     và set `auto_fixable: false` với `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) để con người chọn — không bao giờ âm thầm bỏ một bên.
+   - Nếu một finding bị **vô hiệu** bởi finding khác (vd một finding cấu trúc nói một section
+     bị thiếu, nhưng một finding khác trích dẫn nội dung từ chính section đó) → bỏ cái không hợp lệ.
+3. **Sắp xếp** theo severity (critical → major → minor), rồi theo thứ tự `section` trong file.
+4. **Gán ID ổn định** `F001, F002, …` theo thứ tự đã sắp đó.
+5. Map `dimension` của mỗi finding vào field schema của lệnh
+   (`lens` cho `/refine-prd`; `check_id` cho `/review-context`).
+6. Ghi **một** file findings duy nhất theo FINDINGS SCHEMA mà lệnh định nghĩa.
+
+Trong report cuối của lệnh, thêm một dòng:
+```
+Convergence: {convergence_rounds} vòng critic — file findings đã đầy đủ; chạy lại sẽ lòi ra 0 vấn đề mới.
+```

package/steps/spawn-agent.md

@@ -0,0 +1,129 @@
+# Pattern điều phối Sub-Agent
+
+Dùng bởi các lệnh nặng khi target vượt ngưỡng phức tạp.
+Session chính trở thành một **orchestrator nhẹ** — chỉ điều phối.
+Mỗi đơn vị công việc chạy trong sub-agent riêng với context window mới.
+
+---
+
+## Ngưỡng phức tạp
+
+| Tín hiệu | Ngưỡng | Hành động |
+|--------|-----------|--------|
+| Số UC trong PRD | > 3 UC | spawn 1 agent cho mỗi UC |
+| Độ dài PRD | > 300 dòng | spawn agent bất kể số UC |
+
+Nếu vượt **một trong hai** ngưỡng → chuyển sang chế độ orchestration.
+
+---
+
+## Các bước của Orchestrator (session chính)
+
+### Bước A — Dựng context gọn
+
+Chỉ trích xuất những gì sub-agent cần — KHÔNG truyền nguyên CLAUDE.md hay nguyên business-dictionary:
+
+```json
+{
+  "project_name": "{project.name}",
+  "tech_stack": {
+    "language":       "{tech_stack.language}",
+    "framework":      "{tech_stack.framework}",
+    "build_tool":     "{tech_stack.build_tool}",
+    "test_framework": "{tech_stack.test_framework}",
+    "database":       "{tech_stack.database}",
+    "module":         "{tech_stack.module}"
+  },
+  "conventions": {
+    "build_command":  "{conventions.build_command}",
+    "commit_format":  "{conventions.commit_format}"
+  },
+  "paths": {
+    "specs_dir":     "{paths.specs_dir}",
+    "trace_dir":     "{paths.trace_dir}",
+    "tech_docs_dir": "{paths.tech_docs_dir}"
+  },
+  "architecture_summary": "<3-5 gạch đầu dòng: thứ tự layer + quy tắc chính>",
+  "domains": ["{domain1}", "{domain2}"],
+  "banned_terms": ["{term1}", "{term2}"]
+}
+```
+
+### Bước B — Trích danh sách UC
+
+Quét PRD target tìm các heading `#### {TICKET-ID}-UC{N}:`.
+Dựng list: `[ { uc_id, uc_name, line_start, line_end } ]`
+
+### Bước C — Công bố kế hoạch
+
+```
+Phát hiện độ phức tạp cao — {N} UC / {L} dòng trong {prd_file}
+Đang spawn {N} sub-agent (1 cho mỗi UC)...
+  Agent 1 → {TICKET-ID}-UC1: {tên UC}
+  Agent 2 → {TICKET-ID}-UC2: {tên UC}
+  ...
+```
+
+### Bước D — Spawn một sub-agent cho mỗi UC
+
+Dựng payload và gọi Agent tool cho từng UC:
+
+```json
+{
+  "_agent_mode": true,
+  "command":         "generate-bdd",
+  "uc_id":           "{TICKET-ID}-UC{N}",
+  "target_file":     "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
+  "uc_section":      { "line_start": {N}, "line_end": {N} },
+  "context":         { "<context gọn từ Bước A>" },
+  "active_platform": "{web|app|system — platform orchestrator đã chọn ở Platform Selection}",
+  "design_coverage": { "<Screen States + AC-UI behavioral orchestrator đã trích ở 'Design Spec — Gate & Load' (B1); rỗng nếu BE / không có design-spec>" }
+}
+```
+
+> **Truyền state orchestrator đã phân giải (quan trọng):** orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec MỘT LẦN *trước* khi spawn. Phải kèm `active_platform` và `design_coverage` vào payload để sub-agent áp đúng (đặc biệt phủ Screen States + AC-UI cho FE/App). KHÔNG kèm → sub-agent sinh BDD thiếu phần design (PRD lớn mất B1).
+
+> **Phạm vi lệnh**: Chỉ `/generate-bdd` khởi động chế độ orchestration. `/generate-code` và `/dev-gen-test` có thể chạy như sub-agent (chúng tôn trọng `_agent_mode: true` từ Gate Bước 0), nhưng không spawn thêm sub-agent — phạm vi của chúng vốn đã là một UC duy nhất.
+
+Serialize JSON này và truyền làm `$ARGUMENTS` khi gọi lệnh sub-agent.
+
+### Bước E — Thu thập và merge kết quả
+
+Mỗi sub-agent trả về:
+```json
+{
+  "uc_id":         "{TICKET-ID}-UC{N}",
+  "files_created": ["path/to/file1", "path/to/file2"],
+  "status":        "success | error",
+  "errors":        []
+}
+```
+
+Merge vào một report duy nhất (theo định dạng report-footer.md).
+Nếu có sub-agent lỗi → liệt kê rõ ràng và đề xuất chạy lại riêng UC đó.
+
+---
+
+## Điểm vào của Sub-Agent (các lệnh được gọi)
+
+Khi `gate.md Bước 0` phát hiện `_agent_mode: true`:
+
+1. Parse toàn bộ payload từ `$ARGUMENTS`
+2. **Bỏ qua context-loader.md** — dùng trực tiếp `payload.context`
+3. **Chỉ giới hạn ở `payload.uc_id`** — không xử lý các UC khác trong file
+4. Chỉ đọc section PRD giữa `payload.uc_section.line_start` và `line_end`
+5. **Dùng state orchestrator đã phân giải:** `active_platform` = `payload.active_platform`; `design_coverage` = `payload.design_coverage`. **KHÔNG chạy lại** các Guard (PRD approved / Design-Spec) hay tự nạp lại design-spec / hỏi platform — orchestrator đã làm một lần ở session chính.
+6. Thực thi logic thường của lệnh cho riêng UC này (dùng `design_coverage` từ payload để phủ Screen States + AC-UI)
+7. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
+
+---
+
+## Tiết kiệm Context Window
+
+| Chế độ | Nạp gì mỗi session |
+|------|------------------------|
+| Single session (≤ 3 UC) | Full context + full PRD + tất cả UC |
+| Orchestrator | Context gọn + chỉ các heading UC |
+| Mỗi sub-agent | Context gọn + **chỉ 1 section UC** |
+
+PRD càng lớn, mức tiết kiệm trên mỗi sub-agent càng nhiều.

package/steps/trace-mirror.md

@@ -0,0 +1,26 @@
+# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+
+*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
+`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+
+Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
+
+**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
+`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
+Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
+commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
+1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
+2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+   `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
+   `@trace.service` của từng row.
+
+**Legacy (không có `spec_source` — trace theo service):**
+Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`
+(namespace theo `active_service`).
+
+Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
+một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
+`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
+được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
+bên trong từng sub-agent.

package/templates/architecture.template.md

@@ -0,0 +1,113 @@
+# §1. Project Overview
+
+Project    : {{PROJECT_NAME}}
+Language   : {{LANGUAGE}}          # vd: Java 17 / TypeScript / C# / Go
+Framework  : {{FRAMEWORK}}         # vd: Spring Boot 3.2 / Angular 17 / .NET 8
+Build      : {{BUILD_COMMAND}}     # vd: mvn clean install -DskipTests / dotnet build / ng build
+Test       : {{TEST_COMMAND}}      # vd: mvn test / dotnet test / ng test
+Domains    : {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+
+style: "{{ARCH_STYLE}}"  # vd: Layered / Clean / Hexagonal / Component-based
+
+layers: "{{LAYER_STACK}}"
+# Ví dụ:
+#   Java/Spring:  Controller → Facade → Service → Repository
+#   .NET Clean:   Presentation → Application → Domain → Infrastructure
+#   Angular:      Component → Service → HTTP Client → Backend API
+#   Go:           Handler → UseCase → Repository → Domain
+
+rules:
+  - "{{ARCH_RULE_1}}"  # vd: Controller không được chứa business logic
+  - "{{ARCH_RULE_2}}"  # vd: Service sở hữu ranh giới transaction
+  - "{{ARCH_RULE_3}}"  # vd: Repository không được gọi service
+
+# Chiều phụ thuộc giữa các layer (layer trong không được phụ thuộc layer ngoài):
+# {{OUTER_LAYER}} → {{MIDDLE_LAYER}} → {{INNER_LAYER}}
+
+# §3. Coding Standards
+
+naming:
+  classes: "{{CLASS_NAMING}}"        # vd: PascalCase / PascalCase+Suffix
+  methods: "{{METHOD_NAMING}}"       # vd: camelCase / PascalCase
+  packages: "{{PACKAGE_NAMING}}"     # vd: lowercase / lowercase.snake_case
+  files: "{{FILE_NAMING}}"           # vd: PascalCase.java / kebab-case.ts
+
+patterns:
+  response_wrapper: "{{RESPONSE_WRAPPER}}"  # vd: ApiResponse<T> / Result<T> / IActionResult
+  mapping: "{{MAPPING_LIBRARY}}"            # vd: MapStruct / AutoMapper / manual
+  exception_base: "{{BASE_EXCEPTION}}"      # vd: ResourceNotFoundException / DomainException
+
+forbidden:
+  - "Magic number — dùng hằng số có tên"
+  - "Lệnh debug print trong code production"
+  - "{{PROJECT_SPECIFIC_FORBIDDEN_PATTERN}}"
+
+# §4. API Conventions
+
+versioning: "{{API_VERSIONING}}"     # vd: tiền tố /v1/ / theo header / query param
+auth: "{{AUTH_MECHANISM}}"           # vd: JWT Bearer / OAuth2 / API Key
+
+http_status:
+  get_list:    200   # danh sách phân trang hoặc đầy đủ
+  get_single:  200
+  create:      201
+  update:      200
+  delete:      204
+  bad_request: 400
+  unauthorized: 401
+  forbidden:   403
+  not_found:   404
+  server_error: 500
+
+error_response_format: |
+  {
+    "code": "ERROR_CODE",
+    "message": "Human readable message",
+    "details": {}   // optional field-level errors
+  }
+
+# §5. Error Handling
+
+not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # vd: ResourceNotFoundException
+validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # vd: ValidationException
+domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # vd: DomainException / BusinessRuleViolationException
+
+global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # vd: @ControllerAdvice / ExceptionHandlerMiddleware
+
+rules:
+  - "Không bao giờ nuốt exception âm thầm"
+  - "Log ở mức error kèm full stack trace cho lỗi 5xx"
+  - "{{PROJECT_SPECIFIC_ERROR_RULE}}"
+
+# §6. Testing Standards
+
+unit_test_framework: "{{UNIT_TEST_FW}}"        # vd: JUnit 5 + Mockito / xUnit + Moq / Jest
+integration_test_framework: "{{IT_TEST_FW}}"   # vd: Spring Boot Test / WebApplicationFactory
+
+coverage_targets:
+  unit: "{{UNIT_COVERAGE_PCT}}%"          # vd: 80%
+  integration: "{{IT_COVERAGE_PCT}}%"     # vd: phủ các flow chính
+
+naming_pattern: "{{TEST_METHOD_NAMING}}"  # vd: methodName_whenCondition_shouldExpectation
+
+rules:
+  - "Unit test chỉ mock các dependency trực tiếp"
+  - "Integration test phủ happy path + các luồng lỗi chính"
+  - "Mọi scenario trong .feature phải có test tương ứng"
+
+# §7. Git Conventions
+
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_fix:     "fix/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_chore:   "chore/{slug}"
+
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+commit_fix:     "fix({{TICKET_PREFIX}}-{N}): {description}"
+commit_chore:   "chore: {description}"
+commit_docs:    "docs: {description}"
+
+pr_title: "{{TICKET_PREFIX}}-{N}: {feature name}"
+pr_requires_review: true
+pr_branch_protection: "{{BASE_BRANCH}}"  # vd: main / develop

package/templates/design-spec.template.md

@@ -0,0 +1,217 @@
+# {TICKET-ID} {Feature Name} — Design Spec [{Platform}]
+
+<!--
+  Template này được sử dụng bởi /generate-design-spec.
+  Platform = web | app | app-ios | app-android
+
+  PLATFORM SECTIONS:
+  - Section 3A + 4A: chỉ dành cho web (react/nextjs/vue/angular). Xóa C khi dùng cho web.
+  - Section 3C + 4B: chỉ dành cho app (flutter/react-native/ios/android). Xóa A+B khi dùng cho app.
+
+  COMPONENT MAPPING (bắt buộc):
+  - Mọi component trong Component Inventory PHẢI được map với figma-components/{module}.md
+  - ✅ Matched     → dùng Code Component và Import Path từ catalog
+  - ⚠️ TODO        → đánh dấu [TODO — chưa implement]
+  - ❌ Chưa có     → đánh dấu [NEW — cần confirm với designer]
+
+  FIGMA LINKS (bắt buộc mỗi màn):
+  - Mỗi screen PHẢI có link Figma node-level (URL chứa ?node-id=...) — lấy bằng
+    right-click frame → "Copy link to selection". Đây là link AI đọc được qua Figma MCP.
+  - Link file trần (không có node-id) KHÔNG hợp lệ — AI không định vị được frame.
+  - Screen chưa có design → đánh dấu ❌ Missing; spec giữ Status "draft", chặn sign-off
+    và /generate-bdd cho tới khi đủ link.
+
+  SCREEN STATES (bắt buộc mỗi màn):
+  - Tối thiểu: default, loading, error
+  - Thêm "empty" nếu màn có thể hiển thị trạng thái không có dữ liệu
+  - Thêm "success" nếu action tạo ra trạng thái xác nhận riêng biệt
+-->
+
+---
+
+## Metadata
+
+| Field              | Value                                                         |
+|--------------------|---------------------------------------------------------------|
+| **Spec ID**        | {TICKET-ID}-DS-{platform}                                     |
+| **Version**        | 1.0                                                           |
+| **Status**         | draft / approved                                              |
+| **Platform**       | {web \| app \| app-ios \| app-android}                        |
+| **Module**         | {active_module}                                               |
+| **Service**        | {active_service}                                              |
+| **Domain**         | {domain}                                                      |
+| **Business PRD**   | [{TICKET-ID}](./{TICKET-ID}-slug.md)                          |
+| **Figma**          | {link file feature} ({linked}/{N} frame đã link)             |
+| **Author**         | {tên PO hoặc "AI-assisted"}                                   |
+| **Created**        | {YYYY-MM-DD}                                                  |
+| **Updated**        | {YYYY-MM-DD}                                                  |
+
+---
+
+# 1. Danh mục màn hình (Screen Inventory)
+
+| # | Tên màn hình | Điểm vào | Figma Frame (link node-level) | Ghi chú |
+|---|-------------|-------------|-------------------------------|-------|
+| 1 | {Màn hình 1}  | {người dùng đến từ đâu} | [Frame]({node-level url}) | |
+| 2 | {Màn hình 2}  | {điểm vào} | ❌ Missing — thêm link node-id | |
+
+---
+
+# 2. Đặc tả màn hình (Screen Specs)
+
+## Màn hình 1: {Tên màn hình}
+
+**Figma**: [{Tên frame}]({figma_frame_url})
+
+### Layout
+
+{Grid / max-width / padding / spacing — tham chiếu design token nếu áp dụng được}
+
+### Component Inventory
+
+| Component (Figma)      | Code Component | Import Path            | States                          | Ghi chú |
+|------------------------|----------------|------------------------|---------------------------------|---------|
+| {Figma/Button/Primary} | Button         | @/components/ui/Button | default, loading, disabled      |         |
+| {Figma/Input/Text}     | TextInput      | @/components/ui/Input  | default, focus, error, disabled |         |
+
+### Screen States
+
+| State     | Trigger                          | Hành vi UI                                              |
+|-----------|----------------------------------|----------------------------------------------------------|
+| default   | Màn đã load, có dữ liệu           | {Mô tả toàn bộ giao diện đã render}                      |
+| loading   | API đang gọi                      | {Vị trí và kiểu skeleton / spinner}                      |
+| error     | API thất bại / lỗi validation     | {Toast / lỗi inline / màn lỗi + CTA khôi phục}           |
+| empty     | Không có dữ liệu trả về            | {Illustration + CTA — vd: "Chưa có mục nào. Thêm mới →"} |
+| success   | Action hoàn tất (nếu có)          | {Toast xác nhận / điều hướng / thay đổi giao diện}       |
+
+### Actions & Navigation
+
+| Action          | Trigger                   | Kết quả                                           |
+|-----------------|---------------------------|---------------------------------------------------|
+| {Tên action}    | Tap/click {phần tử}       | Điều hướng tới {Màn hình N} / Mở {Tên modal}      |
+| {Back/Cancel}   | Cử chỉ back / nút          | Quay lại {màn trước} mà không lưu                  |
+
+---
+
+<!--  Lặp lại ## Màn hình N cho mỗi màn bổ sung  -->
+
+---
+
+# 3. Pattern tương tác (Interaction Patterns)
+
+<!-- === CHỈ WEB — xóa section này cho app === -->
+
+## A. Hành vi Responsive  *(web)*
+
+| Breakpoint | Width      | Thay đổi layout                             |
+|------------|------------|---------------------------------------------|
+| Mobile     | < 768px    | {1 cột, bottom nav, CTA full-width}         |
+| Tablet     | 768–1279px | {grid 2 cột, sidebar thu gọn}               |
+| Desktop    | ≥ 1280px   | {layout đầy đủ, max-width 1440px}           |
+
+## B. Hover / Focus / Keyboard  *(web)*
+
+| Phần tử        | Hover                         | Focus                           | Keyboard      |
+|----------------|-------------------------------|---------------------------------|---------------|
+| Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space |
+| Text input     | Border → {color.border.hover} | Border → {color.primary}        | Tab to focus  |
+
+<!-- === CHỈ APP — xóa section A+B cho app === -->
+
+## C. Cử chỉ & Điều hướng  *(app)*
+
+| Cử chỉ               | Màn / Phần tử       | Hành vi                                     |
+|----------------------|---------------------|---------------------------------------------|
+| Cử chỉ back          | Mọi màn             | {Quay lại / hiện dialog "Discard changes?"} |
+| Pull-to-refresh      | {Tên màn}           | Refresh dữ liệu, spinner ở trên cùng        |
+| Swipe trái trên row  | {List item}         | Hiện action {Delete / Archive}              |
+
+### Navigation Stack  *(app)*
+
+```
+{vd: BottomTab(Home) → ListPage → DetailPage → EditPage}
+```
+
+### Platform Conventions  *(app)*
+
+| Khía cạnh        | iOS                                       | Android                             |
+|------------------|-------------------------------------------|-------------------------------------|
+| Navigation bar   | Nút back trên-trái, title canh giữa        | Mũi tên Up, title canh trái         |
+| Bottom sheet     | UISheetPresentation, hiện grabber          | BottomSheet, drag handle            |
+| Dialog           | Action canh phải                          | Action canh trái                    |
+
+---
+
+# 4. Cân nhắc theo Platform (Platform Considerations)
+
+<!-- === CHỈ WEB === -->
+
+## A. Accessibility  *(web)*
+
+- [ ] Mọi phần tử tương tác đều tới được bằng phím Tab — không có keyboard trap
+- [ ] Focus trap bên trong modal
+- [ ] Nút chỉ có icon phải có `aria-label`
+- [ ] Nội dung động thông báo qua `aria-live`
+- [ ] Tương phản WCAG AA: text ≥ 4.5:1, text lớn ≥ 3:1
+- [ ] Input form có label hiển thị (không chỉ dùng placeholder)
+
+<!-- === CHỈ APP === -->
+
+## B. Thiết bị & OS  *(app)*
+
+- [ ] Áp dụng safe area insets (trên + dưới) ở mọi màn
+- [ ] Touch target tối thiểu: 44×44pt (iOS) / 48×48dp (Android)
+- [ ] Đã test trên 375pt (iPhone SE) và 360dp (Android nhỏ)
+- [ ] Deep link: `{scheme}://{host}/{path}` → {tên màn}
+- [ ] Permission: {Camera / Location / Notification} — nội dung lý do TBD
+- [ ] Offline: {tên màn} hiện dữ liệu cache + banner; {action} bị disable kèm tooltip
+- [ ] Đã test dark mode — không có màu hardcode
+
+---
+
+# 5. AC-UI — Tiêu chí chấp nhận về Design
+
+> Được **PO + Designer** review và sign off trước khi sinh BDD.
+> Bổ sung cho AC mức nghiệp vụ trong [Business PRD](./{TICKET-ID}-slug.md).
+
+| ID     | Tiêu chí chấp nhận                                                       | Verified by     |
+|--------|--------------------------------------------------------------------------|-----------------|
+| AC-UI1 | Mọi màn khớp với frame Figma đã duyệt trong dung sai design-system        | Designer        |
+| AC-UI2 | Trạng thái loading xuất hiện trong vòng 200ms kể từ khi gọi API           | QA              |
+| AC-UI3 | Mọi thông báo lỗi đều hiển thị, rõ ràng, và kèm CTA khôi phục             | PO              |
+| AC-UI4 | Empty state có illustration và call-to-action                            | PO + Designer   |
+| AC-UI5 | {Tiêu chí riêng theo platform}                                           | QA              |
+
+---
+
+# Appendix
+
+## Tóm tắt Figma
+
+| Màn hình   | Figma Frame (node-level) | Trạng thái Link / Fetch         |
+|------------|--------------------------|--------------------------------|
+| {Màn hình 1} | [Link]({node-level url}) | ✅ Đã link & fetch             |
+| {Màn hình 2} | —                        | ❌ Missing — không có link node-id |
+
+## Design Token đã tham chiếu
+
+| Token             | Value    | Dùng ở                     |
+|-------------------|----------|----------------------------|
+| `color.primary`   | {#hex}   | Button, link               |
+| `spacing.md`      | {16px}   | Khoảng cách dọc tiêu chuẩn |
+
+## Tài liệu tham khảo
+
+- [{TICKET-ID}](./{TICKET-ID}-slug.md) — Business PRD
+
+## Giả định AI
+
+- {Giả định — [AI DRAFT]}
+
+---
+
+## Changelog
+
+| Version | Date         | Changes         |
+|---------|--------------|-----------------|
+| 1.0     | {YYYY-MM-DD} | Initial version |