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

package/commands/generate-code.tmpl

@@ -27,6 +27,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.
 
 ---
 
@@ -50,6 +51,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:
@@ -72,7 +118,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`.
@@ -226,9 +272,12 @@ 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
+{{include:steps/trace-mirror.md}}
+
 ## Commit
 ```bash
 git add {files}
@@ -245,6 +294,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:
@@ -254,9 +304,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.
 ```

package/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,7 +175,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -206,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).
@@ -299,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).
 
 ---
 
@@ -399,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.
@@ -432,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
 
 ```
@@ -443,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)
 ```
 
@@ -470,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.
@@ -499,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}                                                  |
@@ -510,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 | |
 
 ---
 
@@ -524,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
 
@@ -680,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
 
@@ -705,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."}
 
 ---
 
@@ -716,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.
 -->
 ````
 
@@ -733,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`
 
 ---
 
@@ -777,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}` |
@@ -801,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/commands/generate-design-spec.tmpl

@@ -46,19 +46,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.
@@ -79,6 +66,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
 
 ```
@@ -90,9 +125,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)
 ```
 
@@ -117,6 +156,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.
@@ -146,7 +194,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}                                                  |
@@ -157,8 +205,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 | |
 
 ---
 
@@ -171,7 +219,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
 
@@ -327,10 +375,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
 
@@ -352,6 +400,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."}
 
 ---
 
@@ -363,9 +412,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.
 -->
 ````
 
@@ -380,7 +430,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`
 
 ---
 
@@ -388,12 +440,25 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 {{include:steps/report-footer.md}}
 
+{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/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,7 +175,7 @@ If `services` section is present:
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
-- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
+- Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
@@ -206,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).
@@ -299,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).
 
 ---
 
@@ -632,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}` |