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

package/steps/context-loader.md

@@ -36,6 +36,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -48,6 +50,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -73,7 +77,7 @@ If `services` section is present:
 - If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
 
 **2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -84,6 +88,7 @@ If `services` section is present:
 - Set `active_service = unresolved`
 
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -92,8 +97,10 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -113,12 +120,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `conventions.test_command` | service's `conventions.test_command` |
 | `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
-| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 

package/steps/report-footer.md

@@ -20,6 +20,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
 
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -61,7 +91,10 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*

package/steps/trace-mirror.md

@@ -1,18 +1,26 @@
 # Refresh Living Docs panel mirror *(local, umbrella mode)*
 
 *Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
-the service `.trace/` IS the panel location, so nothing to mirror.*
+the repo's own `.trace/` IS the panel location, so nothing to mirror.*
 
-After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+After updating the authoritative TSV(s) at `{paths.trace_dir}`:
 
-1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+**When `setup.spec_source` is set (consolidated trace — the common case):**
+`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
+This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
+commit/push the spec submodule for the trace update (same as `feedback/`).
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
 2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
-   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
-   (create the dir; overwrite). Use `active_service` for `{service-name}`.
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
+   No per-service namespacing — there is one trace set; the owning service is carried in each
+   row's `@trace.service`.
+
+**Legacy (no `spec_source` — per-service trace):**
+Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespaced by `active_service`).
 
 This keeps the open workspace's Living Docs panel current **between syncs** — it is a
-**local convenience mirror only**. The *canonical* report in the spec module
-(`{spec_source}/.living-docs/`) and the merged `trace-report.json` are rebuilt by
-`/sync` or `/validate-traces` (those need every service's data, so a single per-UC
-command cannot produce them). For orchestrated commands, do this once in the orchestrator
-after all sub-agents return — not inside each sub-agent.
+**local convenience mirror only**. The merged `trace-report.json` (canonical, in
+`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
+commands, do this once in the orchestrator after all sub-agents return — not inside each
+sub-agent.

package/templates/project-context.yaml

@@ -36,6 +36,21 @@ paths:
   prd_template: "specs/templates/prd.template.md"
   refinement_dir: ".agent/review"
 
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
   # Product Definitions
   product_definitions_dir: "specs/product-definition"
   product_definition_template: "specs/templates/product-definition.template.md"
@@ -61,11 +76,14 @@ paths:
   # Trace
   trace_dir: ".trace"
 
-  # Tester feedback (written by /report-bug and /propose-scenario).
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
   # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
   # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
   bug_reports_dir: "feedback/bug-reports"
   bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
 
 tech_stack:
   language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go
@@ -93,19 +111,22 @@ domains:
 #   mode: umbrella                            # "umbrella" | "single" (default: single)
 #   spec_source: "{{SPEC_SUBMODULE_PATH}}"   # path to PO spec submodule, e.g. "free-trial-specs"
 #
-# When spec_source is set, context-loader auto-derives:
+# When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo;
+# service submodules hold only code + .trace/):
+#   specs_dir            → {spec_source}/specs/bdd            # ALL BDD (web/app/system) — cross-team
 #   prd_dir              → {spec_source}/specs/prd
 #   design_spec_dir      → {spec_source}/specs/design-spec
-#   tech_docs_dir        → {spec_source}/specs/tech-docs   # shared API contract (per-service tech_docs_dir below wins in multi-service)
+#   tech_docs_dir        → {spec_source}/specs/tech-docs      # BE API contract + FE tech-design
 #   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
 # (You can still override these manually in paths: section below.)
 #
 # services:                                   # domain → service submodule routing
 #   {{DOMAIN_1}}:                             # must match @trace.domain in PRD files
-#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule
+#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     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"
+#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
 #
 # IMPORTANT — per-service CLAUDE.md:
 #   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its

package/docs/02-guides/qc-automation.md

@@ -1,92 +0,0 @@
-[📚 Docs](../README.md) › [Guides](README.md) › QC Automation
-
-# Hướng Dẫn QC Automation — Spec-Driven Dev
-
-Pipeline QC automation **chính thức** của framework — được port từ agent của team QC (reference repo `ai-automation-qc-base`) vào ngay trong framework. Nó sinh và chạy automation **Playwright/pytest** từ BDD `.feature` chính thức, rồi ghi tín hiệu **`qc_status`** (authoritative) vào trace TSV → Living Docs.
-
-## Mục Lục
-
-- [Hai luồng test: dev self-check vs QC chính thức](#hai-luồng-test-dev-self-check-vs-qc-chính-thức)
-- [Pipeline 6 bước](#pipeline-6-bước)
-- [Stack — module qc-playwright](#stack--module-qc-playwright)
-- [Trace join: qc_status đến Living Docs như thế nào](#trace-join-qc_status-đến-living-docs-như-thế-nào)
-- [Entry point](#entry-point)
-- [Skills theo layer](#skills-theo-layer)
-
-## Hai Luồng Test: Dev Self-Check vs QC Chính Thức
-
-Pipeline QC này **khác** với developer **self-check** (`/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test`):
-
-| Signal | Owner | Command | Ý nghĩa |
-|--------|-------|---------|---------|
-| `dev_selftest` | Dev | `/dev-run-test` | smoke check của riêng dev (KHÔNG authoritative) |
-| `qc_status` | QC | `/qc-run-test` | kết quả QC automation **chính thức** |
-
-Cả hai hiển thị **cạnh nhau** trong Living Docs; không cái nào ghi đè cái nào. `dev_selftest: pass` chỉ nghĩa "dev đã tự smoke qua"; coverage chính thức nằm ở `qc_status`.
-
-## Pipeline 6 Bước
-
-```
-/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
- (requirement   (risk/plan   (test-case      (review     (gen+run     (report +
-  breakdown)     + Q-for-dev)  .Test.md)       gate)       Python →     evidence)
-                                                            qc_status)
-```
-
-| Command | Vai trò | Output |
-|---------|---------|--------|
-| `/qc-analyze` | bóc tách spec chính thức thành requirement + BR/AC + data-flow + `DOC_GAPS` | `{refinement_dir}/qc/{UC-ID}/` |
-| `/qc-plan` | risk / what-if / questions-for-dev + test plan | `TEST_PLAN.md` |
-| `/qc-design-test` | thiết kế test case (Markdown `.Test.md`), tag `@trace.verifies={UC-ID}-SC{N}` | `test-cases/` |
-| `/qc-review` | cổng review hai chiều: review test case (sau design) và script (sau run) | findings |
-| `/qc-run-test` | sinh + chạy Python pytest-playwright; **ghi `qc_status`** per scenario | `{trace_dir}/{UC-ID}.tsv` |
-| `/qc-report` | report pytest-html + Playwright trace + evidence | `reports/<feature>/report.html` |
-
-## Stack — Module qc-playwright
-
-`/qc-run-test` và `/qc-report` dùng stack module `qc-playwright`
-(`.agent/modules/qc-playwright/stack-profile.yaml`): **Python + pytest-playwright + Page
-Object** (slim `BasePage`, 3-layer), **Playwright Trace + pytest-html** (KHÔNG Allure). Stack
-này độc lập với module implementation của dev (java-spring, react, flutter, …).
-
-Per-layer guides chi tiết nằm trong `skills/qc/<stage>/` (port từ skills của agent QC):
-functional / integration / e2e / non-functional / exploratory.
-
-## Trace Join: qc_status Đến Living Docs Như Thế Nào
-
-1. `.feature` chính thức định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}`.
-2. `/qc-design-test` ghi SC mà test case thuộc về; `/qc-run-test` tag mỗi pytest test
-   `# @trace.verifies={UC-ID}-SC{N}`.
-3. `/qc-run-test` ghi `qc_status` (`pass|fail|skip|not_run`) + `qc_run_at` vào trace TSV của
-   service (authoritative), rồi refresh panel mirror local.
-4. `/validate-traces` (hoặc `/sync`) tổng hợp các TSV thành report Living Docs tại
-   `{spec_source}/.living-docs/` — dashboard hiển thị `qc_status` cạnh `dev_selftest`.
-
-## Entry Point
-
-Pipeline QC bắt đầu ngay khi BDD của một UC được approved (`/review-context (BDD)` APPROVED):
-
-```
-/qc-analyze {UC-ID}   →  … → /qc-report {UC-ID}  →  /validate-traces {UC-ID}
-```
-
-## Skills Theo Layer
-
-Các skill chi tiết theo từng giai đoạn QC nằm trong `skills/qc/`:
-
-| Stage skill | Vai trò |
-|---|---|
-| `qa-analyst` | phân tích requirement, sinh `DOC_GAPS` |
-| `qa-planner` | test plan, risk, questions-for-dev |
-| `qa-designer` | thiết kế test case `.Test.md` theo layer (functional / integration / e2e / non-functional / exploratory) |
-| `qa-reviewer` | cổng review test case và script |
-| `qa-runner` | sinh + chạy Python pytest-playwright, sinh report (Playwright Trace + pytest-html) |
-
-Mỗi skill **tự chứa** (self-contained) và có version frontmatter để theo dõi khi nâng cấp.
-
-## Xem Thêm
-
-- [Guide › Tester](tester/README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`
-- [Concepts › Traceability](../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
-- [Reference › Modules](../05-reference/modules.md) — chi tiết module `qc-playwright`
-- [Reference › Commands](../05-reference/commands.md) — danh mục đầy đủ mọi command