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

package/core/commands/fix-bug.md

@@ -31,7 +31,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.
 
@@ -140,7 +140,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.
@@ -217,6 +217,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.
@@ -227,6 +247,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}
@@ -264,17 +285,59 @@ If no ticket — CHECKPOINT:
 
 ## Phase 2 — Root Cause Analysis
 
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
 | Bug Type | Common Location | How to Check |
 |----------|----------------|--------------|
 | Wrong response data | Mapping layer | Check field mapping, DTO conversions |
-| 400 Bad Request | Input validation | Check DTO constraints |
+| 400 Bad Request | Input validation | Check DTO constraints / validators |
+| 401 Unauthorized | Auth filter | Check token config, filter order |
 | 403 Forbidden | Auth config | Check role-based access rules |
 | 404 Not Found | Repository query | Check find method, ID types |
-| N+1 Query | Data access | Check for missing JOIN FETCH |
-| Null Pointer | Optional not handled | Check Optional.orElseThrow |
-| Transaction rollback | Missing @Transactional | Check transaction scope |
-| Stale cache | Missing cache eviction | Check cache invalidation |
-| Type mismatch in query | Filter/specification | Check field types in predicates |
+| N+1 Query | Data access | Check for missing JOIN FETCH / eager load |
+| Null Pointer | Optional not handled | Check Optional.orElseThrow, null guards |
+| Transaction rollback | Missing @Transactional | Check transaction scope, propagation |
+| Stale cache | Missing eviction | Check cache invalidation triggers |
+| Type mismatch | Filter / specification | Check field types in predicates |
+
+#### context-engineering (AI/LLM pipelines)
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong pipeline output | Prompt template | Check prompt content; verify variables are substituted correctly |
+| Missing context in output | Context assembly | Verify all required context blocks are included and non-empty |
+| Schema validation failure | Output parser | Compare raw LLM output vs expected schema; add stricter output instructions |
+| Flaky / non-deterministic results | LLM temperature | Check temperature setting; use fixed seed/mock in tests |
+| API rate limit errors | LLM client | Implement backoff; check quota usage in provider dashboard |
+| Token limit exceeded | Prompt assembly | Reduce context size; add chunking strategy |
+
+### If `platform_type = web-frontend`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong data displayed | State / store | Check state update logic, selector |
+| UI not re-rendering | Missing reactive dep | Check deps array, state immutability |
+| API data not loading | HTTP client / hook | Check network tab, error handler |
+| 401 on API call | Auth token | Check token refresh, header injection |
+| Form not submitting | Validation / handler | Check form state, required fields, errors |
+| Route not found | Router config | Check route definition, lazy import |
+| Build / type error | TypeScript types | Compare type definitions vs actual API shape |
+
+### If `platform_type = mobile`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Screen shows stale data | State / BLoC / ViewModel | Check event dispatched, state emitted correctly |
+| Crash on navigation | Route param missing | Check params passed, null safety |
+| API call not firing | Repository / service layer | Add log in repo method, check network |
+| UI not reflecting state | Widget not observing stream | Check `BlocBuilder` / `StateObserver` setup |
+| Crash on app resume | Lifecycle handler | Check `onResume` / `viewDidAppear` logic |
+| Auth token expired | Token refresh logic | Check refresh flow, token storage |
+| Permission denied | OS permission | Check runtime permission request code |
 
 CHECKPOINT — Root Cause Report:
 ```
@@ -342,6 +405,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}` |
@@ -350,13 +414,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          |
 

package/core/commands/generate-bdd.md

@@ -31,7 +31,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.
 
@@ -138,7 +138,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.
@@ -215,6 +215,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.
@@ -225,6 +245,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}
@@ -270,6 +291,18 @@ After loading context, check if the target PRD is large enough to warrant sub-ag
 
 ---
 
+## Sub-Agent Return Format
+
+*This section applies when running as a sub-agent (Gate Step 0 detected `_agent_mode: true`).*
+
+After generating all `.feature` and `.tsv` files for the assigned UC, return the structured result JSON (as specified in `steps/spawn-agent.md` Step E):
+
+```json
+{ "uc_id": "{TICKET-ID}-UC{N}", "files_created": ["path/to/file1", "path/to/file2"], "status": "success | error", "errors": [] }
+```
+
+---
+
 ## Version Check
 
 Before generating, check for existing `.feature` files for this PRD:
@@ -383,15 +416,16 @@ For each UC, write `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`
 # ============================================================
 # @trace.id: {TICKET-ID}-UC{N}
 # @trace.title: <Feature name>
-# @trace.revision: 1
+# @trace.revision: 1  ← static field; use @trace.bdd_version for version tracking (incremented by /review-context --fix or --resume)
 # @trace.domain: <domain>
 # @trace.service: <ServiceName>
+# @trace.module: {tech_stack.module value — e.g. java-spring | react | flutter; write "unknown" if not set in project-context.yaml}
 # @trace.status: draft
 # @trace.author: AI-generated
 # @trace.created_at: {YYYY-MM-DD}
 # @trace.prd: {TICKET-ID}
 # @trace.prd_version: {read from PRD metadata "| **Version** |"}
-# @trace.bdd_version: {1 if fresh generation; increment by 1 if re-generation}
+# @trace.bdd_version: {1.0 if fresh generation; increment by 0.1 on re-generation — e.g. 1.0 → 1.1}
 # @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
 # @trace.dataset: {domain}.testdata.yaml
 # ============================================================
@@ -499,7 +533,8 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 **Rules:**
 - If file does not exist → create with header row + all scenario rows.
 - If file exists (re-generation) → for each SC in the new `.feature`:
-  - SC already in `.tsv` → update only: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
+  - SC already in `.tsv` AND `spec_ver` is unchanged → update only: `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Leave all other columns unchanged.
+  - SC already in `.tsv` AND `spec_ver` changed (scenario was modified) → update: `sc_title`, `spec_ver`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated` AND set `status = DRIFT` immediately (so the TSV reflects drift without waiting for `/validate-traces`). Leave `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` unchanged.
   - SC is new (added in this re-gen) → append new row with `gen_ver`, `implemented_by`, `test_count`, `test_classes`, `tech_doc_revision` all set to `—`.
   - SC no longer in `.feature` (removed) → delete its row.
 
@@ -552,6 +587,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}` |
@@ -560,13 +596,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          |
 
@@ -587,5 +623,10 @@ Files:
 Trace:
   {paths.trace_dir}/{TICKET-ID}-UC1.tsv ({N} rows)
   {paths.trace_dir}/{TICKET-ID}-UC2.tsv ({N} rows)
-Next: /generate-tech-docs OR /generate-code {paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature
+Next: Run /review-context on EACH generated feature file (one per UC):
+        /review-context {paths.specs_dir}/{domain}/{TICKET-ID}-UC1-{slug}.feature
+        /review-context {paths.specs_dir}/{domain}/{TICKET-ID}-UC2-{slug}.feature
+        ...
+      → then per UC: /generate-tech-docs {feature-file}   (if tech design required)
+      → or   per UC: /generate-code {feature-file}         (if skipping tech design)
 ```

package/core/commands/generate-code.md

@@ -31,7 +31,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.
 
@@ -140,7 +140,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.
@@ -217,6 +217,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.
@@ -227,6 +247,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}
@@ -252,27 +273,88 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## Scope Lock
+
+This command is strictly scoped to the **single feature file** passed as `$ARGUMENTS`:
+
+- Feature file: `{exact path from $ARGUMENTS}`
+- UC: `{UC-ID}` (read from `@trace.id` in that file's header)
+
+**Do NOT read or implement scenarios from any other `.feature` file** in the same domain folder, even if they share the same entity, domain concept, or service name.
+
+---
+
+## Context Load (additional)
+
+Read:
+1. The scoped `.feature` file only
+2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` (if exists)
+3. CLAUDE.md §architecture + §coding_standards
+
+---
+
+## Read Trace State
+
+Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
+
+| Status | Meaning | Action in this run |
+|--------|---------|-------------------|
+| `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
+| `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
+| `OK` | implemented + tested | Skip unless explicitly re-generating |
+| `GAP` | implemented, no tests | Skip codegen — already coded; run `/generate-tests` instead |
+
+Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
+If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
+
+---
+
+## File Scan
+
+Before generating, determine which files will be needed for this UC's scenarios. Check whether each file already exists on disk.
+
+Classify each file:
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `CREATE` | File does not exist | Generate full new file |
+| `EXTEND` | File exists, new methods needed | Add new methods only — do NOT rewrite existing code |
+| `SKIP` | File exists and already covers all UC scenarios | Leave untouched |
+
+> **EXTEND rule:** Read the existing file fully. Locate the correct class/interface. Add only the methods required by `{UC-ID}` scenarios. Preserve all existing methods, fields, and annotations exactly as-is. Attach `@trace.implements={UC-ID}-SC{N}` on each new method.
+
 ---
 
 ## CHECKPOINT — Code Generation Plan
 
 Before generating any code, show:
+
 ```
-I understand:
-- Feature: {name} | Ticket: {ID if known}
-- UC: {UC-ID} | Domain: {domain}
-- Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
-- Layer order: {from CLAUDE.md §2 architecture}
-- Tech stack: {language} / {framework}
-- Files to create: [list]
+Code Generation Plan — {UC-ID}
+──────────────────────────────────────────────────────
+Feature  : {name}
+Ticket   : {TICKET_ID if known}
+Domain   : {domain}
+UC       : {UC-ID} only  ← other feature files in this folder are NOT read
+Tech     : {language} / {framework}
+Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
+Layer    : {from CLAUDE.md §2}
+
+Files:
+  CREATE  {N} new files
+    + {path/FileName.ext}
+  EXTEND  {M} existing files  (add methods only)
+    ~ {path/FileName.ext}  — adding: {methodA}, {methodB}
+  SKIP    {K} files  (no change needed)
+    = {path/FileName.ext}
+──────────────────────────────────────────────────────
 Proceed? (Y/N)
 ```
 
 Wait for explicit "Y" before generating.
 
-## Context Load (additional)
-Read: `.feature` file, tech-doc (if exists at `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`), CLAUDE.md §architecture + §coding_standards, existing entity files.
-
 ## Branch
 ```bash
 git checkout -b feature/{TICKET_ID}-{slug}
@@ -283,13 +365,17 @@ git checkout -b feature/{TICKET_ID}-{slug}
 Default order (override from CLAUDE.md if different):
 DTOs → Entity/Model → Repository → Service interface → Service impl → Facade (if applicable) → Controller
 
-**Controller must have traceability tags (adapt to your language's comment syntax):**
+**For `CREATE` files:** generate the full file.
+
+**For `EXTEND` files:** open the existing file → add only the new methods for `{UC-ID}` → do not touch anything else.
+
+**Traceability tags on controller/handler (adapt to your language's comment syntax):**
 ```
 @trace.implements={UC-ID}-SC{N}
 @trace.prd_version={read @trace.prd_version from the .feature file header}
 @trace.bdd_version={read @trace.bdd_version from the .feature file header}
 @trace.tech_doc_revision={read @trace.revision from tech-doc header, or omit if no tech-doc}
-@trace.source={paths.specs_dir}/{domain}/{UC-ID}.feature
+@trace.source={paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
 ```
 
 `@trace.prd_version` records which PRD version this code was written against.
@@ -297,6 +383,8 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 `@trace.tech_doc_revision` records which tech-design revision this code follows.
 `/validate-traces` will flag drift if any upstream artifact is updated to a newer version.
 
+> **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
+
 ## Self-Review (3 rounds)
 - [ ] Every scenario has a corresponding endpoint
 - [ ] @trace.implements on every endpoint
@@ -360,6 +448,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}` |
@@ -368,13 +457,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          |
 
@@ -389,7 +478,9 @@ Next   : {suggested command with example arguments}
 
 ```
 /generate-code Complete — {UC-ID}
-Files: created={N}, updated={M} | Build: SUCCESS
+Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
-Next: /review-code OR /generate-tests {UC-ID}
+Next:
+  First generation for this UC → /review-code {UC-ID}   ← code review required before tests
+  Re-generation (already reviewed) → /generate-tests {UC-ID}
 ```

package/core/commands/generate-prd.md

@@ -31,7 +31,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.
 
@@ -140,7 +140,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.
@@ -217,6 +217,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.
@@ -227,6 +247,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}
@@ -455,6 +476,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}` |
@@ -463,13 +485,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          |
 
@@ -483,6 +505,11 @@ Next   : {suggested command with example arguments}
 
 
 ```
-✅ PRD created: {paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md  (v1.0)
-Next: /refine-prd {paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md
+/generate-prd Complete — {TICKET-ID}
+---
+Status : ✅ Complete
+Output Artifacts:
+  created {paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md  (PRD v1.0)
+Next   : /refine-prd {paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md
+         → then /review-context {prd-file}   ← verify PRD quality before generating BDD
 ```