@anhth2/spec-driven-dev-plugin 0.10.0 → 0.12.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`
@@ -92,6 +96,7 @@ 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`
 
 > **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.
 
@@ -132,19 +137,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 +271,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/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/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
@@ -106,6 +124,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/ARCHITECTURE.md

@@ -1,258 +0,0 @@
-# Framework Architecture
-
-> **Nguyên tắc**: Nhìn file này để hiểu toàn bộ framework trước khi đọc bất kỳ file chi tiết nào.
-
----
-
-## Layer Diagram
-
-```
-╔══════════════════════════════════════════════════════════════════════╗
-║               SPEC-DRIVEN DEV FRAMEWORK  v0.3                       ║
-╚══════════════════════════════════════════════════════════════════════╝
-
-┌──────────────────────────────────────────────────────────────────────┐
-│  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              skills/*/SKILL.tmpl                   │
-│  (slash commands)             (auto-trigger by description match)    │
-│  /generate-bdd                detect: "tạo BDD", "sinh feature"     │
-│  /generate-code               detect: "viết code", "implement"      │
-└──────────────────────────────────────────────────────────────────────┘
-                               │ both built by 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 at build time via {{include:steps/X.md}}                  │
-│  Source: *.tmpl  →  Output: *.md  (gitignored)                      │
-└──────────────────────────────────────────────────────────────────────┘
-                               │ context loaded
-┌──────────────────────────────────────────────────────────────────────┐
-│  LAYER 3 — PROJECT CONTEXT              (read from consumer project) │
-│                                                                      │
-│  .agent/project-context.yaml  → paths, tech_stack, domains          │
-│  CLAUDE.md                    → architecture, coding standards       │
-│  rules/data-protection.md     → what AI must never access           │
-│  .agent/modules/{stack}/      → stack rules (plug-in, optional)     │
-└──────────────────────────────────────────────────────────────────────┘
-                               │ context-aware
-┌──────────────────────────────────────────────────────────────────────┐
-│  LAYER 4 — EXECUTION                            (command logic)      │
-│                                                                      │
-│  DISCOVERY        PRD / BDD           CODE / DEV-CHECK  DEBUG        │
-│  /define-product  /generate-prd       /generate-code  /fix-bug      │
-│                   /refine-prd         /dev-gen-test   /debug        │
-│                   /generate-bdd       /dev-run-test   /validate-    │
-│                   /generate-tech-docs /dev-smoke-test    traces     │
-│                   /review-code        /setup-ai-first               │
-│                                                                      │
-│  Lưu ý: /dev-gen-test, /dev-run-test, /dev-smoke-test là dev        │
-│  self-check / smoke (dev tự kiểm code của mình), KHÔNG phải bộ      │
-│  test QC chính thức — QC là một flow riêng chạy sau.                │
-└──────────────────────────────────────────────────────────────────────┘
-                               │
-┌──────────────────────────────────────────────────────────────────────┐
-│  LAYER 5 — OUTPUT                       (artifacts in consumer proj) │
-│                                                                      │
-│  Spec module (cross-team, via {spec_source}):                       │
-│    specs/product-definition/  specs/prd/  specs/bdd/                │
-│    specs/tech-docs/ (API contract)   .living-docs/ (gitignored)     │
-│  Service submodule (per-service):                                   │
-│    src/   .trace/*.tsv (authoritative, committed)   .agent/review/  │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Data Flow — Một command chạy như thế nào
-
-```
-User types: /generate-bdd specs/prd/payment/PAY-01.md
-                │
-                ▼
-[L0] data-guard.js checks tool calls in real-time
-     → nếu AI cố đọc .env / *.key → BLOCK + warn
-                │
-                ▼
-[L1] commands/generate-bdd.md được Claude đọc
-     (assembled từ generate-bdd.tmpl + injected steps)
-                │
-                ▼
-[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 to avoid, stack-specific patterns
-                │
-                ▼
-[L4] generate-bdd logic:
-     → đọc PRD → extract UC/BR/AC
-     → apply BDD rules R1-R10
-     → viết specs/bdd/{domain}/{UC-ID}.feature
-                │
-                ▼
-[L5] Output: specs/bdd/payment/PAY-01-UC1.feature
-```
-
----
-
-## Build System
-
-```
-Source (committed to git)        Build output (gitignored)
-──────────────────────────       ─────────────────────────
-commands/*.tmpl         ──┐
-skills/**/SKILL.tmpl    ──┤  node bin/build.js  →  commands/*.md
-steps/*.md   (shared)   ──┘                         skills/**/SKILL.md
-
-Trigger:
-  npm run build          ← manual
-  prepublishOnly hook    ← auto before npm publish
-  bin/index.js install   ← auto when user runs npx
-```
-
----
-
-## Module Plug-in System
-
-```
-Available modules (modules/):
-  java-spring, angular, react, nextjs,
-  dotnet, golang, php-laravel, context-engineering
-
-Usage:
-  npx @anhth2/spec-driven-dev-plugin --module java-spring
-    └─ copies modules/java-spring/ → consumer/.agent/modules/java-spring/
-
-At runtime, context-loader.md reads:
-  .agent/modules/{tech_stack.module}/stack-profile.yaml
-  .agent/modules/{tech_stack.module}/architecture-snippets/
-```
-
----
-
-## Hook System — Data Protection
-
-```
-Consumer project setup:
-  .claude/settings.json   ← registers hook (provided as template)
-  hooks/data-guard.js     ← copied from this package on install
-
-Runtime:
-  Every 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
-```
-
----
-
-## Future — Sub-Agent Pattern (v2 roadmap)
-
-Khi một số command quá nặng cho single context window:
-
-```
-Main session (orchestrator — lightweight, chỉ coordinate)
-  │
-  ├─ spawn spec-agent ──→ /refine-prd analysis (own context window)
-  │    └─ returns: findings.yaml
-  │
-  ├─ spawn codegen-agent ──→ /generate-code UC1 (own context window)
-  │    └─ returns: src/ changes
-  │
-  └─ spawn test-agent ──→ /dev-gen-test UC1 (own context window)
-       └─ returns: dev self-check test files (smoke, không phải QC)
-
-Benefits:
-  - Main session không bị bloat bởi large file reads
-  - Mỗi agent focus vào 1 task, ít hallucination hơn
-  - Parallel execution cho multiple UCs
-
-Implementation path:
-  1. Tạo steps/spawn-agent.md — pattern + handoff payload format
-  2. Tạo commands/orchestrate-feature.tmpl — top-level orchestrator
-  3. Sub-agent commands nhận input qua $ARGUMENTS (JSON payload)
-```
-
----
-
-## Directory Map
-
-```
-spec-driven-dev/
-├── ARCHITECTURE.md          ← Đọc đây trước  ◀◀◀
-├── bin/
-│   ├── build.js             ← assembles *.tmpl → *.md
-│   └── index.js             ← npm installer + hook installer
-├── commands/
-│   └── *.tmpl               ← slash commands (23 commands)
-├── hooks/
-│   ├── data-guard.js        ← PreToolUse sensitive file protection
-│   └── settings.json        ← hook registration template
-├── modules/
-│   └── {stack}/             ← 8 stacks: java-spring, angular, react,
-│       ├── module.yaml          nextjs, dotnet, golang, php-laravel,
-│       ├── stack-profile.yaml   context-engineering
-│       └── 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 (8 skills)
-├── 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`, and `core/` (the distributable copied into a consumer's `.agent/` by `--init`). Consumer-side tester artifacts live in the shared spec repo under `feedback/bug-reports/` and `feedback/bdd-proposals/`. In umbrella mode the **API contract (tech-docs)** is a **cross-team artifact**: khi `setup.spec_source` được set, tech-docs LUÔN route về `{spec_source}/specs/tech-docs/` (giống PRD / design-spec / domain-knowledge), 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**: `.trace/*.tsv` của mỗi service là **authoritative** và được commit trong chính SERVICE submodule. Canonical report của Living Docs (`trace-report.json` + bản TSV mirror đã namespaced) được sinh vào SPEC MODULE tại `{spec_source}/.living-docs/` (gitignored) bởi `/sync` hoặc `/validate-traces`. Ngoài ra một panel mirror cục bộ tại `./.trace` của workspace hiện tại cũng được ghi để VS Code panel resolve được data ngay cả khi mở bên trong một service submodule (không chỉ ở umbrella root). Lý do: spec module được mount vào mọi umbrella/service workspace, nên nó là nơi chung, luôn resolve được cho cross-team dashboard.
->
-> Trace TSV schema có thêm 2 cột `dev_selftest` (pass/fail/not_run) và `dev_selftest_at`, được set bởi `/dev-run-test` và surface trong Living Docs report như tín hiệu **dev self-check** (không phải coverage QC chính thức).
-
----
-
-## 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` |
-| 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
-```