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

package/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.
 
@@ -129,6 +129,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -138,13 +139,46 @@ 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`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -215,6 +249,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,10 +279,12 @@ 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}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -270,6 +326,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 +451,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 +568,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,21 +622,23 @@ 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)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /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 +659,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/commands/generate-bdd.tmpl

@@ -26,6 +26,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:
@@ -139,15 +151,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
 # ============================================================
@@ -255,7 +268,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.
 
@@ -290,5 +304,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/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.
 
@@ -131,6 +131,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -140,13 +141,46 @@ 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`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -217,6 +251,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,10 +281,12 @@ 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}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -252,27 +308,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 +400,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 +418,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,21 +483,23 @@ 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)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /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 +514,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/commands/generate-code.tmpl

@@ -10,25 +10,86 @@
 
 ---
 
+## 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}
@@ -39,13 +100,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.
@@ -53,6 +118,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
@@ -92,7 +159,9 @@ git commit -m "{commit_format}: {description}"
 
 ```
 /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}
 ```