@edupia-tutor/spec-driven-docs 0.14.0

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/auth/login/prd.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/auth/login/prd.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/auth/login/bdd/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 specs/auth/login/tech-docs/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 Docs Tools*. 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)

package/docs/05-reference/commands.md

@@ -0,0 +1,232 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Command Reference
+
+# Command Reference
+
+> Mọi slash command của framework, gom theo phase. Mỗi command kèm **Cách dùng (ví dụ cụ thể)**, **Output**, và **When to use**. Phần cuối mô tả **Command Internals** — kiến trúc step file dùng chung bởi mọi command.
+>
+> Ví dụ dùng chung một feature xuyên suốt: domain `auth`, ticket `FEAT-01`, use case `FEAT-01-UC1` (đăng nhập). Thay bằng file/UC-ID của bạn.
+
+---
+
+## Mục lục
+
+- [Setup & Maintenance](#setup--maintenance)
+- [Phase 1 — Discovery](#phase-1--discovery)
+- [Phase 2 — PRD](#phase-2--prd)
+- [Phase 2b — Design Spec (FE/App)](#phase-2b--design-spec-feapp)
+- [Phase 3 — BDD Spec](#phase-3--bdd-spec)
+- [Phase 4 — Tech Design](#phase-4--tech-design)
+- [Phase 5 — Code](#phase-5--code)
+- [Phase 6 — Dev Self-Check](#phase-6--dev-self-check)
+- [Phase 6b — QC Automation (official QC suite)](#phase-6b--qc-automation-official-qc-suite)
+- [Phase 7 — Traceability Audit](#phase-7--traceability-audit)
+- [Phase 8 — Tester / QC Feedback](#phase-8--tester--qc-feedback)
+- [Debugging & Cross-cutting](#debugging--cross-cutting)
+- [Command Internals — Step Architecture](#command-internals--step-architecture)
+
+> **Lưu ý số phase:** README dùng cả "Phase 5b / Phase 6b" (sơ đồ workflow) và "Phase 6b" (bảng tổng quan) cho QC Automation. Ở đây dùng nhãn **Phase 6b** cho QC suite để khớp bảng "Phase overview". Dù số khác nhau, ý nghĩa không đổi: QC suite là pipeline `/qc-*` riêng biệt với dev self-check `/dev-*`.
+
+---
+
+## Setup & Maintenance
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/setup-ai-first` | `/setup-ai-first` | Project structure + config files | First-time project setup |
+| `/sync` | `/sync` | Git pull + submodule update + Living Docs sync | **Daily driver** — đồng bộ *nội dung* project (code/specs trong submodule) |
+| `/update-framework` | `/update-framework` | Refreshed `.agent/` command files from npm | **Occasionally** — nâng cấp *bản thân framework* khi có version mới |
+| `/sync-figma-components {module}` | `/sync-figma-components react` | Updated `figma-components/{module}.md` | After Figma design system changes |
+| `/sync-figma-tokens {url?}` | `/sync-figma-tokens` *(hoặc kèm URL Figma)* | Updated `figma-tokens.md` | After design token changes |
+
+> **`/sync` vs `/update-framework` là hai thứ khác nhau:**
+> - `/sync` cập nhật **nội dung project** — pull code/specs mới từ git remote + refresh Living Docs. Nguồn = git remotes của bạn. Chạy thường xuyên.
+> - `/update-framework` cập nhật **framework tooling** — refresh `.agent/commands/`, `steps/`, `modules/` lên version mới nhất. Nguồn = npm registry. Chạy hiếm. Không bao giờ đụng `project-context.yaml`, `CLAUDE.md`, domain-knowledge, hay `.trace/`.
+
+---
+
+## Phase 1 — Discovery
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/define-product` | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` | Starting any new feature. AI dẫn PO qua 7 phase Q&A có cấu trúc — không cần spec viết sẵn. |
+
+---
+
+## Phase 2 — PRD
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/{domain}/{prd-slug}/prd.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
+| `/refine-prd` | `/refine-prd specs/auth/login/prd.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
+| `/refine-prd --resume` | `/refine-prd --resume specs/auth/login/prd.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
+| `/review-context` (PRD) | `/review-context specs/auth/login/prd.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
+| `/review-context --fix` | `/review-context --fix specs/auth/login/prd.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
+| `/review-context --resume` | `/review-context --resume specs/auth/login/prd.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
+
+---
+
+## Phase 2b — Design Spec (FE/App)
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-design-spec` | `/generate-design-spec specs/auth/login/prd.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
+
+> BE teams bỏ qua Phase 2b — đọc PRD trực tiếp rồi `/generate-bdd`.
+
+---
+
+## Phase 3 — BDD Spec
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-bdd` | `/generate-bdd specs/auth/login/prd.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
+| `/review-context` (BDD) | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate bắt buộc trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. |
+| `/review-context --fix` | `/review-context --fix specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
+| `/review-context --resume` | `/review-context --resume specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version | SA review. |
+
+---
+
+## Phase 4 — Tech Design
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-tech-docs` | `/generate-tech-docs specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | **BE** (`system`): `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (API contract) · **FE/App** (`web`/`app`): `{UC-ID}-tech-design-{platform}.md` (client design) | After BDD approved. **Platform-aware** (`@trace.platform`): BE = API contract; FE/App = client design (components/state/API-integration/routing + **§2b Test Selectors**: test-id ổn định cho element có action → QC locate khỏi scan) — **GATED**: HALT nếu thiếu System BDD hoặc BE contract approved. Brownfield (`@trace.api_source: existing`) → reverse-document (BE). |
+| `/map-testids {UC-ID}` | `/map-testids FEAT-01-UC1` | Cập nhật FE tech-design §2b Test Selectors + patch forwarding/usage-site + ghi `figma-components/{module}.md` | FE/App, cho component **reuse** / code **có sẵn** (brownfield): reverse-document id đang có, gán id còn thiếu, đảm bảo component dùng chung forward được test-id. Bổ trợ cho `/generate-tech-docs` (chỉ gán id cho code mới). |
+| `/review-tech-docs` | `/review-tech-docs specs/auth/login/tech-docs/FEAT-01-UC1-tech-design.md` | `.agent/review/{uc-id}-tech-review-findings.yaml` | After generate-tech-docs — mở Review Board. |
+| `/review-tech-docs --resume` | `/review-tech-docs --resume specs/auth/login/tech-docs/FEAT-01-UC1-tech-design.md` | Applies accepted findings + bump revision | Sau khi review trong Review Board. |
+
+---
+
+## Phase 5 — Code
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-code` | `/generate-code specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/...` (tags `@trace.implements`) | After tech-design approved. Default = full impl/BE. |
+| `/generate-code --phase=ui` | `/generate-code --phase=ui specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter. Mock **shape**: BE contract nếu có (chuẩn) → else System BDD + warn; fixture values luôn từ System BDD. Tester test FE ngay được. |
+| `/generate-code --phase=integration` | `/generate-code --phase=integration specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
+| `/review-code` | `/review-code FEAT-01-UC1` | Review report: Critical / Major / Minor | After generate-code. Check: mỗi scenario có endpoint, trace tags, layer rules, error handling khớp CLAUDE.md §5. Fix CRITICAL + MAJOR trước khi merge. |
+
+---
+
+## Phase 6 — Dev Self-Check
+
+> Đây là **developer self-check / smoke** — dev tự kiểm tra code mình vừa sinh ra. **Không phải** official QC suite (đó là Phase 6b `/qc-*`). Signal = `dev_selftest`, tách biệt với `qc_status`.
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/dev-gen-test` | `/dev-gen-test specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `src/test/...` (tags `@trace.verifies`) | After generate-code. Tự chọn test framework đúng platform. |
+| `/dev-run-test` | `/dev-run-test FEAT-01-UC1` | Self-check report — ghi `dev_selftest` (pass/fail/not_run) + `dev_selftest_at` vào trace TSV | After dev-gen-test. |
+| `/dev-smoke-test` | `/dev-smoke-test FEAT-01-UC1` | Live endpoint check | Optional — sau deploy. |
+
+---
+
+## Phase 6b — QC Automation (official QC suite)
+
+> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** sau khi BDD approved (`/review-context` (BDD) APPROVED). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/qc-analyze` | `/qc-analyze FEAT-01-UC1` | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD approved — đầu pipeline QC. |
+| `/qc-plan` | `/qc-plan FEAT-01-UC1` | `{qc_dir}/{UC-ID}/TEST_PLAN.md` (scope, layers, priorities, questions-for-dev) | After `/qc-analyze`. |
+| `/qc-design-test` | `/qc-design-test FEAT-01-UC1` | `{qc_dir}/{UC-ID}/test-cases/*.Test.md` mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
+| `/qc-review` | `/qc-review FEAT-01-UC1` | Verdict APPROVED / NEEDS_FIX + findings (**inline — không sinh file**) | After `/qc-design-test` (test-case) hoặc `/qc-run-test` (script). |
+| `/qc-run-test` | `/qc-run-test FEAT-01-UC1` | Script Python (`pages/`, `tests/`) + ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
+| `/qc-report` | `/qc-report FEAT-01-UC1` | QC report `reports/<feature>/report.html` (Playwright Trace + pytest-html) | After `/qc-run-test`. |
+
+---
+
+## Phase 7 — Traceability Audit
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/validate-traces {domain}` | `/validate-traces auth` *(hoặc `/validate-traces FEAT-01-UC1`)* | Coverage matrix + drift report + `trace-report.json` | Anytime — verify traceability. Đọc mọi `.trace/{domain}/{prd-slug}/{UC-ID}.tsv` rồi tính status OK / DRIFT / GAP / UNTRACKED. |
+
+---
+
+## Phase 8 — Tester / QC Feedback
+
+> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Tester/QC không bao giờ sửa `.feature` trực tiếp. QC cũng dùng hai lệnh này: `/qc-run-test` FAIL = product-gap và `/qc-analyze` DOC_GAPS blocker đều route sang `/report-bug` hoặc `/propose-scenario` (xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md)).
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/report-bug {UC-ID} {desc}` | `/report-bug FEAT-01-UC1 "nhập sai mật khẩu vẫn đăng nhập được"` | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester hoặc QC tìm thấy bug (gồm QC product-gap). Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
+| `/propose-scenario {UC-ID} {desc}` | `/propose-scenario FEAT-01-UC1 "khoá tài khoản sau 5 lần sai mật khẩu"` | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
+
+---
+
+## Debugging & Cross-cutting
+
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/fix-bug {BUG-ID\|ticket\|desc}` | `/fix-bug BUG-012` *(hoặc ticket / mô tả lỗi)* | Code fix trên branch + regression test; nếu nhận `{BUG-ID}` → set report State `🟢 Open` → `🟡 Fixed` (QC re-verify pass mới → `🟢 Closed`) | Khi tìm thấy bug/ticket, hoặc route một filed bug report. |
+| `/debug` | `/debug "NullPointerException ở LoginService"` | Debug session | Deep debugging. |
+| `/learn {text}` | `/learn "AI hay dùng var, phải dùng const"` | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
+| `/generate-spec-manifest` | `/generate-spec-manifest` | `spec-manifest.yaml` | Sinh manifest làm entry point cho external/tester agents. |
+
+> **Project Lessons:** lessons lưu ở `paths.lessons_file` (default `specs/domain-knowledge/lessons-learned.md`; per-service `.agent/project-lessons.md` trong umbrella mode). Context-loader **Step 6.7** load mọi lesson đầu **mỗi** command như hard constraint. Đây là *project memory*, không phải fine-tuning model.
+
+---
+
+## Command Internals — Step Architecture
+
+Mọi command trong `.agent/commands/` được compose từ **step file** dùng chung trong `.agent/steps/`. Các step này là nền móng — mọi command gọi chúng tuần tự trước khi chạy logic riêng.
+
+### Step files at a glance
+
+| File | Role | Called by |
+|------|------|-----------|
+| `gate.md` | Universal entry — model check, file resolution, context load, user checkpoint | Every command |
+| `context-loader.md` | Multi-step context loading (stack → service routing → service conventions → arch → safety → domain → UI → recap) | `gate.md` Step 2 |
+| `spawn-agent.md` | Sub-agent orchestration cho PRD lớn | `generate-bdd`, `generate-code`, `dev-gen-test` |
+| `capture-lesson.md` | Append/refine guardrail vào project lessons file | `learn`, `review-code`, `fix-bug`, `debug` |
+| `report-footer.md` | Standard output format (status badge, artifact list, next command) | Every command |
+
+### gate.md — Universal Entry Procedure
+
+| Step | What it does |
+|------|-------------|
+| **Step 0** | Sub-agent mode check — nếu `$ARGUMENTS` là JSON payload có `_agent_mode: true`, skip Steps 1–3 và dùng slim context trực tiếp |
+| **Step 0-B** | Model check — prompt chuyển sang `claude-opus`; `S` để skip |
+| **Step 1** | Resolve target file từ `$ARGUMENTS`; nếu thiếu, list candidates và hỏi user |
+| **Step 2** | Execute `context-loader.md` — load mọi project context vào working memory |
+| **Step 3** | CHECKPOINT — hiện summary (target file, stack, module, domains), chờ `Y` |
+
+### context-loader.md — Context Loading Sequence
+
+Load context theo thứ tự ưu tiên nghiêm ngặt (anti-lost-in-middle: facts critical load trước, RECAP restate cuối):
+
+| Step | Priority | What loads |
+|------|----------|-----------|
+| 1 | PROJECT-CONFIG | `project-context.yaml` → stack, conventions, domains, services, paths |
+| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `trace_dir` (+ code) → service submodule, store `service_root`. Khi `spec_source` set: `specs_dir` (BDD) / `tech_docs_dir` / PRD / design-spec / domain-knowledge / feedback → **spec repo** (cross-team), KHÔNG per-service |
+| 1.6 | SERVICE CONVENTIONS | *(umbrella only)* load `{service_root}/.agent/project-context.yaml` → override `test_command`, `build_command`, `paths.trace_dir` |
+| 2 | PROJECT-CONFIG | `.agent/modules/{module}/stack-profile.yaml` → framework-specific layer patterns |
+| 3 | **CRITICAL** | `CLAUDE.md` → architecture layers, coding standards, naming |
+| 4 | SAFETY | `.agent/rules/data-protection.md` → sensitive file patterns |
+| 5 | DOMAIN | `business-dictionary.md` → canonical + banned terms |
+| 6 | DOMAIN | `core-entities.md` → entity catalog |
+| 6.7 | **GUARDRAILS** | `lessons_file` → accumulated lessons (via `/learn`) as hard constraints |
+| 6-B | UI COMPONENTS | `figma-components/{module}.md` → Figma → code component + import path |
+| 6-C | UI TOKENS | `figma-tokens.md` → design tokens |
+| 7 | **RECAP** | `[CTX LOADED]` block printed để khóa critical facts vào working memory |
+
+Status values của RECAP: `FULL` · `PARTIAL — missing: {list}` · `MINIMAL` (chỉ project-context.yaml).
+
+### spawn-agent.md — Sub-Agent Orchestration
+
+Khi PRD vượt ngưỡng complexity, `generate-bdd` / `generate-code` / `dev-gen-test` tự chuyển từ single-session sang orchestration mode.
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| UC count in PRD | > 3 UCs | Spawn 1 sub-agent per UC |
+| PRD length | > 300 lines | Spawn agents regardless of UC count |
+
+Orchestrator: Step A build slim context JSON → Step B scan PRD → UC list → Step C announce plan → Step D spawn 1 sub-agent/UC (parallel, mỗi agent chỉ đọc UC section của mình) → Step E collect + merge results.
+
+### report-footer.md — Standard Output Format
+
+Mọi command kết thúc bằng footer: `Status` badge (`✅ Complete` · `⚠️ Warnings` · `❌ Failed`), danh sách **Output Artifacts** (created/updated), và field **Next** gợi ý command kế tiếp.
+
+---
+
+*Xem thêm:* [Trace TSV Schema](trace-schema.md) · [Stack Modules](modules.md) · [02 · Guides](../02-guides/) (theo vai trò).

package/docs/05-reference/modules.md

@@ -0,0 +1,110 @@
+[📚 Docs](../README.md) › [Reference](README.md) › Stack Modules
+
+# Stack Modules
+
+> Mỗi module dưới `modules/` ship một `stack-profile.yaml` chứa layer pattern, naming rule, và test pattern riêng cho framework đó. Framework detect platform type từ `tech_stack.module` (hoặc `active_module` trong multi-service) và adapt mọi artifact sinh ra.
+
+---
+
+## Mục lục
+
+- [Danh sách module](#danh-sách-module)
+- [Platform type grouping](#platform-type-grouping)
+- [qc-playwright — QC automation stack](#qc-playwright--qc-automation-stack)
+
+---
+
+## Danh sách module
+
+15 module (xác minh bằng listing thư mục `modules/`):
+
+| Module | Language / Framework | Platform type |
+|--------|----------------------|---------------|
+| `java-spring` | Java + Spring Boot | backend |
+| `golang` | Go + Gin/Echo | backend |
+| `dotnet` | C# + .NET / ASP.NET Core | backend |
+| `php-laravel` | PHP + Laravel | backend |
+| `context-engineering` | Generic AI/LLM projects | backend |
+| `react` | TypeScript + React | web-frontend |
+| `nextjs` | TypeScript + Next.js | web-frontend |
+| `vue` | TypeScript + Vue 3 | web-frontend |
+| `nuxt` | TypeScript + Nuxt 3 + @nuxt/ui | web-frontend |
+| `angular` | TypeScript + Angular | web-frontend |
+| `flutter` | Dart + Flutter | mobile |
+| `react-native` | TypeScript + React Native / Expo | mobile |
+| `ios-swiftui` | Swift + SwiftUI | mobile |
+| `android-compose` | Kotlin + Jetpack Compose | mobile |
+| `qc-playwright` | Python + pytest-playwright + Page Object | QC / E2E (xem dưới) |
+
+---
+
+## Platform type grouping
+
+`platform_type` được suy ra từ module và quyết định cách adapt BDD vocabulary, tech-design sections, và test templates.
+
+| `platform_type` | Modules |
+|-----------------|---------|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+Ví dụ adapt theo platform type:
+
+- **BDD vocabulary** — backend dùng "submits a request" / "receives response"; web dùng "clicks" / "types into" / "navigates to"; mobile dùng "taps" / "enters" / "opens".
+- **Tech-design sections** — backend: §4 API Endpoints / §5 Service Flow / §6 Data Model…; web-frontend: §4 Screen/Component Breakdown / §5 State Management…; mobile: §4 Screen/Widget Breakdown / §5 State & Data Flow….
+- **Test templates** — Java → JUnit 5 + Mockito + `@WebMvcTest`; web → Vitest/Jest + Testing Library + Playwright/Cypress; Flutter → `testWidgets`; iOS → `XCTestCase`; Android → Compose rule + `@HiltAndroidTest`.
+
+---
+
+## qc-playwright — QC automation stack
+
+`qc-playwright` là **stack QC automation độc lập** với dev implementation module. Nó power native QC pipeline (`/qc-run-test`, `/qc-report`) và được chọn qua `tech_stack.qc_module` hoặc per `/qc-*` run — không phụ thuộc vào stack dev (java-spring, react, flutter…). Per-layer guides nằm ở `skills/qc/<stage>/`. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
+
+**Stack** (từ `modules/qc-playwright/stack-profile.yaml`): Python 3 + pytest-playwright + Page Object Model. Report = Playwright Trace + pytest-html (**không** dùng Allure, không hand-written dashboard, không `record_video`).
+
+**Build commands:**
+
+| Mục đích | Command |
+|----------|---------|
+| Test | `python3 -m pytest` |
+| E2E | `python3 -m pytest -m e2e` |
+| Report | `python3 -m pytest --html=reports/<feature>/report.html --self-contained-html` |
+| Show trace | `python3 -m playwright show-trace <test-results/<nodeid>/trace.zip>` |
+
+**Key architecture rules:**
+- **Markdown-first** — không sinh Python cho tới khi có `.Test.md` đã review cho feature.
+- Không hard-code URL/credential/timeout — đọc từ `Env.*` và `CONFIG[...]`.
+- Không `time.sleep()` — dùng Playwright auto-wait / `expect()`.
+- Mỗi test độc lập qua pytest-playwright fixtures (`page` / `logged_in_page` / …).
+- Page Object extends slim `BasePage`; tách 3 layer: locators `_x()`, actions `verb_noun()`, assertions `assert_x()` dùng `expect()`.
+- Locator priority: `data-testid` → role → label/text → CSS → tránh XPath.
+- Group test theo `(role, account)` để login/logout không interleave giữa các role.
+- Cover 100% TC trong `.Test.md` — mỗi TC kết thúc Pass/Fail/Skip, không để Draft.
+
+**Naming:** test case id `TC_<FEATURE>_<NNN>` · test class `TestFeatureHappyCase` · test function `test_TC<NNN>_<snake_case>` · page object `<feature>_page.py` (`<Feature>Page` extends `BasePage`).
+
+**Folder structure:**
+```
+{paths.qc_dir}/{UC-ID}/test-cases/ ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
+pages/                      ← Page Object Model (base_page.py + <feature>_page.py)
+tests/                      ← pytest scripts, 1-1 với test-cases/ (conftest.py + test_<feature>.py)
+utils/                      ← config_loader, logger, steps, test_ordering, report helpers
+test_data/                  ← JSON datasets
+config/config.yaml          ← browser, timeout, video/screenshot/trace toggles
+reports/  test-results/     ← generated (gitignored): html report, trace.zip, screenshots
+```
+
+**Test layers:** functional (gui-screen / gui-feature / api) · integration (api/db/gui/kafka) · e2e (journey) · non-functional · exploratory.
+
+**Trace tags** (map QC test về scenario, drive `qc_status`):
+```python
+# @trace.verifies={UC-ID}-SC{N}
+# @trace.source=<official .feature path>
+# @trace.test_type=functional|integration|e2e|non-functional
+```
+
+> `/qc-run-test` ghi `pass|fail|skip|not_run` + `qc_run_at` vào `{trace_dir}/{UC-ID}.tsv` (song song với `dev_selftest`), surfaced trong Living Docs là kết quả QC automation **chính thức**. Mỗi FAIL được phân loại script-bug (fix selector/logic) vs product-gap (giữ FAIL + evidence, không bao giờ fake-pass).
+
+---
+
+*Xem thêm:* [Trace TSV Schema](trace-schema.md) (`qc_status` vs `dev_selftest`) · [Command Reference](commands.md) (pipeline `/qc-*`) · [02 · Guides · QC Automation](../02-guides/tester/qc-automation.md).