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

package/core/skills/test/SKILL.md

@@ -254,6 +254,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -420,19 +427,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -532,7 +561,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -655,6 +685,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -824,19 +861,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -936,7 +995,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -1074,6 +1134,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

package/core/steps/context-loader.md

@@ -132,19 +132,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -244,7 +266,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}

package/core/steps/report-footer.md

@@ -34,6 +34,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

package/core/templates/project-context.yaml

@@ -106,6 +106,14 @@ domains:
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
 #     specs_dir: "{{SERVICE_SUBMODULE_DIR}}/specs/bdd"
 #     tech_docs_dir: "{{SERVICE_SUBMODULE_DIR}}/specs/tech-docs"
+#
+# IMPORTANT — per-service CLAUDE.md:
+#   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
+#   architecture + coding standards for ITS stack. context-loader loads CLAUDE.md in two
+#   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
+#   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
+#   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
+#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
 #   {{DOMAIN_2}}:
 #     path: "{{SERVICE_2_DIR}}"
 #     module: "{{STACK_MODULE}}"

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

@@ -0,0 +1,19 @@
+[📚 Docs](../README.md) › Getting Started
+
+# Getting Started
+
+Bắt đầu với spec-driven-dev framework — cài đặt, chạy feature đầu tiên, và nắm các khái niệm cốt lõi trong vài phút.
+
+## Mục lục (this section)
+
+- [installation.md](installation.md) — Cài framework, prerequisites (Node, Claude Code), QC automation stack, và VS Code extension (Review Board + Living Docs panels).
+- [quickstart.md](quickstart.md) — Chạy feature đầu tiên end-to-end: Discovery → PRD → BDD → Tech Design → Code → Dev self-check.
+- [core-concepts.md](core-concepts.md) — Khái niệm trong 5 phút: spec-as-source-of-truth, pipeline phases, traceability, dev_selftest vs qc_status, umbrella/spec-module.
+
+## Đọc gì trước?
+
+1. Mới hoàn toàn? → bắt đầu ở [core-concepts.md](core-concepts.md) để hiểu triết lý.
+2. Sẵn sàng cài? → [installation.md](installation.md).
+3. Đã cài xong? → [quickstart.md](quickstart.md) để chạy feature đầu tiên.
+
+> Cần đào sâu hơn? Xem các section khác trong [📚 Docs](../README.md) — concepts, multi-repo/umbrella, QC pipeline, command reference, architecture.

package/docs/01-getting-started/core-concepts.md

@@ -0,0 +1,102 @@
+[📚 Docs](../README.md) › [Getting Started](README.md) › Core Concepts
+
+# Core Concepts
+
+Các khái niệm cốt lõi trong 5 phút. Đào sâu hơn ở [../03-concepts](../03-concepts).
+
+## Mục lục
+
+- [Spec là source of truth](#spec-là-source-of-truth)
+- [Pipeline phases](#pipeline-phases)
+- [Traceability](#traceability)
+- [dev_selftest vs qc_status](#dev_selftest-vs-qc_status)
+- [Umbrella & spec module](#umbrella--spec-module)
+
+## Spec là source of truth
+
+> **Write the spec first. Generate the code from the spec. Trace everything.**
+
+- Con người định nghĩa *WHAT* — acceptance criteria, business rules, platform requirements.
+- AI sinh ra *HOW* — BDD scenarios, tech design, code, tests — thích ứng theo platform.
+- Mỗi artifact được review trước khi sang phase kế tiếp (AI review gate ở mọi transition).
+- Mỗi dòng code truy ngược về một scenario trong file `.feature`.
+
+**PRD platform-agnostic (Option C):** một PRD phục vụ mọi platform — chỉ mô tả nghiệp vụ, không có chi tiết UI hay API. FE/App đọc PRD → Design Spec → BDD; BE đọc PRD trực tiếp → BDD. Thêm platform mới sau không cần sửa PRD.
+
+## Pipeline phases
+
+```
+Discovery → PRD → BDD Spec → Tech Design → Code → Dev Self-Check
+                                                       (+ QC suite chính thức song song)
+```
+
+| Phase | Ai | Lệnh chính | Output |
+|-------|-----|-----------|--------|
+| Discovery | PO + AI | `/define-product` | `specs/product-definition/{slug}.md` |
+| PRD | AI → SA/PO | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/prd/{domain}/{slug}.md` |
+| Design Spec *(FE/App)* | AI → Designer/PO | `/generate-design-spec` | `specs/design-spec/...` |
+| BDD Spec | AI → SA/Dev | `/generate-bdd`, `/review-context` | `specs/bdd/{domain}/{UC-ID}.feature` |
+| Tech Design | AI → SA/Lead | `/generate-tech-docs`, `/review-tech-docs` | `tech-docs/{domain}/{UC-ID}-tech-design.md` |
+| Code | AI → Dev | `/generate-code`, `/review-code` | `src/...` |
+| Dev Self-Check | Dev | `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` | `src/test/...` |
+| QC Automation | QC | `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` | QC designs + run results |
+| Trace audit | Tech Lead | `/validate-traces {domain}` | Coverage + drift report |
+
+Chi tiết từng phase + happy-path lệnh: [quickstart.md](quickstart.md).
+
+## Traceability
+
+Mỗi artifact link tới artifact khác qua `@trace.*` tags:
+
+```
+product-definition.md
+  └─► PRD.md (Service, Module trong metadata)
+        └─► {UC-ID}.feature (@trace.service, @trace.module, @trace.prd_version)
+              └─► tech-design.md (@trace.bdd_version)
+                    └─► src/ code (@trace.implements, @trace.prd_version, @trace.bdd_version)
+                          └─► src/test/ (@trace.verifies, @trace.service)
+                                └─► .trace/{UC-ID}.tsv (drift tracking)
+```
+
+`/validate-traces {domain}` đọc các `.trace/{UC-ID}.tsv` và báo cáo:
+
+| Status | Nghĩa |
+|--------|-------|
+| ✅ OK | Code version khớp spec version |
+| ⚠️ DRIFT | Code sinh từ PRD/BDD version cũ — cần re-generate |
+| 🔴 GAP | Scenario có trong spec nhưng chưa có code implement |
+| — UNTRACKED | Scenario ghi nhận nhưng chưa code-gen |
+
+Chi tiết tags + chain: [../03-concepts/traceability.md](../03-concepts/traceability.md).
+
+## dev_selftest vs qc_status
+
+Hai signal **độc lập** trong trace TSV — đừng nhầm lẫn:
+
+| Signal | Set bởi | Ý nghĩa |
+|--------|---------|---------|
+| `dev_selftest` (+ `dev_selftest_at`) | `/dev-run-test` | Dev tự verify code của mình (smoke / self-check). **KHÔNG phải** official coverage. |
+| `qc_status` (+ `qc_run_at`) | `/qc-run-test` | Bộ QC suite chính thức (native `/qc-*` pipeline), keyed theo `@trace.verifies={UC-ID}-SC{N}`. |
+
+QC owns `qc_status`; dev owns `dev_selftest`. Living Docs panel hiển thị cả hai cạnh nhau. `/qc-run-test` & `/qc-report` dùng stack `qc-playwright` (độc lập với dev module — xem [installation.md](installation.md)).
+
+## Umbrella & spec module
+
+Cho project có nhiều service repo riêng (microservices, multi-platform): pattern khuyến nghị là **umbrella repo** — repo tổng chứa các service repo dưới dạng git submodule.
+
+```
+my-project-umbrella/          ← mở Claude Code ở đây
+├── .agent/project-context.yaml   ← routing config (domain → service)
+├── my-project-specs/         ← submodule: spec module của PO (PRD, design-spec, tech-docs)
+├── user-service/             ← submodule: microservice
+└── web-app/                  ← submodule: FE app
+```
+
+- **Spec module** (`{spec_source}/`): chứa PRD, Design Spec, và tech-docs (API contract) — shared để mọi umbrella đọc cùng contract. Report canonical của Living Docs cũng sinh tại `{spec_source}/.living-docs/`.
+- **Routing:** context-loader đọc `@trace.domain` từ PRD → tra trong `services` config → route BDD/code vào đúng service submodule. PRD phải có `@trace.domain` khớp một key trong `services`.
+
+Setup umbrella đầy đủ, file ownership, two-layer commit, multi-platform → [Operations › Sync & Update §4 Umbrella mode](../04-operations/sync-and-update.md#4-umbrella-mode--git-submodule).
+
+---
+
+Sẵn sàng chạy? → [quickstart.md](quickstart.md).

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

@@ -0,0 +1,154 @@
+[📚 Docs](../README.md) › [Getting Started](README.md) › Installation
+
+# Installation
+
+Cài đặt framework vào project và (tùy chọn) VS Code extension.
+
+## Mục lục
+
+- [Prerequisites](#prerequisites)
+- [Cài framework](#cài-framework)
+- [Kiểm tra cài đặt](#kiểm-tra-cài-đặt)
+- [Upgrade](#upgrade)
+- [QC automation stack (tùy chọn)](#qc-automation-stack-tùy-chọn)
+- [VS Code extension (khuyến nghị)](#vs-code-extension-khuyến-nghị)
+- [Uninstall](#uninstall)
+
+## Prerequisites
+
+| Tool | Version | Link |
+|------|---------|------|
+| Node.js | bất kỳ (check: `node -v`) | [nodejs.org](https://nodejs.org) |
+| Claude Code CLI | Latest | [claude.ai/code](https://claude.ai/code) |
+| VS Code | ≥ 1.85 | [code.visualstudio.com](https://code.visualstudio.com) |
+| Git | bất kỳ | |
+
+> Claude Code cần subscription (Claude Pro / Team / API key).
+
+## Cài framework
+
+Chạy từ **thư mục root của project**. Cách khuyến nghị là `--init` — cài framework vào `.agent/` (commit vào git, cả team dùng chung) và tạo shortcut trong `.claude/commands/`.
+
+```bash
+# Single-service project:
+npx @anhth2/spec-driven-dev-plugin --init --module java-spring
+
+# Multi-service monorepo (cài vào từng subfolder trong 1 lệnh):
+npx @anhth2/spec-driven-dev-plugin --init \
+  --services backend:java-spring,web-admin:react,app-mobile:flutter
+```
+
+Kết quả:
+- `.agent/` — toàn bộ framework files (commit vào git, shared với team)
+- `.claude/commands/` — shortcut trỏ về `.agent/commands/`
+- `.agent/FRAMEWORK_VERSION` — tracking version để upgrade
+
+```bash
+git add .agent/ .claude/commands/
+git commit -m "chore: init spec-driven-dev"
+```
+
+> **Multi-repo / umbrella?** Xem hướng dẫn umbrella setup chi tiết trong [Operations › Sync & Update §4 Umbrella mode](../04-operations/sync-and-update.md#4-umbrella-mode--git-submodule).
+
+### Legacy install (global / per-project)
+
+```bash
+npx @anhth2/spec-driven-dev-plugin           # global: ~/.claude/commands/
+npx @anhth2/spec-driven-dev-plugin --project # project: ./.claude/commands/
+```
+
+## Kiểm tra cài đặt
+
+Mở Claude Code tại project, gõ `/` — bạn sẽ thấy các lệnh:
+
+```
+/setup-ai-first
+/define-product
+/generate-prd
+/generate-bdd
+...
+```
+
+> Không thấy lệnh? Chạy lại lệnh cài (global lưu tại `~/.claude/commands/`, trên Windows: `ls "$env:USERPROFILE\.claude\commands\"`).
+
+## Upgrade
+
+Từ **trong Claude Code** (khuyến nghị — check version, xử lý umbrella mode, review diff):
+
+```
+/update-framework
+```
+
+Hoặc từ terminal:
+
+```bash
+bash scripts/upgrade.sh
+# hoặc:
+npx @anhth2/spec-driven-dev-plugin@latest --init
+git diff .agent/ && git add .agent/ && git commit -m "chore: upgrade framework"
+```
+
+> Chỉ upgrade framework command files. `project-context.yaml`, `CLAUDE.md`, domain-knowledge, và `.trace/` không bao giờ bị ghi đè. Để sync *content* của project (submodule code/specs) dùng `/sync`.
+
+## QC automation stack (tùy chọn)
+
+Bộ QC suite chính thức (`/qc-*`) là **native** trong framework. Hai lệnh cuối — `/qc-run-test` và `/qc-report` — dùng stack module **`qc-playwright`**, **độc lập với dev module**. Cài riêng:
+
+```bash
+# 1. Python 3 + pytest-playwright
+pip install pytest-playwright
+
+# 2. Cài browsers
+python3 -m playwright install
+```
+
+`qc-playwright` = Python + pytest-playwright + Page Object (output: Playwright Trace + pytest-html). Chi tiết pipeline: [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+
+## VS Code extension (khuyến nghị)
+
+**Spec Driven Dev** là VS Code extension với 2 panels. Không bắt buộc nhưng khuyến nghị. VS Code tự cập nhật khi có version mới.
+
+```bash
+code --install-extension edupia-team.spec-driven-dev-team
+```
+
+Hoặc: `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → search **Spec Driven Dev**.
+
+### Panel 1 — Review Board
+
+Đọc `*-findings.yaml` từ `.agent/review/` — hỗ trợ findings từ mọi review command (`/refine-prd`, `/review-context`, `/review-tech-docs`).
+
+- Lens tabs: All / QA / DEV / SA / PO hoặc PRD / BDD / TECH.
+- Mỗi finding có badge `⚡ auto-fix` / `👤 human`.
+- 4 actions: Accept · Modify (có note) · Defer · Reject — kèm progress bar, full-text search.
+- **Smart Apply** spawn terminal chạy đúng lệnh `--resume`.
+
+Mở Review Board: sidebar panel (Activity Bar), hoặc right-click file `*-findings.yaml` → "Open Review Board", hoặc Command Palette. Nếu panel trống: file phải có đuôi `-findings.yaml`, nằm trong `.agent/review/`, và đóng hẳn rồi mở lại VS Code.
+
+### Panel 2 — Living Documentation
+
+Đọc `.trace/*.tsv` — dashboard traceability health toàn project.
+
+- Stat cards: PRDs, Use Cases, Scenarios, Code Cov%, Test Cov%, Drift, Gap.
+- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Status).
+- Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED. Filter + search + live reload.
+
+Mở: `Ctrl+Shift+P` → **"Spec Driven Dev: Open Living Documentation"**. Mở được cả ở umbrella root lẫn trong một service submodule riêng lẻ. Nếu trống, chạy `/generate-bdd` cho ≥1 feature để tạo file `.trace/{UC-ID}.tsv` đầu tiên.
+
+> Report canonical sinh vào spec module tại `{spec_source}/.living-docs/` (gitignored); bản mirror cục bộ ở `./.trace`. Chi tiết traceability: [core-concepts.md](core-concepts.md) và [../03-concepts/traceability.md](../03-concepts/traceability.md).
+
+## Uninstall
+
+**Mac/Linux:**
+```bash
+rm -rf .agent/ .claude/commands/
+```
+
+**Windows (PowerShell):**
+```powershell
+Remove-Item -Recurse -Force .agent, .claude\commands
+```
+
+---
+
+Cài xong? → [quickstart.md](quickstart.md) để chạy feature đầu tiên.

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