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

package/commands/smoke-test.md

@@ -1,6 +1,6 @@
-# /smoke-test — Test Live API Endpoints
+# /smoke-test — Smoke Test Live Service or App
 
-Use when service is **already running**. Different from `/run-tests` (no live server needed).
+Use when service/app is **already running**. Different from `/run-tests` (no live server needed).
 
 ## Gate
 # Gate — Universal Entry Procedure
@@ -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.
 
@@ -86,7 +86,7 @@ Wait for explicit "Y" or "N" from the user before continuing.
 - "N" → stop and ask what the user wants to change.
 
 
-*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Context loading provides `conventions.service_run` and port information.*
+*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Context loading provides `conventions.service_run`, port information, and `tech_stack.module`.*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -142,7 +142,7 @@ If `paths` section is absent, use these defaults:
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
@@ -219,6 +219,26 @@ If the file does not exist → skip silently.
 
 ---
 
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+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).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -229,6 +249,7 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
@@ -256,19 +277,40 @@ Proceed to the next step of the calling command.
 
 ---
 
-## Phase 1 — Find Service URL
+## Service Detection
+
+Read `active_module` from context. Use to select the correct smoke-test approach.
+
+| Platform | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+---
+
+## If `platform_type = backend`
+
+### Phase 1 — Verify service is running
+
 Read `conventions.service_run` from project-context.yaml to determine port.
+
 ```bash
-curl -s http://localhost:{port}/health
+# Try common health endpoints (use whichever applies):
+curl -s http://localhost:{port}/health            # generic / Go / Node
+curl -s http://localhost:{port}/actuator/health   # Spring Boot
+curl -s http://localhost:{port}/ping              # some frameworks
 ```
-If not running: "Start with `{conventions.service_run}` from project root."
 
-## Phase 2 — Identify Endpoints
-From UC-ID (or `$ARGUMENTS`) → find controller with `@trace.implements={UC-ID}`.
+If not running → "Start with `{conventions.service_run}` from project root."
+
+### Phase 2 — Identify endpoints
+
+From UC-ID → find controller/handler with `@trace.implements={UC-ID}`.
 List: method, path, required auth/role.
 
-## Phase 3 — Get Auth Token (if needed)
-Ask:
+### Phase 3 — Get auth token (if needed)
+
 ```
 Endpoint requires auth. Options:
 1. Paste Bearer token (from Postman/DevTools)
@@ -276,10 +318,11 @@ Endpoint requires auth. Options:
 3. Skip — test public endpoints only
 ```
 
-## Phase 4 — Run Smoke Test
+### Phase 4 — Run
+
 ```bash
 # GET
-curl -s -X GET "http://localhost:{port}/v1/{resource}?page=0&size=5" \
+curl -s -X GET "http://localhost:{port}/v1/{resource}" \
   -H "Authorization: Bearer {token}" | {JSON_FORMATTER}
 
 # POST
@@ -289,7 +332,6 @@ curl -s -X POST "http://localhost:{port}/v1/{resource}" \
   -d '{"field1": "test_value"}'
 ```
 
-## Interpret Results
 | Result | Meaning |
 |--------|---------|
 | 200/201 + correct data | ✅ OK |
@@ -297,9 +339,131 @@ curl -s -X POST "http://localhost:{port}/v1/{resource}" \
 | 400 | Wrong request body → check required fields |
 | 401 | Token expired or wrong config |
 | 403 | Wrong role → check auth rules |
-| 500 | Server error → paste into /debug |
+| 500 | Server error → /debug |
 | Connection refused | Service not running |
 
+### If `active_module = context-engineering`
+
+#### Phase 1 — Verify pipeline entry point is reachable
+
+Run the prompt function directly with a minimal valid input:
+
+```bash
+# Python (pytest / script):
+python -c "from {module}.{function} import {function}; print({function}(input='{test_input}'))"
+
+# Or using the project test command with a smoke marker:
+{conventions.test_command} -m smoke -v
+```
+
+#### Phase 2 — Verify output structure
+
+Check the output conforms to the expected schema:
+
+```
+Expected output schema: {output fields from @trace or tech-doc}
+Actual output: {paste output here}
+```
+
+#### Phase 3 — Interpret results
+
+| Result | Meaning |
+|--------|---------|
+| Output matches schema | ✅ OK |
+| Output present but wrong format | ⚠️ Logic bug → /debug |
+| `APIError` / `AuthenticationError` | API key invalid or service unavailable |
+| `TokenLimitError` | Input too long — check prompt template size |
+| Exception / traceback | Code error → /debug |
+
+---
+
+## If `platform_type = web-frontend`
+
+### Phase 1 — Verify dev server is running
+
+```bash
+# Linux / macOS:
+curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}
+
+# Windows (cmd / PowerShell):
+curl -s -o NUL -w "%{http_code}" http://localhost:{port}
+
+# Should return 200. If not: start with {conventions.service_run} (e.g., npm run dev)
+```
+
+### Phase 2 — Run E2E smoke test
+
+Identify E2E tool in the project (Playwright or Cypress):
+
+```bash
+# Playwright — run scenarios tagged with this UC:
+npx playwright test --grep "{UC-ID}"
+
+# Cypress:
+npx cypress run --spec "cypress/e2e/{UC-ID}*"
+```
+
+If no E2E tests exist yet → open browser and manually verify:
+1. Navigate to the route for this UC
+2. Perform the main user action
+3. Confirm the expected outcome is visible
+
+### Phase 3 — Interpret results
+
+| Result | Meaning |
+|--------|---------|
+| All E2E tests pass | ✅ OK |
+| Assertion failed | ⚠️ Logic bug → /debug |
+| `ERR_CONNECTION_REFUSED` | Dev server not running |
+| API returns 4xx/5xx | Backend issue → check backend service |
+
+---
+
+## If `platform_type = mobile`
+
+### Phase 1 — Verify device/emulator is ready
+
+```bash
+# Flutter:
+flutter devices              # list connected devices/emulators
+flutter install              # install current build on device
+
+# React Native:
+npx react-native run-android   # build + install on connected Android
+npx react-native run-ios       # build + install on iOS simulator
+
+# Android (Compose):
+./gradlew installDebug         # install APK on connected device/emulator
+
+# iOS (SwiftUI):
+# Open Xcode → select simulator → Product → Run
+```
+
+### Phase 2 — Manual smoke-test checklist
+
+For the UC under test, verify on device:
+1. Navigate to the screen for this UC
+2. Perform the main action from the `.feature` Scenario (`When` step)
+3. Confirm the expected outcome is visible (`Then` step)
+4. Check for any crash or unexpected error dialog
+
+### Phase 3 — Capture issues if found
+
+```bash
+# Flutter:
+flutter logs
+
+# Android:
+adb logcat -d | grep -i "error\|exception\|crash"
+
+# iOS:
+# Copy crash log from Xcode → Devices and Simulators → View Device Logs
+```
+
+Paste output into `/debug`.
+
+---
+
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -330,6 +494,7 @@ 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}` |
@@ -338,13 +503,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          | `/generate-tests {UC-ID}`                     |
+| /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        | `/generate-code {UC-ID}` for gaps             |
+| /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          |
 
@@ -359,8 +524,13 @@ Next   : {suggested command with example arguments}
 
 ```
 /smoke-test Report — {UC-ID}
-| Method | Path | Status | Result |
-|--------|------|--------|--------|
+Platform: {backend | web-frontend | mobile}
+| Endpoint / Flow       | Status      | Result  |
+|-----------------------|-------------|---------|
+| {method} {path/screen}| ✅/⚠️/❌   | {notes} |
+
+Status legend: ✅ = OK  |  ⚠️ = Responded but wrong data / logic bug  |  ❌ = Error / not running
+
 Issues: {describe any failures}
-Next: /debug {stacktrace} OR /fix-bug {TICKET_ID} OR ready to PR
+Next: /debug (paste error interactively) OR /fix-bug {TICKET_ID} OR ready to PR
 ```

package/commands/smoke-test.tmpl

@@ -1,30 +1,51 @@
-# /smoke-test — Test Live API Endpoints
+# /smoke-test — Smoke Test Live Service or App
 
-Use when service is **already running**. Different from `/run-tests` (no live server needed).
+Use when service/app is **already running**. Different from `/run-tests` (no live server needed).
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Context loading provides `conventions.service_run` and port information.*
+*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Context loading provides `conventions.service_run`, port information, and `tech_stack.module`.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
-## Phase 1 — Find Service URL
+## Service Detection
+
+Read `active_module` from context. Use to select the correct smoke-test approach.
+
+| Platform | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+---
+
+## If `platform_type = backend`
+
+### Phase 1 — Verify service is running
+
 Read `conventions.service_run` from project-context.yaml to determine port.
+
 ```bash
-curl -s http://localhost:{port}/health
+# Try common health endpoints (use whichever applies):
+curl -s http://localhost:{port}/health            # generic / Go / Node
+curl -s http://localhost:{port}/actuator/health   # Spring Boot
+curl -s http://localhost:{port}/ping              # some frameworks
 ```
-If not running: "Start with `{conventions.service_run}` from project root."
 
-## Phase 2 — Identify Endpoints
-From UC-ID (or `$ARGUMENTS`) → find controller with `@trace.implements={UC-ID}`.
+If not running → "Start with `{conventions.service_run}` from project root."
+
+### Phase 2 — Identify endpoints
+
+From UC-ID → find controller/handler with `@trace.implements={UC-ID}`.
 List: method, path, required auth/role.
 
-## Phase 3 — Get Auth Token (if needed)
-Ask:
+### Phase 3 — Get auth token (if needed)
+
 ```
 Endpoint requires auth. Options:
 1. Paste Bearer token (from Postman/DevTools)
@@ -32,10 +53,11 @@ Endpoint requires auth. Options:
 3. Skip — test public endpoints only
 ```
 
-## Phase 4 — Run Smoke Test
+### Phase 4 — Run
+
 ```bash
 # GET
-curl -s -X GET "http://localhost:{port}/v1/{resource}?page=0&size=5" \
+curl -s -X GET "http://localhost:{port}/v1/{resource}" \
   -H "Authorization: Bearer {token}" | {JSON_FORMATTER}
 
 # POST
@@ -45,7 +67,6 @@ curl -s -X POST "http://localhost:{port}/v1/{resource}" \
   -d '{"field1": "test_value"}'
 ```
 
-## Interpret Results
 | Result | Meaning |
 |--------|---------|
 | 200/201 + correct data | ✅ OK |
@@ -53,17 +74,144 @@ curl -s -X POST "http://localhost:{port}/v1/{resource}" \
 | 400 | Wrong request body → check required fields |
 | 401 | Token expired or wrong config |
 | 403 | Wrong role → check auth rules |
-| 500 | Server error → paste into /debug |
+| 500 | Server error → /debug |
 | Connection refused | Service not running |
 
+### If `active_module = context-engineering`
+
+#### Phase 1 — Verify pipeline entry point is reachable
+
+Run the prompt function directly with a minimal valid input:
+
+```bash
+# Python (pytest / script):
+python -c "from {module}.{function} import {function}; print({function}(input='{test_input}'))"
+
+# Or using the project test command with a smoke marker:
+{conventions.test_command} -m smoke -v
+```
+
+#### Phase 2 — Verify output structure
+
+Check the output conforms to the expected schema:
+
+```
+Expected output schema: {output fields from @trace or tech-doc}
+Actual output: {paste output here}
+```
+
+#### Phase 3 — Interpret results
+
+| Result | Meaning |
+|--------|---------|
+| Output matches schema | ✅ OK |
+| Output present but wrong format | ⚠️ Logic bug → /debug |
+| `APIError` / `AuthenticationError` | API key invalid or service unavailable |
+| `TokenLimitError` | Input too long — check prompt template size |
+| Exception / traceback | Code error → /debug |
+
+---
+
+## If `platform_type = web-frontend`
+
+### Phase 1 — Verify dev server is running
+
+```bash
+# Linux / macOS:
+curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}
+
+# Windows (cmd / PowerShell):
+curl -s -o NUL -w "%{http_code}" http://localhost:{port}
+
+# Should return 200. If not: start with {conventions.service_run} (e.g., npm run dev)
+```
+
+### Phase 2 — Run E2E smoke test
+
+Identify E2E tool in the project (Playwright or Cypress):
+
+```bash
+# Playwright — run scenarios tagged with this UC:
+npx playwright test --grep "{UC-ID}"
+
+# Cypress:
+npx cypress run --spec "cypress/e2e/{UC-ID}*"
+```
+
+If no E2E tests exist yet → open browser and manually verify:
+1. Navigate to the route for this UC
+2. Perform the main user action
+3. Confirm the expected outcome is visible
+
+### Phase 3 — Interpret results
+
+| Result | Meaning |
+|--------|---------|
+| All E2E tests pass | ✅ OK |
+| Assertion failed | ⚠️ Logic bug → /debug |
+| `ERR_CONNECTION_REFUSED` | Dev server not running |
+| API returns 4xx/5xx | Backend issue → check backend service |
+
+---
+
+## If `platform_type = mobile`
+
+### Phase 1 — Verify device/emulator is ready
+
+```bash
+# Flutter:
+flutter devices              # list connected devices/emulators
+flutter install              # install current build on device
+
+# React Native:
+npx react-native run-android   # build + install on connected Android
+npx react-native run-ios       # build + install on iOS simulator
+
+# Android (Compose):
+./gradlew installDebug         # install APK on connected device/emulator
+
+# iOS (SwiftUI):
+# Open Xcode → select simulator → Product → Run
+```
+
+### Phase 2 — Manual smoke-test checklist
+
+For the UC under test, verify on device:
+1. Navigate to the screen for this UC
+2. Perform the main action from the `.feature` Scenario (`When` step)
+3. Confirm the expected outcome is visible (`Then` step)
+4. Check for any crash or unexpected error dialog
+
+### Phase 3 — Capture issues if found
+
+```bash
+# Flutter:
+flutter logs
+
+# Android:
+adb logcat -d | grep -i "error\|exception\|crash"
+
+# iOS:
+# Copy crash log from Xcode → Devices and Simulators → View Device Logs
+```
+
+Paste output into `/debug`.
+
+---
+
 ## Output
 
 {{include:steps/report-footer.md}}
 
 ```
 /smoke-test Report — {UC-ID}
-| Method | Path | Status | Result |
-|--------|------|--------|--------|
+Platform: {backend | web-frontend | mobile}
+| Endpoint / Flow       | Status      | Result  |
+|-----------------------|-------------|---------|
+| {method} {path/screen}| ✅/⚠️/❌   | {notes} |
+
+Status legend: ✅ = OK  |  ⚠️ = Responded but wrong data / logic bug  |  ❌ = Error / not running
+
 Issues: {describe any failures}
-Next: /debug {stacktrace} OR /fix-bug {TICKET_ID} OR ready to PR
+Next: /debug (paste error interactively) OR /fix-bug {TICKET_ID} OR ready to PR
 ```

package/commands/validate-traces.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.
 
@@ -142,7 +142,7 @@ If `paths` section is absent, use these defaults:
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
@@ -219,6 +219,26 @@ If the file does not exist → skip silently.
 
 ---
 
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+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).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -229,6 +249,7 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
@@ -263,6 +284,13 @@ Proceed to the next step of the calling command.
 Read all `{paths.trace_dir}/{UC-ID}.tsv` files matching the target domain (or all domains if no domain filter).
 Each file gives the persisted trace state for that UC.
 
+**If no `.tsv` files found** in `{paths.trace_dir}`:
+- Scan all `{paths.specs_dir}/**/*.feature` files in the target domain to build an in-memory list of all scenarios.
+- Treat all scenarios as `UNTRACKED` (no code generated yet).
+- Print: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
+- Suggest: "Run `/generate-bdd {prd-file}` to initialize trace state, or `/generate-code {feature-file}` to generate code."
+- **Skip Steps 2–6 entirely.** Proceed directly to Step 7 using this in-memory state — do NOT abort.
+
 ### Step 2 — Reconcile with current `.feature` files
 
 For each `.tsv` row, read the corresponding `.feature` file and get the **current** `@trace.sc_version` for that SC.
@@ -300,6 +328,8 @@ If code was generated from an older revision → flag `TECHDOC_DRIFT`.
 
 ### Step 6 — Write status back to TSV
 
+*Skip this step if no TSV files existed (handled by Step 1 no-TSV path).*
+
 For each `.tsv` file processed: write updated `spec_ver`, `status`, `last_updated` back to disk.
 
 ### Step 7 — Compute dashboard aggregates
@@ -309,6 +339,7 @@ total_prds       = count distinct PRD files in {paths.prd_dir}/{domain}/
 approved_prds    = PRDs with | Status | approved
 total_ucs        = count distinct UC-IDs across all .tsv files
 approved_ucs     = UCs with uc_status == approved
+draft_ucs        = UCs with uc_status == draft
 total_scs        = total rows across all .tsv files
 code_coverage    = rows where implemented_by != — / total_scs
 test_coverage    = rows where test_count > 0 / total_scs
@@ -320,7 +351,7 @@ tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/
 
 ### Step 8 — Write JSON report
 
-Write `.trace/trace-report.json` (overwrite if exists). This file is the single source of truth for web dashboards — it contains the full snapshot at the time `/validate-traces` was last run.
+Write `{paths.trace_dir}/trace-report.json` (overwrite if exists). This file is the single source of truth for web dashboards — it contains the full snapshot at the time `/validate-traces` was last run.
 
 Schema:
 
@@ -430,7 +461,8 @@ Schema:
 - `test_classes`: use `[]` (not `"—"`) when no test classes
 - `tech_doc_revision`: use integer; `0` if not yet generated
 - `code_coverage_pct` / `test_coverage_pct`: round to nearest integer (0–100)
-- Always write to `.trace/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
+- Always write to `{paths.trace_dir}/trace-report.json` regardless of domain filter — if a domain filter was applied, include only those PRDs in `prds[]` but note the domain in the `domain` field
+- **TSV `"—"` mapping**: when reading TSV files, map dash values to JSON types: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`
 
 ## Output
 
@@ -462,6 +494,7 @@ 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}` |
@@ -470,13 +503,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          | `/generate-tests {UC-ID}`                     |
+| /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        | `/generate-code {UC-ID}` for gaps             |
+| /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          |
 
@@ -492,7 +525,7 @@ Next   : {suggested command with example arguments}
 ```
 /validate-traces — {domain}
 
-📄 .trace/trace-report.json  ← updated
+📄 {paths.trace_dir}/trace-report.json  ← updated
 
 ┌─────────────────────────────────────────────────────────────────────────────────────┐
 │  PRDs      Use Cases     Scenarios   Code Cov.  Test Cov.  Drift  Untracked  Gap   │