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

package/steps/context-loader.md

@@ -74,7 +74,7 @@ If `services` section is present:
 
 **2. Route to service** — if active domain matches a key in `services`:
 - Override `paths.specs_dir` → `services.{domain}.specs_dir`
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- 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`
 - If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
@@ -86,7 +86,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - 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` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- 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.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -117,7 +117,7 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 | `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- 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`
 
 **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).
@@ -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.
 
 ---
 
@@ -210,7 +232,7 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 
 If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
@@ -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/steps/report-footer.md

@@ -34,15 +34,22 @@ 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 → `/generate-tests {UC-ID}` |
-| /generate-tests         | `/run-tests {UC-ID}`                          |
-| /run-tests (passing)    | `/review-code {UC-ID}`                        |
-| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/smoke-test {UC-ID}` or create PR            |
-| /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 | /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |

package/steps/review-fanout.md

@@ -0,0 +1,138 @@
+# Exhaustive Review Fan-Out + Completeness Convergence
+
+**Why this exists:** A single-pass review never lists every issue at once — the model
+stops at "enough" findings, so each later review round surfaces *new* problems
+(whack-a-mole). This procedure forces the review to **converge in one command run**:
+fan out across review dimensions in parallel, then loop a completeness critic until a
+round produces nothing new, *before* writing the findings file.
+
+The calling command supplies two things:
+- **DIMENSIONS** — the list of review dimensions to fan out over
+  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
+- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
+
+> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
+> procedure is **skipped** — the orchestrator is already running one dimension/UC per
+> sub-agent. Run the command's checks directly on the scoped section and return findings.
+
+---
+
+## Phase 1 — Parallel dimension scan
+
+**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
+fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
+same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
+granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+
+| Target size | Granularity | Agent count |
+|-------------|-------------|-------------|
+| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
+| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+
+The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
+single UC — which is what prevents misses on big PRDs.
+
+> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
+> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
+> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
+> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
+> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
+> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+
+### Agent cap — batch UCs when the fan-out gets too wide
+
+`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
+agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+
+1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
+2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
+   - Else split the scope list into `groups` contiguous buckets of roughly equal size
+     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
+     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
+3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+
+A batched agent reviews several UCs at once — still scoped far tighter than the whole
+file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
+more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+
+Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
+run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
+through its **one** dimension only — deeper coverage than one session juggling every
+dimension at once (avoids lost-in-the-middle).
+
+Sub-agent prompt template (fill the braces):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Completeness-critic convergence loop
+
+This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
+findings**, or a hard cap of **3 rounds**, whichever comes first:
+
+1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
+   - the full target file (`{target_file}`),
+   - the current `ALL_FINDINGS` list (so it knows what is already captured),
+   - the same slim context.
+   Prompt it:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
+3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
+4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+
+Record `convergence_rounds` (how many critic rounds ran) for the report.
+
+---
+
+## Phase 3 — Dedup, resolve conflicts, merge
+
+Sub-agents run **blind to each other** (independence = diverse coverage). They never
+talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
+the orchestrator**, where the full set is visible.
+
+1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
+   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
+   richer `suggestion`; if they differ on severity, keep the **higher** severity.
+2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
+   contradictions (two findings whose `suggestion`s cannot both be applied, or that
+   propose opposite fixes for the same spot):
+   - If the two suggestions can be **merged** into one coherent fix → merge them into a
+     single finding.
+   - If they are **mutually exclusive** → emit **one** finding that states both options
+     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) so a human picks — never silently drop one side.
+   - If a finding is **invalidated** by another (e.g. a structural finding says a section
+     is missing, but another quotes content from it) → drop the invalid one.
+3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
+4. **Assign stable IDs** `F001, F002, …` in that sorted order.
+5. Map each finding's `dimension` into the command's schema field
+   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
+6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
+
+In the command's final report, add one line:
+```
+Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+```

package/steps/spawn-agent.md

@@ -80,7 +80,7 @@ Build payload and invoke Agent tool for each UC:
 }
 ```
 
-> **Command scope**: Only `/generate-bdd` initiates orchestration mode. `/generate-code` and `/generate-tests` can run as sub-agents (they respect `_agent_mode: true` from Gate Step 0), but they do not spawn further sub-agents — their scope is already a single UC.
+> **Command scope**: Only `/generate-bdd` initiates orchestration mode. `/generate-code` and `/dev-gen-test` can run as sub-agents (they respect `_agent_mode: true` from Gate Step 0), but they do not spawn further sub-agents — their scope is already a single UC.
 
 Serialize this JSON and pass as `$ARGUMENTS` when invoking the sub-agent command.
 

package/steps/trace-mirror.md

@@ -0,0 +1,18 @@
+# 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.*
+
+After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+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}`.
+
+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.

package/templates/design-spec.template.md

@@ -14,6 +14,13 @@
   - ⚠️ TODO        → đánh dấu [TODO — chưa implement]
   - ❌ Chưa có     → đánh dấu [NEW — cần confirm với designer]
 
+  FIGMA LINKS (bắt buộc mỗi màn):
+  - Mỗi screen PHẢI có link Figma node-level (URL chứa ?node-id=...) — lấy bằng
+    right-click frame → "Copy link to selection". Đây là link AI đọc được qua Figma MCP.
+  - Link file trần (không có node-id) KHÔNG hợp lệ — AI không định vị được frame.
+  - Screen chưa có design → đánh dấu ❌ Missing; spec giữ Status "draft", chặn sign-off
+    và /generate-bdd cho tới khi đủ link.
+
   SCREEN STATES (bắt buộc mỗi màn):
   - Tối thiểu: default, loading, error
   - Thêm "empty" nếu màn có thể hiển thị trạng thái không có dữ liệu
@@ -34,7 +41,7 @@
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}](./{TICKET-ID}-slug.md)                          |
-| **Figma**          | {figma_url or TBD}                                            |
+| **Figma**          | {feature file link} ({linked}/{N} frames linked)             |
 | **Author**         | {PO name or "AI-assisted"}                                    |
 | **Created**        | {YYYY-MM-DD}                                                  |
 | **Updated**        | {YYYY-MM-DD}                                                  |
@@ -43,10 +50,10 @@
 
 # 1. Screen Inventory
 
-| # | Screen Name | Entry Point | Figma Frame | Notes |
-|---|-------------|-------------|-------------|-------|
-| 1 | {Screen 1}  | {how user arrives} | [Frame]({figma_url}) | |
-| 2 | {Screen 2}  | {entry point} | [Frame]({figma_url}) | |
+| # | Screen Name | Entry Point | Figma Frame (node-level link) | Notes |
+|---|-------------|-------------|-------------------------------|-------|
+| 1 | {Screen 1}  | {how user arrives} | [Frame]({node-level url}) | |
+| 2 | {Screen 2}  | {entry point} | ❌ Missing — add node-id link | |
 
 ---
 
@@ -181,9 +188,10 @@
 
 ## Figma Summary
 
-| Screen     | Figma Frame          | Status                         |
-|------------|----------------------|--------------------------------|
-| {Screen 1} | [Link]({url})        | ✅ Ready / ⏳ WIP / ❌ Missing  |
+| Screen     | Figma Frame (node-level) | Link / Fetch Status            |
+|------------|--------------------------|--------------------------------|
+| {Screen 1} | [Link]({node-level url}) | ✅ Linked & fetched            |
+| {Screen 2} | —                        | ❌ Missing — no node-id link    |
 
 ## Design Tokens Referenced
 

package/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/ARCHITECTURE.md

@@ -1,247 +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 / TEST     DEBUG          │
-│  /define-product  /generate-prd       /generate-code  /fix-bug      │
-│                   /refine-prd         /generate-tests /debug        │
-│                   /generate-bdd       /run-tests      /validate-    │
-│                   /generate-tech-docs /smoke-test      traces       │
-│                   /review-code        /setup-ai-first               │
-└──────────────────────────────────────────────────────────────────────┘
-                               │
-┌──────────────────────────────────────────────────────────────────────┐
-│  LAYER 5 — OUTPUT                       (artifacts in consumer proj) │
-│                                                                      │
-│  specs/product-definition/   specs/prd/   specs/bdd/               │
-│  tech-docs/                  src/         .trace/   .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 ──→ /generate-tests UC1 (own context window)
-       └─ returns: test files
-
-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)** also lives in the shared spec repo (`{spec_source}/specs/tech-docs/`) so BE and FE/App read the same contract via the spec submodule.
-
----
-
-## 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
-```