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

package/docs/01-getting-started/quickstart.md

@@ -0,0 +1,85 @@
+[📚 Docs](../README.md) › [Getting Started](README.md) › Quick Start
+
+# Quick Start
+
+Chạy feature đầu tiên end-to-end theo happy path. Mở Claude Code tại root project và làm theo thứ tự.
+
+## Mục lục
+
+- [Bước 0 — Setup project (một lần)](#bước-0--setup-project-một-lần)
+- [Happy-path command sequence](#happy-path-command-sequence)
+- [Bước tiếp theo](#bước-tiếp-theo)
+
+## Bước 0 — Setup project (một lần)
+
+```bash
+# 1. Cài framework (nếu chưa) — xem installation.md
+npx @anhth2/spec-driven-dev-plugin --init
+
+# 2. Mở project trong Claude Code, tạo cấu trúc + config files:
+/setup-ai-first
+```
+
+`/setup-ai-first` tạo cấu trúc thư mục (`specs/`, `tech-docs/`, `.trace/`, `.agent/`, `CLAUDE.md`). Sau đó điền thông tin thực tế vào 4 file config:
+
+| File | Nội dung |
+|------|----------|
+| `CLAUDE.md` | Architecture layers, coding standards, git conventions |
+| `.agent/project-context.yaml` | Tech stack, services, paths, ticket prefix |
+| `specs/domain-knowledge/business-dictionary.md` | Canonical terms, banned terms |
+| `specs/domain-knowledge/core-entities.md` | Entity glossary (fields, relationships) |
+
+> Project đã có sẵn `specs/`, `CLAUDE.md`, `.agent/project-context.yaml`? Bỏ qua bước này, vào thẳng happy path bên dưới. Chi tiết điền config + Figma setup: xem [../02-guides](../02-guides) và [../03-concepts](../03-concepts).
+
+## Happy-path command sequence
+
+Discovery → PRD → BDD → Tech Design → Code → Dev self-check:
+
+```
+# PHASE 1 — DISCOVERY
+/define-product
+    → specs/product-definition/{slug}.md
+
+# PHASE 2 — PRD
+/generate-prd specs/product-definition/{slug}.md
+    → specs/prd/{domain}/{slug}.md
+/refine-prd specs/prd/{domain}/{slug}.md         # AI suggestions → Review Board
+/refine-prd --resume specs/prd/{domain}/{slug}.md  # apply + bump version
+/review-context specs/prd/{domain}/{slug}.md      # quality gate (P1–P4)
+/review-context --resume specs/prd/{domain}/{slug}.md
+    → ✅ APPROVED → tiếp Phase 3
+
+# PHASE 3 — SPEC & DESIGN
+# (FE/App only) /generate-design-spec specs/prd/{domain}/{slug}.md → designer + PO sign-off
+/generate-bdd specs/prd/{domain}/{slug}.md
+    → specs/bdd/{domain}/{UC-ID}.feature
+/review-context specs/bdd/{domain}/{UC-ID}.feature
+/review-context --resume specs/bdd/{domain}/{UC-ID}.feature   # apply + bump bdd_version
+/generate-tech-docs specs/bdd/{domain}/{UC-ID}.feature
+    → tech-docs/{domain}/{UC-ID}-tech-design.md
+/review-tech-docs tech-docs/{domain}/{UC-ID}-tech-design.md
+/review-tech-docs --resume tech-docs/{domain}/{UC-ID}-tech-design.md
+
+# PHASE 4 — CODE
+/generate-code specs/bdd/{domain}/{UC-ID}.feature
+    → src/...  (@trace.implements tags)
+/review-code                                       # fix CRITICAL / MAJOR
+
+# PHASE 5 — DEV SELF-CHECK (dev verify code của mình — KHÔNG phải QC suite chính thức)
+/dev-gen-test specs/bdd/{domain}/{UC-ID}.feature
+    → src/test/...  (@trace.verifies tags)
+/dev-run-test                                      # sets dev_selftest in trace
+/dev-smoke-test                                    # optional — live endpoint check
+/validate-traces {domain}                          # coverage & drift
+```
+
+Mỗi review command ghi findings vào `.agent/review/*-findings.yaml`. Mở **Review Board** (VS Code panel) → Accept / Modify / Defer / Reject từng finding → chạy `--resume` để apply. Quick-fix không qua Review Board: `/review-context --fix {file}` (chỉ apply auto-fixable).
+
+> **FE/App:** `/generate-code --phase=ui` (UI + mock adapter, tester test ngay) rồi `--phase=integration` (wire API thật sau sign-off).
+
+## Bước tiếp theo
+
+- Hiểu khái niệm phía sau pipeline → [core-concepts.md](core-concepts.md).
+- QC suite chính thức (`/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report`) → [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+- Role guides, scenarios thực tế, multi-repo/umbrella → [../02-guides](../02-guides) và [../03-concepts](../03-concepts).
+- Full command reference → [../05-reference](../05-reference).

package/docs/02-guides/README.md

@@ -0,0 +1,27 @@
+[📚 Docs](../README.md) › Guides
+
+# Guides — Role Playbooks
+
+Mỗi role trong framework spec-driven-dev có một guide riêng: vai trò, commands, workflow, và các tình huống thực tế. Bắt đầu từ guide khớp với role của bạn.
+
+## Mục Lục
+
+| Guide | Dành cho | Nội dung |
+|---|---|---|
+| [Product Owner / BA](product-owner/README.md) | PO, BA | Viết PRD platform-agnostic, generate Design Spec + BDD, handoff cho dev team |
+| [Developer (FE / BE / App)](developer/README.md) | Dev | Đọc PRD + BDD từ spec submodule, generate tech-docs + code, dev self-check, trace system |
+| [Tester / QA](tester/README.md) | QA, Tester | Spec-manifest, đọc spec chain, viết test cases, `/report-bug` + `/propose-scenario` |
+| [QC Automation](qc-automation.md) | QC | Pipeline `/qc-*` 6 bước, `qc_status` chính thức, stack module `qc-playwright` |
+| Designer | Designer, UX | Tham gia giai đoạn Design Spec — sign-off màn hình + component trước khi PO gen BDD. Chưa có guide riêng; xem [Product Owner › Design Spec](product-owner/scenarios.md#tình-huống-3--tạo-design-spec-và-bdd-sau-khi-prd-approved) để biết điểm giao. |
+
+## Phân biệt nhanh hai luồng test
+
+- **Dev self-check** — `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test`, ghi `dev_selftest`. Smoke check của riêng dev, KHÔNG phải coverage chính thức.
+- **QC chính thức** — pipeline `/qc-analyze … /qc-report`, ghi `qc_status`. Bộ test authoritative, do QC chạy.
+
+Hai tín hiệu này đứng cạnh nhau trong Living Docs và không ghi đè nhau.
+
+## Xem thêm
+
+- [Concepts › Traceability](../03-concepts/traceability.md) — trace chain PRD → BDD → Code
+- [Reference › Commands](../05-reference/commands.md) — danh mục đầy đủ mọi command

package/docs/02-guides/developer/README.md

@@ -0,0 +1,46 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › Developer
+
+# Hướng Dẫn Developer — Spec-Driven Dev
+
+Tài liệu dành cho **Developer (FE / BE / App)** — vai trò, commands, trace system, workflow, và các tình huống thực tế. Được chia nhỏ theo chủ đề để dễ đọc:
+
+## Mục Lục
+
+| Trang | Nội dung |
+|---|---|
+| [Commands](commands.md) | Bảng lệnh cho dev · project lessons · xử lý feedback tester · khi nào dùng `--phase` |
+| [BDD & Trace System](bdd-and-trace.md) | Tại sao BDD quan trọng với dev · `@trace.*` fields · trace chain · khi nào `/validate-traces` |
+| [Workflow](workflow.md) | Luồng làm việc cơ bản từ nhận PRD đến tạo PR |
+| [Tình huống thực tế](scenarios.md) | 8 scenario: nhận PRD mới, đọc System/Web BDD, PRD đổi, API sign-off, bug từ tester, design spec, brownfield, umbrella, validate-traces |
+| [Checklist trước khi tạo PR](pr-checklist.md) | Checklist verify trước khi mở PR |
+
+## Vai Trò Dev Trong Framework
+
+```
+PO/BA                     Dev
+──────────────────────    ──────────────────────────────────────
+/define-product           /review-context (đọc PRD + BDD)
+/generate-prd        →    đọc BDD từ spec submodule
+/refine-prd               /generate-tech-docs (từ BDD → Tech Docs)
+/review-context           /generate-code     (từ BDD + Tech Docs → Code)
+/generate-design-spec →   /dev-gen-test
+/generate-bdd (web)       /review-code
+/generate-bdd (app)       /dev-run-test
+/generate-bdd (system)    /fix-bug / /debug
+                          /validate-traces
+```
+
+**Dev chịu trách nhiệm:**
+- Đọc và hiểu PRD + BDD từ spec submodule trước khi bắt đầu
+- **KHÔNG tự generate BDD** — BDD đã được PO generate trong spec repo
+- Đảm bảo code trace về đúng BDD scenario, BDD trace về đúng PRD
+- Báo PO/BA khi PRD hoặc BDD có gì không rõ hoặc mâu thuẫn — không tự suy diễn
+
+**Dev KHÔNG làm:**
+- Viết/sửa PRD — đó là việc của PO/BA
+- Viết/sửa Design Spec — đó là việc của PO/BA + Designer
+- Approve PRD — chỉ PO mới có quyền này
+
+---
+
+*Xem thêm:* [Product Owner Guide](../product-owner/README.md) · [Tester Guide](../tester/README.md) · [QC Automation Guide](../qc-automation.md) · [Concepts › Traceability](../../03-concepts/traceability.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/developer/bdd-and-trace.md

@@ -0,0 +1,123 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › BDD & Trace System
+
+# BDD & Trace System
+
+- [Tại sao BDD quan trọng với Dev](#tại-sao-bdd-quan-trọng-với-dev)
+- [Hiểu Trace System](#hiểu-trace-system)
+
+## Tại Sao BDD Quan Trọng Với Dev
+
+### BDD không phải "viết test thêm"
+
+BDD là **spec thực thi được** — nó định nghĩa CHÍNH XÁC hệ thống phải làm gì trước khi viết một dòng code.
+```
+PRD (business language)  →  BDD (technical spec)  →  Code (implementation)
+"Sai password 5 lần         Given 5 failed logins       if failCount >= 5:
+ → khoá 30 phút"            Then account locked            lockAccount(30min)
+                            And locked_until = now+30m
+```
+
+### BDD định hướng kiến trúc code
+
+BDD scenario là unit of work — mỗi scenario ánh xạ thành một test case, một function, một API endpoint. Viết BDD trước buộc dev phải nghĩ về interface trước implementation.
+```gherkin
+# BDD này buộc dev phải tạo:
+# - POST /auth/login endpoint
+# - lockAccount(duration) service method
+# - AccountLocked exception/response
+
+Scenario: Lock account after 5 failed attempts
+  Given user "alice@example.com" exists
+  When user attempts login with wrong password 5 times
+  Then account is locked for 30 minutes
+  And login returns 423 Locked with "retry_after" header
+```
+
+### BDD là tài liệu sống
+
+Khi BDD pass → code đang hoạt động đúng spec. Khi BDD fail → code lệch khỏi yêu cầu. Không cần đọc PRD để biết feature có đang hoạt động không — chạy BDD là biết ngay.
+
+### BDD đến từ spec repo — Dev đọc, không tự gen
+
+BDD được PO generate trong spec repo, nằm tại `specs/bdd/{domain}/`:
+
+| Subfolder | Platform | Dev team đọc |
+|---|---|---|
+| `web/` | FE/Web (clicks, sees, navigates) | FE/Web dev |
+| `app/` | Mobile (taps, sees screen, navigates) | App dev |
+| `system/` | System/BE (request, response, business rules) | BE dev |
+
+Cả 3 subfolder đều trace về **cùng 1 PRD**. BE không cần đọc BDD của FE và ngược lại.
+
+## Hiểu Trace System
+
+Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi tiết khái niệm: [Concepts › Traceability](../../03-concepts/traceability.md).)
+
+### Các trace fields quan trọng
+
+| Field | Vị trí | Ý nghĩa |
+|---|---|---|
+| `@trace.domain` | PRD frontmatter | Domain của feature (auth, payment, ...) — dùng để route vào đúng service submodule |
+| `@trace.module` | BDD / Tech Doc header | Module trong codebase sẽ implement |
+| `@trace.prd` | BDD / Tech Doc header | Link về PRD gốc |
+| `@trace.bdd` | Code comment / test | Link về BDD scenario |
+| `@trace.status` | PRD frontmatter | `draft` / `approved` — chỉ code khi `approved` |
+| `dev_selftest` | Trace TSV | `pass` / `fail` / `not_run` — kết quả dev self-check, set bởi `/dev-run-test`. Surfaced trong Living Docs để QC biết dev đã chạy self-check — **KHÔNG phải coverage chính thức** |
+| `dev_selftest_at` | Trace TSV | Timestamp lần chạy `/dev-run-test` gần nhất |
+| `qc_status` | Trace TSV | `pass` / `fail` / `skip` / `not_run` — kết quả **QC chính thức**, set bởi `/qc-run-test` (do QC chạy, KHÔNG phải dev). Orthogonal với `dev_selftest` và với coverage `status` |
+| `qc_run_at` | Trace TSV | Timestamp lần chạy `/qc-run-test` gần nhất |
+
+### Ví dụ trace chain hoàn chỉnh
+
+```
+specs/prd/auth/FT-001-login.md          ← @trace.domain: auth, @trace.status: approved
+    ↓
+specs/bdd/auth/FT-001-login.feature     ← @trace.prd: FT-001, @trace.module: AuthService
+    ↓
+src/auth/auth.service.ts                ← // @trace.bdd: FT-001-UC1-SC1
+```
+
+### Khi nào chạy /validate-traces?
+
+- Sau khi refactor đổi tên file/function
+- Sau khi PRD được PO cập nhật (version mới)
+- Trước khi tạo PR lớn
+- Khi CI báo trace validation fail
+- **Sau mỗi codegen session trong umbrella mode** — để sync Living Docs panel
+
+```
+/validate-traces
+→ Sẽ report: broken links, orphan BDD (không có PRD), dead code traces
+```
+
+**Lưu ý khi dùng umbrella (submodule):**
+```
+Vấn đề: Living Docs panel mở ở umbrella root (hoặc một service submodule đơn lẻ) → nếu không có mirror local → TRỐNG.
+         TSV authoritative nằm committed trong từng service submodule: user-service/.trace/, order-service/.trace/
+
+Giải pháp: /validate-traces (hoặc /sync) regenerate canonical trace-report.json + TSV mirror
+          trong SPEC MODULE tại {spec_source}/.living-docs/ (gitignored), đồng thời ghi
+          mirror local tại ./.trace của workspace hiện tại để panel không trống khi dev mở
+          một service submodule đơn lẻ.
+
+Lệnh chạy sau mỗi session:
+/validate-traces
+→ Reads .trace/*.tsv authoritative (committed) trong từng service: user-service/.trace/, order-service/.trace/, ...
+→ Writes canonical trace-report.json + TSV mirror → {spec_source}/.living-docs/ (gitignored, regenerated bởi /sync hoặc /validate-traces)
+→ Writes panel mirror → ./.trace của workspace hiện tại (non-empty khi mở single service)
+→ Living Docs panel cập nhật ngay
+```
+
+> **Authoritative vs mirror:** per-service `.trace/*.tsv` vẫn được **commit** trong từng service (nguồn sự thật). `{spec_source}/.living-docs/` và `./.trace` chỉ là mirror gitignored, regenerated bởi `/sync` hoặc `/validate-traces`.
+
+Thêm `.living-docs/` (spec module) và umbrella/workspace `.trace/` mirror vào `.gitignore`:
+```
+# .gitignore — spec module
+.living-docs/
+# .gitignore — workspace/umbrella root (mirror, không commit)
+.trace/
+```
+
+---
+
+← [Commands](commands.md) · Tiếp theo: [Workflow](workflow.md)

package/docs/02-guides/developer/commands.md

@@ -0,0 +1,76 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Commands
+
+# Commands Dành Cho Dev
+
+| Command | Mục đích | Khi nào dùng |
+|---|---|---|
+| `/sync` `[spec-branch]` | **One-command setup hoặc update** — git pull + submodule sync + Living Docs refresh. Truyền branch để override branch spec submodule (vd `/sync develop`) | **Mỗi sáng trước khi bắt đầu work** |
+| `/update-framework` | Nâng cấp **bản thân framework** (`.agent/commands/`, steps/, modules/) từ npm | Khi có version framework mới — không đụng project-context/CLAUDE.md |
+| `/review-context {prd-file}` | Đọc + xác nhận PRD + BDD đủ rõ trước khi code — fan-out review dimension thành sub-agent song song + completeness-critic loop, findings file đầy đủ ngay trong 1 lần chạy | **Bước đầu tiên** khi nhận PRD mới |
+| `/generate-tech-docs {prd-file}` | Sinh Tech Docs (API, DB schema, sequence diagram) | Sau khi đọc BDD từ spec submodule |
+| `/generate-code {bdd-file}` | Sinh code — BE hoặc FE khi API đã sẵn sàng | Sau khi tech docs `approved` |
+| `/generate-code {bdd-file} --phase=ui` | FE: gen UI + mock adapter (BE chưa ready) | Ngay sau khi đọc BDD |
+| `/generate-code {bdd-file} --phase=integration` | FE: wire API thật thay mock | Sau khi sign-off gate `approved` |
+| `/dev-gen-test {bdd-file}` | **Dev self-check** — sinh test cases từ BDD để dev tự verify code mình vừa gen (KHÔNG phải bộ test chính thức của QC/dev-team) | Song song hoặc sau generate-code |
+| `/review-code {file}` | Review code theo 4 lens (Security/Perf/Arch/Test) | Trước khi tạo PR |
+| `/review-tech-docs {tech-doc-file}` | Review chất lượng Tech Docs | Sau generate-tech-docs |
+| `/dev-run-test` | **Dev self-check** — chạy test do dev tự gen để xác nhận code mình hoạt động (smoke/self-verify, KHÔNG phải coverage chính thức) — *umbrella mode: tự `cd` vào service_root, dùng service's `test_command`*. Ghi `dev_selftest` (pass/fail) vào trace TSV | Sau khi code + tests sẵn sàng |
+| `/fix-bug {issue}` | Phân tích + fix bug có trace | Khi có bug report |
+| `/debug {symptom}` | Debug vấn đề chưa rõ nguyên nhân | Khi cần trace root cause |
+| `/dev-smoke-test` | **Dev self-check** — kiểm tra nhanh các luồng chính của code mình vừa làm (smoke, không thay thế bộ test chính thức) | Sau deploy hoặc merge lớn |
+| `/validate-traces` | Kiểm tra toàn bộ trace chain còn hợp lệ | Sau refactor hoặc khi PRD update |
+| `/learn {text}` | Ghi lại lỗi AI hay lặp thành guardrail | Khi AI lặp lại lỗi mà bạn không muốn nó tái diễn |
+
+> **Dev self-check vs QC chính thức:** `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` (ghi `dev_selftest`) chỉ là **smoke self-check của riêng dev**. Bộ QC chính thức giờ là native pipeline `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — **do QC chạy, không phải việc của dev** — và ghi `qc_status` riêng. Chi tiết: [QC Automation Guide](../qc-automation.md).
+
+> Danh mục đầy đủ mọi command: [Reference › Commands](../../05-reference/commands.md).
+
+## Project Lessons — dạy framework không lặp lỗi
+
+AI đôi khi lặp đi lặp lại một lỗi trong dự án (vd: gọi repository thẳng từ controller, quên null-check). Thay vì sửa thủ công mỗi lần, **ghi lại thành "lesson"** — context-loader sẽ nạp nó vào đầu **mọi** lệnh như một ràng buộc cứng.
+
+**2 cách ghi nhận:**
+```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: khi /review-code, /fix-bug, /debug phát hiện lỗi lặp lại
+# → nó hỏi "Record as a project lesson? (Y/N)" → Y
+```
+
+**Lưu ở đâu:** `paths.lessons_file` (mặc định `specs/domain-knowledge/lessons-learned.md`; umbrella: `.agent/project-lessons.md` mỗi service). **Commit file này** để cả team cùng được bảo vệ.
+
+> Đây là **bộ nhớ dự án**, không phải fine-tune model — lesson được nạp vào context mỗi lần chạy, nên AI "nhớ" và không lặp lại. Xem `[CTX LOADED]` có dòng `Lessons: loaded — N guardrails`.
+
+## Xử lý feedback từ tester
+
+Tester gửi bug report (`/report-bug`) và đề xuất scenario (`/propose-scenario`) vào `feedback/` của **spec repo**. Khi dev chạy `/sync`, nó liệt kê:
+```
+📥 New tester feedback (pulled this sync):
+   Bug reports:    BUG-20260608-01  FT-001 — ...  [layer: Code]
+   Scenario proposals: FT-001-trailing-spaces → AC2 (pending review)
+```
+
+Dev hành động theo phân loại:
+- **Bug report** → `/fix-bug {BUG-ID}` (report đã có sẵn spec-context + AC bị vi phạm + layer)
+- **Scenario proposal map vào AC sẵn có** → thêm scenario vào `.feature` (hoặc `/generate-bdd` lại), rồi `/generate-code` + `/dev-gen-test`
+- **Proposal là yêu cầu mới (PRD change request)** → chuyển PO sửa PRD trước
+
+> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → tester chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
+
+> Tester chỉ *đề xuất* trong `feedback/` — dev/PO mới đưa vào BDD chính thức. Giữ đúng ownership.
+
+## Khi nào dùng `--phase` cho FE/App?
+
+| Tình huống | Command |
+|---|---|
+| API **đã có sẵn** và đang hoạt động | `/generate-code {file}` — không flag, gen real API ngay |
+| BE **chưa ready**, FE muốn bắt đầu ngay | `/generate-code {file} --phase=ui` — UI + mock adapter |
+| Sign-off gate xong, cần wire API thật | `/generate-code {file} --phase=integration` |
+| BE implement (system BDD) | `/generate-code {file}` — không flag |
+
+> `--phase` chỉ có giá trị khi BE chưa sẵn sàng. Nếu API đã live → bỏ qua `--phase`, chạy thẳng default.
+
+---
+
+← [Developer Guide](README.md) · Tiếp theo: [BDD & Trace System](bdd-and-trace.md)

package/docs/02-guides/developer/pr-checklist.md

@@ -0,0 +1,15 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › PR Checklist
+
+# Checklist Trước Khi Tạo PR
+
+- [ ] `/validate-traces` → all green (không broken trace)
+- [ ] `/dev-run-test` → all pass *(umbrella: đảm bảo service có `.agent/project-context.yaml` với `test_command` trước khi chạy)*
+- [ ] `/review-code` → không có issue Critical hoặc Major chưa xử lý
+- [ ] Code trace về đúng BDD scenarios trong `my-project-specs/specs/bdd/`
+- [ ] Code có `@trace.bdd` comment cho các function implement BDD scenario
+- [ ] Tech Docs đã được update nếu có thay đổi API/DB schema
+- [ ] **Không tự sửa BDD** — BDD là của PO, nếu cần update thì báo PO rồi pull lại
+
+---
+
+← [Tình huống thực tế](scenarios.md)