@anhth2/spec-driven-dev-plugin 0.10.0 → 0.11.0

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

@@ -0,0 +1,328 @@
+[📚 Docs](../README.md) › [Operations](README.md) › Sync & Update
+
+# Sync & Update — Vận hành hằng ngày
+
+> Cách đồng bộ nội dung dự án (`/sync`), nâng cấp framework (`/update-framework`), làm việc ở umbrella mode với git submodule, đồng bộ Living Docs, và workflow hằng ngày theo từng role.
+
+---
+
+## Mục lục
+
+1. [Hai loại "update" — đừng nhầm](#1-hai-loại-update--đừng-nhầm)
+2. [`/sync` — đồng bộ nội dung dự án](#2-sync--đồng-bộ-nội-dung-dự-án)
+3. [`/update-framework` — nâng cấp framework](#3-update-framework--nâng-cấp-framework)
+4. [Umbrella mode & git submodule](#4-umbrella-mode--git-submodule)
+5. [Living Docs sync](#5-living-docs-sync)
+6. [Workflow hằng ngày theo role](#6-workflow-hằng-ngày-theo-role)
+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.
+
+---
+
+## 1. Hai loại "update" — đừng nhầm
+
+Có 2 thứ cần update, **nguồn khác nhau, tần suất khác nhau**:
+
+| | `/sync` | `/update-framework` |
+|---|---|---|
+| **Update cái gì** | Nội dung dự án: code/specs trong submodule + Living Docs | Bản thân framework: `.agent/commands/`, steps/, modules/ |
+| **Nguồn** | Git remote của các submodule | npm registry |
+| **Tần suất** | Mỗi sáng / trước khi work | Khi có version framework mới (hiếm) |
+| **Đụng `project-context.yaml` / `CLAUDE.md`?** | Không | Không (chỉ refresh file framework) |
+
+```bash
+# Update nội dung dự án — chạy thường xuyên
+/sync
+
+# Nâng cấp framework — chạy khi có bản mới
+/update-framework
+```
+
+---
+
+## 2. `/sync` — đồng bộ nội dung dự án
+
+`/sync` gộp `git pull` + cập nhật submodule + refresh Living Docs vào **1 lệnh duy nhất**, chạy từ umbrella root:
+
+- Pull specs (spec submodule) + services (service submodules).
+- Refresh Living Docs panel (regenerate trace report — xem [§5](#5-living-docs-sync)).
+- Liệt kê **📥 New tester feedback** — bug report / scenario proposal mới từ tester trong vùng `feedback/` của spec repo.
+
+```bash
+/sync
+# hoặc override branch của spec submodule một lần:
+/sync develop
+```
+
+**Branch nào được kéo?** `/sync` đọc `submodule.<spec>.branch` trong `.gitmodules`; nếu không khai báo → lấy **default branch của remote** (`origin/HEAD`, thường `main`). PO làm trên branch khác (vd `develop`) → pin một lần cho cả team:
+
+```bash
+git config -f .gitmodules submodule.my-project-specs.branch develop
+git add .gitmodules && git commit -m "chore: pin spec submodule branch = develop"
+```
+
+Service submodules không bị ảnh hưởng — luôn checkout đúng SHA mà umbrella ghi, không phụ thuộc branch.
+
+---
+
+## 3. `/update-framework` — nâng cấp framework
+
+```bash
+/update-framework
+# → đọc .agent/FRAMEWORK_VERSION, so với npm
+# → chạy npx @latest --init
+# → review `git diff .agent/` rồi commit
+```
+
+> **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.
+
+---
+
+## 4. Umbrella mode & git submodule
+
+Claude Code luôn mở ở **umbrella repo** (không mở trong service submodule). Umbrella thấy được cả spec submodule (read-only) lẫn service submodule (code).
+
+### 4.1 — Clone lần đầu
+
+```bash
+git clone --recurse-submodules https://gitlab.company.com/my-project-web.git
+
+# Hoặc nếu đã clone mà submodule trống:
+git submodule update --init --recursive
+```
+
+### 4.2 — Kiểm tra trạng thái submodule
+
+```bash
+git submodule status
+```
+
+| Ký hiệu | Ý nghĩa | Cách xử lý |
+|---|---|---|
+| `abc1234 my-project-specs` | Bình thường | — |
+| `+abc1234 …` | Umbrella có thay đổi chưa commit | `git add <sub> && git commit` |
+| `-abc1234 …` | Chưa init | `git submodule update --init` |
+| `Uabc1234 …` | Conflict | Giải quyết conflict rồi commit |
+
+### 4.3 — Cập nhật spec submodule (lấy PRD mới từ PO)
+
+```bash
+# Cách 1: kéo version mới nhất của branch (thường dùng nhất)
+git submodule update --remote my-project-specs
+
+# Cách 2: kéo version mà umbrella đang trỏ (sau git pull)
+git submodule update my-project-specs
+
+# Commit lại pointer để cả team cùng version
+git add my-project-specs
+git commit -m "chore: update spec submodule to latest"
+git push
+```
+
+> **Khác biệt:** `--remote` lấy commit mới nhất từ remote branch (khi PO vừa push); không có `--remote` → sync về đúng commit umbrella đang trỏ. `/sync` xử lý việc này tự động.
+
+### 4.4 — Commit 2 tầng (thay đổi trong service submodule)
+
+```bash
+# Tầng 1: commit trong service submodule
+cd user-service
+git add specs/bdd/ src/
+git commit -m "feat(FEAT-01): add BDD and implementation"
+git push origin main
+cd ..
+
+# Tầng 2: update pointer ở umbrella
+git add user-service
+git commit -m "chore: update user-service submodule to FEAT-01"
+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`.
+
+### 4.5 — Lỡ tay sửa file trong spec submodule (read-only)
+
+Spec submodule là **read-only** cho dev/tester. Nếu lỡ sửa → bỏ thay đổi:
+
+```bash
+cd my-project-specs
+git checkout .      # hoặc: git restore .
+```
+
+Muốn cập nhật PRD → báo PO sửa trong spec repo của họ rồi push.
+
+### 4.6 — Troubleshooting
+
+| Lỗi | Nguyên nhân | Cách xử lý |
+|---|---|---|
+| Thư mục submodule trống | Chưa init | `git submodule update --init` |
+| `fatal: not a git repository` | Sai thư mục | `cd` về đúng chỗ |
+| `object not found` sau pull | Push umbrella nhưng quên push submodule | Người commit submodule chạy `cd <sub> && git 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>` |
+
+---
+
+## 5. Living Docs sync
+
+Living Docs panel hiển thị trạng thái trace của toàn bộ feature. Refresh nó bằng `/validate-traces` (hoặc tự động qua `/sync`):
+
+```bash
+/validate-traces
+```
+
+- Đọc TSVs từ **tất cả** service submodule (`.trace/*.tsv` là authoritative — commit ở mỗi 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).
+- 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.
+>
+> **.gitignore:** thêm `.trace/` trong repo hiện tại **và** `.living-docs/` trong spec module — đều là mirror read-only, không commit.
+
+### `dev_selftest` vs `qc_status` — đừng nhầm
+
+| Cột | Set bởi | Ý nghĩa |
+|---|---|---|
+| `dev_selftest` (+ `dev_selftest_at`) | `/dev-run-test` | Dev tự kiểm tra code mình viết (self-check / smoke). **KHÔNG** phải coverage QC chính thức. |
+| `qc_status` (+ `qc_run_at`) | `/qc-run-test` (keyed theo `@trace.verifies={UC-ID}-SC{N}`) | Kết quả QC chính thức của framework. |
+
+Sau khi chạy `/qc-run-test` rồi `/validate-traces` (hoặc `/sync`), `qc_status` hiện lên Living Docs cạnh `dev_selftest`.
+
+---
+
+## 6. Workflow hằng ngày theo role
+
+### PO — Viết tài liệu cho tính năng mới
+
+```bash
+cd my-project-spec
+git pull
+# Mở Claude Code tại thư mục này:
+/define-product                          # khởi tạo product definition
+/generate-prd {product-definition-file}
+/refine-prd {prd-file}                   # review 4 lens: QA/DEV/SA/PO
+/review-context {prd-file}               # chất lượng + P0 check
+/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)
+
+git add specs/
+git commit -m "feat({domain}): add {TICKET-ID} PRD, design spec, and BDD"
+git push
+```
+
+### FE/Web Dev — Nhận task mới
+
+```bash
+cd my-project-web
+/sync                                    # pull + submodule + Living Docs
+git add my-project-specs && git commit -m "chore: sync specs" && git push
+
+/review-context my-project-specs/specs/prd/{domain}/{TICKET-ID}-prd.md
+# → P0: @trace.domain khớp services config? @trace.status: approved?
+# Đọ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)
+/dev-gen-test  {domain}/{TICKET-ID}-UC1
+/review-code   {files-changed}
+/dev-run-test                                            # dev self-check (dev_selftest)
+# → sau khi sign-off gate approved:
+/generate-code {domain}/{TICKET-ID}-UC1 --phase=integration   # wire API thật
+
+# ── API đã có sẵn ──
+/generate-code {domain}/{TICKET-ID}-UC1                  # không cần --phase
+/dev-gen-test  {domain}/{TICKET-ID}-UC1
+/review-code   {files-changed}
+/dev-run-test
+
+# Commit 2 tầng (xem §4.4)
+```
+
+### BE Dev — Nhận task mới
+
+```bash
+cd my-project-be
+/sync
+# → cũng liệt kê "📥 New tester feedback" → /fix-bug · promote proposal · báo PO
+
+/review-context my-project-specs/specs/prd/{domain}/{TICKET-ID}-prd.md
+# Đọc System BDD: my-project-specs/specs/bdd/{domain}/system/{TICKET-ID}-UC*.feature
+
+/generate-tech-docs {domain}/{TICKET-ID}-UC1
+/review-tech-docs   {domain}/{TICKET-ID}-UC1
+/generate-code      {domain}/{TICKET-ID}-UC1
+/dev-gen-test       {domain}/{TICKET-ID}-UC1
+/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)
+```
+
+### QC — Chạy native QC pipeline (tóm tắt)
+
+Điều kiện: BDD đã `approved`. Module `qc-playwright` (Python + pytest-playwright + Page Object).
+
+```bash
+cd my-project-web
+/sync
+/qc-analyze · /qc-plan · /qc-design-test · /qc-review · /qc-run-test · /qc-report
+/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).
+
+---
+
+## 7. Project Lessons — không để AI lặp lỗi
+
+Khi AI lặp đi lặp lại một lỗi, ghi lại thành **lesson** thay vì sửa thủ công mỗi lần. context-loader nạp lesson vào đầu **mọi** lệnh như ràng buộc cứng.
+
+```bash
+# Cách 1 — chủ động:
+/learn "AI hay gọi repository thẳng từ controller, phải đi qua service layer"
+
+# Cách 2 — tự động: /review-code, /fix-bug, /debug hỏi "Record as a project lesson? (Y/N)" → Y
+```
+
+- **Lưu ở:** `paths.lessons_file` (mặc định `specs/domain-knowledge/lessons-learned.md`; umbrella: `.agent/project-lessons.md` mỗi service).
+- **Commit file lessons** để cả team cùng được bảo vệ — đây là **bộ nhớ dự án**, không phải fine-tune model.
+- Kiểm tra `[CTX LOADED]` có dòng `Lessons: loaded — N guardrails`.
+
+---
+
+## 8. Câu hỏi thường gặp
+
+**Q: Có cần cài framework vào từng service submodule không?**
+A: Không. Chỉ cài ở umbrella repo. Service submodule là git repo thường chứa code + specs (+ `.agent/project-context.yaml` config).
+
+**Q: Claude Code nên mở ở đâu?**
+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/`.
+
+**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.
+
+**Q: PO sửa PRD, có cần generate lại BDD?**
+A: Chạy `/review-context {feature-file}` (B1 check) xem có coverage gap không. Có → `/review-context --resume`. Không cần viết lại toàn bộ BDD.
+
+**Q: Mở nhiều Claude Code cho nhiều umbrella cùng lúc được không?**
+A: Được. Mỗi umbrella là session riêng, hoàn toàn độc lập.
+
+**Q: Đang ở `detached HEAD` trong submodule, có sao không?**
+A: Bình thường — submodule trỏ tới một commit cụ thể. Chỉ lo nếu định sửa file (phải checkout branch trước). Chỉ đọc thì không sao.
+
+---
+
+*Xem thêm:* [Bug Flow](bug-flow.md) · [Publishing](publishing.md) · [02 · Guides](../02-guides/) · [03 · Concepts — Traceability](../03-concepts/traceability.md).

package/docs/05-reference/README.md

@@ -0,0 +1,29 @@
+[📚 Docs](../README.md) › Reference
+
+# 05 · Reference
+
+> Tra cứu nhanh: mọi slash command, schema của trace TSV, và danh sách stack module. Đây là phần "đọc khi cần" — không phải hướng dẫn tuần tự.
+
+Dùng mục này khi bạn đã biết mình muốn làm gì và chỉ cần tra input/output, tên cột, hoặc module phù hợp với stack.
+
+---
+
+## Trong mục này
+
+| Trang | Nội dung |
+|-------|----------|
+| [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`. |
+
+---
+
+## Điều hướng nhanh
+
+- **"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)
+
+---
+
+*Xem thêm:* [02 · Guides](../02-guides/) (theo vai trò) · [03 · Concepts](../03-concepts/) (kiến trúc & traceability) · [04 · Operations](../04-operations/) (vận hành).

package/docs/05-reference/commands.md

@@ -0,0 +1,229 @@
+[📚 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 **Input**, **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.
+
+---
+
+## 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 Feedback](#phase-8--tester-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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/setup-ai-first` | — | Project structure + config files | First-time project setup |
+| `/sync` | — | Git pull + submodule update + Living Docs sync | **Daily driver** — đồng bộ *nội dung* project (code/specs trong submodule) |
+| `/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}` | Module name | Updated `figma-components/{module}.md` | After Figma design system changes |
+| `/sync-figma-tokens {url?}` | Optional Figma URL | 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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/generate-prd` | product-definition file | `specs/prd/{domain}/{TICKET-ID}-{slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
+| `/refine-prd` | prd file | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
+| `/refine-prd --resume` | prd file | Applied findings + bumped version | Sau khi review trong Review Board. |
+| `/review-context` (PRD) | prd file | `.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` | prd file | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
+| `/review-context --resume` | prd file | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
+
+---
+
+## Phase 2b — Design Spec (FE/App)
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/generate-design-spec` | prd file | `specs/design-spec/{domain}/{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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/generate-bdd` | prd file | `specs/bdd/{domain}/{UC-ID}.feature` (multi-service: `{domain}/{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. PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
+| `/review-context` (BDD) | feature file | `.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` | feature file | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
+| `/review-context --resume` | feature file | Applies accepted findings + bump bdd_version | SA review. |
+
+---
+
+## Phase 4 — Tech Design
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/generate-tech-docs` | feature file | `tech-docs/{domain}/{UC-ID}-tech-design.md` (multi-service: `{domain}/{service}/...`) | After BDD approved. Đọc `@trace.module` → chọn template theo platform type. Brownfield (`@trace.api_source: existing`) → reverse-document mode. |
+| `/review-tech-docs` | tech-design file | `.agent/review/{uc-id}-tech-review-findings.yaml` | After generate-tech-docs — mở Review Board. |
+| `/review-tech-docs --resume` | tech-design file | Applies accepted findings + bump revision | Sau khi review trong Review Board. |
+
+---
+
+## Phase 5 — Code
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/generate-code` | feature file | `src/...` (tags `@trace.implements`) | After tech-design approved. Default = full impl/BE. |
+| `/generate-code --phase=ui` | feature file | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter từ System BDD contract; tester test FE ngay được. |
+| `/generate-code --phase=integration` | feature file | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
+| `/review-code` | — | 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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/dev-gen-test` | feature file | `src/test/...` (tags `@trace.verifies`) | After generate-code. Tự chọn test framework đúng platform. |
+| `/dev-run-test` | — | Self-check report — ghi `dev_selftest` (pass/fail/not_run) + `dev_selftest_at` vào trace TSV | After dev-gen-test. |
+| `/dev-smoke-test` | — | 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/qc-automation.md](../02-guides/qc-automation.md).
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/qc-analyze` | feature file / UC-ID | QC analysis of scenarios + risks | After BDD approved — đầu pipeline QC. |
+| `/qc-plan` | QC analysis | Test plan (scope, layers, priorities) | After `/qc-analyze`. |
+| `/qc-design-test` | test plan | Test case designs mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
+| `/qc-review` | test designs | Reviewed/approved test design set | After `/qc-design-test`. |
+| `/qc-run-test` | test designs | Execution results — 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` | run results | QC report (Playwright Trace + pytest-html) | After `/qc-run-test`. |
+
+---
+
+## Phase 7 — Traceability Audit
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/validate-traces {domain}` | domain name (hoặc UC-ID) | Coverage matrix + drift report + `trace-report.json` | Anytime — verify traceability. Đọc mọi `.trace/{UC-ID}.tsv` rồi tính status OK / DRIFT / GAP / UNTRACKED. |
+
+---
+
+## Phase 8 — Tester 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`. Testers không bao giờ sửa `.feature` trực tiếp.
+
+| Command | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/report-bug {UC-ID} {desc}` | UC/TICKET + description | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester tìm thấy bug. Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
+| `/propose-scenario {UC-ID} {desc}` | UC + edge-case description | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester 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 | Input | Output | When to use |
+|---------|-------|--------|-------------|
+| `/fix-bug` | — | Bug fix | When a bug is found. |
+| `/debug` | — | Debug session | Deep debugging. |
+| `/learn {text}` | "AI does X, should Y" | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
+| `/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 `specs_dir`/`tech_docs_dir` → service submodule, store `service_root` |
+| 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ò).