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

package/core/commands/generate-design-spec.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).
 
 ---
 
@@ -398,19 +399,6 @@ Using `active_module` and `platform_type` derived from context loading:
 
 ---
 
-## Figma Check
-
-Ask:
-
-```
-Do you have a Figma link for this feature? (paste URL or press Enter to skip)
-```
-
-- If URL provided → store as `figma_url`.
-- If skipped → `figma_url = "TBD"`. Add AI Assumption: "Figma link not provided — all screen descriptions are text-based. Link must be added and verified before Design Spec sign-off."
-
----
-
 ## Screen Discovery
 
 From the PRD's Section 4 (User Flow + Wireframe), extract all screen / page / modal names mentioned.
@@ -431,6 +419,54 @@ Wait for confirmation. Store the confirmed list as `screen_list`.
 
 ---
 
+## Figma Frame Links *(mandatory — one readable node-level link per screen)*
+
+A Design Spec is only as good as the design it points to. The AI **cannot read a plain
+file link** (`figma.com/design/{fileKey}/...` with no `node-id`) — it needs a
+**node-level link to each specific frame** so it can fetch that frame's real layout,
+components, and tokens via the Figma MCP. So collect one link **per screen**, not one
+link for the whole feature.
+
+**Ask the PO, listing every screen in `screen_list`:**
+
+```
+Paste the Figma frame link for each screen below.
+
+  In Figma: select the frame → right-click → "Copy link to selection"
+  (the URL must contain  ?node-id=...  — that is the per-frame link the AI can read)
+
+  1. {Screen 1} : ____
+  2. {Screen 2} : ____
+  ...
+
+If a screen has no design yet, type  none  for that screen.
+```
+
+**For each answer:**
+
+1. **Validate format** — the URL must match `figma.com/design/{fileKey}/...?node-id={nodeId}`.
+   - Valid → store as `figma_frames[{screen}] = {url}`, parse out `fileKey` + `nodeId`.
+   - A file link with **no `node-id`** → reject it: "This link points to the whole file, not a frame. Re-copy via right-click → Copy link to selection." Re-ask for that screen.
+   - `none` → `figma_frames[{screen}] = "TBD"`, mark that screen ❌ Missing.
+
+2. **Fetch the frame via Figma MCP** (only for valid links) — call `get_design_context`
+   (and `get_screenshot` when useful) with the parsed `fileKey` + `nodeId` to read the
+   real layout, component names, and design tokens. Ground every Screen Spec in this
+   fetched data; do **not** invent layout the frame does not show. If a fetch fails
+   (permission / not found) → treat that screen as ❌ Missing and note the fetch error.
+
+3. Derive the feature-level `figma_url` = the file link (without `node-id`) shared by the
+   frames, for the Metadata row. If frames span multiple files, list each.
+
+**Mandatory gate (does not abort — produces a draft):**
+- If **any** screen is ❌ Missing → the spec is generated as a **draft** with those screens
+  flagged, but `Status` stays `draft` and **sign-off / `/generate-bdd` is blocked** until
+  every screen has a readable, fetched frame link. Record `missing_frames = [screens]`.
+- Add one AI Assumption per missing screen: "No readable Figma frame for {screen} — spec
+  for this screen is text-only and must not be signed off until a `node-id` link is added."
+
+---
+
 ## CHECKPOINT
 
 ```
@@ -442,9 +478,13 @@ Module      : {active_module}
 Service     : {active_service}
 Domain      : {domain}
 Screens     : {N} — {comma-separated screen_list}
-Figma       : {figma_url}
+Figma       : {linked}/{N} screens have readable frame links{; missing: comma-separated missing_frames}
 Output path : {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md
 
+{If missing_frames non-empty}:
+⚠️  {count} screen(s) without a readable Figma frame link — these will be generated as
+   text-only drafts and the spec cannot be signed off until their node-id links are added.
+
 Generate? (Y/N)
 ```
 
@@ -469,6 +509,15 @@ Apply these rules consistently when generating all sections:
   - `app` / `app-ios` / `app-android` → include gestures, safe area, minimum touch targets, navigation pattern, deep links, permissions, offline behavior.
   - Only generate the section relevant to `active_platform`. Omit the other platform's section entirely.
 
+**Figma grounding (mandatory):**
+- For every screen with a fetched frame (`figma_frames[screen]` is a valid link), base the
+  Layout, Component Inventory, and Screen States on the **fetched Figma data** — real
+  component names, real tokens, real frame structure. Do not contradict or invent layout.
+- Use the exact per-screen `figma_frames[screen]` URL in the Screen Inventory, each Screen
+  Spec header, and the Figma Summary — never a synthetic `{figma_url}#screen1` fragment.
+- For ❌ Missing screens: generate a text-only draft from the PRD, prefix the Screen Spec
+  with `> [DRAFT — no Figma frame; do not sign off]`, and leave the Figma cell as ❌ Missing.
+
 **Screen states (mandatory per screen):**
 - Every screen must document at minimum: `default`, `loading`, `error`.
 - Add `empty` when the screen can display zero-data state.
@@ -498,7 +547,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}]({relative-path-to-prd.md})                      |
-| **Figma**          | {figma_url}                                                   |
+| **Figma**          | {figma_url — feature file link} ({linked}/{N} frames linked)  |
 | **Author**         | {PO name or "AI-assisted"}                                    |
 | **Created**        | {YYYY-MM-DD}                                                  |
 | **Updated**        | {YYYY-MM-DD}                                                  |
@@ -509,8 +558,8 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 | # | Screen Name | Entry Point | Figma Frame | Notes |
 |---|-------------|-------------|-------------|-------|
-| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_url}#screen1) | |
-| 2 | {Screen 2}  | {entry point} | [Frame]({figma_url}#screen2) | |
+| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_frames[Screen 1]}) | |
+| 2 | {Screen 2}  | {entry point} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | |
 
 ---
 
@@ -523,7 +572,7 @@ Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform
 
 ## Screen 1: {Screen Name}
 
-**Figma**: [{Frame name}]({figma_frame_url})
+**Figma**: [{Frame name}]({figma_frames[Screen 1]})   <!-- ❌ Missing → prefix this screen with `> [DRAFT — no Figma frame; do not sign off]` -->
 
 ### Layout
 
@@ -679,10 +728,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 ## Figma Summary
 
-| Screen          | Figma Frame                   | Designer Status        |
-|-----------------|-------------------------------|------------------------|
-| {Screen 1}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
-| {Screen 2}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
+| Screen          | Figma Frame                          | Link / Fetch Status                  |
+|-----------------|--------------------------------------|--------------------------------------|
+| {Screen 1}      | [Link]({figma_frames[Screen 1]})     | ✅ Linked & fetched                  |
+| {Screen 2}      | —                                    | ❌ Missing — no node-id link provided |
 
 ## Design Tokens Referenced
 
@@ -704,6 +753,7 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 > PO must review and confirm before sign-off.
 
 - {Assumption 1 — [AI DRAFT]}
+- {One per ❌ Missing screen: "No readable Figma frame for {screen} — text-only draft; blocks sign-off until a node-id link is added."}
 
 ---
 
@@ -715,9 +765,10 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 <!--
   NEXT STEPS:
-  1. Share with Designer — verify Figma links, update component inventory.
-  2. PO + Designer sign off: change Status → "approved".
-  3. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
+  1. Fill any ❌ Missing Figma frame links (node-id links) — re-run to fetch & ground them.
+  2. Share with Designer — verify Figma links, update component inventory.
+  3. PO + Designer sign off: change Status → "approved" (only allowed when 0 screens are ❌ Missing).
+  4. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
 -->
 ````
 
@@ -732,7 +783,9 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 - [ ] Only the platform-relevant section generated in Section 4
 - [ ] AC-UI items are testable (clear pass/fail, not "looks good")
 - [ ] Business PRD cross-reference link is valid relative path
-- [ ] If `figma_url = "TBD"` → AI Assumption added in Appendix
+- [ ] Every screen has a node-level Figma frame link (`?node-id=`) — and screens with a link were fetched via Figma MCP and used to ground the spec
+- [ ] Each ❌ Missing screen is flagged in-spec (`> [DRAFT — no Figma frame...]`), listed in Figma Summary, and has an AI Assumption
+- [ ] If any screen is ❌ Missing → Status stays `draft` and the Output below blocks `/generate-bdd`
 
 ---
 
@@ -776,13 +829,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}` |
@@ -800,12 +853,25 @@ Next   : {suggested command with example arguments}
 ```
 
 
+{If missing_frames is empty}:
 ```
 /generate-design-spec Complete — {TICKET-ID} [{active_platform}]
 ---
-Status : ✅ Complete
+Status : ✅ Complete — all {N} screens linked & fetched from Figma
 Output Artifacts:
   created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
-Next   : Share with Designer → add Figma links → PO + Designer sign-off (Status: approved)
+Next   : Share with Designer → PO + Designer sign-off (Status: approved)
          → /generate-bdd {prd-file}  (generates BDD per service; reads AC-UI from Design Spec)
 ```
+
+{If missing_frames is non-empty}:
+```
+/generate-design-spec Complete (DRAFT) — {TICKET-ID} [{active_platform}]
+---
+Status : ⚠️ Warnings — {count} screen(s) without a readable Figma frame: {comma-separated missing_frames}
+Output Artifacts:
+  created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
+Next   : 🔒 Sign-off & /generate-bdd are BLOCKED until every screen has a node-id Figma link.
+         1. In Figma: select each missing frame → right-click → Copy link to selection
+         2. Re-run /generate-design-spec {prd-file} → AI fetches & grounds the new frames
+```

package/core/commands/generate-prd.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).
 
 ---
 
@@ -631,13 +632,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-spec-manifest.md

@@ -168,7 +168,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`)
@@ -180,13 +180,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.
 
 ---
 
@@ -210,7 +211,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).
@@ -303,7 +304,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).
 
 ---
 
@@ -528,13 +529,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-tech-docs.md

@@ -184,7 +184,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`)
@@ -196,13 +196,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.
 
 ---
 
@@ -226,7 +227,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).
@@ -319,7 +320,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).
 
 ---
 
@@ -453,25 +454,49 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 ---
 
 ## §1. Overview
+
+{Tóm tắt ngắn: UC này implement gì, scope kỹ thuật chính.}
+
 ## §2. API Endpoints
-  *Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
-  *Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD.
-    Ghi chú gaps nếu contract thực tế khác với BDD expectations.
-  | Method | Path | Auth/Role | Request | Response |
+
+*Greenfield:* endpoints được infer từ BDD scenarios — thiết kế mới.
+*Reverse-document:* mô tả lại API đã tồn tại từ bảng "Existing API Contract" trong PRD. Ghi chú gaps nếu contract thực tế khác với BDD expectations.
+
+| Method | Path | Auth/Role | Request | Response |
+|--------|------|-----------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/...} | {Bearer / role} | `{ field: type }` | `{ field: type }` |
+
 ## §3. Data Model
-  Key entities and relationships.
+
+Key entities and relationships.
+
 ## §4. Service Flow
-  {Client} → Controller → {Facade/Service} → {Repository}
+
+{Client} → Controller → {Facade/Service} → {Repository}
+
 ## §5. Business Rules Implementation
-  | BR-ID | Rule | Implementation approach |
+
+| BR-ID | Rule | Implementation approach |
+|-------|------|-------------------------|
+| {UC-ID}-BR1 | {rule} | {approach} |
+
 ## §6. Error Handling
-  | Scenario | Exception | HTTP Status |
+
+| Scenario | Exception | HTTP Status |
+|----------|-----------|-------------|
+| {scenario} | {ExceptionClass} | {4xx/5xx} |
+
 ## §7. Database Changes
-  Migration scripts or schema changes.
+
+Migration scripts or schema changes.
+
 ## §8. Caching Strategy
-  What to cache, TTL, invalidation triggers.
+
+What to cache, TTL, invalidation triggers.
+
 ## §9. Cross-Service Dependencies
-  External calls, events produced/consumed.
+
+External calls, events produced/consumed.
 
 ## Changelog
 
@@ -480,6 +505,21 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
+## Publish — share the contract (umbrella + shared spec repo)
+
+If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the tech-doc was just written **inside the spec submodule**. It is the cross-team **API contract** — FE/App read it via their own `/sync`. Publish it so they can (2-layer commit):
+
+```bash
+cd {spec_source}
+git add specs/tech-docs/{domain}/{UC-ID}-tech-design.md
+git commit -m "docs({UC-ID}): tech design / API contract"
+git push origin {spec_branch}          # the branch FE/App track in .gitmodules
+cd -
+git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} tech design)"
+```
+
+If `tech_docs_dir` is **local** — i.e. no `setup.spec_source` (single-repo, or a pure multi-service BE repo with no shared spec module) — skip this; no cross-repo publish needed. Whenever `spec_source` is set, tech-docs route to the spec submodule and this publish step applies.
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -520,13 +560,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}` |
@@ -549,5 +589,6 @@ Next   : {suggested command with example arguments}
 File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
 Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
       ← SA/Lead review required before code generation
+      → if tech-docs live in the shared spec repo: commit + push to the spec submodule (see Publish above) so FE/App `/sync` can read the contract
       → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
 ```