@anhth2/spec-driven-dev-plugin 0.12.0 → 0.14.0

package/docs/04-operations/sync-and-update.md

@@ -17,7 +17,7 @@
 7. [Project Lessons — không để AI lặp lỗi](#7-project-lessons--không-để-ai-lặp-lỗi)
 8. [Câu hỏi thường gặp](#8-câu-hỏi-thường-gặp)
 
-> Pipeline QC native (`/qc-*`) có trang riêng — xem [Guide · QC Automation](../02-guides/qc-automation.md). Ở đây chỉ điểm qua chỗ `/sync` chạm vào QC.
+> Pipeline QC native (`/qc-*`) có trang riêng — xem [chương QC Automation](../02-guides/tester/qc-automation.md). Ở đây chỉ điểm qua chỗ `/sync` chạm vào QC.
 
 ---
 
@@ -79,7 +79,7 @@ Service submodules không bị ảnh hưởng — luôn checkout đúng SHA mà
 > **Umbrella mode:** `/update-framework` chỉ cần chạy ở **umbrella root**. Service submodule chỉ chứa `.agent/project-context.yaml` (config), không có command files → không cần nâng cấp riêng.
 
 > ⚠️ **`--init` ghi đè TOÀN BỘ `.agent/`** (gồm cả `.agent/skills/qc/`) — KHÔNG đụng `.agent/project-context.yaml` (config của bạn) và mọi thứ **ngoài** `.agent/`.
-> **Hệ quả với skill QC:** nếu QC sửa skill **trực tiếp trong `.agent/skills/qc/`** thì sẽ **mất sau upgrade**. Để skill QC tồn tại độc lập, trỏ `paths.qc_skills_dir` (trong `.agent/project-context.yaml`) tới **repo QC riêng / submodule** (vd `qc-base/.claude/skills`) — `qc_skills_dir` nằm ngoài `.agent/` nên upgrade không bao giờ chạm. Chi tiết: [Guide · QC Automation](../02-guides/qc-automation.md#skill-sourcing--upgrade-safety).
+> **Hệ quả với skill QC:** nếu QC sửa skill **trực tiếp trong `.agent/skills/qc/`** thì sẽ **mất sau upgrade**. Để skill QC tồn tại độc lập, trỏ `paths.qc_skills_dir` (trong `.agent/project-context.yaml`) tới **repo QC riêng / submodule** (vd `qc-base/.claude/skills`) — `qc_skills_dir` nằm ngoài `.agent/` nên upgrade không bao giờ chạm. Chi tiết: [chương QC Automation](../02-guides/tester/qc-automation.md#skill-sourcing--upgrade-safety).
 
 ---
 
@@ -96,30 +96,35 @@ Claude Code luôn mở ở **umbrella repo** (không mở trong service submodul
                       │  giữ pointer (SHA) tới từng submodule
         ┌─────────────┴──────────────┐
         ▼                             ▼
- SPEC SUBMODULE                SERVICE SUBMODULE(s)
- (PO sở hữu · origin riêng)    (Dev sở hữu · origin riêng)
- specs/prd · specs/bdd               src/
- specs/design-spec                   .trace/*.tsv   (qc_status + dev_selftest)
- specs/tech-docs (API contract)
- feedback/ (bug · proposal · prd-change-request)
+ SPEC SUBMODULE                       SERVICE SUBMODULE(s)
+ (PO sở hữu · origin riêng)           (Dev sở hữu · origin riêng)
+ specs/prd · specs/bdd (web/app/system)     src/   (chỉ code + tooling)
+ specs/design-spec · specs/tech-docs
+ feedback/ (bug · proposal · prd-change)
+ .trace/*.tsv  (qc_status + dev_selftest — write area của dev/QC)
 ```
 
+> **Tất cả spec + `.trace/` ở SPEC repo; service submodule chỉ chứa code.** PRD/BDD/design-spec/tech-docs read-only với dev/QC; `feedback/` và `.trace/` là vùng dev/QC được ghi.
+
 | Role | Tạo gì | Repo đích | Push mấy tầng |
 |------|--------|-----------|---------------|
-| **PO** | PRD · BDD · design-spec · sửa PRD theo change-request | SPEC repo | **1 tầng** (spec repo) |
-| **Dev (FE/BE)** | tech-docs · code · dev test (`dev_selftest`) | tech-docs → SPEC repo · code + `.trace/` → SERVICE | code: **2 tầng** (service → umbrella pointer) · tech-docs: thêm 1 tầng ở spec repo |
-| **QC** | analysis/test-cases · `qc_status` · bug/gap | artifacts → `{qc_dir}/{UC-ID}/` (umbrella root `docs/`) · `qc_status` → SERVICE `.trace/` · bug/gap → SPEC `feedback/` | trace: **2 tầng** · feedback: 1 tầng (spec repo) |
-| **Tester** | bug report · scenario proposal · prd-change-request | SPEC repo `feedback/` | **1 tầng** (spec repo) — read-only trên specs/code |
+| **PO** | PRD · BDD (web/app/system) · design-spec · sửa PRD theo change-request | SPEC repo | **1 tầng** (spec repo) |
+| **Dev (FE/BE)** | tech-docs · code · dev test (`dev_selftest`) | tech-docs → SPEC repo · `dev_selftest` → SPEC `.trace/` · code → SERVICE | code: **2 tầng** (service → umbrella pointer) · tech-docs + trace: 1 tầng ở spec repo (cross-repo write) |
+| **QC / Tester (QA)** | QC pipeline (analysis/test-cases · `qc_status`) · bug report · scenario proposal · prd-change-request | artifacts → `{qc_dir}/{UC-ID}/` (umbrella `docs/`) · `qc_status` → SPEC `.trace/` · bug/proposal/change-request → SPEC `feedback/` | artifacts: 1 tầng (umbrella) · trace + feedback: **1 tầng** (spec repo) — read-only trên specs/code |
+
+> **QC = Tester (một vai trò QA):** cùng một người chạy pipeline `/qc-*` (sinh `qc_status` chính thức) **và** `/report-bug` · `/propose-scenario`. Phân biệt thật sự là **Dev self-test (`dev_selftest`) vs QC/Tester authoritative (`qc_status`)** — không phải QC vs Tester.
 
 Thứ tự bàn giao (mỗi mũi tên = `git push` rồi role kế tiếp `/sync`):
 
 ```
-PO ─push spec─▶ Dev /sync ─code 2 tầng─▶ QC /sync ─qc_status 2 tầng + bug/gap 1 tầng─▶ PO/Dev /sync
- BDD approved      tech-docs + src         test + report            fix code / sửa PRD → /generate-bdd lại
-                                                                    (vòng feedback: xem Bug Flow §9)
+PO ─push spec─▶ Dev /sync ─code 2 tầng─▶ QC/Tester /sync ─qc_status + bug 1 tầng (spec)─▶ PO/Dev /sync
+ BDD approved      tech-docs + src         test + report                 fix code / sửa PRD → /generate-bdd lại
+                                                                         (vòng feedback: xem Bug Flow §9)
 ```
 
-> **`qc_status` ở service nhưng analysis docs ở umbrella:** `qc_dir` (mặc định `docs/`) **không** auto-route theo service như `trace_dir`. Muốn artifacts QC nằm cùng service submodule (push chung 2 tầng với trace) → set `paths.qc_dir` trong `{service}/.agent/project-context.yaml`, hoặc trỏ ra repo QC riêng.
+> **`qc_status` ở spec repo nhưng QC analysis docs ở umbrella root:** `qc_status` ghi vào `.trace/` (đã dồn về `{spec_source}/.trace`), còn `qc_dir` (analysis/test-cases, mặc định `docs/`) **không** auto-route — nằm ở umbrella root. Muốn artifacts QC nằm chỗ khác → set `paths.qc_dir` trong `.agent/project-context.yaml`, hoặc trỏ ra repo QC riêng.
+
+> **Git flow `git` cụ thể cho từng role** (ví dụ end-to-end một feature, kèm `cd`/`add`/`commit`/`push` thực tế): [§4.7](#47--git-flow-cụ-thể-theo-role-ví-dụ-feature-ft-042-checkout-domain-payment).
 
 ### 4.1 — Clone lần đầu
 
@@ -163,10 +168,10 @@ git push
 ### 4.4 — Commit 2 tầng (thay đổi trong service submodule)
 
 ```bash
-# Tầng 1: commit trong service submodule
+# Tầng 1: commit trong service submodule (CHỈ code — BDD, tech-docs, .trace đều ở spec repo)
 cd user-service
-git add specs/bdd/ src/
-git commit -m "feat(FEAT-01): add BDD and implementation"
+git add src/
+git commit -m "feat(FEAT-01): implementation"
 git push origin main
 cd ..
 
@@ -179,10 +184,12 @@ git push
 > ⚠️ **PHẢI push cả 2 tầng.** Push umbrella mà quên push submodule → người khác pull về bị lỗi "commit không tồn tại".
 >
 > **Tech-docs (API contract):** khi `setup.spec_source` được set, tech-design **luôn** nằm ở `{spec_source}/specs/tech-docs` (spec repo chung) — commit + push riêng trong spec submodule, FE/App đọc qua `/sync`. Per-service tech-docs chỉ dùng khi **không** có `spec_source`.
+>
+> **`.trace/` cũng ở spec repo:** khi `spec_source` set, `/generate-code` · `/dev-run-test` · `/qc-run-test` chạy trong service nhưng ghi trace vào `{spec_source}/.trace` → commit + push **trong spec submodule** (1 tầng, cross-repo, giống `feedback/`). Service submodule **không** còn `.trace/`.
 
-### 4.5 — Lỡ tay sửa file trong spec submodule (read-only)
+### 4.5 — Lỡ tay sửa **spec** trong spec submodule (PRD/BDD/design-spec/tech-docs read-only)
 
-Spec submodule là **read-only** cho dev/tester. Nếu lỡ sửa → bỏ thay đổi:
+PRD/BDD/design-spec/tech-docs trong spec submodule là **read-only** cho dev/tester (chỉ PO sửa). `feedback/` và `.trace/` thì dev/QC được ghi. Nếu lỡ sửa spec → bỏ thay đổi:
 
 ```bash
 cd my-project-specs
@@ -201,6 +208,123 @@ Muốn cập nhật PRD → báo PO sửa trong spec repo của họ rồi push.
 | Submodule ở `detached HEAD` | Bình thường khi dùng submodule | Không cần lo nếu không sửa file trong đó |
 | Conflict trong submodule pointer | 2 người cùng update submodule | `git checkout --theirs <sub> && git add <sub>` |
 
+### 4.7 — Git flow cụ thể theo role (ví dụ feature **FT-042 Checkout**, domain `payment`)
+
+Topology giả định cho mọi ví dụ dưới đây:
+
+| Repo | Vai trò | Ai sở hữu |
+|------|---------|-----------|
+| `my-project/` | **umbrella** — Claude Code mở ở đây, giữ pointer | team |
+| `my-project-specs/` | **spec** submodule — PRD/BDD/design-spec/tech-docs + `.trace/` + `feedback/` | PO |
+| `payment-be/` | **service** submodule — chỉ code BE | BE dev |
+| `my-project-web/` | **service** submodule — chỉ code FE | FE dev |
+
+> **Quy tắc 1 dòng:** chỉ **code** mới push **2 tầng** (service → umbrella pointer). Mọi thứ khác — PRD/BDD/tech-docs/`.trace/`/`feedback/` ở spec repo, và QC artifacts ở umbrella — đều **1 tầng**.
+
+**① PO — 1 tầng (spec repo)**
+```bash
+cd my-project-specs && git pull
+# /generate-prd · /generate-design-spec · /generate-bdd (web/app/system) · set @trace.status: approved
+git add specs/prd/payment/FT-042-checkout.md \
+        specs/design-spec/payment/FT-042-checkout-design.md \
+        specs/bdd/payment/system/FT-042-UC1-checkout-system.feature \
+        specs/bdd/payment/web/FT-042-UC1-checkout-web.feature \
+        specs/bdd/payment/app/FT-042-UC1-checkout-app.feature
+git commit -m "feat(payment): FT-042 checkout — PRD + design-spec + BDD (web/app/system)"
+git push origin main          # → báo Dev team chạy /sync
+```
+
+**② BE Dev — code 2 tầng · tech-docs + trace 1 tầng (cross-repo)**
+```bash
+cd my-project && /sync        # umbrella root: pull spec + services + Living Docs
+
+# (a) tech-docs (API contract) → SPEC repo  [1 tầng]
+#     /generate-tech-docs payment/system/FT-042-UC1 ghi vào my-project-specs/specs/tech-docs/payment/
+cd my-project-specs
+git add specs/tech-docs/payment/FT-042-UC1-tech-design.md
+git commit -m "docs(payment): FT-042 UC1 BE API contract"
+git push origin main
+cd ..
+
+# (b) code → SERVICE repo  [Tầng 1]
+#     /generate-code payment/system/FT-042-UC1 ghi vào payment-be/src/
+cd payment-be
+git checkout -b feat/FT-042-checkout
+git add src/
+git commit -m "feat(payment): FT-042 UC1 checkout endpoint + service"
+git push origin feat/FT-042-checkout      # → mở MR trong payment-be
+cd ..
+
+# (c) dev_selftest → SPEC repo .trace  [1 tầng, cross-repo]
+#     /dev-run-test ghi my-project-specs/.trace/FT-042.tsv
+cd my-project-specs
+git add .trace/FT-042.tsv
+git commit -m "chore(trace): FT-042 dev_selftest=pass"
+git push origin main
+cd ..
+
+# (d) sau khi MR payment-be merge → bump umbrella pointer  [Tầng 2]
+cd payment-be && git checkout main && git pull && cd ..
+git add payment-be
+git commit -m "chore: bump payment-be → FT-042 checkout"
+git push origin main
+```
+
+**③ FE/Web Dev — 2 phase; push giống BE (code 2 tầng · tech-docs + trace 1 tầng)**
+```bash
+cd my-project && /sync
+
+# Phase 1 — UI + mock (chưa cần BE deploy)
+#   /generate-code payment/web/FT-042-UC1 --phase=ui  → code trong my-project-web
+cd my-project-web
+git checkout -b feat/FT-042-checkout-ui
+git add src/
+git commit -m "feat(payment): FT-042 checkout UI + mock adapter"
+git push origin feat/FT-042-checkout-ui
+cd ..
+
+# Phase 2 — khi BE System BDD + contract approved:
+#   (a) FE tech-design (§2b test-ids + §4 API map) → SPEC repo  [1 tầng]
+cd my-project-specs
+git add specs/tech-docs/payment/FT-042-UC1-tech-design-web.md
+git commit -m "docs(payment): FT-042 UC1 FE web tech-design (§2b test-ids + §4 API)"
+git push origin main
+cd ..
+#   (b) /generate-code payment/web/FT-042-UC1 --phase=integration → wire API thật  [Tầng 1]
+cd my-project-web
+git add src/
+git commit -m "feat(payment): FT-042 wire real checkout API"
+git push origin feat/FT-042-checkout-ui
+cd ..
+# (c) dev_selftest → spec .trace  +  (d) bump umbrella pointer sau merge — giống BE bước (c)(d)
+```
+
+**④ QC / Tester (một vai trò QA) — artifacts 1 tầng (umbrella) · qc_status + bug/proposal 1 tầng (spec repo)**
+
+> QC và Tester là **cùng một người**: vừa chạy pipeline `/qc-*` (sinh `qc_status` chính thức) vừa `/report-bug` · `/propose-scenario`. Read-only trên specs + code.
+
+```bash
+cd my-project && /sync         # đọc specs read-only
+# /qc-analyze · /qc-plan · /qc-design-test · /qc-review · /qc-run-test · /qc-report
+
+# (a) artifacts phân tích/test-case → {qc_dir}/{UC-ID}/ (qc_dir mặc định = docs/) → commit UMBRELLA  [1 tầng]
+git add docs/FT-042/           # REQUIREMENT_ANALYSIS.md · TEST_PLAN.md · test-cases/*.Test.md
+git commit -m "qc(payment): FT-042 analysis + test design"
+git push origin main
+
+# (b) qc_status → SPEC .trace  +  bug/proposal/change-request → SPEC feedback/  [1 tầng, cross-repo]
+cd my-project-specs
+git add .trace/FT-042.tsv
+git add feedback/bugs/FT-042-UC1-SC3-bug.md              # /report-bug khi qc_status=fail
+#   hoặc: feedback/bdd-proposals/FT-042-new-scenario.md  # /propose-scenario (edge case ngoài BDD)
+#   hoặc: feedback/prd-change-requests/FT-042-change.md   # đề xuất sửa PRD
+git commit -m "qc(payment): FT-042 qc_status=fail (SC3) + bug report"
+git push origin main           # → PO/Dev /sync thấy '📥 New tester feedback' → /fix-bug · promote
+cd ..
+```
+
+> **Tóm tắt số tầng push:** chỉ **code = 2 tầng** (service → umbrella pointer); PRD/BDD/tech-docs/`.trace`/`feedback` (spec repo) = **1 tầng**; QC artifacts `qc_dir` (umbrella) = **1 tầng**. Lỡ tay sửa spec read-only → §4.5.
+
 ---
 
 ## 5. Living Docs sync
@@ -211,12 +335,12 @@ Living Docs panel hiển thị trạng thái trace của toàn bộ feature. Ref
 /validate-traces
 ```
 
-- Đọc TSVs từ **tất cả** service submodule (`.trace/*.tsv` là authoritative — commit ở mỗi service).
+- Đọc TSVs từ **một nơi duy nhất** `{spec_source}/.trace/*.tsv` (authoritative — commit trong spec repo; mỗi scenario mang `@trace.service` để biết service nào). KHÔNG còn quét/merge từng service.
 - Cập nhật cột `dev_selftest` (pass/fail/not_run) + `dev_selftest_at`.
-- Ghi canonical `trace-report.json` + bản TSV mirror → `{spec_source}/.living-docs/` (gitignored).
+- Ghi `trace-report.json` → `{spec_source}/.living-docs/` (generated, gitignored).
 - Mirror thêm về `./.trace` của workspace hiện tại → panel không rỗng kể cả khi đứng trong 1 service submodule đơn lẻ.
 
-> **Report nằm ở đâu:** canonical `trace-report.json` + TSV mirror ở **spec module** tại `{spec_source}/.living-docs/` (gitignored, regenerate bởi `/sync` hoặc `/validate-traces`). Authoritative per-service `.trace/*.tsv` vẫn commit trong mỗi service.
+> **Report nằm ở đâu:** authoritative `.trace/*.tsv` ở **spec module** `{spec_source}/.trace/` (committed — một chỗ cho PM). Report `trace-report.json` ở `{spec_source}/.living-docs/` + panel mirror `./.trace` đều **generated, gitignored** — regenerate bởi `/sync` hoặc `/validate-traces`.
 >
 > **.gitignore:** thêm `.trace/` trong repo hiện tại **và** `.living-docs/` trong spec module — đều là mirror read-only, không commit.
 
@@ -246,7 +370,7 @@ git pull
 /review-context --fix {prd-file}         # auto-fix vấn đề nhỏ
 # → update @trace.status: approved khi PRD sẵn sàng
 /generate-design-spec {prd-file}         # FE/App
-/generate-bdd {prd-file}                 # → web / app / system (lần lượt)
+/generate-bdd {prd-file}                 # outside-in: web → app → system (System BDD tổng hợp từ web+app)
 
 git add specs/
 git commit -m "feat({domain}): add {TICKET-ID} PRD, design spec, and BDD"
@@ -265,16 +389,17 @@ git add my-project-specs && git commit -m "chore: sync specs" && git push
 # Đọc Web BDD do PO generate (KHÔNG tự generate BDD):
 #   my-project-specs/specs/bdd/{domain}/web/{TICKET-ID}-UC*.feature
 
-/generate-tech-docs {domain}/{TICKET-ID}-UC1
-/review-tech-docs   {domain}/{TICKET-ID}-UC1
-
-# ── BE chưa sẵn sàng ──
-/generate-code {domain}/{TICKET-ID}-UC1 --phase=ui      # UI + mock adapter (tester test ngay)
+# ── BE chưa deploy API → làm UI trước ──
+/generate-code {domain}/web/{TICKET-ID}-UC1 --phase=ui  # UI + mock (shape: BE contract nếu có, else System BDD + warn)
 /dev-gen-test  {domain}/{TICKET-ID}-UC1
 /review-code   {files-changed}
-/dev-run-test                                            # dev self-check (dev_selftest)
+/dev-run-test                                           # dev self-check (dev_selftest)
+
+# ── Khi BE đã có System BDD + tech-docs (API contract) approved ──
+/generate-tech-docs {domain}/web/{TICKET-ID}-UC1        # FE client design — GATED: cần System BDD + BE contract
+/review-tech-docs   {domain}/{TICKET-ID}-UC1-web        # SA/Lead review (bump revision)
 # → sau khi sign-off gate approved:
-/generate-code {domain}/{TICKET-ID}-UC1 --phase=integration   # wire API thật
+/generate-code {domain}/web/{TICKET-ID}-UC1 --phase=integration   # wire API thật theo §4 FE tech-design
 
 # ── API đã có sẵn ──
 /generate-code {domain}/{TICKET-ID}-UC1                  # không cần --phase
@@ -282,7 +407,7 @@ git add my-project-specs && git commit -m "chore: sync specs" && git push
 /review-code   {files-changed}
 /dev-run-test
 
-# Commit 2 tầng (xem §4.4)
+# Commit 2 tầng (code) + 1 tầng (tech-docs/trace) — git flow cụ thể: §4.7 ②③
 ```
 
 ### BE Dev — Nhận task mới
@@ -302,12 +427,12 @@ cd my-project-be
 /review-code        {files-changed}      # AI lặp lỗi → accept "Record as lesson?"
 /dev-run-test
 
-# Commit 2 tầng vào đúng service submodule theo domain (xem §4.4)
+# Commit 2 tầng vào service submodule theo domain + tech-docs/trace 1 tầng — git flow cụ thể: §4.7 ②
 ```
 
-### QC — Chạy native QC pipeline (tóm tắt)
+### QC / Tester — Chạy native QC pipeline (tóm tắt)
 
-Điều kiện: BDD đã `approved`. Module `qc-playwright` (Python + pytest-playwright + Page Object).
+QC và Tester là **một vai trò QA** (xem [Tester guide](../02-guides/tester/README.md)) — cùng người chạy pipeline `/qc-*` **và** `/report-bug` · `/propose-scenario`. Điều kiện: BDD đã `approved`. Module `qc-playwright` (Python + pytest-playwright + Page Object).
 
 ```bash
 cd my-project-web
@@ -316,7 +441,7 @@ cd my-project-web
 /validate-traces            # refresh dashboard → qc_status hiện trên Living Docs
 ```
 
-> `/qc-run-test` ghi `qc_status` + `qc_run_at` vào trace TSV. Chi tiết từng layer: [Guide · QC Automation](../02-guides/qc-automation.md).
+> `/qc-run-test` ghi `qc_status` + `qc_run_at` vào trace TSV. Chi tiết từng layer: [chương QC Automation](../02-guides/tester/qc-automation.md). Git flow cụ thể (artifacts umbrella + qc_status/bug/proposal → spec): §4.7 ④ (QC/Tester là một role).
 
 ---
 
@@ -346,7 +471,7 @@ A: Không. Chỉ cài ở umbrella repo. Service submodule là git repo thườn
 A: Luôn ở **umbrella repo** — có config và thấy được cả spec submodule lẫn service submodule.
 
 **Q: Generate BDD ra file ở đâu?**
-A: Phụ thuộc `@trace.domain` trong PRD. Context-loader tra `services.{domain}.specs_dir`. Vd `@trace.domain: user` → `user-service/specs/bdd/user/`.
+A: Khi có `spec_source` (umbrella) → **spec repo**: `{spec_source}/specs/bdd/{domain}/…` (tất cả BDD web/app/system đều ở đây, cross-team). Trace `.tsv` **cũng** ở spec repo (`{spec_source}/.trace`) — một chỗ cho PM. Service submodule chỉ chứa code. Chỉ khi KHÔNG có `spec_source` thì BDD + trace mới per-service.
 
 **Q: Quên push service submodule, chỉ push umbrella, người khác báo lỗi?**
 A: `cd <service> && git push origin main` — xong, người khác pull lại hết lỗi.

package/docs/05-reference/README.md

@@ -12,6 +12,7 @@ Dùng mục này khi bạn đã biết mình muốn làm gì và chỉ cần tra
 
 | Trang | Nội dung |
 |-------|----------|
+| [Command Cheat-Sheet](command-cheatsheet.md) | **Bắt đầu ở đây nếu bối rối:** bản đồ 1 trang — luồng end-to-end (ai chạy gì), chọn lệnh review nào, vòng review→Board→resume, giải mã flag `--fix`/`--resume`. |
 | [Command Reference](commands.md) | Bảng đầy đủ MỌI slash command — gom theo phase, kèm input/output/when. Cộng phần Command Internals (step architecture). |
 | [Trace TSV Schema](trace-schema.md) | Header chuẩn của `.trace/{UC-ID}.tsv`, ý nghĩa từng cột (gồm `dev_selftest`, `qc_status`…), các `@trace.*` tag, và JSON report. |
 | [Stack Modules](modules.md) | 15 module dưới `modules/`, cách gom theo `platform_type` (backend / web-frontend / mobile), và module QC `qc-playwright`. |
@@ -20,6 +21,8 @@ Dùng mục này khi bạn đã biết mình muốn làm gì và chỉ cần tra
 
 ## Điều hướng nhanh
 
+- **"Tôi nên chạy lệnh nào / theo thứ tự nào?"** → [Command Cheat-Sheet](command-cheatsheet.md)
+- **"Review PRD/BDD/tech/code dùng lệnh nào? `--fix` vs `--resume`?"** → [Command Cheat-Sheet](command-cheatsheet.md)
 - **"Lệnh này nhận gì, sinh ra gì?"** → [Command Reference](commands.md)
 - **"Cột `qc_status` vs `dev_selftest` khác nhau thế nào?"** → [Trace TSV Schema](trace-schema.md)
 - **"Stack của tôi map sang module nào?"** → [Stack Modules](modules.md)

package/docs/05-reference/command-cheatsheet.md

@@ -0,0 +1,147 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Command Cheat-Sheet
+
+# Command Cheat-Sheet — luồng & chọn lệnh
+
+> Bối rối không biết **chạy lệnh nào, theo thứ tự nào, ai chạy**? Trang này là bản đồ 1 trang. Chi tiết Input/Output từng lệnh: [Command Reference](commands.md).
+
+- [Luồng end-to-end (ai chạy gì)](#luồng-end-to-end-ai-chạy-gì)
+- [Tôi muốn REVIEW thứ này → dùng lệnh nào?](#tôi-muốn-review-thứ-này--dùng-lệnh-nào)
+- [Vòng review chuẩn: 3 bước (review → Board → resume)](#vòng-review-chuẩn-3-bước-review--board--resume)
+- [Giải mã flag: mặc định vs --fix vs --resume](#giải-mã-flag-mặc-định-vs---fix-vs---resume)
+- [QC pipeline — 6 bước tuần tự](#qc-pipeline--6-bước-tuần-tự)
+- [dev-* vs qc-* — đừng nhầm](#dev--vs-qc---đừng-nhầm)
+
+---
+
+## Luồng end-to-end (ai chạy gì)
+
+Mỗi mũi tên = "xong cái trước mới sang cái sau". Nhãn dưới mỗi lệnh là **vai trò** chạy nó.
+
+```mermaid
+flowchart LR
+  A["/define-product<br/><b>PO</b>"] --> B["/generate-prd<br/><b>PO</b>"]
+  B --> C["/refine-prd<br/><b>PO</b> + Board"]
+  C --> D["/review-context (PRD)<br/><b>PO</b> · cổng chất lượng"]
+  D --> E["/generate-design-spec<br/><b>PO</b> (chỉ FE/App)"]
+  E --> F["/generate-bdd<br/><b>PO</b> · web→app→system"]
+  F --> G["/review-context (BDD)<br/><b>SA/Dev</b>"]
+  G --> H["/generate-tech-docs<br/><b>Dev</b> · BE trước, FE sau"]
+  H --> I["/review-tech-docs<br/><b>Dev</b> + Board"]
+  I --> J["/generate-code<br/><b>Dev</b>"]
+  J --> K["/review-code<br/><b>Dev</b> · 4 lens"]
+  K --> L["/dev-gen-test → /dev-run-test<br/><b>Dev</b> · self-check"]
+  L --> M["/qc-* (6 bước)<br/><b>QC/Tester</b>"]
+  M --> N["/validate-traces<br/><b>Tech Lead</b>"]
+```
+
+> **BE bỏ qua Design Spec** (bước E) — đọc PRD trực tiếp rồi `/generate-bdd`. **Full-stack/không tách mock** → `/generate-code` một lần (bỏ qua FE 2-phase). Cross-cutting (`/sync`, `/fix-bug`, `/debug`, `/learn`, `/report-bug`, `/propose-scenario`) chạy bất cứ lúc nào, không nằm trong chuỗi này.
+
+<details>
+<summary>Bản text (ASCII fallback)</summary>
+
+```
+PO ───────────────────────────────────────────────────────────────────────────
+  /define-product → /generate-prd → /refine-prd → /review-context(PRD)
+                                                   → /generate-design-spec (FE/App)
+                                                   → /generate-bdd (web→app→system)
+SA/Dev ────────────────────────────────────────────────────────────────────────
+  /review-context(BDD) → /generate-tech-docs → /review-tech-docs
+                       → /generate-code → /review-code → /dev-gen-test → /dev-run-test
+QC/Tester ──────────────────────────────────────────────────────────────────────
+  /qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+Tech Lead ──────────────────────────────────────────────────────────────────────
+  /validate-traces
+```
+</details>
+
+---
+
+## Tôi muốn REVIEW thứ này → dùng lệnh nào?
+
+Có **4 lệnh review** cho **4 loại artifact khác nhau**. Đây là điểm hay nhầm nhất:
+
+| Tôi muốn review… | Cách dùng (ví dụ) | Nó kiểm cái gì | Ai chạy |
+|---|---|---|---|
+| **PRD — nội dung & độ đầy đủ** | `/refine-prd specs/prd/auth/FEAT-01-login.md` | 4 lens QA·DEV·SA·PO: AC có test được? edge case? scope rõ? | PO |
+| **PRD — chất lượng trước khi approve** | `/review-context specs/prd/auth/FEAT-01-login.md` | P-checks: banned term, mơ hồ, mâu thuẫn PRD khác, thiếu section, routing `@trace.domain` | PO |
+| **BDD `.feature`** | `/review-context specs/bdd/auth/system/FEAT-01-UC1-login.feature` | B-checks: mỗi AC/BR → có ≥1 scenario? Gherkin R1–R10, compliance C1–C5 | SA/Dev |
+| **Tech design** | `/review-tech-docs tech-docs/auth/FEAT-01-UC1-tech-design.md` | T-checks: đúng layer/architecture, entity, trace BDD, cross-team API sign-off | Dev/SA |
+| **Code** | `/review-code FEAT-01-UC1` | 4 lens: Security · Performance · Architecture · Test coverage | Dev |
+
+> **Vì sao PRD có 2 lệnh review?** `/refine-prd` làm **trước** (cải thiện nội dung, fan-out 4 lens). `/review-context` làm **sau** như **cổng chất lượng cuối** trước khi approve + sang BDD. Thứ tự: `generate-prd → refine-prd → review-context → approve`.
+>
+> **Vì sao `/review-context` dùng cho cả PRD lẫn BDD?** Nó tự nhận loại theo file: `.md` trong `prd/` → PRD mode (P-checks); `.feature` → BDD mode (B-checks). Cùng một "cổng chất lượng", hai bộ tiêu chí.
+
+---
+
+## Vòng review chuẩn: 3 bước (review → Board → resume)
+
+Mọi lệnh review (`/refine-prd`, `/review-context`, `/review-tech-docs`) đều chạy **cùng một vòng 3 bước**. Lệnh review **không sửa file** — nó chỉ ghi ra findings; bạn duyệt ở Review Board; rồi `--resume` mới áp dụng.
+
+```
+①  /refine-prd {file}                 ②  Mở Review Board (extension)        ③  /…  --resume {file}
+   ───────────────────────────           ──────────────────────────────        ──────────────────────────
+   PHÂN TÍCH (read-only)        →         DUYỆT từng finding:            →       ÁP DỤNG cái đã accept
+   ghi .agent/review/                     ✓Accept ✎Modify ⏸Defer ✗Reject        + bump version + changelog
+   {slug}-findings.yaml                   💬 Giải thích (nếu khó hiểu)
+```
+
+- **① không đụng vào file gốc.** An toàn chạy bất cứ lúc nào.
+- **② Review Board** = panel của extension *Spec Driven Dev*. Right-click file `*-findings.yaml` → Open Review Board, hoặc bấm thông báo khi findings vừa tạo. Finding khó hiểu → bấm **💬 Giải thích** (no-tech + đề xuất phương án, chờ confirm).
+- **③ `--resume`** đọc các finding `accepted`/`modified` và áp vào file gốc, rồi bump version. Nút **⚡ Apply** trên Board tự chạy đúng lệnh `--resume` này cho bạn.
+
+---
+
+## Giải mã flag: mặc định vs --fix vs --resume
+
+Cùng một lệnh `/review-context` (và họ review nói chung) có **3 chế độ**. Đây là khác biệt:
+
+| Chế độ | Lệnh | Làm gì | Khi nào |
+|---|---|---|---|
+| **Phân tích** (mặc định, không flag) | `/review-context {file}` | Chỉ phân tích → ghi findings. **Không sửa file.** | Bước ① mọi vòng review |
+| **`--fix`** | `/review-context --fix {file}` | Phân tích **rồi tự áp ngay** các finding `auto_fixable` (banned term, metadata, coverage matrix…). Bỏ qua Board. | Dev muốn dọn nhanh lỗi máy-sửa-được, không cần người quyết |
+| **`--resume`** | `/review-context --resume {file}` | **Không phân tích lại.** Đọc findings file, áp các finding **người đã accept** ở Board. | Bước ③ sau khi duyệt ở Board |
+
+> **Nhớ nhanh:** `--fix` = "máy tự sửa cái an toàn **ngay**" · `--resume` = "áp cái **tôi đã duyệt**". Không flag = "chỉ xem, đừng động vào file".
+
+---
+
+## QC pipeline — 6 bước tuần tự
+
+QC là **chuỗi 6 lệnh chạy theo thứ tự** sau khi BDD đã approved. Output bước trước là input bước sau:
+
+```
+/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+   scope         test         test-case        duyệt        chạy +          report
+   + gaps        plan         chi tiết         TC/script    qc_status       HTML
+```
+
+| # | Lệnh | Ra cái gì |
+|---|---|---|
+| 1 | `/qc-analyze` | `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` |
+| 2 | `/qc-plan` | `TEST_PLAN.md` (scope, layer, ưu tiên) |
+| 3 | `/qc-design-test` | `test-cases/*.Test.md` |
+| 4 | `/qc-review` | Verdict APPROVED / NEEDS_FIX (inline) |
+| 5 | `/qc-run-test` | Script Python + ghi `qc_status` vào trace TSV |
+| 6 | `/qc-report` | `report.html` (Playwright trace + pytest-html) |
+
+> Chi tiết: [chương QC Automation](../02-guides/tester/qc-automation.md). Stack `qc-playwright`, độc lập với module code của dev.
+
+---
+
+## dev-* vs qc-* — đừng nhầm
+
+Hai luồng test **tách biệt**, ghi **hai cột khác nhau** trong trace TSV:
+
+| | `/dev-*` (dev self-check) | `/qc-*` (QC chính thức) |
+|---|---|---|
+| Ai chạy | **Dev** — tự kiểm code mình | **QC/Tester** |
+| Lệnh | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` | `/qc-analyze` … `/qc-report` (6 bước) |
+| Ghi signal | `dev_selftest` (pass/fail/not_run) | `qc_status` (pass/fail/skip/not_run) |
+| Là coverage chính thức? | **KHÔNG** — chỉ tín hiệu "dev đã smoke" | **CÓ** — coverage authoritative |
+
+> Cả hai hiển thị **cạnh nhau** trong Living Docs. `dev_selftest: pass` **không** thay thế QC. Xem [Traceability](../03-concepts/traceability.md#hai-tín-hiệu-test-dev_selftest-vs-qc_status).
+
+---
+
+*Xem thêm:* [Command Reference (chi tiết)](commands.md) · [Concepts › Pipeline](../03-concepts/pipeline.md) · [Developer › Workflow](../02-guides/developer/workflow.md)