@anhth2/spec-driven-dev-plugin 0.7.0 → 0.8.0

package/core/commands/setup-ai-first.md

@@ -98,6 +98,51 @@ Check if already set up:
   - Y → continue (existing files will be preserved — each step will offer merge/skip)
 - If only `specs/` exists or only partial setup detected → continue normally (safe to re-run)
 
+## Step 0.5 — Project Type
+
+Ask the user:
+
+```
+What type of project is this?
+  1. Single-service  — one codebase, one platform (standard setup)
+  2. Umbrella repo   — this repo contains multiple service submodules (microservices / multi-app)
+  3. PO Spec repo    — docs only, no runnable code (PRD + design-spec only)
+```
+
+Store the answer as `project_type`. Default to `1` if user does not answer.
+
+Based on answer:
+
+**project_type = 1 (Single-service):** Continue standard setup below.
+
+**project_type = 2 (Umbrella):** Ask two follow-up questions:
+- "Path to spec submodule (e.g. `free-trial-specs`)? Press Enter to skip."
+- "List services as `domain:module` pairs, comma-separated
+  (e.g. `user:java-spring,order:java-spring`). Press Enter to skip."
+
+Then:
+- Skip creating `specs/prd/`, `specs/design-spec/`, `specs/domain-knowledge/` (those live in spec submodule)
+- Create only: `specs/bdd/`, `specs/tech-docs/`, `.trace/`, `.agent/review/` at umbrella level
+  *(Unless user explicitly asks to create the full structure)*
+- Generate `.agent/project-context.yaml` in umbrella mode with the services and spec_source provided
+- Skip creating `CLAUDE.md` (umbrella has no single tech stack)
+- After setup, remind: "Open each service submodule separately in Claude Code to install the framework there if needed."
+
+**project_type = 3 (PO Spec repo):**
+- Create: `specs/prd/`, `specs/design-spec/`, `specs/product-definition/`, `specs/domain-knowledge/`, `.agent/review/`
+- Skip: `specs/bdd/`, `specs/tech-docs/`, `.trace/`
+- Generate minimal `CLAUDE.md` with only §1 (project overview) and §7 (git conventions)
+- Ask the user: **"List your business domains (e.g. auth, payment, loyalty):"** — store as domain list for `project-context.yaml` and remind PO these names must be used consistently as `@trace.domain` in every PRD
+- Inform:
+  - Commands for PO repo: `/define-product`, `/generate-prd`, `/review-context`, `/generate-design-spec`
+  - **Critical for dev team handoff:** Every PRD must have `@trace.domain: {domain}` in its frontmatter. Dev team uses this to route generated BDD/code to the correct service submodule. Inconsistent domain names will break routing.
+  - Recommended PRD frontmatter:
+    ```
+    @trace.domain: {domain}    ← must match a key in dev team's services config
+    @trace.id: {TICKET-ID}
+    @trace.status: draft | approved
+    ```
+
 ## Step 1 — Create Directory Structure
 
 Create these directories (skip if they exist):
@@ -108,6 +153,7 @@ Create these directories (skip if they exist):
 │   ├── product-definition/
 │   ├── prd/
 │   ├── bdd/
+│   ├── design-spec/          ← Design Spec documents (FE/App platforms only)
 │   ├── tech-docs/            ← technical design documents
 │   └── domain-knowledge/     ← business dictionary & domain context
 ├── .trace/
@@ -115,8 +161,19 @@ Create these directories (skip if they exist):
     └── review/
 ```
 
+*Directory structure varies by `project_type` set in Step 0.5:*
+
+| project_type | Create | Skip |
+|---|---|---|
+| **1 — Single-service** | Full structure above | — |
+| **2 — Umbrella** | `.agent/review/` only (at umbrella root) | Everything else — `specs/` dirs live inside service submodules |
+| **3 — PO Spec repo** | `specs/prd/`, `specs/design-spec/`, `specs/product-definition/`, `specs/domain-knowledge/`, `.agent/review/` | `specs/bdd/`, `specs/tech-docs/`, `.trace/` |
+
 ## Step 2 — Create CLAUDE.md
 
+*Skip this step entirely if `project_type = 2` (Umbrella) — umbrella has no single tech stack.*
+*For `project_type = 3` (PO Spec repo) — create a minimal CLAUDE.md with only §1 (project overview) and §7 (git conventions). Skip §2–§6.*
+
 Check if `CLAUDE.md` exists:
 - Yes → ask "Merge template or skip?"
 - No → create from the template below
@@ -173,12 +230,19 @@ commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
 
 ## Step 3 — Create project-context.yaml
 
+*For `project_type = 2` (Umbrella):*
+- *If `.agent/project-context.yaml` was already generated by `--init --umbrella` → open it and verify/edit the `services` section (domain keys, paths, modules). Skip template copy below.*
+- *If not yet generated → ask: "Spec submodule path?" and "Services (domain:module pairs)?" then generate umbrella config (see Step 0.5 for format).*
+
 Create `.agent/project-context.yaml` using `.agent/templates/project-context.yaml` as the source template.
 
 Copy the template and instruct: "Open `.agent/project-context.yaml` and fill in all `{{PLACEHOLDER}}` values. The `paths` section is pre-configured with sensible defaults — adjust if your project uses different directory names."
 
 ## Step 4 — Create business-dictionary.md
 
+*Skip Steps 4 and 5 if `project_type = 2` (Umbrella) — business dictionary and core entities live in the spec submodule and are managed by the PO team. Dev team reads them from `{spec_source}/specs/domain-knowledge/`.*
+
+
 Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
 
 ```markdown
@@ -272,8 +336,12 @@ Or: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"**
 
 ## Step 7 — Verify
 
+Checklist varies by `project_type`:
+
+**project_type = 1 (Single-service):**
 - [ ] `specs/` exists
 - [ ] `specs/bdd/` exists
+- [ ] `specs/design-spec/` exists *(skip if backend-only project)*
 - [ ] `specs/tech-docs/` exists
 - [ ] `specs/domain-knowledge/` exists
 - [ ] `.trace/` exists
@@ -282,6 +350,24 @@ Or: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"**
 - [ ] `specs/domain-knowledge/business-dictionary.md` exists
 - [ ] `specs/domain-knowledge/core-entities.md` exists
 
+**project_type = 2 (Umbrella):**
+- [ ] `.agent/project-context.yaml` exists with `setup.mode: umbrella`
+- [ ] `services` section has at least one entry with correct domain keys
+- [ ] `spec_source` path exists (e.g., `my-project-specs/` directory is present)
+- [ ] `.agent/review/` exists
+- [ ] Spec submodule initialized: `git submodule status` shows no `-` prefix
+
+**project_type = 3 (PO Spec repo):**
+- [ ] `specs/prd/` exists
+- [ ] `specs/design-spec/` exists
+- [ ] `specs/product-definition/` exists
+- [ ] `specs/domain-knowledge/` exists
+- [ ] `.agent/review/` exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists (minimal)
+- [ ] `specs/domain-knowledge/business-dictionary.md` exists
+- [ ] `specs/domain-knowledge/core-entities.md` exists
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -316,7 +402,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -342,13 +429,54 @@ Next   : {suggested command with example arguments}
 
 ```
 /setup-ai-first Complete ✅
+```
+
+Output varies by `project_type`:
+
+**Single-service:**
+```
 Next:
   1. Fill CLAUDE.md (replace {{PLACEHOLDER}} values)
   2. Fill .agent/project-context.yaml
-  3. Fill specs/domain-knowledge/business-dictionary.md  ← terminology rules
-  4. Fill specs/domain-knowledge/core-entities.md        ← entity glossary for code gen
+  3. Fill specs/domain-knowledge/business-dictionary.md
+  4. Fill specs/domain-knowledge/core-entities.md
   5. git add and commit those 4 files
-  6. Install VS Code extension (if not yet installed):
+  6. Install VS Code extension:
      code --install-extension edupia-team.spec-driven-dev-team
   7. /define-product to start your first feature
 ```
+
+**Umbrella:**
+```
+Next:
+  1. Review .agent/project-context.yaml:
+     - Update services[].path to match actual submodule directory names
+     - Update services domain keys to match @trace.domain in your PRD files
+     - Confirm spec_source path is correct
+  2. Ensure spec submodule is initialized:
+     git submodule update --init --recursive
+  3. Pull latest specs from PO before generating:
+     git submodule update --remote {spec_source}
+  4. Start generating:
+     /generate-bdd {spec_source}/specs/prd/{domain}/TICKET-ID-prd.md
+```
+
+**PO Spec repo:**
+```
+Next:
+  1. Fill .agent/project-context.yaml:
+     - domains: [list all business domains — these become @trace.domain values in PRDs]
+     - project.name, project.description
+  2. Fill specs/domain-knowledge/business-dictionary.md  ← canonical terms
+  3. Fill specs/domain-knowledge/core-entities.md        ← entity glossary
+  4. git add and commit those files
+  5. Install VS Code extension:
+     code --install-extension edupia-team.spec-driven-dev-team
+  6. /define-product to start your first feature
+
+⚠️  Dev team handoff reminder:
+  - Each PRD must have @trace.domain matching one of your domains list
+  - When dev team sets up their umbrella repo, they map these domain names
+    to service submodule paths in their project-context.yaml services section
+  - Share domain names with dev team before they configure their umbrellas
+```

package/core/commands/smoke-test.md

@@ -133,6 +133,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -144,11 +145,44 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -254,6 +288,7 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -498,7 +533,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |

package/core/commands/validate-traces.md

@@ -133,6 +133,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -144,11 +145,44 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -254,6 +288,7 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -498,7 +533,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |

package/core/skills/code/SKILL.md

@@ -158,6 +158,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -169,11 +170,44 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -279,6 +313,7 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -412,7 +447,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -524,7 +560,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |

package/core/skills/debug/SKILL.md

@@ -73,6 +73,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -84,11 +85,44 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**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`
+- 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`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**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.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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -194,6 +228,7 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -350,7 +385,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -488,7 +524,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -583,7 +620,8 @@ Suggest the logical next command based on workflow phase:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
 | /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |