@edupia-tutor/spec-driven-docs 0.14.0

package/docs/02-guides/tester/test-checklist.md

@@ -0,0 +1,31 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Checklist Test Pass
+
+# Checklist Trước Khi Báo "test pass"
+
+**Spec & coverage:**
+- [ ] Tất cả BDD scenarios đã được cover (happy path + edge + error)
+- [ ] Mọi AC trong PRD đã được verify
+- [ ] Manifest version khớp với PRD version đang deploy
+- [ ] Không có scenarios bị skip mà không có lý do ghi chú
+
+**Môi trường:**
+- [ ] Test đã chạy trên đúng môi trường (staging, không phải local dev)
+- [ ] Cross-service flows đã được verify (nếu feature span nhiều service)
+
+**TSV & Living Docs:**
+- [ ] `/qc-run-test` đã chạy → `qc_status` đã ghi vào `{spec_source}/.trace/{UC-ID}.tsv` (spec repo — một chỗ)
+- [ ] TSV đã được commit vào **spec repo** (1 tầng, giống `feedback/`) + push — KHÔNG commit vào service submodule
+- [ ] `/validate-traces` (hoặc `/sync`) đã chạy → Living Docs panel hiển thị `qc_status: pass`
+- [ ] Không còn scenario nào `qc_status: not_run` trong UC đang test
+- [ ] Nếu có `qc_status: fail` → đã `/report-bug` kèm path evidence (`reports/<feature>/report.html`)
+
+## Xem Thêm
+
+- [Guide › QC Automation](qc-automation.md) — pipeline `/qc-*` chi tiết, `qc_status`, stack `qc-playwright`
+- [Operations › Bug Flow](../../04-operations/bug-flow.md) — flow phối hợp Tester ↔ Dev ↔ PO
+- [Concepts › Traceability](../../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+- [Reference › Commands](../../05-reference/commands.md) — danh mục đầy đủ mọi command
+
+---
+
+← [Báo cáo bug](bug-reporting.md)

package/docs/02-guides/tester/workflow.md

@@ -0,0 +1,77 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Workflow
+
+# Workflow Cơ Bản
+
+```
+Nhận task: "Test FT-042 — Checkout flow"
+        │
+        ▼
+git pull && git submodule update --remote --recursive
+        │
+        ▼
+/generate-spec-manifest
+→ spec-manifest.yaml được refresh
+        │
+        ▼
+Lookup FT-042 trong spec-manifest.yaml
+→ status: approved? ✅ (nếu draft → dừng, báo PO)
+→ ghi lại paths (tất cả đều nằm trong submodule):
+    prd:          {spec_source}/specs/{domain}/{prd-slug}/prd.md
+    bdd.system:   {spec_source}/specs/{domain}/{prd-slug}/bdd/system/FT-042-*.feature
+    bdd.web:      {spec_source}/specs/{domain}/{prd-slug}/bdd/web/FT-042-*.feature
+    tech_docs.be: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*.md
+    tech_docs.fe: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*-tech-design-web.md
+        │
+        ▼
+Đọc PRD tại path manifest.prd
+→ file nằm trong SPEC submodule (shared — PO viết)
+→ hiểu AC, UC, BR — đây là "ground truth"
+        │
+        ▼
+Đọc BDD tại path manifest.bdd.be / bdd.web
+→ file nằm trong SPEC submodule (PO gen từ PRD — tất cả BDD web/app/system ở spec repo)
+→ mỗi Scenario = 1 test case cần cover
+→ BE có BDD riêng (system/), Web có BDD riêng (web/), App có BDD riêng (app/)
+        │
+        ▼
+Đọc Tech Docs tại path manifest.tech_docs.be / tech_docs.web
+→ file nằm trong SPEC submodule (shared — Dev gen, SA sign-off)
+→ BE: API endpoints, request/response schema, error codes
+→ Web: screen flow, component states
+        │
+        ▼
+Chạy QC automation pipeline (6 bước — ghi kết quả chính thức vào TSV)
+        │
+        ├─ /qc-analyze {UC-ID}       → 2 file: REQUIREMENT_ANALYSIS.md + DOC_GAPS.md
+        ├─ /qc-plan {UC-ID}          → TEST_PLAN.md (risk + plan + questions-for-dev)
+        ├─ /qc-design-test {UC-ID}   → test-cases/*.Test.md
+        │     ⌙ artifact phân tích/thiết kế → {qc_dir}/{UC-ID}/ (mặc định docs/, VISIBLE)
+        ├─ /qc-review {UC-ID}        → review test design trước khi chạy
+        ├─ /qc-run-test {UC-ID}      → sinh + chạy pytest-playwright
+        │                               → ghi qc_status (pass/fail/skip) per scenario
+        │                               → vào {spec_source}/.trace/{domain}/{prd-slug}/{UC-ID}.tsv  ← AUTHORITATIVE (spec repo)
+        └─ /qc-report {UC-ID}        → report pytest-html + Playwright trace evidence
+                                        → reports/<feature>/report.html  ← LOCAL, gitignored
+        │
+        ▼
+Commit TSV vào spec repo (1 tầng — trace dồn về specs, giống feedback/)
+  cd {spec_source}
+  git add .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+  git commit -m "qc: record qc_status for {UC-ID} — pass/fail"
+  git push
+        │
+        ▼
+/validate-traces (hoặc /sync)
+→ đọc {spec_source}/.trace/ (một chỗ) → Living Docs cập nhật cột qc_status
+        │
+        ▼
+Kết quả:
+  qc_status: pass  → done, Living Docs phản ánh coverage chính thức
+  qc_status: fail  → /report-bug với BDD scenario + AC bị vi phạm
+                      đính kèm path evidence: reports/<feature>/report.html
+                      (evidence local — share file hoặc upload riêng nếu cần)
+```
+
+---
+
+← [Spec Manifest & Setup](spec-manifest.md) · Tiếp theo: [Đọc Spec Chain](reading-specs.md)

package/docs/03-concepts/README.md

@@ -0,0 +1,19 @@
+[📚 Docs](../README.md) › Concepts
+
+# Concepts
+
+Hiểu **cách framework được xây dựng và vận hành** — kiến trúc nhiều lớp, pipeline các phase, và hệ thống traceability. Đọc section này khi bạn muốn biết *vì sao* mọi thứ hoạt động như vậy, không chỉ *cách dùng* lệnh.
+
+## Mục lục (this section)
+
+- [architecture.md](architecture.md) — 6 lớp (Protection → Output), module plug-in system, build pipeline (`*.tmpl` → `*.md` → `core/`), directory map, sub-agent orchestration, hook data-protection.
+- [pipeline.md](pipeline.md) — các phase Discovery → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-check → QC automation → Tester feedback; review gates; và step-architecture model (gate / context-loader / spawn-agent / report-footer) đằng sau mỗi command.
+- [traceability.md](traceability.md) — `@trace.*` tags, trace TSV, hai tín hiệu `dev_selftest` vs `qc_status`, Living Docs (canonical trong spec-module + panel mirror), và `/validate-traces`.
+
+## Đọc gì trước?
+
+1. Muốn cái nhìn tổng thể? → [architecture.md](architecture.md) — file "đọc trước khi đọc bất kỳ file chi tiết nào".
+2. Muốn hiểu luồng làm việc end-to-end? → [pipeline.md](pipeline.md).
+3. Muốn hiểu coverage / drift / Living Docs? → [traceability.md](traceability.md).
+
+> Tra cứu chi tiết schema và module thì sang [05 · Reference](../05-reference/) — [trace-schema.md](../05-reference/trace-schema.md) và [modules.md](../05-reference/modules.md).

package/docs/03-concepts/architecture.md

@@ -0,0 +1,248 @@
+[📚 Docs](../README.md) › [Concepts](README.md) › Architecture
+
+# Architecture
+
+> **Nguyên tắc**: Đọc file này để hiểu toàn bộ framework trước khi đọc bất kỳ file chi tiết nào.
+
+Cách framework được xây dựng: 6 lớp runtime, build pipeline `*.tmpl → *.md → core/`, module plug-in system, hook data-protection, và sub-agent orchestration.
+
+## Mục lục
+
+- [Layer diagram (L0 → L5)](#layer-diagram-l0--l5)
+- [Data flow — một command chạy như thế nào](#data-flow--một-command-chạy-như-thế-nào)
+- [Build system](#build-system)
+- [Module plug-in system](#module-plug-in-system)
+- [Hook system — data protection](#hook-system--data-protection)
+- [Sub-agent orchestration](#sub-agent-orchestration)
+- [Directory map](#directory-map)
+- [Maintenance guide](#maintenance-guide)
+
+---
+
+## Layer diagram (L0 → L5)
+
+Mỗi command chạy qua 6 lớp, từ bảo vệ dữ liệu đến sinh artifact:
+
+```
+LAYER 0 — PROTECTION                              (luôn chạy trước)
+  hooks/data-guard.js     → PreToolUse hook: chặn đọc file nhạy cảm
+  rules/data-protection.md → quy tắc declarative cho AI agent
+                          │ safe ↓   blocked → ✋ STOP
+LAYER 1 — ENTRY POINT                             (user trigger)
+  commands/*.tmpl          (slash commands: /generate-bdd, /generate-code, …)
+  skills/*/SKILL.tmpl      (auto-trigger theo description match)
+                          │ cả hai build bởi bin/build.js
+LAYER 2 — SHARED STEPS                            (DRY, injected)
+  steps/gate.md            → resolve target file + CHECKPOINT
+  steps/context-loader.md  → load project config + rules
+  steps/report-footer.md   → standard output format
+  Injected ở build time qua {{include:steps/X.md}}  (*.tmpl → *.md, gitignored)
+                          │ context loaded
+LAYER 3 — PROJECT CONTEXT                 (đọc từ consumer project)
+  .agent/project-context.yaml  → paths, tech_stack, domains
+  CLAUDE.md (root)             → umbrella-wide shared rules (base layer)
+  {service_root}/CLAUDE.md     → service architecture + coding standards (overlay, wins)
+  rules/data-protection.md     → AI không được đọc gì
+  .agent/modules/{stack}/      → stack rules (plug-in, optional)
+                          │ context-aware
+LAYER 4 — EXECUTION                               (command logic)
+  Discovery   /define-product
+  PRD / BDD   /generate-prd · /refine-prd · /generate-bdd · /generate-tech-docs
+  Code        /generate-code · /review-code
+  Dev check   /dev-gen-test · /dev-run-test · /dev-smoke-test  → set dev_selftest
+  QC suite    /qc-analyze → /qc-plan → /qc-design-test → /qc-review →
+              /qc-run-test → /qc-report                        → set qc_status
+  Trace/Debug /validate-traces · /fix-bug · /debug
+                          │
+LAYER 5 — OUTPUT                          (artifacts in consumer proj)
+  Spec module (cross-team, via {spec_source}):
+    specs/product-definition/
+    specs/{domain}/{prd-slug}/ — feature package gom mọi artifact của một PRD:
+      prd.md · bdd/ (web/app/system) · tech-docs/ (API contract + FE tech-design) · design-spec/
+    feedback/
+    .trace/{domain}/{prd-slug}/*.tsv (authoritative, committed — một chỗ cho PM) · .living-docs/ (gitignored)
+  Service submodule (per-service):
+    src/ (chỉ code) · .agent/review/
+  QC automation outputs:
+    QC test cases / scripts (Python pytest-playwright, Page Object)
+    → QC analysis / test-cases ghi vào {qc_dir}/{UC-ID}/ (mặc định docs/,
+      visible — KHÔNG nằm trong .agent/)
+    → guides per-layer ở skills/qc/<stage>/ · qc_status trong .trace/*.tsv
+```
+
+> **Dev self-check vs QC chính thức:** `/dev-*` set `dev_selftest` (smoke, dev tự kiểm code của mình); 6 lệnh `/qc-*` là QC automation pipeline CHÍNH THỨC (port từ agent của team QC; QC repo nay chỉ còn reference) → set `qc_status`. Hai tín hiệu **orthogonal**, cả hai surface trong Living Docs. Chi tiết: [traceability.md](traceability.md).
+
+---
+
+## Data flow — một command chạy như thế nào
+
+Ví dụ `/generate-bdd specs/payment/process-payment/prd.md`:
+
+```
+User types: /generate-bdd specs/payment/process-payment/prd.md
+  │
+[L0] data-guard.js check tool calls real-time → đọc .env/*.key → BLOCK + warn
+  │
+[L1] commands/generate-bdd.md (assembled từ .tmpl + injected steps) được Claude đọc
+  │
+[L2] gate.md → resolve file path từ $ARGUMENTS
+     context-loader.md → đọc project-context.yaml, CLAUDE.md,
+                         rules/data-protection.md, modules/{stack}/stack-profile.yaml
+  │
+[L3] Claude biết: tech_stack, domains, architecture rules, sensitive files, stack patterns
+  │
+[L4] generate-bdd logic: đọc PRD → extract UC/BR/AC → apply BDD rules R1–R10
+  │
+[L5] Output: specs/payment/process-payment/bdd/PAY-01-UC1.feature
+```
+
+Chi tiết về step-architecture (gate / context-loader / report-footer) và sub-agent model: xem [pipeline.md](pipeline.md#command-internals--step-architecture).
+
+---
+
+## Build system
+
+`*.tmpl` (committed) được assemble thành `*.md` (gitignored) bởi `bin/build.js`:
+
+```
+Source (committed)                Build output (gitignored)
+commands/*.tmpl       ──┐
+skills/**/SKILL.tmpl  ──┤  node bin/build.js  →  commands/*.md · skills/**/SKILL.md
+steps/*.md (shared)   ──┘
+
+Trigger:
+  npm run build         ← manual
+  prepublishOnly hook   ← auto trước npm publish
+  bin/index.js install  ← auto khi user chạy npx
+```
+
+> Build output cũng bao gồm `core/` — bản distributable được copy vào `.agent/` của consumer khi `--init`.
+
+---
+
+## Module plug-in system
+
+Stack module là plug-in tùy chọn: cài qua `--module`, đọc ở runtime bởi `context-loader.md`.
+
+```
+Available modules (modules/):
+  java-spring, angular, react, nextjs, vue, nuxt, dotnet, golang,
+  php-laravel, flutter, react-native, ios-swiftui, android-compose,
+  context-engineering, qc-playwright
+
+Usage:
+  npx @edupia-tutor/spec-driven-docs --module java-spring
+    └─ copies modules/java-spring/ → consumer/.agent/modules/java-spring/
+
+Runtime, context-loader.md đọc:
+  .agent/modules/{tech_stack.module}/stack-profile.yaml
+  .agent/modules/{tech_stack.module}/architecture-snippets/
+```
+
+> **`qc-playwright`** là stack module cho native QC pipeline (`/qc-run-test`, `/qc-report`) — Python + pytest-playwright + Page Object — **ĐỘC LẬP** với dev implementation module (java-spring / react / flutter / …). Per-layer guides ở `skills/qc/<stage>/`. Danh sách module đầy đủ: [../05-reference/modules.md](../05-reference/modules.md).
+
+---
+
+## Hook system — data protection
+
+```
+Consumer project setup:
+  .claude/settings.json   ← registers hook (template)
+  hooks/data-guard.js     ← copied khi install
+
+Runtime — mỗi tool use (Read, Write, Edit, Bash):
+  data-guard.js checks:
+    .env* · *.key · *.pem · *secret* · *password* · *credential*
+    application-prod.* · appsettings.Production.*
+       │
+    safe → allow      blocked → exit(2) + warn user
+```
+
+---
+
+## Sub-agent orchestration
+
+Khi một command quá nặng cho single context window, orchestrator spawn các sub-agent độc lập (mỗi agent có context window riêng):
+
+```
+Main session (orchestrator — lightweight, chỉ coordinate)
+  ├─ spawn spec-agent   ──→ /refine-prd analysis      → returns findings.yaml
+  ├─ spawn codegen-agent ──→ /generate-code UC1        → returns src/ changes
+  └─ spawn test-agent   ──→ /dev-gen-test UC1          → returns self-check test files
+```
+
+**Lợi ích:** main session không bị bloat bởi large file reads · mỗi agent focus 1 task, ít hallucination · parallel cho nhiều UC.
+
+Pattern này được hiện thực hóa qua `steps/spawn-agent.md` và tự kích hoạt cho `/generate-bdd`, `/generate-code`, `/dev-gen-test` khi PRD vượt ngưỡng phức tạp (> 3 UC hoặc > 300 dòng). Chi tiết flow + tiết kiệm context: [pipeline.md](pipeline.md#spawn-agentmd--sub-agent-orchestration).
+
+---
+
+## Directory map
+
+```
+spec-driven-docs/
+├── docs/                    ← Toàn bộ tài liệu (bắt đầu ở docs/README.md)  ◀◀◀
+│   ├── 01-getting-started/
+│   ├── 02-guides/
+│   ├── 03-concepts/         ← file này (architecture.md)
+│   ├── 04-operations/
+│   └── 05-reference/
+├── bin/
+│   ├── build.js             ← assembles *.tmpl → *.md
+│   └── index.js             ← npm installer + hook installer
+├── commands/
+│   └── *.tmpl               ← slash commands
+├── hooks/
+│   ├── data-guard.js        ← PreToolUse sensitive file protection
+│   └── settings.json        ← hook registration template
+├── modules/
+│   └── {stack}/             ← java-spring, react, …, qc-playwright
+│       ├── module.yaml
+│       ├── stack-profile.yaml
+│       └── architecture-snippets/
+├── rules/
+│   ├── data-protection.md   ← what AI must NEVER read/write
+│   └── workflow.md          ← general AI behavior rules
+├── skills/
+│   ├── {name}/SKILL.tmpl    ← Claude plugin skills
+│   └── qc/<stage>/          ← per-layer QC automation guides
+├── steps/
+│   ├── gate.md              ← shared: file resolve + checkpoint
+│   ├── context-loader.md    ← shared: load all project context
+│   ├── spawn-agent.md       ← shared: sub-agent orchestration
+│   ├── capture-lesson.md    ← shared: record a guardrail (/learn etc.)
+│   └── report-footer.md     ← shared: standard output format
+└── templates/
+    ├── project-context.yaml ← consumer project config template
+    ├── architecture.template.md
+    └── platform-guide.template.md
+```
+
+> **Build output (gitignored):** `commands/*.md`, `skills/**/SKILL.md`, và `core/`. Consumer-side tester artifacts nằm trong shared spec repo tại `feedback/bug-reports/` và `feedback/bdd-proposals/`.
+
+> **Umbrella mode — API contract (tech-docs) là cross-team artifact:** khi `setup.spec_source` được set, tech-docs LUÔN route về spec repo tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/` (cùng feature-package với PRD / BDD / design-spec), KHÔNG per-service — để FE/App đọc contract qua spec submodule ở `/generate-code --phase=integration`. Chỉ khi không có `spec_source` thì tech-docs mới nằm per-service.
+
+> **Living Docs / trace data location:** khi `spec_source` set, `.trace/*.tsv` **authoritative** nằm **một chỗ** ở `{spec_source}/.trace/` (committed trong spec repo — PM quản lý tập trung; mỗi scenario mang `@trace.service`). Report `trace-report.json` sinh vào `{spec_source}/.living-docs/` (gitignored) + panel mirror cục bộ `./.trace`. Chỉ khi không có `spec_source` thì `.trace` mới per-service. Chi tiết: [traceability.md](traceability.md#living-docs--canonical-trong-spec-module--panel-mirror).
+
+---
+
+## Maintenance guide
+
+| Muốn thay đổi gì | Sửa file nào |
+|------------------|-------------|
+| Logic của 1 command cụ thể | `commands/{name}.tmpl` |
+| Logic của 1 skill cụ thể | `skills/{name}/SKILL.tmpl` |
+| Gate / checkpoint pattern | `steps/gate.md` |
+| Context loading | `steps/context-loader.md` |
+| Report format | `steps/report-footer.md` |
+| Sensitive file patterns | `hooks/data-guard.js` + `rules/data-protection.md` |
+| Stack-specific rules | `modules/{stack}/stack-profile.yaml` |
+| QC automation rules (per-layer) | `skills/qc/<stage>/` + `modules/qc-playwright/` |
+| Project setup template | `templates/project-context.yaml` |
+| Build system | `bin/build.js` |
+| Installer | `bin/index.js` |
+
+Sau khi sửa bất kỳ `.tmpl` hoặc `steps/*.md`:
+```bash
+npm run build   # regenerate tất cả *.md
+```

package/docs/03-concepts/pipeline.md

@@ -0,0 +1,274 @@
+[📚 Docs](../README.md) › [Concepts](README.md) › Pipeline
+
+# Pipeline
+
+Vòng đời feature đi qua các phase, mỗi transition có một **AI review gate**:
+**Discovery → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-check → QC automation → Tester feedback.** Phần sau mô tả từng phase và **step-architecture model** đằng sau mỗi command.
+
+## Mục lục
+
+- [Phase overview](#phase-overview)
+- [Workflow chi tiết](#workflow-chi-tiết)
+- [QC automation pipeline (Phase 5b)](#qc-automation-pipeline-phase-5b)
+- [Command internals — step architecture](#command-internals--step-architecture)
+  - [gate.md — universal entry](#gatemd--universal-entry)
+  - [context-loader.md — context loading sequence](#context-loadermd--context-loading-sequence)
+  - [spawn-agent.md — sub-agent orchestration](#spawn-agentmd--sub-agent-orchestration)
+  - [report-footer.md — standard output format](#report-footermd--standard-output-format)
+
+---
+
+## Phase overview
+
+| Phase | Who | Commands | Output |
+|-------|-----|----------|--------|
+| **0. Setup** *(one-time)* | Tech Lead | `/setup-ai-first`, `/sync`, `/sync-figma-*` | Config files, submodules, component catalog |
+| **1. Discovery** | PO + AI | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` |
+| **2. PRD** | AI → SA/PO review | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/prd.md` |
+| **2b. Design Spec** *(FE/App only)* | AI → Designer/PO sign-off | `/generate-design-spec` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` |
+| **3. BDD Spec** | AI → SA/Dev review | `/generate-bdd`, `/review-context` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` |
+| **4. Tech Design** *(platform-aware)* | AI → SA/Lead review | `/generate-tech-docs`, `/review-tech-docs` | BE: `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (API contract) · FE/App: `{UC-ID}-tech-design-{platform}.md` (client design — **gated** trên System BDD + BE contract) |
+| **5. Code** | AI → Dev review | `/generate-code` *(FE: `--phase=ui`/`--phase=integration`)*, `/review-code` | `src/...` |
+| **6. Dev Self-Check** | Dev (own code) | `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` | `src/test/...` — dev smoke (`dev_selftest`), tách khỏi QC suite |
+| **6b. QC Automation** *(official QC suite)* | QC | `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review` → `/qc-run-test` → `/qc-report` | QC test designs + run results — set `qc_status` (`qc-playwright` module) |
+| **7. Trace** | Tech Lead | `/validate-traces` | Coverage matrix + drift report |
+| **8. Tester Feedback** | QA → PO/Dev | `/report-bug`, `/propose-scenario` → `/sync` surfaces | `{spec}/feedback/...` → bug fix / new scenario / PRD update |
+| **Cross-cutting** | Any role | `/sync`, `/learn`, `/update-framework` | Synced repo · project guardrails · upgraded tooling |
+
+> **PRD là platform-agnostic (Option C):** Một PRD phục vụ mọi platform — chỉ mô tả business outcome, không UI/API. FE/App: PRD → Design Spec (2b) → BDD. BE: PRD → BDD (skip 2b). Thêm platform sau không cần đổi PRD.
+
+---
+
+## Workflow chi tiết
+
+```
+Phase 1: Discovery
+  /define-product ──────────→ specs/product-definition/{slug}.md
+        (7 phase Q&A: knowledge sync → feature def → user flow → clarify →
+         business rules → business logic → AC → validation matrix)
+
+Phase 2: PRD
+  /generate-prd ────────────→ specs/{domain}/{prd-slug}/prd.md
+  /refine-prd ──────────────→ .agent/review/{prd-slug}-findings.yaml
+                  [Review Board: Accept/Modify/Reject]
+                /refine-prd --resume → apply + bump version
+  /review-context {prd} ────→ .agent/review/{prd-slug}-review-context-findings.yaml
+       --fix (auto-fixable)  |  Review Board → --resume (apply + bump)
+       Checks: banned terms (P1) · ambiguity AC/BR (P2) · conflicts (P3) · completeness (P4)
+       ✅ APPROVED → Phase 3   ·   ❌ NEEDS_FIX → fix + re-run
+
+Phase 2b/3: Design Spec & BDD
+  /generate-design-spec ────→ specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md
+       (FE/App only — PO supplies node-level Figma link ?node-id= per screen;
+        AI fetches each frame via Figma MCP. Screen with no readable link → ❌ Missing;
+        sign-off + /generate-bdd blocked tới khi mọi screen có link)
+              [Designer review + PO sign-off]
+  /generate-bdd ────────────→ specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
+       THỨ TỰ OUTSIDE-IN (khi có client): web → app → system
+         System BDD được TỔNG HỢP từ web+app BDD (client-facing trước → BE/system suy ra để phục vụ)
+         (project chỉ-BE, không web/app: system gen thẳng từ PRD)
+       (apply platform vocabulary: web "clicks" / mobile "taps" / backend "submits a request")
+  /review-context {feature} → .agent/review/{uc-id}-review-bdd-findings.yaml
+       Checks: PRD coverage (mỗi AC + BR bullet → ≥1 scenario) · Gherkin R1–R10 · compliance C1–C5
+       ✅ APPROVED → Phase 4
+
+Phase 4: Tech Design  (platform-aware — đọc @trace.platform)
+  BE (system):
+    /generate-tech-docs {system .feature} → specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md
+         API contract: endpoints, data model, DB, caching (brownfield: reverse-document)
+  FE/App (web|app) — GATED, cần CÓ trước: System BDD + BE contract (approved):
+    /generate-tech-docs {web|app .feature} → specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md
+         client design: components, state, API-integration map theo BE contract, routing,
+         §2b Test Selectors (test-id ổn định cho element có action → QC locate khỏi scan)
+         (thiếu System BDD hoặc BE contract → HALT, in hướng dẫn)
+  /review-tech-docs ────────→ .agent/review/{uc-id}-tech-review-findings.yaml
+              [Review Board] → --resume (apply + bump revision)
+       ✅ APPROVED → Phase 5
+
+Phase 5: Code
+  /generate-code ───────────→ src/...  (@trace.implements tags)
+       FE: --phase=ui (UI + mock adapter, tester-ready)
+           mock shape: BE contract nếu có (chuẩn) → else System BDD (tạm, warn) — fixture values luôn từ System BDD
+           → khi BE contract approved → /generate-tech-docs {web|app} (FE design, Phase 4)
+           → --phase=integration (wire real API theo §4 của FE tech-design)
+       (component enforcement: ✅ existing / ⚠️ TODO blocked / ❌ NEW confirm)
+  /review-code ─────────────→ Report: Critical / Major / Minor → fix CRITICAL/MAJOR
+
+Phase 5 (cont): Dev Self-Check  (dev verifies their OWN code — NOT the official QC suite)
+  /dev-gen-test ────────────→ src/test/...  (@trace.verifies tags)
+  /dev-run-test ────────────→ records dev_selftest (pass/fail/not_run) + dev_selftest_at in trace
+  /dev-smoke-test ──────────→ live endpoint check (optional)
+  /validate-traces {domain} → coverage matrix + drift detection
+
+Phase 5b: QC Automation  (the OFFICIAL QC suite — see below)
+
+Phase 6: Tester / QC Feedback  (QA/QC → PO/Dev, closes the loop)
+  /report-bug {UC-ID} ──────→ {spec}/feedback/bug-reports/{BUG-ID}.md (State: Open) → push
+  /propose-scenario {UC-ID} → behavior ∈ AC → {spec}/feedback/bdd-proposals/{...}.md → push
+                              behavior MỚI  → {spec}/feedback/prd-change-requests/{...}.md → push
+              QC nguồn: /qc-run-test FAIL & /qc-analyze DOC_GAPS cũng route vào đây
+              PO/Dev: /sync → "📥 State: Open" → /fix-bug {BUG-ID} (Open→Fixed) · add BDD · update PRD
+              QC: /qc-run-test re-verify pass → bug Closed (qc_owner/qc_blocked_by clear)
+
+Cross-cutting (any role, anytime)
+  /sync ────────────────────→ git pull + submodules + Living Docs + surface feedback
+  /learn "AI does X, should Y" → project guardrail (loaded vào mọi command)
+  /update-framework ────────→ upgrade framework tooling từ npm
+```
+
+> **Large PRD (> 3 UC hoặc > 300 dòng):** `/generate-bdd`, `/generate-code`, `/dev-gen-test` tự chuyển sang **orchestration mode** — spawn 1 sub-agent/UC (xem [spawn-agent.md](#spawn-agentmd--sub-agent-orchestration)).
+
+> **Phase 7 — `/validate-traces` statuses:** ✅ OK (code version khớp spec) · ⚠️ DRIFT (code gen từ PRD/BDD cũ → re-generate) · 🔴 GAP (scenario có trong spec nhưng không có code) · — UNTRACKED (scenario ghi nhận nhưng chưa code-gen). Chi tiết: [traceability.md](traceability.md).
+
+---
+
+## QC automation pipeline (Phase 5b)
+
+Bộ test QC **chính thức** — native pipeline, chạy như một **branch sau khi BDD được approve** (`/review-context` (BDD) APPROVED), song song / sau khi dev `/generate-code`. 6 stage tuần tự, port từ agent của team QC (QC repo nay chỉ còn reference):
+
+```
+BDD approved (specs/{domain}/{prd-slug}/bdd/*.feature)
+        ▼
+/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+   (đọc UC/SC, phân tích)                          chạy test → set qc_status
+        ▼                                                ▼
+  QC analysis + test cases                      .trace/*.tsv: qc_status
+  → {qc_dir}/{UC-ID}/  (visible, mặc định docs/) (pass/fail/skip/not_run)
+    REQUIREMENT_ANALYSIS.md · DOC_GAPS.md ·       + qc_owner / qc_blocked_by
+    TEST_PLAN.md · test-cases/*.Test.md           (skills load từ {qc_skills_dir})
+
+  ── Feedback loop về spec (đóng vòng) ───────────────────────────────────
+  /qc-analyze DOC_GAPS blocker (spec sai/mơ hồ) ┐
+  /qc-run-test FAIL = product-gap               ├─▶ /report-bug · /propose-scenario
+  /qc-report tổng hợp gap → in sẵn lệnh         ┘            │  (cùng flow tester)
+                                                             ▼
+                                  feedback/ trong spec repo (State: Open)
+                                  → commit+push → PO/Dev thấy qua /sync (xem bug-flow.md)
+
+Mapping: mỗi QC test → scenario qua @trace.verifies={UC-ID}-SC{N}
+```
+
+- **Implementation module:** `qc-playwright` (Python + pytest-playwright + Page Object; Playwright Trace + pytest-html, KHÔNG dùng Allure). ĐỘC LẬP với dev implementation module — dùng bởi `/qc-run-test` & `/qc-report`.
+- **Khác biệt với dev self-check:** dev self-check (`/dev-*`) → `dev_selftest` (smoke, dev tự kiểm); QC automation (`/qc-*`) → `qc_status` (coverage QC chính thức). Hai tín hiệu **orthogonal**, cả hai surface trong Living Docs → xem [traceability.md](traceability.md).
+
+---
+
+## Command internals — step architecture
+
+Mỗi command trong `.agent/commands/` được compose từ các **step file** dùng chung trong `.agent/steps/`. Đây là nền tảng — mọi command gọi chúng theo thứ tự trước khi chạy logic riêng.
+
+| File | Role | Called by |
+|------|------|-----------|
+| `gate.md` | Universal entry — model check, file resolution, context load, user checkpoint | Mọi command |
+| `context-loader.md` | Multi-step context loading (stack → service routing → 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 trong project lessons file | `learn`, `review-code`, `fix-bug`, `debug` |
+| `report-footer.md` | Standard output format (status badge, artifact list, next command) | Mọi command |
+
+### gate.md — universal entry
+
+Mọi command bắt đầu ở đây, theo thứ tự:
+
+| Step | What it does |
+|------|-------------|
+| **Step 0** | Sub-agent mode check — nếu `$ARGUMENTS` là JSON payload với `_agent_mode: true`, skip Step 1–3, dùng slim context trực tiếp |
+| **Step 0-B** | Model check — prompt switch sang `claude-opus` cho generation phức tạp; `S` để skip |
+| **Step 1** | Resolve target file từ `$ARGUMENTS`; nếu thiếu, liệt kê candidate và hỏi user chọn |
+| **Step 2** | Execute `context-loader.md` — load toàn bộ project context vào working memory |
+| **Step 3** | CHECKPOINT — hiển thị summary (target file, stack, module, domains), chờ `Y` |
+
+```
+CHECKPOINT
+-----------
+Target     : specs/auth/FEAT-042-login/prd.md
+Project    : My App
+Tech stack : TypeScript / React 18
+Module     : react
+Domains    : auth, profile
+
+Proceed? (Y/N)
+```
+
+### context-loader.md — context loading sequence
+
+Load toàn bộ project context vào working memory theo thứ tự ưu tiên nghiêm ngặt:
+
+| 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) tới 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` → 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` → mistakes tích lũy (via `/learn`) loaded như hard constraints |
+| 6-B | UI COMPONENTS | `figma-components/{module}.md` → Figma name → code component + import path |
+| 6-C | UI TOKENS | `figma-tokens.md` → design tokens |
+| 7 | **RECAP** | `[CTX LOADED]` block — lock critical facts vào working memory |
+
+**Anti-lost-in-middle:** critical facts (Step 3) load đầu tiên; RECAP (Step 7) restate ở cuối để fresh khi generation bắt đầu (recency effect).
+
+```
+[CTX LOADED]
+Stack      : TypeScript / React 18 / PostgreSQL
+Layers     : Controller → Facade → Service → Repository
+Services   : 2 services: web-admin(react), api-backend(java-spring)
+Svc Root   : api-backend — conventions + trace_dir loaded from service config
+Dict       : loaded — 42 canonical terms, 8 banned terms
+Entities   : loaded — User, Order, Product
+Lessons    : loaded — 6 guardrails
+Components : loaded — web-admin (react) — 23 components mapped
+Tokens     : loaded — colors: 18, spacing: 12, typography: 6
+Status     : FULL
+```
+
+Status values: `FULL` · `PARTIAL — missing: {list}` · `MINIMAL` (chỉ project-context.yaml).
+
+### spawn-agent.md — sub-agent orchestration
+
+Khi PRD vượt ngưỡng phức tạp, `generate-bdd`, `generate-code`, `dev-gen-test` tự chuyển từ single-session sang orchestration mode.
+
+**Complexity thresholds:**
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| UC count trong PRD | > 3 UC | Spawn 1 sub-agent / UC |
+| PRD length | > 300 dòng | Spawn agents bất kể UC count |
+
+**Orchestration flow:**
+
+```
+Main session (orchestrator)
+  ├─ Step A: Build slim context JSON (stack + active_service + active_module + paths + arch summary + banned_terms)
+  ├─ Step B: Scan PRD → extract UC list [{uc_id, line_start, line_end}]
+  ├─ Step C: Announce plan → "Spawning N sub-agents..."
+  ├─ Step D: Spawn 1 sub-agent / UC (parallel)
+  │     mỗi agent nhận: { _agent_mode: true, uc_id, target_file, uc_section, context }
+  │     mỗi agent đọc CHỈ UC section của mình (không phải full PRD)
+  └─ Step E: Collect results → merge → { uc_id, files_created, status, errors }
+```
+
+**Tiết kiệm context window:**
+
+| Mode | What loads per agent |
+|------|---------------------|
+| Single session (≤ 3 UC) | Full context + full PRD + all UCs |
+| Orchestrator | Slim context + UC heading list only |
+| Each sub-agent | Slim context + **1 UC section only** |
+
+### report-footer.md — standard output format
+
+Mọi command kết thúc với footer này:
+
+```
+---
+Status : ✅ Complete
+Output Artifacts:
+  created  specs/auth/FEAT-042-login/bdd/FEAT-042-UC1-login.feature (3 scenarios)
+  updated  .trace/auth/FEAT-042-login/FEAT-042.tsv
+Next   : /review-context specs/auth/FEAT-042-login/bdd/FEAT-042-UC1-login.feature
+```
+
+**Status badges:** `✅ Complete` · `⚠️ Warnings` · `❌ Failed`. Field **Next** luôn gợi ý command tiếp theo hợp lý — không phải tra cứu.