@anhth2/spec-driven-dev-plugin 0.5.0

package/commands/generate-bdd.tmpl

@@ -0,0 +1,294 @@
+# /generate-bdd — Generate BDD Feature Files
+
+## Gate
+{{include:steps/gate.md}}
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Orchestration Check
+
+*Skip this section if already in sub-agent mode (Step 0 of Gate was triggered).*
+
+After loading context, check if the target PRD is large enough to warrant sub-agents:
+
+1. Count `#### {TICKET-ID}-UC` headings in the PRD → **UC count**.
+2. Count total lines in the PRD → **line count**.
+3. If **UC count > 3** OR **line count > 300**:
+   - Switch to orchestration mode — follow `steps/spawn-agent.md`.
+   - The main session becomes the orchestrator: spawn 1 sub-agent per UC.
+   - Each sub-agent runs `/generate-bdd` with `_agent_mode: true` payload.
+   - Collect results and show merged report.
+   - **Do NOT continue with the steps below.**
+4. If UC count ≤ 3 AND line count ≤ 300 → continue with Version Check below (single-session mode).
+
+---
+
+## Version Check
+
+Before generating, check for existing `.feature` files for this PRD:
+
+1. Look for `{paths.specs_dir}/{domain}/{TICKET-ID}-UC*.feature`.
+2. Read current PRD `| **Version** |` from metadata (e.g., `1.2`).
+
+**If no existing feature files** → fresh generation, proceed normally. Use PRD version as `@trace.prd_version`.
+
+**If existing feature files found**:
+- Read `# @trace.prd_version:` from the existing feature file header.
+- Compare with current PRD version.
+- If **same** → ask: "BDD already generated from PRD v{version}. Regenerate? (Y/N)"
+- If **different** (PRD was updated):
+  1. Read `## Changelog` from the PRD — extract all rows newer than the existing BDD's `@trace.prd_version`.
+  2. Show CHECKPOINT:
+     ```
+     ⚠️  PRD version drift detected
+     BDD was generated from PRD v{old}
+     PRD is now at v{new}
+
+     Changes since v{old}:
+       {changelog rows}
+
+     Options:
+       Y — update only affected scenarios
+       F — full regeneration of all scenarios
+       N — cancel
+     ```
+  3. Proceed based on user choice.
+
+---
+
+## BDD Writing Rules (R1-R10 — enforce strictly)
+
+| Rule | Name | Requirement |
+|------|------|-------------|
+| R1 | Given/When/Then Semantics | Given=state, When=action, Then=outcome. Every SC needs full G/W/T. |
+| R2 | One Behavior Per Scenario | 1 SC = 1 behavior. Do NOT chain When→Then→When→Then. |
+| R3 | Ubiquitous Language | Do NOT use UI selectors / API names / tech terms in steps. |
+| R4 | Outside-in Naming | SC name describes business outcome. No "click" / "(Case X)" / component names. |
+| R5 | Declarative over Imperative | Describe WHAT (business intent), NOT HOW (UI mechanic). |
+| R6 | Observable Outcomes Only | Then asserts observable outcome. Not UI intermediate state / internal state. |
+| R7 | Key Examples / Concrete | Use concrete values. Not vague "valid data". |
+| R8 | Independence | SC runs independently. Does not depend on state from another SC. |
+| R9 | Test Data Completeness | Data table has enough fields to derive expected Then. |
+| R10 | Scope Boundary Explicit | Cross-UC reference uses navigation wording + Note comment. |
+
+## Project Compliance (fail review if missing — C.1-C.5)
+
+| Check | Rule |
+|-------|------|
+| C.1 Wireframe Coverage | Every component/action in Wireframe has ≥1 SC. |
+| C.2 PRD Traceability | Every AC and every BR (including each logic bullet) maps to ≥1 SC. |
+| C.3 Business Dictionary | Use correct canonical terms from business-dictionary.md. |
+| C.4 Banned Terms | 0 banned terms in file — grep before generating. |
+| C.5 NHÓM Grouping | Feature ≥3 SCs → MUST have NHÓM grouping by business theme. |
+
+---
+
+## NHÓM Grouping Convention (C.5 — mandatory for ≥3 scenarios)
+
+Group by business theme, NOT by happy/negative/edge.
+
+Format header (indent 2 spaces, same level as Background):
+```
+  # ==========================================================
+  # NHÓM N: <Business theme> (<BR refs if applicable>)
+  # ==========================================================
+```
+
+Rules:
+- Number sequentially NHÓM 1 → N. SC IDs sequential across lifecycle (do not reset per NHÓM).
+- Each NHÓM can contain @happy + @edge + @negative of the same theme.
+- SCs in NHÓM do not need to be in ID order (NHÓM 2 can contain SC4, SC8, SC11 if same theme).
+
+Suggested patterns (adjust per UC):
+- `Init / Save success — valid data combinations`
+- `Validation / Block when invalid`
+- `Error handling — API fail / system error`
+- `Cancel changes / Close modal without saving`
+- `Cross-system / Downstream effects`
+- `Idempotency & Concurrency`
+
+---
+
+## UC Decomposition
+
+For each UC in the PRD, present the SC outline **before generating**:
+```
+{TICKET-ID}-UC1: {Use Case Name}
+  NHÓM 1: {Theme} (BR1, BR2)
+    SC1 [@happy]:              {business outcome}
+    SC2 [@happy @alternative]: {variant outcome}
+  NHÓM 2: {Theme} (BR2, BR3)
+    SC3 [@edge]:               {edge case}
+    SC4 [@negative]:           {error handling}
+  ACs covered: AC1, AC2
+  BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
+```
+
+CHECKPOINT: "Does this outline look correct? Do you want to add or remove any SCs?" → **Wait for confirm before generating.**
+
+---
+
+## Generate
+
+For each UC, write `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`:
+
+```gherkin
+# ============================================================
+# @trace.id: {TICKET-ID}-UC{N}
+# @trace.title: <Feature name>
+# @trace.revision: 1
+# @trace.domain: <domain>
+# @trace.service: <ServiceName>
+# @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.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
+# @trace.dataset: {domain}.testdata.yaml
+# ============================================================
+
+# === CONTEXT ===
+# Actor:     <role performing the action, e.g., Consumer, Staff, System>
+# Screens:   <related screens, e.g., Cart → Confirm Order → Order Detail>
+# Entities:  <business entities, e.g., Order, OrderItem, Consumer>
+# Pre-state: <shared state before entering scenarios>
+
+# === SCOPE ===
+# In:  <what this UC covers>
+# Out: <what is NOT in this UC — link to other UC/feature (R10)>
+
+# === BUSINESS DEFINITION ===
+# Quick reference for terms used in this feature. SoT details: business-dictionary.md
+# <Term 1>: <short definition>
+# <Term 2>: <short definition>
+
+Feature: <Feature name>
+  As a <role>
+  I want to <action>
+  So that <business value>
+
+  Background:
+    Given <shared precondition — use aliases from dataset, not technical IDs>
+
+  # ==========================================================
+  # NHÓM 1: <Business theme> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <list brief Then side-effects to verify>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC1
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
+  @happy
+  Scenario: <describe business outcome — use precise verb: create/receive/assign/block>
+    Given <input state — alias from dataset>
+    When <single action>
+    Then <main observable outcome>
+      And <side-effect 1 declared in header>
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC2
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
+  @happy @alternative
+  Scenario: <same NHÓM 1 theme but different path — e.g., different enum value>
+    Given <state>
+    When <action>
+    Then <outcome>
+
+  # ==========================================================
+  # NHÓM 2: <Business theme 2> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET-ID}-UC{N}-SC3
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
+  @edge
+  Scenario: <boundary / error scenario>
+    Given <state>
+    When <action>
+    Then <expected error handling>
+```
+
+### Coverage Matrix & Pre-merge Checklist *(appended to end of each file)*
+
+```gherkin
+# === PRD COVERAGE (C.1 + C.2) ===
+# AC mapping:
+#   AC1 (...) → SC1, SC2
+#   AC2 (...) → SC3
+# BR mapping (each bullet MUST have ≥1 SC — C.2):
+#   {TICKET-ID}-UC{N}-BR1 (...) → SC1, SC2
+#   {TICKET-ID}-UC{N}-BR2 (...) → SC3
+# Wireframe mapping (every component/action ≥1 SC — C.1):
+#   Screen "<screen name>":
+#     [x] <action 1>  → SC1
+#     [x] <action 2>  → SC2
+#     [ ] <action 3>  → MISSING ← BLOCK MERGE
+
+# === PRE-MERGE CHECKLIST ===
+# - [ ] Every SC has Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
+# - [ ] Coverage Matrix: 0 MISSING lines (C.1)
+# - [ ] Every AC/BR maps to ≥1 SC (C.2)
+# - [ ] 0 banned terms (C.4) — grep file before merging
+# - [ ] Feature ≥3 SCs has NHÓM grouping by business theme (C.5)
+# - [ ] If popup/modal: Popup/Modal Lifecycle declared in BUSINESS DEFINITION
+# - [ ] If display logic ≥2 dimensions: Display Logic Matrix in BUSINESS DEFINITION
+```
+
+---
+
+## Write Trace State
+
+After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-ID}.tsv` for each UC.
+
+**TSV columns (tab-separated, one header row + one data row per scenario):**
+```
+sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tprd_version\tbdd_version\ttech_doc_revision\tprd_status\tuc_status\tstatus\tlast_updated
+```
+
+**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 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.
+
+**Values to write for each scenario:**
+
+| Column | Value |
+|--------|-------|
+| `sc_id` | `{UC-ID}-SC{N}` |
+| `sc_title` | scenario title text |
+| `spec_ver` | `@trace.sc_version` of this scenario |
+| `gen_ver` | `—` (not yet generated) |
+| `implemented_by` | `—` |
+| `test_count` | `—` |
+| `test_classes` | `—` |
+| `prd_version` | `@trace.prd_version` from `.feature` header |
+| `bdd_version` | `@trace.bdd_version` from `.feature` header |
+| `tech_doc_revision` | `—` |
+| `prd_status` | read `\| **Status** \|` from PRD metadata |
+| `uc_status` | `draft` for new UCs; keep existing value for re-gen |
+| `status` | `UNTRACKED` |
+| `last_updated` | today `YYYY-MM-DD` |
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-bdd Complete
+Files:
+  {paths.specs_dir}/{domain}/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+  {paths.specs_dir}/{domain}/{TICKET-ID}-UC2-{slug}.feature ({N} scenarios)
+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
+```

package/commands/generate-code.md

@@ -0,0 +1,395 @@
+# /generate-code — Generate Implementation Code
+
+## Gate
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a UC-ID, ticket ID, or partial name → search for matching files in the relevant directory.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/prd/**/*.md` for PRD commands, `specs/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID. If `$ARGUMENTS` is a UC-ID, find the matching feature file under `{paths.specs_dir}/`. Also check `{paths.trace_dir}/{UC-ID}.tsv` for drift (new vs drifted vs synced).*
+
+## Context
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → BDD specs root
+- `paths.prd_dir` → PRD documents root
+- `paths.refinement_dir` → findings/review output dir
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root
+- `paths.trace_dir` → trace state directory
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs/bdd`
+- `prd_dir` = `specs/prd`
+- `refinement_dir` = `.agent/review`
+- `product_definitions_dir` = `specs/product-definition`
+- `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`
+- `trace_dir` = `.trace`
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+Read `CLAUDE.md`. Extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
+- **§7 Git Conventions** → branch naming pattern, commit message format
+
+If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+
+After loading all context, synthesize and output a compact summary block.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+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}
+Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.
+
+
+---
+
+## 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]
+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}
+```
+
+## Generate (layer order from CLAUDE.md §2)
+
+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):**
+```
+@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.prd_version` records which PRD version this code was written against.
+`@trace.bdd_version` records which BDD version this code was generated from.
+`@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.
+
+## Self-Review (3 rounds)
+- [ ] Every scenario has a corresponding endpoint
+- [ ] @trace.implements on every endpoint
+- [ ] Architecture layer rules respected (CLAUDE.md §2)
+- [ ] Error handling matches CLAUDE.md §5
+- [ ] No magic numbers, no debug logging
+
+## Build Verify
+```bash
+{conventions.build_command}   # from project-context.yaml, max 3 retries
+```
+
+## Write Trace State
+
+Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns:
+
+| Column | Value |
+|--------|-------|
+| `gen_ver` | copy `spec_ver` from the current `.tsv` row (= scenario version at time of codegen) |
+| `implemented_by` | `{ControllerClass}.{methodName}` |
+| `bdd_version` | `@trace.bdd_version` from `.feature` header |
+| `tech_doc_revision` | `@trace.revision` from tech-doc header, or `—` if no tech-doc |
+| `last_updated` | today `YYYY-MM-DD` |
+
+Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`) unchanged.
+`status` is computed by `/validate-traces` — do not set here.
+
+## Commit
+```bash
+git add {files}
+git commit -m "{commit_format}: {description}"
+```
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /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 |
+| /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-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             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+```
+/generate-code Complete — {UC-ID}
+Files: created={N}, updated={M} | Build: SUCCESS
+Branch: feature/{TICKET_ID}-{slug}
+Next: /review-code OR /generate-tests {UC-ID}
+```