@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/02-concepts/overview.md

@@ -0,0 +1,93 @@
+[← Docs Home](../README.md) · [Concepts](./) · [Glossary →](glossary.md)
+
+# Overview — Mô hình toàn trình (Big Picture)
+
+> Bức tranh lớn của framework: pipeline một chiều, gate hai đầu, và feedback ngược có kiểm soát. Muốn đào sâu từng bước → [Pipeline Steps](pipeline-steps/).
+
+---
+
+## Sơ đồ toàn trình (End-to-end Flow)
+
+```mermaid
+flowchart TD
+    S["0 · Setup<br/>/setup-ai-first"] --> D["1 · Discovery<br/>/define-product"]
+    D --> SP["2 · Specification<br/>/generate-prd · /refine-prd · /review-context"]
+    SP --> DS["3 · Design-Spec<br/>(chỉ FE/App)"]
+    SP --> B["4 · BDD<br/>/generate-bdd · /review-context"]
+    DS --> B
+    B --> T["5 · Tech-Docs<br/>/generate-tech-docs · /review-tech-docs"]
+    T --> C["6 · Code<br/>/generate-code"]
+    C --> DV["7 · Dev self-test"]
+    DV --> Q["8 · QC Automation"]
+    Q --> V["9 · Validate Traces"]
+    V -.->|"report-bug · propose-scenario · learn"| SP
+```
+
+---
+
+## Ba đặc tính bất biến (Invariants)
+
+1. **Pipeline một chiều** — output giai đoạn N là input N+1. Không nhảy bước.
+2. **Gate hai đầu** mỗi giai đoạn — gate đầu vào (validate) + gate đầu ra (findings/approval).
+3. **Feedback ngược không tạo loop** — bug/scenario/lesson cải tiến spec & tri thức, rồi pipeline lại chảy một chiều.
+
+---
+
+## HITL: dày ở thượng nguồn, mỏng ở hạ nguồn
+
+**Rule vàng:** AI có thể sai ở bất kỳ đâu, nhưng sai ở **thượng nguồn** (PRD/BDD) nhân lên **cấp số nhân** ở hạ nguồn (code/test). Nên checkpoint **dày** ở spec/design, **mỏng dần** xuống code.
+
+| Giai đoạn | HITL | Checkpoint chính |
+|-----------|:----:|------------------|
+| Discovery | 🔴 cao nhất | Chốt từng chặng Q&A |
+| Specification | 🔴 cao | `/review-context` sạch critical + PO approve |
+| Design-Spec / BDD | 🔴 cao | UC decomposition, findings |
+| Tech-Docs | 🟠 vừa | Review đa chiều + ký T7 |
+| Code | 🟡 mỏng | Comprehension checkpoint |
+| Dev-test / QC | 🟡–🟠 | Cổng review test |
+
+→ Chi tiết: [Roles & HITL](roles-and-hitl.md).
+
+---
+
+## Bốn "ngăn altitude" (không lộn tầng)
+
+Mọi tài liệu **trước** Tech-Docs nói bằng **ngôn ngữ nghiệp vụ** (Business Language Guard giữ ranh giới):
+
+| Ngăn | Là gì | Ví dụ |
+|------|-------|-------|
+| **AC** | Nghiệm thu (outcome) | "Người dùng đăng nhập được sau khi đặt lại mật khẩu" |
+| **BR / BL** | Cơ chế nghiệp vụ | "Link reset hết hạn sau 15 phút" |
+| **Scope** | Ranh giới | "Không hỗ trợ khôi phục qua SMS" |
+| **Dictionary** | Định nghĩa | "Link reset = one-time token gửi qua email" |
+
+Chi tiết kỹ thuật (retry/timeout/API/selector) chỉ xuất hiện từ **Tech-Docs** trở đi.
+
+---
+
+## Ba lớp kiến trúc (3-layer)
+
+```
+Command (orchestrator)  →  điều phối các phase của workflow
+   ├── Skill            →  domain logic, stateless, chỉ consume context
+   └── Step             →  infra tái dùng (context-loader, gate, spawn-agent…)
+```
+
+Đổi pipeline không đụng skill; đổi skill không đụng infra. → [Architecture](architecture.md).
+
+---
+
+## Đa domain & Umbrella (Multi-domain)
+
+- Mọi artifact theo bố cục **feature-package**: `specs/{domain}/{prd-slug}/…`.
+- **Umbrella**: nhiều service submodule + một **spec repo dùng chung** (`spec_source`) chứa PRD/BDD/tech-docs/design-spec/`.trace`/`feedback`/findings. `/sync` đồng bộ.
+- `CLAUDE.md` phân tầng: root (luật chung) + `{service}/CLAUDE.md` (kiến trúc + coding standards theo stack).
+
+---
+
+## Đọc tiếp (Next)
+
+- [Glossary](glossary.md) — thuật ngữ
+- [Roles & HITL](roles-and-hitl.md) — ma trận vai trò
+- [Traceability](traceability.md) — trace & drift
+- [Pipeline Steps](pipeline-steps/) — chi tiết từng bước

package/docs/02-concepts/pipeline-steps/00-setup.md

@@ -0,0 +1,102 @@
+[← Pipeline Steps](README.md) · [Next: Discovery →](01-discovery.md)
+
+# Bước 0 · Setup — Dựng khung dự án (Project Bootstrap)
+
+> **Tóm tắt.** Chạy **một lần** cho mỗi dự án để tạo cấu trúc thư mục, config và `CLAUDE.md` mà mọi workflow về sau dựa vào.
+> **Command:** `/setup-ai-first` (hoặc `npx @educa-corp/sdd-framework --init`)
+
+| | |
+|---|---|
+| **Giai đoạn** | Setup (tiền pipeline) |
+| **Owner** | Admin / Tech Lead |
+| **Tần suất** | Một lần khi khởi tạo dự án (single) hoặc khi thêm service (umbrella) |
+| **HITL** | ⚪ Thấp — chỉ chọn mode & module |
+
+---
+
+## Mục đích (Purpose)
+
+Framework cần biết **dự án của bạn nằm ở đâu và dùng stack gì** trước khi có thể sinh spec/code đúng chỗ, đúng convention. Bước Setup:
+
+- Tạo bộ khung thư mục chuẩn (`specs/`, `.trace/`, `.agent/`, `.claude/`).
+- Sinh **`project-context.yaml`** — single source of truth cho **paths, mode, services, conventions, tech_stack**.
+- Tạo **`CLAUDE.md`** phân tầng (root + overlay theo service) — nơi tích luỹ kiến trúc & coding standards để AI *follow* thay vì *invent*.
+- Cài các **module stack** đã chọn (java-spring, react, flutter, qc-playwright…).
+
+> Bỏ qua bước này = mọi lệnh sau không biết đọc/ghi ở đâu → halt ở gate "required context missing".
+
+---
+
+## Input (Đầu vào)
+
+- Một thư mục dự án (repo git — có thể trống hoặc đã có code).
+- Quyết định **mode**: `single` (một repo) hay `umbrella` (nhiều service submodule + một spec repo dùng chung).
+- Danh sách **tech stack** của các service (để cài đúng module).
+- (Umbrella) đường dẫn tới **spec repo** dùng chung.
+
+---
+
+## Output (Đầu ra)
+
+| Artifact | Vai trò |
+|----------|---------|
+| `.agent/` | Bản runtime của framework: `commands/`, `steps/`, `rules/`, `skills/`, `templates/`, `modules/`, `hooks/` |
+| `.claude/` | Cấu hình Claude Code (slash command, settings) |
+| `.agent/project-context.yaml` | **Config runtime** — mọi workflow đọc để biết paths/mode/conventions |
+| `CLAUDE.md` (root) | Luật chung + trỏ tới overlay. Umbrella: thêm `{service}/CLAUDE.md` theo stack |
+| `specs/` + `.trace/` | Khung thư mục cho PRD/BDD/tech-docs/design-spec và trace state |
+| `specs/domain-knowledge/` | Nơi chứa business dictionary & tri thức miền |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **Admin/Lead** | Chọn mode single/umbrella, khai báo services & stack, trả lời Q&A setup |
+| 🤖 **AI** | Copy framework files, sinh `project-context.yaml` từ template (token substitution), cài module, dựng `CLAUDE.md` |
+| 👤 **Lead (sau setup)** | **Điền nội dung** `CLAUDE.md` (§2 kiến trúc, §3 coding standards, §5 error handling) và `domain-knowledge/` — phần AI không tự biết |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Dự án này là **single** hay **umbrella** (nhiều service)?
+- Mỗi service dùng **stack** gì → cài module nào?
+- Spec sẽ nằm ở đâu (`specs_dir`), trace ở đâu (`.trace/`)?
+- Lệnh build/test của từng stack là gì (`conventions.build_command`)?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+1. **Init** — `npx … --init` hoặc `/setup-ai-first` copy `.agent/*` và `.claude/*` vào dự án.
+2. **Token substitution** — điền `{{PROJECT_NAME}}`, paths, services… vào `templates/project-context.yaml` → sinh `.agent/project-context.yaml`.
+3. **Cài module** — mỗi module mang `module.yaml` + `stack-profile.yaml` (khai báo `artifact_types`, `generation_layers`, `build_verify`, `test_types`). Skill **đọc profile** thay vì hardcode stack.
+4. **Dựng CLAUDE.md** — tạo file root; umbrella thì thêm overlay cho từng service.
+5. **Verify môi trường** — kiểm Node.js, cấu trúc thư mục.
+
+> `project-context.yaml` dùng `{domain}` và `{prd-slug}` làm biến — mọi path đều theo bố cục **feature-package**: `specs/{domain}/{prd-slug}/…`. Xem [Configuration](../../04-reference/configuration.md).
+
+---
+
+## HITL / Gate
+
+- Không có gate chặn — đây là bước dựng khung.
+- Điểm cần con người: **chọn mode/module đúng** và **điền `CLAUDE.md` + `domain-knowledge/`** sau khi setup. Đây là "trí nhớ nền" mà toàn bộ pipeline sẽ dựa vào.
+
+---
+
+## Anti-pattern
+
+- ❌ Bỏ trống `CLAUDE.md` rồi than "AI sinh code sai convention" — AI *follow* file này; trống thì nó *đoán*.
+- ❌ Sửa thẳng `.agent/commands/*.md` — sẽ mất khi `/update-framework`. Nội dung của bạn nằm ở `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/` (không bị ghi đè).
+- ❌ Chọn `single` cho một hệ nhiều service — sau này khó tách spec/trace dùng chung.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Điền xong `CLAUDE.md` + `domain-knowledge/` → bắt đầu feature đầu tiên:
+
+➡️ [Bước 1 · Discovery — `/define-product`](01-discovery.md)

package/docs/02-concepts/pipeline-steps/01-discovery.md

@@ -0,0 +1,129 @@
+[← Setup](00-setup.md) · [Pipeline Steps](README.md) · [Next: Specification →](02-specification.md)
+
+# Bước 1 · Discovery — Khám phá tính năng (Feature Discovery)
+
+> **Tóm tắt.** Biến một **ý tưởng bằng lời** thành một **khung intent có cấu trúc** thông qua Q&A 8 chặng, PO chốt từng chặng — *trước khi* viết PRD.
+> **Command:** `/define-product`
+
+| | |
+|---|---|
+| **Giai đoạn** | Discovery (đầu pipeline) |
+| **Owner** | 👤 Product Owner / BA |
+| **Đầu vào** | Ý tưởng bằng lời (+ tuỳ chọn Figma/wireframe) |
+| **Đầu ra** | `product-definition/*.md` — khung intent đã duyệt từng chặng |
+| **HITL** | 🔴 **Cao nhất** — chốt mỗi chặng |
+
+---
+
+## Mục đích (Purpose)
+
+Đây là **thượng nguồn của cả pipeline**. Sai ở đây thì mọi thứ downstream (PRD → BDD → code → test) đều sai theo cấp số nhân. Bước Discovery ép PO diễn đạt intent **một lần, có cấu trúc** để:
+
+- Cả người lẫn AI hiểu **giống nhau** ngay từ đầu.
+- Không nhảy thẳng từ "ý tưởng" sang "code" bỏ qua tư duy về user/flow/rule/edge-case.
+- Tạo **nền tảng ổn định** để `/generate-prd` viết PRD chuẩn, không phải đoán.
+
+> Đây **chưa phải PRD** — nó là *bộ khung intent* (product definition) mà PRD sẽ dựa vào.
+
+---
+
+## Input (Đầu vào)
+
+- **Ý tưởng bằng ngôn ngữ tự nhiên** — "Tôi muốn người dùng đăng nhập bằng số điện thoại".
+- (Tuỳ chọn) **Visual**: link Figma, ảnh wireframe — giúp AI hỏi đúng trọng tâm.
+- Context nền đã có: `CLAUDE.md`, `domain-knowledge/`, `project-context.yaml` (nạp tự động qua Gate).
+
+---
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `product-definition/{slug}.md` | Khung intent 8 chặng đã được PO chốt: vấn đề · user · flow · UC · business rule · AC · edge case · scope |
+
+Output này là **input trực tiếp** của `/generate-prd`.
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **PO / BA** | **Lead** — trả lời Q&A, chốt từng chặng, quyết định *cái gì đáng làm* |
+| 🤖 **AI** | Co-pilot — hỏi có cấu trúc theo 8 chặng, tổng hợp câu trả lời thành khung intent, phát hiện chỗ mơ hồ để hỏi lại |
+| 👤 **SA/Dev (tuỳ chọn)** | Consult — nếu ý tưởng có ràng buộc kỹ thuật lớn |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+Q&A đi qua **8 chặng**, mỗi chặng chốt xong mới sang chặng sau:
+
+| # | Chặng | Trả lời câu hỏi |
+|---|-------|-----------------|
+| 1 | **Vấn đề** | Đang giải quyết pain point gì? Tại sao đáng làm? |
+| 2 | **User** | Ai dùng? Vai trò/persona nào? |
+| 3 | **Flow** | Luồng chính người dùng đi qua là gì? |
+| 4 | **Use Case (UC)** | Tính năng gồm những UC nào? |
+| 5 | **Business Rule (BR)** | Ràng buộc nghiệp vụ nào chi phối? |
+| 6 | **Acceptance Criteria (AC)** | Thế nào là "làm xong đúng"? |
+| 7 | **Edge case** | Trường hợp biên/ngoại lệ nào cần lường trước? |
+| 8 | **Scope** | Ranh giới: cái gì **trong**, cái gì **ngoài** phạm vi? |
+
+> Toàn bộ nói bằng **ngôn ngữ nghiệp vụ** — chi tiết kỹ thuật (API, retry, timeout) bị **Business Language Guard** đẩy sang bước Design/Tech-Docs.
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+1. **Gate chung** (model check, context-loader, checkpoint — xem [README](README.md#khung-chung-mọi-command-common-gate)).
+2. **Q&A tuần tự 8 chặng** — AI hỏi từng chặng, chờ PO chốt, **lưu state sau mỗi chặng** để có thể resume nếu ngắt giữa chừng.
+3. **Short-circuit** — nếu AI tự thấy một chặng đã đủ rõ, được phép rút gọn nhưng phải nêu lý do.
+4. **Tổng hợp** — gộp câu trả lời thành `product-definition/*.md` có cấu trúc.
+5. Áp **Business Language Guard** để chặn thuật ngữ kỹ thuật lọt vào.
+
+---
+
+## HITL / Gate
+
+- 🔴 **Mật độ cao nhất toàn pipeline.** Mỗi chặng là một checkpoint — PO xác nhận trước khi đi tiếp.
+- Nguyên tắc checkpoint: AI **không hỏi "OK chưa?"** mà hỏi cụ thể — *"UC list đủ chưa? thiếu/thừa UC nào?"*.
+- Nếu PO sửa nhiều lần cùng một kiểu → cân nhắc `/learn` để ghi lesson (xem [Feedback Loop](10-feedback-loop.md)).
+
+---
+
+## Ví dụ (Example)
+
+```
+PO: /define-product
+    "Người dùng quên mật khẩu cần lấy lại qua email"
+
+AI: [Chặng 1 · Vấn đề] Tôi hiểu vấn đề là: user bị khoá ngoài tài khoản khi
+    quên mật khẩu, gây mất khách. Đúng không? Có kênh nào ngoài email không?
+
+PO: Đúng. Chỉ email thôi.
+
+AI: [Chặng 4 · UC] Tôi đề xuất 3 UC:
+    UC-01 Yêu cầu link reset · UC-02 Đặt lại mật khẩu · UC-03 Hết hạn link.
+    Đủ chưa? Có thiếu UC "giới hạn số lần yêu cầu" không?
+
+PO: Thêm UC giới hạn số lần. …
+```
+
+Kết quả: `product-definition/quen-mat-khau.md` với 4 UC, BR (link hết hạn 15 phút, tối đa 3 lần/giờ), AC, edge case đã chốt.
+
+---
+
+## Anti-pattern
+
+- ❌ Nhảy thẳng từ ý tưởng sang `/generate-prd` (hoặc tệ hơn: sang code) — mất chặng tư duy user/rule/edge-case.
+- ❌ Trả lời chặng cho có, "để AI tự hiểu" — AI sẽ suy diễn và bạn trả giá ở downstream.
+- ❌ Nhồi chi tiết kỹ thuật vào đây — sai altitude, để dành cho Tech-Docs.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Khung intent đã chốt → viết PRD:
+
+➡️ [Bước 2 · Specification — `/generate-prd` · `/refine-prd` · `/review-context`](02-specification.md)

package/docs/02-concepts/pipeline-steps/02-specification.md

@@ -0,0 +1,130 @@
+[← Discovery](01-discovery.md) · [Pipeline Steps](README.md) · [Next: Design-Spec →](03-design-spec.md)
+
+# Bước 2 · Specification — Hình thành đặc tả (PRD)
+
+> **Tóm tắt.** Biến khung intent thành **PRD** chuẩn nghiệp vụ, tinh chỉnh qua 3 lăng kính, rồi qua **gate chất lượng** để PO đóng dấu `approved`.
+> **Commands:** `/generate-prd` → `/refine-prd` → `/review-context`
+
+| | |
+|---|---|
+| **Giai đoạn** | Specification |
+| **Owner** | 👤 Product Owner (SA/Dev review) |
+| **Đầu vào** | `product-definition/*.md` (từ Discovery) |
+| **Đầu ra** | PRD `Status: draft → approved` |
+| **HITL** | 🔴 Cao — `/review-context` sạch critical + PO approve |
+
+---
+
+## Mục đích (Purpose)
+
+PRD là **hợp đồng nghiệp vụ** giữa PO ↔ Dev ↔ AI. Đây là **cổng chất lượng cuối cùng ở thượng nguồn** trước khi phân rã xuống BDD/code. Nếu PRD mơ hồ/lệch, mọi code sinh ra sau đó là "rác hàng loạt". Bước này:
+
+- Viết PRD **thuần ngôn ngữ nghiệp vụ**, đúng cấu trúc, có traceability.
+- Bắt lỗi **trước** khi truyền xuống — qua 3 lăng kính DEV/SA/PO và findings có mã.
+- Chốt một trạng thái `approved` rõ ràng để mở khoá downstream.
+
+---
+
+## Ba lệnh, ba vai trò (Three commands)
+
+| Lệnh | Vai trò | Kết quả |
+|------|---------|---------|
+| `/generate-prd` | **Sinh** PRD draft từ product-definition | PRD `Status: draft` |
+| `/refine-prd` | **Tinh chỉnh** qua 3 lăng kính DEV/SA/PO (fan-out per-UC) | Findings để PO accept/reject |
+| `/review-context` | **Gate chất lượng** — findings P0–P5, phải sạch critical | PO đặt `Status: approved` |
+
+---
+
+## Input (Đầu vào)
+
+- `product-definition/{slug}.md` từ [Discovery](01-discovery.md).
+- Business dictionary / domain-knowledge (nạp tự động).
+- (Umbrella) metadata routing: `Domain` khớp một service key.
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` | PRD: **Metadata · AC · UC · BR · Wireframe · Change Log** |
+| `.agent/review/*-findings.yaml` | Findings của `/refine-prd` & `/review-context` (để Review Board) |
+| Trạng thái `| Status | approved |` trong Metadata | 🔒 Gate mở khoá `/generate-bdd` |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **PO** | Lead: duyệt scope/terminology, accept/reject findings, đặt `Status: approved` |
+| 👤 **SA** | Lăng kính SA trong `/refine-prd` — đọc PRD bằng mắt kiến trúc, viết lại bằng lời nghiệp vụ |
+| 👤 **Dev** | Lăng kính DEV — bắt chỗ mơ hồ sẽ gây khó khi hiện thực |
+| 🤖 **AI** | Draft PRD, fan-out mỗi UC/lăng kính một sub-agent, completeness-critic, sinh findings |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Scope/terminology đã đúng và nhất quán với business dictionary chưa?
+- Có UC/BR/AC nào mơ hồ, mâu thuẫn, hay lạc tầng (altitude) không?
+- PRD đã đủ cấu trúc để phân rã xuống BDD chưa?
+- (Umbrella) PRD route về đúng service chưa?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+**`/generate-prd`** — Round Q&A + confirm domain/terminology → sinh PRD draft đúng template, áp Business Language Guard.
+
+**`/refine-prd`** — fan-out **mỗi UC × 3 lăng kính**:
+- **DEV** — chỗ nào khó hiện thực / thiếu định nghĩa?
+- **SA** — rủi ro kiến trúc, phụ thuộc, nhất quán hệ thống (nhưng viết bằng lời nghiệp vụ).
+- **PO** — giá trị, scope, hoàn chỉnh nghiệp vụ.
+- Rồi một vòng **completeness-critic**: "đã đủ chưa / có lộn tầng không". PO accept/reject từng finding qua **Review Board** (findings YAML), có thể **resume** để áp fix.
+
+**`/review-context` (PRD)** — findings có mã, sạch **critical** mới cho qua:
+
+| Mã | Check |
+|----|-------|
+| **P0** | Umbrella routing (chỉ mode umbrella) — chạy trước, là gate check |
+| **P1** | Terminology (Business Dictionary) |
+| **P2** | Ambiguity (mơ hồ) |
+| **P3** | Domain conflict (xung đột cross-PRD) |
+| **P4** | Structural completeness (đủ section/metadata) |
+| **P5** | Custom criteria (tuỳ chọn) |
+
+> P0 & P3 do orchestrator chạy (cần config/PRD khác); P1/P2/P4/P5 fan-out mỗi nhóm một sub-agent.
+
+---
+
+## HITL / Gate
+
+- 🛑 `/refine-prd`: PO accept/reject **từng** finding — không auto-apply.
+- 🔒 `/review-context`: phải **sạch critical**, sau đó **PO tự đặt** `| Status | approved |`. Không có lệnh `/approve-prd` — "duyệt" = người đặt field trạng thái.
+- Downstream (`/generate-bdd`) đọc field này; `draft` → cảnh báo mềm.
+
+---
+
+## Ví dụ (Example)
+
+```
+/generate-prd quen-mat-khau        → PRD draft (4 UC, BR, AC)
+/refine-prd                        → 12 findings (3 lăng kính)
+   → PO accept 9, reject 3 → /refine-prd (resume) áp 9 fix
+/review-context <PRD>              → P2: "AC UC-02 mơ hồ 'nhanh chóng'"
+   → PO sửa → chạy lại → sạch critical
+   → PO đặt Status: approved  🔒 mở khoá BDD
+```
+
+---
+
+## Anti-pattern
+
+- ❌ Để chi tiết kỹ thuật (retry/timeout/API) trong PRD — lạc altitude; đẩy xuống Tech-Docs.
+- ❌ Đặt `approved` khi còn finding critical — phá gate, hỏng downstream.
+- ❌ Bỏ `/refine-prd` "vì PRD trông ổn" — 3 lăng kính bắt lỗi mắt thường bỏ sót.
+
+---
+
+## Bước tiếp theo (Next step)
+
+PRD `approved` → nếu là FE/App: [Design-Spec](03-design-spec.md); nếu không: thẳng tới [BDD](04-bdd.md).

package/docs/02-concepts/pipeline-steps/03-design-spec.md

@@ -0,0 +1,90 @@
+[← Specification](02-specification.md) · [Pipeline Steps](README.md) · [Next: BDD →](04-bdd.md)
+
+# Bước 3 · Design-Spec — Đặc tả thiết kế UI (chỉ FE/App)
+
+> **Tóm tắt.** Chốt **chi tiết visual bám Figma thật** trước khi sinh BDD giao diện — chỉ áp dụng cho service **Frontend / App**.
+> **Command:** `/generate-design-spec`
+
+| | |
+|---|---|
+| **Giai đoạn** | Design (nhánh FE/App) |
+| **Owner** | 👤 PO / PM (+ Designer) |
+| **Đầu vào** | PRD `approved` + Figma/wireframe |
+| **Đầu ra** | `design-spec/` — spec visual 2 tầng ngôn ngữ |
+| **HITL** | 🟠 Vừa — checkpoint mềm nếu design-spec chưa `approved`/lỗi thời |
+| **Bỏ qua khi** | Service là **backend/system** (không có UI) |
+
+---
+
+## Mục đích (Purpose)
+
+BDD giao diện (`bdd/web/`, `bdd/app/`) cần biết **màn hình có gì, trạng thái nào, tương tác ra sao**. Nếu để `/generate-bdd` tự đoán UI, coverage sẽ thiếu hoặc lệch Figma. Design-Spec:
+
+- Ghi lại **chi tiết visual thật** (component, state, empty/error/loading, navigation) bám Figma.
+- Dùng **2 tầng ngôn ngữ**: mô tả nghiệp vụ cho PO + tham chiếu component cho Dev/Designer.
+- **Lái coverage UI** của BDD — mỗi trạng thái màn hình → scenario tương ứng.
+
+---
+
+## Input (Đầu vào)
+
+- **PRD `approved`** (bước 2).
+- **Figma/wireframe thật** — nguồn chân lý về visual.
+- `domain-knowledge/figma-components/{stack}.md` — quy ước map component theo stack (react, flutter, vue…).
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}*.md` | Đặc tả từng màn hình: layout, component, state, interaction, navigation |
+| Trạng thái `approved` | 🔒 Mềm — `/generate-bdd` cảnh báo nếu design-spec chưa duyệt/lỗi thời |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **PO / PM** | Duyệt design-spec bám đúng Figma & intent |
+| 👤 **Designer** | Nguồn Figma; xác nhận component/state |
+| 🤖 **AI** | Đọc Figma + PRD → sinh design-spec 2 tầng, map component theo stack |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Màn hình gồm những **component & trạng thái** nào (default/empty/loading/error)?
+- Luồng **navigation** giữa các màn ra sao?
+- Mỗi trạng thái ứng với **scenario UI** nào mà BDD phải phủ?
+- Visual có **khớp Figma** không?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+1. Gate chung + xác định service FE/App.
+2. Đọc PRD `approved` + Figma + `figma-components/{stack}.md`.
+3. Sinh design-spec **2 tầng ngôn ngữ**: mô tả nghiệp vụ (PO đọc) + tham chiếu component (Dev dùng).
+4. Đánh dấu các **trạng thái màn hình** để `/generate-bdd` phủ đủ.
+
+---
+
+## HITL / Gate
+
+- 🟠 Checkpoint **mềm**: nếu design-spec **chưa `approved`** hoặc **lỗi thời** so với PRD, `/generate-design-spec` và `/generate-bdd` cảnh báo, PO xác nhận trước khi tiếp.
+
+---
+
+## Anti-pattern
+
+- ❌ Sinh design-spec khi Figma chưa chốt — spec lệch, phải làm lại.
+- ❌ Chạy bước này cho service backend — không có UI để đặc tả.
+- ❌ Nhét business rule mới vào design-spec — rule thuộc PRD, đây chỉ visual.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Design-spec chốt → sinh BDD giao diện:
+
+➡️ [Bước 4 · BDD — `/generate-bdd`](04-bdd.md)

package/docs/02-concepts/pipeline-steps/04-bdd.md

@@ -0,0 +1,120 @@
+[← Design-Spec](03-design-spec.md) · [Pipeline Steps](README.md) · [Next: Tech-Docs →](05-tech-docs.md)
+
+# Bước 4 · BDD — Kịch bản hành vi (Behavior Specification)
+
+> **Tóm tắt.** Phân rã PRD thành các file `.feature` (Gherkin) mang trace metadata — đây là **anchor cứng** mà mọi code/test sau này link về.
+> **Commands:** `/generate-bdd` → `/review-context`
+
+| | |
+|---|---|
+| **Giai đoạn** | Design |
+| **Owner** | 👤 PO (+ Dev review) |
+| **Đầu vào** | PRD `approved` (+ design-spec nếu FE/App) |
+| **Đầu ra** | `bdd/**/*.feature` với `@trace.*`; `@trace.status: approved` |
+| **HITL** | 🔴 Cao — 🛑 UC decomposition + gate findings B1–B6 |
+
+---
+
+## Mục đích (Purpose)
+
+BDD là **trái tim của traceability**. Mỗi scenario là một đơn vị hành vi có thể kiểm chứng; mỗi dòng code sau này link `@trace.source` về một scenario. Cấu trúc UC/SC quyết ở đây **tác động tới mọi file code phía sau** — nên đây là checkpoint nặng.
+
+- Phân rã PRD → **UC → Scenario** bằng Gherkin (Given/When/Then).
+- Gắn **trace metadata** (`@trace.id/scenario/business_rules/bdd_version/prd_version`).
+- Gate B1–B6 đảm bảo BDD phủ đủ PRD, đúng thuật ngữ, đúng luật Gherkin.
+
+---
+
+## Input (Đầu vào)
+
+- **PRD `approved`** (gate mềm — cảnh báo nếu `draft`, áp mọi mode).
+- **Design-spec** (nếu FE/App) — lái coverage UI.
+- `feature.template` (SoT skeleton) + `bdd-writing-guide.md`.
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `specs/{domain}/{prd-slug}/bdd/{web\|app\|system}/{UC-ID}*.feature` | Scenario Gherkin + tag `@trace.*` + Coverage Matrix |
+| `@trace.status: approved` (sau review) | 🔒 Mở khoá `/generate-tech-docs` |
+
+> BDD chia theo **platform/scope**: `web/`, `app/`, `system/` (cross-service).
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **PO** | Quyết cấu trúc UC/SC; xác nhận decomposition đúng intent |
+| 👤 **Dev** | Lăng kính review BDD (side-effect, khả thi) |
+| 🤖 **AI** | Phân rã UC→SC; PRD lớn → orchestrator **spawn mỗi UC một sub-agent**; sinh Gherkin + trace |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- PRD phân rã thành những **UC/Scenario** nào? Có thiếu/thừa không?
+- Mỗi scenario có phủ một **AC/BR** cụ thể không (B1 coverage)?
+- Gherkin có đúng luật (R1–R10), đúng thuật ngữ (business dictionary) không?
+- Có **side-effect** nào chưa được scenario mô tả không (B6)?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+**`/generate-bdd`**
+1. Gate: kiểm PRD `Status: approved` (cảnh báo mềm mọi mode).
+2. 🛑 **UC decomposition checkpoint** — trình danh sách UC/SC để PO chốt.
+3. PRD lớn → **fan-out**: orchestrator giao mỗi UC cho một sub-agent (`_agent_mode`) sinh song song.
+4. Sinh `.feature` theo `feature.template`, gắn `@trace.*`, dựng Coverage Matrix.
+5. Có thể incorporate **scenario proposal** đã `accepted` từ tester (xem [Feedback Loop](10-feedback-loop.md)).
+
+**`/review-context` (BDD)** — findings có mã, sạch critical mới `approved`:
+
+| Mã | Check |
+|----|-------|
+| **B1** | PRD coverage — mọi AC/UC được phủ |
+| **B2** | Terminology & entity (đúng dictionary) |
+| **B3** | Gherkin rules (R1–R10) |
+| **B4** | Compliance (C.1–C.5) |
+| **B5** | Metadata & structural (đủ `@trace` header) |
+| **B6** | Side-effect completeness |
+
+> B1–B6 fan-out mỗi nhóm một sub-agent quét toàn file cho nhóm đó.
+
+---
+
+## HITL / Gate
+
+- 🛑 **UC decomposition** — điểm dừng quan trọng nhất: cấu trúc sai ở đây nhân xuống mọi code.
+- 🔒 `/review-context` sạch **critical** → đặt `@trace.status: approved` → mở khoá Tech-Docs.
+
+---
+
+## Ví dụ (Example)
+
+```gherkin
+@trace.id=UC-02 @trace.scenario=SC-02.1
+@trace.business_rules=BR-03 @trace.bdd_version=1.0 @trace.prd_version=1.2
+Scenario: Đặt lại mật khẩu với link còn hạn
+  Given người dùng mở link reset còn hiệu lực
+  When nhập mật khẩu mới hợp lệ và xác nhận
+  Then hệ thống cập nhật mật khẩu và cho đăng nhập lại
+```
+
+---
+
+## Anti-pattern
+
+- ❌ Sinh code khi BDD còn `draft` (chưa `approved`).
+- ❌ Nhét thuật ngữ kỹ thuật (selector, API, retry) vào step Gherkin — vi phạm B3/R3.
+- ❌ Bỏ qua UC decomposition checkpoint — cấu trúc UC lệch kéo cả pipeline lệch.
+
+---
+
+## Bước tiếp theo (Next step)
+
+BDD `approved` → thiết kế kỹ thuật:
+
+➡️ [Bước 5 · Tech-Docs — `/generate-tech-docs` · `/review-tech-docs`](05-tech-docs.md)