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

package/{commands/run-tests.md → core/commands/dev-run-test.md}

@@ -1,4 +1,10 @@
-# /run-tests — Run Tests & Report Results
+# /dev-run-test — Run Dev Self-Check Tests & Report Results
+
+> **Scope — dev self-check (smoke), not the official test suite.** Runs the tests produced
+> by `/dev-gen-test` so the developer can confirm their own code works before review. This
+> is a developer self-check, **not** the QC/dev-team's authoritative test run (separate flow).
+> The pass/fail is published to Living Docs as a **dev self-test** signal — it tells QC the
+> dev ran their checks; it is NOT a statement of official test coverage.
 
 ## Gate
 # Gate — Universal Entry Procedure
@@ -163,7 +169,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`)
@@ -175,13 +181,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.
 
 ---
 
@@ -205,7 +212,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).
@@ -298,7 +305,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).
 
 ---
 
@@ -522,6 +529,44 @@ xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhon
 
 ---
 
+## Write Trace State
+
+After the run, persist results to the **authoritative TSV** in the service so they reach
+the Living Docs report at the spec module (via `/sync` + `/validate-traces`). The test
+files themselves stay in the service — only the run *status* is reported.
+
+Update `{paths.trace_dir}/{UC-ID}.tsv` — for each scenario row (matched by `sc_id` via its
+test's `@trace.verifies={UC-ID}-SC{N}` tag):
+
+| Column | Value |
+|--------|-------|
+| `dev_selftest` | `pass` if all tests for this SC passed · `fail` if any failed · `not_run` if its tests were skipped/absent |
+| `dev_selftest_at` | today `YYYY-MM-DD` |
+
+Leave all other columns unchanged. `dev_selftest`/`dev_selftest_at` are orthogonal to `status`
+(OK/GAP/DRIFT/UNTRACKED): `status` tracks *coverage*, `dev_selftest` tracks the latest *run result*.
+
+## Refresh Panel Mirror
+# 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.
+
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -562,13 +607,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}` |
@@ -587,7 +632,7 @@ Next   : {suggested command with example arguments}
 
 
 ```
-/run-tests Report — {UC-ID} ({active_module})
+/dev-run-test Report — {UC-ID} ({active_module})
 ✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
 
 ## Failed Tests
@@ -597,7 +642,11 @@ Next   : {suggested command with example arguments}
 ## Recommendations
 {specific fix per failure}
 
+Trace: {paths.trace_dir}/{UC-ID}.tsv updated (dev_selftest, dev_selftest_at)
+
 Next:
   All tests pass → /review-code {UC-ID}
   Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/{commands/smoke-test.md → core/commands/dev-smoke-test.md}

@@ -1,6 +1,6 @@
-# /smoke-test — Smoke Test Live Service or App
+# /dev-smoke-test — Smoke Test Live Service or App
 
-Use when service/app is **already running**. Different from `/run-tests` (no live server needed).
+Use when service/app is **already running**. Different from `/dev-run-test` (no live server needed).
 
 ## Gate
 # Gate — Universal Entry Procedure
@@ -165,7 +165,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`)
@@ -177,13 +177,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.
 
 ---
 
@@ -207,7 +208,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).
@@ -300,7 +301,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).
 
 ---
 
@@ -366,7 +367,7 @@ Proceed to the next step of the calling command.
 
 ## Service Detection
 
-Read `active_module` from context. Use to select the correct smoke-test approach.
+Read `active_module` from context. Use to select the correct dev-smoke-test approach.
 
 | Platform | Modules |
 |---|---|
@@ -526,7 +527,7 @@ npx react-native run-ios       # build + install on iOS simulator
 # Open Xcode → select simulator → Product → Run
 ```
 
-### Phase 2 — Manual smoke-test checklist
+### Phase 2 — Manual dev-smoke-test checklist
 
 For the UC under test, verify on device:
 1. Navigate to the screen for this UC
@@ -591,13 +592,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}` |
@@ -616,7 +617,7 @@ Next   : {suggested command with example arguments}
 
 
 ```
-/smoke-test Report — {UC-ID}
+/dev-smoke-test Report — {UC-ID}
 Platform: {backend | web-frontend | mobile}
 | Endpoint / Flow       | Status      | Result  |
 |-----------------------|-------------|---------|

package/core/commands/fix-bug.md

@@ -163,7 +163,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`)
@@ -175,13 +175,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.
 
 ---
 
@@ -205,7 +206,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).
@@ -298,7 +299,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).
 
 ---
 
@@ -532,7 +533,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 |
 
@@ -597,13 +598,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/commands/generate-bdd.md

@@ -161,7 +161,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`)
@@ -173,13 +173,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.
 
 ---
 
@@ -203,7 +204,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).
@@ -296,7 +297,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).
 
 ---
 
@@ -810,7 +811,7 @@ After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-I
 
 **TSV columns (tab-separated, one header row + one data row per scenario):**
 ```
-sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tdev_selftest\tdev_selftest_at\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
@@ -818,7 +819,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 - If file exists (re-generation) → for each SC in the new `.feature`:
   - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
   - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
-  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` all set to `—`.
+  - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `tech_doc_revision` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
 **Values to write for each scenario:**
@@ -832,6 +833,8 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `implemented_by` | `—` |
 | `test_count` | `—` |
 | `test_classes` | `—` |
+| `dev_selftest` | `—` (no tests run yet) |
+| `dev_selftest_at` | `—` |
 | `prd_version` | `@trace.prd_version` from `.feature` header |
 | `bdd_version` | `@trace.bdd_version` from `.feature` header |
 | `tech_doc_revision` | `—` |
@@ -841,6 +844,27 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `status` | `UNTRACKED` |
 | `last_updated` | today `YYYY-MM-DD` |
 
+## Refresh Panel Mirror
+# 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.
+
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -881,13 +905,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}` |
@@ -929,4 +953,6 @@ Next (umbrella):
   → /review-context {feature-file} to verify coverage
   → /generate-tech-docs {feature-file}
   → /generate-code {feature-file}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```

package/core/commands/generate-code.md

@@ -163,7 +163,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`)
@@ -175,13 +175,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.
 
 ---
 
@@ -205,7 +206,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).
@@ -298,7 +299,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).
 
 ---
 
@@ -379,6 +380,7 @@ Read:
 1. The scoped `.feature` file only
 2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` (if exists)
 3. CLAUDE.md §architecture + §coding_standards
+4. **(FE/App only)** Design Spec at `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
 
 ---
 
@@ -402,6 +404,51 @@ Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feat
 Extract all `Then` clauses → collect implied response shapes and error states.
 If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
 
+**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
+Spec's frame links are the visual contract, and the local MCP reads them with far more
+fidelity than a plain web link.
+
+---
+
+## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+
+*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
+mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+
+The PO authored the Design Spec from **Figma web links** (read-only, limited). For
+codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
+gives far more: exact layout, design **variables/tokens**, **Code Connect** component
+mappings, selection context, and code snippets — things a web URL alone cannot return.
+
+**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
+(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+
+**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+
+```
+🎨 Figma Dev Mode MCP not detected.
+   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
+
+   1. Open the Figma DESKTOP app (not the browser)
+   2. Open the file/frame for this feature
+   3. Enable the Dev Mode MCP server:
+        Figma menu → Preferences → "Enable Dev Mode MCP Server"
+        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
+   4. Make sure this MCP server is added in your Claude Code MCP config
+   5. Select the frame for the screen you're implementing, then continue
+
+   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+```
+
+- `C` → re-detect; if now connected → proceed using the local MCP.
+- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
+  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+
+**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
+selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
+Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
+real token names, not hardcoded values.
+
 **If `--phase=integration`:**
 Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
 If `draft` or `in-review` → warn:
@@ -424,7 +471,7 @@ Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note i
 | `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
 | `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
 | `OK` | implemented + tested | Skip unless explicitly re-generating |
-| `GAP` | implemented, no tests | Skip codegen — already coded; run `/generate-tests` instead |
+| `GAP` | implemented, no tests | Skip codegen — already coded; run `/dev-gen-test` instead |
 
 Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
 If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
@@ -578,9 +625,30 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `last_updated` | today `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
+Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`) unchanged.
 `status` is computed by `/validate-traces` — do not set here.
 
+## Refresh Panel Mirror
+# 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.
+
+
 ## Commit
 ```bash
 git add {files}
@@ -627,13 +695,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}` |
@@ -657,6 +725,7 @@ Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
 fe_phase : {ui | integrated | —}
+Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
 
 Next:
   --phase=ui done:
@@ -666,9 +735,11 @@ Next:
 
   --phase=integration done:
     → /review-code {UC-ID}   ← code review required
-    → /generate-tests {UC-ID}  ← integration test suite
+    → /dev-gen-test {UC-ID}  ← integration test suite
 
   Default (no phase flag):
     → /review-code {UC-ID}   ← code review required before tests
-    → /generate-tests {UC-ID}
+    → /dev-gen-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
 ```