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

package/commands/run-tests.tmpl

@@ -3,44 +3,164 @@
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID or service name from `$ARGUMENTS`. Context loading provides `conventions.test_command`.*
+*Note: For this command, the target in Step 1 is a UC-ID or service name. Context loading provides `conventions.test_command` and `tech_stack.module`.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
+## Service Detection
+
+Read `active_module` from context (resolved in context-loader Step 1).
+Use it to select the correct run command and error analysis table below.
+
+---
+
 ## Run
+
+### If `platform_type = backend`
+
 ```bash
-{conventions.test_command}                          # all tests in module
-{conventions.test_command} --class {ClassName}      # specific class (faster)
-{conventions.test_command} --pattern "*{Resource}*" # by pattern
+# Run all tests for this UC
+{conventions.test_command}
+
+# Scoped to specific class (faster feedback)
+# java-spring:
+mvn test -Dtest={ClassName}
+# golang:
+go test ./... -run Test{FunctionName}
+# dotnet:
+dotnet test --filter "FullyQualifiedName~{ClassName}"
+# php-laravel:
+php artisan test --filter {ClassName}
+# context-engineering (pytest):
+pytest tests/{domain}/{test_file}.py -v
+pytest tests/{domain}/{test_file}.py::{TestClass}::{test_method} -v
+pytest tests/ --cov={source_dir} --cov-report=term-missing
 ```
 
+### If `platform_type = web-frontend`
+
+```bash
+# Run all tests
+{conventions.test_command}
+
+# Scoped (Vitest / Jest):
+npx vitest run src/features/{domain}/{Component}.test.tsx
+npx jest src/features/{domain}/{Component}.test.tsx
+
+# E2E (Playwright):
+npx playwright test {UC-ID}
+# E2E (Cypress):
+npx cypress run --spec "cypress/e2e/{UC-ID}*"
+```
+
+### If `platform_type = mobile`
+
+```bash
+# Flutter:
+flutter test test/{domain}/{UC-ID}_test.dart
+flutter test integration_test/{UC-ID}_test.dart   # integration
+
+# React Native:
+npx jest {UC-ID}
+
+# iOS (Xcode command line):
+xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhone 15'
+
+# Android:
+./gradlew test                              # unit tests
+./gradlew connectedAndroidTest              # instrumented (device/emulator required)
+```
+
+> **Note for Android instrumented tests:** a running emulator or connected device is required before running `connectedAndroidTest`. Start one via Android Studio or: `emulator -avd {AVD_NAME} &`
+
+---
+
 ## Analyze Failures
 
+### Backend failure patterns
+
+#### java-spring / golang / dotnet / php-laravel
+
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `NullPointerException` | Missing mock setup | Check `given(...)`/`coEvery`/`mockk` for null dependency |
+| `Bean not found` | Missing mock declaration | Add `@MockBean` / inject mock |
+| `Expected 200, got 401` | Missing auth setup | Add auth token/user to test context |
+| `Expected 200, got 400` | Request body fails validation | Check required fields in DTO |
+| `Expected 200, got 403` | Wrong role | Add correct role to test user |
+| `LazyInitializationException` | Lazy collection outside transaction | Add `@Transactional` or eager fetch |
+| `Mapper not found` | Code not compiled | Run build step before tests |
+| `DataIntegrityViolationException` | Duplicate key in DB setup | Use `@Transactional` + rollback, or clean DB between tests |
+| Assertion mismatch | Wrong mock return value | Re-read `given(...).willReturn(...)` setup |
+
+#### context-engineering (AI/LLM pipelines)
+
 | Error Pattern | Common Cause | Suggested Fix |
 |---|---|---|
-| NullPointerException | Missing mock setup | Check `given(...)` for null dependency |
-| Bean not found | Missing mock declaration | Add mock for missing dependency |
-| Expected 200, got 403 | Missing auth setup | Add auth user/role to test context |
-| Expected 200, got 400 | Request body fails validation | Check required fields in DTO |
-| LazyInitializationException | Lazy collection outside transaction | Add `@Transactional` or eager fetch |
-| Mapper not found | Code generator not run | Run compile step before tests |
+| `AssertionError` on LLM mock output | Mock return value not matching schema | Re-check `mock_llm.return_value` / `mock_llm.complete.return_value` setup |
+| `ValidationError` on response | LLM output structure doesn't match expected schema | Tighten schema check or add retry logic in test |
+| `ConnectionError` / `APIError` | Real LLM API being called in test | Ensure `patch('...')` mock is applied — never call real LLM in unit tests |
+| `TimeoutError` | Test calling live LLM endpoint | Add mock; check test fixtures |
+| Flaky / non-deterministic results | Real LLM response used in assertion | Replace with deterministic mock return value |
+
+### Web frontend failure patterns
+
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `Unable to find role "..."` | Element not rendered yet | Wrap in `await waitFor(() => ...)` |
+| `TestingLibraryElementError: Found multiple elements` | Selector too broad | Use `getByRole(..., { name: '...' })` to narrow |
+| `Network request not intercepted` | Missing MSW handler / `cy.intercept` | Add handler for the endpoint |
+| `act(...)` warning | State update after test ended | Await async events / `await userEvent.click(...)` |
+| `Cannot read properties of undefined` | Component rendered before data loaded | Add loading state or mock resolved data |
+| Playwright timeout | Page not navigated / element hidden | Check route, add `waitForSelector` |
+| `expect(page.locator(...)).toBeVisible` fails | Wrong selector | Use Playwright Inspector to find correct locator |
+
+### Mobile failure patterns
+
+#### Flutter
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `pumpAndSettle timed out` | Async operation not completing | Use `pump(Duration(...))` for specific delay |
+| `No widget found` | Widget not rendered / wrong finder | Check `find.byType`, `find.text`, `find.byKey` |
+| `setState called after dispose` | Widget disposed before async completes | Cancel async in `dispose()` |
+| BLoC state mismatch | Wrong event emitted | Verify `mockBloc` received correct event |
+
+#### React Native
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `Unable to find element` | Missing `testID` or wrong query | Add `accessibilityLabel` or `testID` to component |
+| `act(...)` warning | Async state updates | Wrap in `act(async () => { ... })` |
+| Navigation mock missing | `useNavigation` not mocked | Add jest mock for `@react-navigation/native` |
+
+#### iOS / Android
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `XCTAssertEqual failed` | Wrong expected value | Check ViewModel output for given mock |
+| `Compose node not found` | Wrong `contentDescription` / `testTag` | Add `Modifier.testTag(...)` to composable |
+| `Hilt injection failed` | Missing test module | Add `@UninstallModules` + `@BindValue` in test class |
+| Emulator not available | `connectedAndroidTest` without device | Start emulator first, wait for it to boot |
+
+---
 
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
-/run-tests Report — {service}
+/run-tests Report — {UC-ID} ({active_module})
 ✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
 
 ## Failed Tests
 | Test | Error | Root Cause |
-|------|-------|-----------|
+|------|-------|------------|
 
 ## Recommendations
 {specific fix per failure}
-Next: /fix-bug if real bug, or correct test if wrong expectation.
+
+Next:
+  All tests pass → /review-code {UC-ID}
+  Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
 ```

package/commands/setup-ai-first.md

@@ -33,7 +33,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -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,15 +153,27 @@ 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
-├── tech-docs/
 ├── .trace/
 └── .agent/
     └── 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
@@ -153,7 +210,7 @@ forbidden:
 # §4. Traceability
 # Every controller method must be tagged:
 # @trace.implements={UC-ID}-{SC-ID}
-# @trace.source=specs/bdd/{domain}/{UC-ID}.feature
+# @trace.source=specs/bdd/{domain}/{UC-ID}.feature  ← adjust if specs_dir differs in .agent/project-context.yaml
 # Tests must be tagged:
 # @trace.verifies={UC-ID}
 
@@ -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,7 +336,13 @@ 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
 - [ ] `.agent/project-context.yaml` exists
@@ -280,17 +350,133 @@ 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
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /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)   | 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}`        |
+| /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 |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+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/commands/setup-ai-first.tmpl

@@ -17,6 +17,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):
@@ -27,15 +72,27 @@ 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
-├── tech-docs/
 ├── .trace/
 └── .agent/
     └── 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
@@ -72,7 +129,7 @@ forbidden:
 # §4. Traceability
 # Every controller method must be tagged:
 # @trace.implements={UC-ID}-{SC-ID}
-# @trace.source=specs/bdd/{domain}/{UC-ID}.feature
+# @trace.source=specs/bdd/{domain}/{UC-ID}.feature  ← adjust if specs_dir differs in .agent/project-context.yaml
 # Tests must be tagged:
 # @trace.verifies={UC-ID}
 
@@ -92,12 +149,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
@@ -191,7 +255,13 @@ 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
 - [ ] `.agent/project-context.yaml` exists
@@ -199,17 +269,78 @@ 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
 
+{{include:steps/report-footer.md}}
+
 ```
 /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
+```