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

package/commands/review-code.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}
@@ -254,6 +275,26 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## Pre-Review Scan
+
+*(Separate from the Gate CHECKPOINT — this lists the actual files and scenarios in scope.)*
+
+Scan for implementation files and scenarios, then display:
+
+```
+Review Scope — {UC-ID}
+──────────────────────────────────────
+UC        : {UC-ID}
+Files     : {list of files tagged @trace.implements={UC-ID}}
+Scenarios : {N} scenarios in .feature file
+
+Proceed with review? (Y/N)
+```
+
+Wait for explicit "Y" before proceeding.
+
 ---
 
 ## Review Dimensions
@@ -262,7 +303,7 @@ Proceed to the next step of the calling command.
 - [ ] Every controller endpoint has `@trace.implements` tag?
 - [ ] Every test file has `@trace.verifies` tag?
 - [ ] No `@trace` tags on wrong layers?
-- [ ] `{paths.trace_dir}/{UC-ID}.tsv` up to date?
+- [ ] `{paths.trace_dir}/{UC-ID}.tsv` up to date? (if stale → run `/validate-traces {UC-ID}` first, then re-run this review)
 
 ### 2. Layer Architecture (from CLAUDE.md §2)
 - [ ] Each class in the correct layer?
@@ -310,6 +351,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}` |
@@ -318,13 +360,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          |
 
@@ -350,5 +392,15 @@ Critical: {X} | Major: {Y} | Minor: {Z}
 ### Minor
 | # | File | Line | Issue | Suggested Fix |
 
+Output Artifacts: none (read-only)
+
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
+
+If APPROVED ✅:
+  Next: /generate-tests {UC-ID}
+
+If NEEDS_FIX ❌:
+  - Small fix (1–3 lines, no logic change) → fix inline → re-run /review-code {UC-ID}
+  - Logic / architecture issue             → /fix-bug {TICKET_ID}
+  - Spec mismatch (code ≠ scenario)        → /generate-code {feature-file}  (re-gen affected UC)
 ```

package/commands/review-code.tmpl

@@ -12,13 +12,33 @@
 
 ---
 
+## Pre-Review Scan
+
+*(Separate from the Gate CHECKPOINT — this lists the actual files and scenarios in scope.)*
+
+Scan for implementation files and scenarios, then display:
+
+```
+Review Scope — {UC-ID}
+──────────────────────────────────────
+UC        : {UC-ID}
+Files     : {list of files tagged @trace.implements={UC-ID}}
+Scenarios : {N} scenarios in .feature file
+
+Proceed with review? (Y/N)
+```
+
+Wait for explicit "Y" before proceeding.
+
+---
+
 ## Review Dimensions
 
 ### 1. Traceability
 - [ ] Every controller endpoint has `@trace.implements` tag?
 - [ ] Every test file has `@trace.verifies` tag?
 - [ ] No `@trace` tags on wrong layers?
-- [ ] `{paths.trace_dir}/{UC-ID}.tsv` up to date?
+- [ ] `{paths.trace_dir}/{UC-ID}.tsv` up to date? (if stale → run `/validate-traces {UC-ID}` first, then re-run this review)
 
 ### 2. Layer Architecture (from CLAUDE.md §2)
 - [ ] Each class in the correct layer?
@@ -53,5 +73,15 @@ Critical: {X} | Major: {Y} | Minor: {Z}
 ### Minor
 | # | File | Line | Issue | Suggested Fix |
 
+Output Artifacts: none (read-only)
+
 Verdict: APPROVED ✅ | NEEDS_FIX ❌
+
+If APPROVED ✅:
+  Next: /generate-tests {UC-ID}
+
+If NEEDS_FIX ❌:
+  - Small fix (1–3 lines, no logic change) → fix inline → re-run /review-code {UC-ID}
+  - Logic / architecture issue             → /fix-bug {TICKET_ID}
+  - Spec mismatch (code ≠ scenario)        → /generate-code {feature-file}  (re-gen affected UC)
 ```

package/commands/review-context.md

@@ -34,7 +34,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.
 
@@ -147,7 +147,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.
@@ -224,6 +224,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.
@@ -234,6 +254,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}
@@ -379,14 +400,15 @@ Using `{paths.business_dictionary}` and `{paths.core_entities}`:
 ### B4 — Compliance Checks (C.1–C.5)
 
 - [ ] C.1 Wireframe Coverage: every screen component/action has ≥1 SC → finding per missing item
-- [ ] C.2 PRD Traceability: same as B1 (deduplicate)
+- [ ] C.2 PRD Traceability: covered fully by B1 — do NOT create new findings here; deduplicate against B1 findings
 - [ ] C.3 Business Dictionary terms used → same as B2
 - [ ] C.4 Banned Terms: 0 banned terms → **critical**, auto-fixable
 - [ ] C.5 NHÓM Grouping: if ≥3 SCs, grouped by business theme → **major**, auto-fixable
 
 ### B5 — Metadata & Structural Check
 
-- [ ] File header has all `@trace.*` fields → **minor**, auto-fixable
+- [ ] File header has all required `@trace.*` fields — check each explicitly: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** per missing field, auto-fixable
+  - Note: `@trace.revision` is always `1` (static field — see generate-bdd.tmpl). Only check for presence; do NOT flag value as stale.
 - [ ] Every scenario has `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
 - [ ] Coverage Matrix at end of file → **major**, auto-fixable (AI regenerates)
 - [ ] Pre-merge Checklist at end of file → **minor**, auto-fixable
@@ -467,6 +489,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}` |
@@ -475,13 +498,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          |
 
@@ -500,7 +523,9 @@ Mode: {PRD | BDD}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Auto-fixable: {N} | Needs human decision: {N}
 
-Findings file: {paths.refinement_dir}/{slug}-findings.yaml
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 
 Next options:
   A) Quick fix  : /review-context --fix {target-file}
@@ -557,7 +582,7 @@ After applying each finding, mark it `status: "applied_automatically"` in the fi
 
 ### Phase 3 — Version bump
 
-- **PRD**: if ≥1 finding applied → bump minor version, add Changelog entry:
+- **PRD**: if ≥1 finding applied → bump **minor** version (auto-fix only applies P1 banned-term replacements and P4 skeleton additions — never alters UC structure or BR content, so minor bump is always correct), add Changelog entry:
   `Auto-fix: applied {N} auto-fixable review-context findings`
 - **BDD**: if ≥1 finding applied → increment `@trace.bdd_version` by 0.1
 
@@ -577,7 +602,9 @@ Still pending (needs human decision): {N}
 {If PRD}: Version bumped: {old} → {new}
 {If BDD}: bdd_version: {old} → {new}
 
-Findings file: {paths.refinement_dir}/{slug}-findings.yaml
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 Re-run /review-context {file} to confirm 0 remaining critical findings.
 ```
 
@@ -596,8 +623,10 @@ Open findings file in Review Board → then run: /review-context --resume {file}
 
 ### Phase 1 — Read accepted findings
 
-1. Derive findings filename from target file (same rule as above).
-2. Read `{paths.refinement_dir}/{slug}-findings.yaml`.
+1. Derive findings filename from target file using the same rule as Detect Review Mode:
+   - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
+   - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
+2. Read the findings file.
 3. Collect findings where `status: "accepted"` or `status: "modified"`.
 4. If none → report "No accepted findings. File unchanged." and stop.
 
@@ -627,6 +656,7 @@ Apply in order: critical → major → minor.
 | B6 (Side effects) | Add missing `And <side-effect>` to Then block |
 
 → After applying, increment `@trace.bdd_version` in file header by 0.1.
+→ Also update `{paths.trace_dir}/{UC-ID}.tsv`: set `bdd_version` column to the new `@trace.bdd_version` value for all rows, and set `last_updated` to today's date.
 
 ### Phase 3 — Report
 

package/commands/review-context.tmpl

@@ -135,14 +135,15 @@ Using `{paths.business_dictionary}` and `{paths.core_entities}`:
 ### B4 — Compliance Checks (C.1–C.5)
 
 - [ ] C.1 Wireframe Coverage: every screen component/action has ≥1 SC → finding per missing item
-- [ ] C.2 PRD Traceability: same as B1 (deduplicate)
+- [ ] C.2 PRD Traceability: covered fully by B1 — do NOT create new findings here; deduplicate against B1 findings
 - [ ] C.3 Business Dictionary terms used → same as B2
 - [ ] C.4 Banned Terms: 0 banned terms → **critical**, auto-fixable
 - [ ] C.5 NHÓM Grouping: if ≥3 SCs, grouped by business theme → **major**, auto-fixable
 
 ### B5 — Metadata & Structural Check
 
-- [ ] File header has all `@trace.*` fields → **minor**, auto-fixable
+- [ ] File header has all required `@trace.*` fields — check each explicitly: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** per missing field, auto-fixable
+  - Note: `@trace.revision` is always `1` (static field — see generate-bdd.tmpl). Only check for presence; do NOT flag value as stale.
 - [ ] Every scenario has `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
 - [ ] Coverage Matrix at end of file → **major**, auto-fixable (AI regenerates)
 - [ ] Pre-merge Checklist at end of file → **minor**, auto-fixable
@@ -203,7 +204,9 @@ Mode: {PRD | BDD}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Auto-fixable: {N} | Needs human decision: {N}
 
-Findings file: {paths.refinement_dir}/{slug}-findings.yaml
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 
 Next options:
   A) Quick fix  : /review-context --fix {target-file}
@@ -260,7 +263,7 @@ After applying each finding, mark it `status: "applied_automatically"` in the fi
 
 ### Phase 3 — Version bump
 
-- **PRD**: if ≥1 finding applied → bump minor version, add Changelog entry:
+- **PRD**: if ≥1 finding applied → bump **minor** version (auto-fix only applies P1 banned-term replacements and P4 skeleton additions — never alters UC structure or BR content, so minor bump is always correct), add Changelog entry:
   `Auto-fix: applied {N} auto-fixable review-context findings`
 - **BDD**: if ≥1 finding applied → increment `@trace.bdd_version` by 0.1
 
@@ -280,7 +283,9 @@ Still pending (needs human decision): {N}
 {If PRD}: Version bumped: {old} → {new}
 {If BDD}: bdd_version: {old} → {new}
 
-Findings file: {paths.refinement_dir}/{slug}-findings.yaml
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 Re-run /review-context {file} to confirm 0 remaining critical findings.
 ```
 
@@ -299,8 +304,10 @@ Open findings file in Review Board → then run: /review-context --resume {file}
 
 ### Phase 1 — Read accepted findings
 
-1. Derive findings filename from target file (same rule as above).
-2. Read `{paths.refinement_dir}/{slug}-findings.yaml`.
+1. Derive findings filename from target file using the same rule as Detect Review Mode:
+   - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
+   - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
+2. Read the findings file.
 3. Collect findings where `status: "accepted"` or `status: "modified"`.
 4. If none → report "No accepted findings. File unchanged." and stop.
 
@@ -330,6 +337,7 @@ Apply in order: critical → major → minor.
 | B6 (Side effects) | Add missing `And <side-effect>` to Then block |
 
 → After applying, increment `@trace.bdd_version` in file header by 0.1.
+→ Also update `{paths.trace_dir}/{UC-ID}.tsv`: set `bdd_version` column to the new `@trace.bdd_version` value for all rows, and set `last_updated` to today's date.
 
 ### Phase 3 — Report
 

package/commands/review-tech-docs.md

@@ -34,7 +34,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.
 
@@ -144,7 +144,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.
@@ -221,6 +221,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.
@@ -231,6 +251,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}
@@ -428,6 +449,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}` |
@@ -436,13 +458,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          |
 
@@ -471,7 +493,7 @@ Next: Open in Review Board → Accept/Modify/Reject each finding
 ## Resume Mode — Apply Accepted Findings
 
 *Triggered when `$ARGUMENTS` contains `--resume`.*
-*Example: `/review-tech-docs --resume tech-docs/payment/PAY-UC1-tech-design.md`*
+*Example: `/review-tech-docs --resume {paths.tech_docs_dir}/payment/PAY-UC1-tech-design.md`*
 
 ### Phase 1 — Read accepted findings
 
@@ -494,10 +516,19 @@ Apply in order: critical → major → minor.
 **T1, T2, T4 findings with `auto_fixable: false`:** require a human-written resolution in the
 Review Board "Modify" note. Apply exactly what the note says. Do not invent the fix.
 
-### Phase 3 — Update header + Report
+### Phase 3 — Update header + TSV + Report
+
+Edit the tech-doc file directly:
+1. Find `@trace.revision:` in the header — increment its integer value by 1.
+2. Find `@trace.status:` in the header — set its value to `draft`.
+
+Write both changes to the file.
+
+Then update `{paths.trace_dir}/{UC-ID}.tsv`:
+- Set `tech_doc_revision` column to the new `@trace.revision` integer for all rows of this UC.
+- Set `last_updated` to today's date (`YYYY-MM-DD`) for all rows of this UC.
 
-1. Increment `@trace.revision` in the tech-doc header by 1.
-2. Update `@trace.status` to `draft` (reset — must be re-approved after changes).
+Print the report after all file writes are complete.
 
 ```
 /review-tech-docs --resume Applied — {target file}

package/commands/review-tech-docs.tmpl

@@ -174,7 +174,7 @@ Next: Open in Review Board → Accept/Modify/Reject each finding
 ## Resume Mode — Apply Accepted Findings
 
 *Triggered when `$ARGUMENTS` contains `--resume`.*
-*Example: `/review-tech-docs --resume tech-docs/payment/PAY-UC1-tech-design.md`*
+*Example: `/review-tech-docs --resume {paths.tech_docs_dir}/payment/PAY-UC1-tech-design.md`*
 
 ### Phase 1 — Read accepted findings
 
@@ -197,10 +197,19 @@ Apply in order: critical → major → minor.
 **T1, T2, T4 findings with `auto_fixable: false`:** require a human-written resolution in the
 Review Board "Modify" note. Apply exactly what the note says. Do not invent the fix.
 
-### Phase 3 — Update header + Report
+### Phase 3 — Update header + TSV + Report
 
-1. Increment `@trace.revision` in the tech-doc header by 1.
-2. Update `@trace.status` to `draft` (reset — must be re-approved after changes).
+Edit the tech-doc file directly:
+1. Find `@trace.revision:` in the header — increment its integer value by 1.
+2. Find `@trace.status:` in the header — set its value to `draft`.
+
+Write both changes to the file.
+
+Then update `{paths.trace_dir}/{UC-ID}.tsv`:
+- Set `tech_doc_revision` column to the new `@trace.revision` integer for all rows of this UC.
+- Set `last_updated` to today's date (`YYYY-MM-DD`) for all rows of this UC.
+
+Print the report after all file writes are complete.
 
 ```
 /review-tech-docs --resume Applied — {target file}