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

package/core/skills/test/SKILL.md

@@ -1,14 +1,14 @@
 ---
-description: Generates unit and integration tests from BDD specs, runs the test suite and reports results, or smoke-tests live API endpoints on a running service. Trigger when: "/generate-tests", "/run-tests", "/smoke-test", "tạo test", "viết test", "chạy test", "generate tests", "run tests", "test kết quả", "smoke test", "test API", "kiểm tra endpoint đang chạy".
+description: Generates unit and integration tests from BDD specs, runs the test suite and reports results, or dev-smoke-tests live API endpoints on a running service. Trigger when: "/dev-gen-test", "/dev-run-test", "/dev-smoke-test", "tạo test", "viết test", "chạy test", "generate tests", "run tests", "test kết quả", "smoke test", "test API", "kiểm tra endpoint đang chạy".
 ---
 
 # Test Skills — Generate, Run & Smoke Test
 
-This skill handles three commands: `/generate-tests`, `/run-tests`, and `/smoke-test`.
+This skill handles three commands: `/dev-gen-test`, `/dev-run-test`, and `/dev-smoke-test`.
 
 ---
 
-## /generate-tests — Generate Unit & Integration Tests
+## /dev-gen-test — Generate Unit & Integration Tests
 
 ### Gate
 
@@ -212,7 +212,7 @@ src/test/{language}/{package}/
 ### Output
 
 ```
-/generate-tests Complete — {UC-ID}:
+/dev-gen-test Complete — {UC-ID}:
   ✅ service/{Service}Test.{ext} ({M} tests)
   ✅ facade/{Facade}Test.{ext} ({M} tests)
   ✅ controller/{Controller}Test.{ext} ({M} tests)
@@ -256,13 +256,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |
@@ -282,7 +282,7 @@ Next   : {suggested command with example arguments}
 
 ---
 
-## /run-tests — Run Tests & Report Results
+## /dev-run-test — Run Tests & Report Results
 
 ### Gate
 
@@ -362,7 +362,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`)
@@ -374,13 +374,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -404,7 +405,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).
@@ -497,7 +498,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).
 
 ---
 
@@ -602,7 +603,7 @@ Read stack trace and analyze:
 ### Output
 
 ```
-/run-tests Report — {service}
+/dev-run-test Report — {service}
 Run at: {datetime}
 
 ## Summary
@@ -656,13 +657,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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}` |
@@ -682,10 +683,10 @@ Next   : {suggested command with example arguments}
 
 ---
 
-## /smoke-test — Test Live API Endpoints
+## /dev-smoke-test — Test Live API Endpoints
 
 Use when the service is **already running** to verify endpoints work correctly.
-Different from `/run-tests` (which runs unit/integration tests without a live server).
+Different from `/dev-run-test` (which runs unit/integration tests without a live server).
 
 ### Phase 1 — Find Service URL
 
@@ -765,7 +766,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`)
@@ -777,13 +778,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -807,7 +809,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).
@@ -900,7 +902,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).
 
 ---
 
@@ -1022,7 +1024,7 @@ tail -n 100 {LOG_FILE_PATH}
 ### Output
 
 ```
-/smoke-test Report — {UC-ID}
+/dev-smoke-test Report — {UC-ID}
 Tested at: {datetime}
 Base URL: http://localhost:{port}
 
@@ -1074,13 +1076,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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/core/steps/capture-lesson.md

@@ -54,7 +54,7 @@ If `lessons_path` does not exist, create it with this header first:
 | code-gen | /generate-code output |
 | bdd | /generate-bdd output |
 | tech-docs | /generate-tech-docs output |
-| tests | /generate-tests output |
+| tests | /dev-gen-test output |
 | prd | /generate-prd, /refine-prd output |
 | general | every command |
 

package/core/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,13 +86,14 @@ 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` — **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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **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.
 
 ---
 
@@ -116,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).
@@ -209,7 +210,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).
 
 ---
 

package/core/steps/report-footer.md

@@ -36,13 +36,13 @@ Suggest the logical next command based on workflow phase:
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /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/core/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/core/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/core/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/core/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/core/templates/product-definition.template.md

@@ -72,9 +72,9 @@
 - {Function 2}
 
 ### User Story
-As a {User role}
-I want to {User goal}
-So that {Business value}
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
 
 ---
 

package/core/templates/project-context.yaml

@@ -50,7 +50,9 @@ paths:
   # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root).
   lessons_file: "specs/domain-knowledge/lessons-learned.md"
 
-  # Tech Docs
+  # Tech Docs (BE-authored API contract).
+  # In umbrella mode with spec_source set, context-loader auto-routes this to
+  # {spec_source}/specs/tech-docs so FE/App read the contract via the spec submodule.
   tech_docs_dir: "tech-docs"
 
   # Design Specs (FE/App platforms only — web, app)
@@ -94,6 +96,7 @@ domains:
 # When spec_source is set, context-loader auto-derives:
 #   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)
 #   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
 # (You can still override these manually in paths: section below.)
 #

package/modules/android-compose/module.yaml

@@ -0,0 +1,13 @@
+name: "Android (Jetpack Compose)"
+version: "1.0.0"
+description: "Native Android development with Jetpack Compose + Kotlin"
+language: "Kotlin"
+framework: "Jetpack Compose"
+stack_type: "mobile"
+default_layer_order:
+  - Domain models
+  - Repository (data layer)
+  - UseCase (domain logic)
+  - ViewModel (StateFlow<UiState>)
+  - Composable screens (presentation)
+test_framework: "JUnit5 + MockK + Turbine"

package/modules/android-compose/stack-profile.yaml

@@ -0,0 +1,57 @@
+build:
+  compile: "./gradlew assembleRelease"
+  test: "./gradlew test"
+  run: "./gradlew installDebug / Open in Android Studio → Run"
+  lint: "./gradlew lint"
+
+architecture:
+  style: "MVVM + Clean Architecture (Composable → ViewModel → UseCase → Repository)"
+  key_rules:
+    - "Composables are pure UI functions — no business logic, no direct suspend calls"
+    - "ViewModels expose StateFlow<UiState>; Composables collect via collectAsStateWithLifecycle()"
+    - "UseCases are single-responsibility classes injected into ViewModels"
+    - "Repositories are interfaces; implementations live in the data layer"
+    - "Dependency injection via Hilt"
+    - "Never launch coroutines from a Composable directly — use LaunchedEffect or ViewModel"
+  folder_structure: |
+    src/main/java/{package}/
+    ├── core/
+    │   ├── network/      ← Retrofit instance, interceptors
+    │   ├── theme/        ← MaterialTheme, Color, Type, Shape
+    │   └── utils/
+    ├── shared/
+    │   └── components/   ← reusable Composables (AppButton, AppTextField...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── ui/           ← Composable screens + components
+    │       ├── viewmodel/    ← ViewModel + UiState
+    │       ├── domain/       ← UseCases, domain models
+    │       └── data/         ← Repository impl, data sources
+
+coding_standards:
+  naming:
+    composables: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
+    viewmodels: "PascalCase + ViewModel suffix (e.g., OrderListViewModel)"
+    usecases: "PascalCase + UseCase suffix (e.g., CreateOrderUseCase)"
+    files:
+      screen: "{Feature}Screen.kt"
+      viewmodel: "{Feature}ViewModel.kt"
+      usecase: "{Feature}UseCase.kt"
+  patterns:
+    state_management: "StateFlow<UiState> in ViewModel"
+    navigation: "Jetpack Navigation Compose"
+    networking: "Retrofit + OkHttp"
+    serialization: "Kotlinx Serialization or Gson"
+    di: "Hilt"
+    async: "Kotlin Coroutines + Flow"
+
+testing:
+  unit: "JUnit5 + MockK + Turbine (Flow testing)"
+  ui: "Compose UI Test (composeTestRule)"
+  patterns:
+    - "Test ViewModel with fake repositories and TestCoroutineDispatcher"
+    - "UI tests use semantics matchers — set Modifier.testTag() on Composables"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"