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

package/commands/generate-bdd.tmpl

@@ -6,6 +6,194 @@
 ## Context
 {{include:steps/context-loader.md}}
 
+> **Tester proposals (optional input):** before generating, check `{paths.bdd_proposals_dir}/` (default `{spec_source}/feedback/bdd-proposals/`) for scenarios proposed by testers via `/propose-scenario` that map to this UC's ACs. Incorporate any the PO/Dev has accepted — then the tester's draft is removed/archived from `feedback/`. Skip if the folder is empty.
+
+---
+
+## Repo Mode Detection
+
+After loading context, determine which mode to operate in:
+
+- **Spec repo mode**: `project-context.yaml` has NO `services` section OR `setup.mode: spec`
+- **Umbrella mode**: `project-context.yaml` HAS `services` section AND `setup.mode: umbrella`
+
+→ Spec repo mode → proceed to **Platform Selection** below (skip Service Detection)
+→ Umbrella mode → proceed to **Service Detection** below (skip Platform Selection)
+
+---
+
+## Platform Selection (Spec Repo Mode Only)
+
+*Skip this section if running in umbrella mode.*
+
+Ask the user to select the target platform:
+
+```
+Which platform is this BDD for?
+  1. web    — FE/Web (React, Next.js, Angular, Vue, Nuxt)
+  2. app    — Mobile (Flutter, React Native, iOS, Android)
+  3. system — System/BE BDD (synthesized from existing web + app BDDs)
+```
+
+Wait for user selection. Set `active_platform` = chosen value.
+
+**Output path (spec repo mode):**
+`{paths.specs_dir}/{domain}/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
+
+**Platform vocabulary:**
+
+| Platform | "user action" | "type/input" | "observe" | "navigate" |
+|---|---|---|---|---|
+| web | "clicks" | "types into" / "enters" | "sees" / "the page shows" | "navigates to" / "goes to" |
+| app | "taps" | "enters" / "inputs" | "sees" / "the screen shows" | "navigates to" / "opens" |
+| system | N/A — use business events | — | "the system returns" / "receives response" | — |
+
+---
+
+## System BDD Synthesis (active_platform = system)
+
+*Only applies when platform = system. Skip for web and app.*
+
+### Step S0 — Brownfield Check
+
+Check the source PRD Metadata table for `| **API Source** | existing |`.
+
+**Nếu `API Source: existing`:**
+- API contract đã được PO ghi trong phần "Existing API Contract" của PRD.
+- **Skip Steps S1–S3** — không cần scan FE/App BDD, không cần conflict resolution.
+- Dùng bảng "Existing API Contract" trong PRD làm contract input cho Step S4.
+- Set `# @trace.api_source: existing` trong header của file system BDD được gen.
+
+**Nếu `API Source` không có hoặc không phải `existing`:**
+- Tiếp tục Steps S1–S3 (normal synthesis flow).
+
+---
+
+### Step S1 — Scan available FE/App BDDs
+
+Search for existing BDDs for this TICKET-ID:
+- Web BDDs: `{paths.specs_dir}/{domain}/web/{TICKET-ID}-*.feature`
+- App BDDs: `{paths.specs_dir}/{domain}/app/{TICKET-ID}-*.feature`
+
+Classify the feature:
+
+| Condition | Mode |
+|---|---|
+| Both web + app BDDs found | **Multi-platform** — synthesize from both |
+| Only web BDD found | **Web-only** — synthesize from web |
+| Only app BDD found | **App-only** — synthesize from app |
+| No FE/App BDDs found | **Backend-only** — gen directly from PRD |
+
+---
+
+### Step S2 — Extract expected contracts per platform
+
+For each found BDD file, extract:
+- **Triggers**: what user actions call the backend? (map to logical "request" events)
+- **Expected response data**: what fields/shape does each `Then` clause need from the system?
+- **Error signals**: what error states must the backend signal?
+- **Business rules**: what invariants does each platform assume the system enforces?
+
+---
+
+### Step S3 — Cross-Platform Conflict Check (multi-platform mode only)
+
+*Skip if web-only, app-only, or backend-only.*
+
+Compare the extracted contracts across platforms. Flag a conflict if any of these differ:
+
+| Conflict type | Example |
+|---|---|
+| **Response shape mismatch** | Web expects `{ token, redirect_url }`, App expects `{ token, user_profile }` |
+| **Error semantics mismatch** | Web expects HTTP 423 for lock, App expects custom error code `ACC_LOCKED` |
+| **Business rule contradiction** | Web BDD says "lock after 5 attempts", App BDD says "lock after 3 attempts" |
+| **Data field conflict** | Web expects `expires_in: seconds`, App expects `expires_at: ISO timestamp` |
+
+**If conflicts detected → CHECKPOINT (mandatory, cannot skip):**
+
+```
+⚠️  CROSS-PLATFORM CONTRACT CONFLICT
+──────────────────────────────────────────────────────────────────
+Feature : {TICKET-ID} — {UC name}
+
+Conflict 1: Response shape mismatch
+  Web BDD (Then): user sees dashboard → implies { token, redirect_url }
+  App BDD (Then): app navigates to HomeScreen → implies { token, user_profile }
+
+Resolution options:
+  A — Union response
+      BE returns all fields: { token, redirect_url, user_profile }
+      Clients ignore fields they don't use. Simple, slight over-fetch.
+  B — Platform hint in request
+      Client sends X-Platform: web|app in header, BE tailors response.
+      Cleaner responses, more BE logic.
+  C — Separate endpoints
+      POST /auth/login/web  and  POST /auth/login/app
+      Maximum flexibility, more endpoints to maintain.
+  D — Custom: describe your approach
+──────────────────────────────────────────────────────────────────
+Choose resolution for each conflict (A/B/C/D):
+```
+
+Wait for PO's resolution per conflict. Record each decision as a `# @system.resolution:` annotation in the generated system BDD file.
+
+**If no conflicts → proceed to Step S4 directly.**
+
+---
+
+### Step S4 — Generate System BDD scenarios
+
+Generate scenarios based on mode and resolved conflicts:
+
+- **Multi-platform**: synthesize from both web + app contracts, applying resolved resolutions
+- **Web-only / App-only**: derive from the single platform's contracts
+- **Backend-only**: derive directly from PRD AC/BR using business event language (not HTTP)
+
+System BDD step vocabulary (always use — regardless of FE/App vocabulary):
+- Triggers: "the system receives {event}" / "a {actor} submits {action}"
+- Assertions: "the system returns {data}" / "the system signals {error}" / "the system stores {state}"
+- Do NOT use UI words (click, tap, see, navigate) in system BDD
+
+**If multi-platform with resolution A (union):**
+- System BDD shows the full response contract: all fields from all platforms
+- Add comment: `# @system.resolution: union — clients receive all fields`
+
+**If resolution B (platform hint):**
+- Write separate `Scenario Outline` using Examples table for `web` vs `app` response variants
+- Add comment: `# @system.resolution: platform-hint — X-Platform header determines response shape`
+
+**If resolution C (separate endpoints):**
+- Write separate Scenarios for each endpoint
+- Note the endpoint split explicitly in the SCOPE section
+
+---
+
+## Service Detection (Umbrella Mode Only)
+
+*Skip this section if running in spec repo mode.*
+
+Read the PRD Metadata table for `| **Service** |` and `| **Module** |` rows.
+
+| Condition | Action |
+|---|---|
+| PRD has `Service` row AND value is not "default" | Use it as `active_service` + `active_module`. Load catalog for that module. |
+| PRD has no `Service` row AND `services` defined in project-context.yaml | Ask: "Which service is this BDD for?" (list services, wait for selection) |
+| Single-service project (no `services` array) | `active_service = "default"`, `active_module = tech_stack.module` |
+
+**Output path (umbrella mode):**
+- `active_service = "default"` → `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`
+- `active_service ≠ "default"` → `{paths.specs_dir}/{domain}/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
+
+**Platform vocabulary** — adapt BDD step wording based on `active_module`:
+
+| Platform type | Modules | "click" | "type" | "see" | "navigate" |
+|---|---|---|---|---|---|
+| Web | react, nextjs, vue, nuxt, angular | "clicks" | "types into" / "enters" | "sees" / "the page shows" | "navigates to" / "goes to" |
+| Mobile | flutter, react-native, ios-swiftui, android-compose | "taps" | "enters" / "inputs" | "sees" / "the screen shows" | "navigates to" / "opens" |
+| Backend / API | java-spring, golang, dotnet, php-laravel | *(no UI steps — use)* "submits a request" / "calls the API" | — | "receives response" / "the system returns" | — |
+
+Apply this vocabulary silently when writing Gherkin steps. Do NOT mix web and mobile terms in the same feature file.
+
 ---
 
 ## Orchestration Check
@@ -42,7 +230,9 @@ After generating all `.feature` and `.tsv` files for the assigned UC, return the
 
 Before generating, check for existing `.feature` files for this PRD:
 
-1. Look for `{paths.specs_dir}/{domain}/{TICKET-ID}-UC*.feature`.
+1. Resolve the search path based on mode:
+   - **Spec repo mode**: `{paths.specs_dir}/{domain}/{active_platform}/{TICKET-ID}-UC*.feature`
+   - **Umbrella mode**: `{paths.specs_dir}/{domain}/{TICKET-ID}-UC*.feature` (or with `{active_service}/` if multi-service)
 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`.
@@ -145,7 +335,12 @@ CHECKPOINT: "Does this outline look correct? Do you want to add or remove any SC
 
 ## Generate
 
-For each UC, write `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`:
+**Output path by mode:**
+- **Spec repo mode**: `{paths.specs_dir}/{domain}/{active_platform}/{TICKET-ID}-UC{N}-{slug}.feature`
+- **Umbrella mode (single-service)**: `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`
+- **Umbrella mode (multi-service)**: `{paths.specs_dir}/{domain}/{active_service}/{TICKET-ID}-UC{N}-{slug}.feature`
+
+For each UC, write to the resolved path above. Use vocabulary for the active platform (from Platform Selection or Service Detection).
 
 ```gherkin
 # ============================================================
@@ -153,8 +348,9 @@ For each UC, write `{paths.specs_dir}/{domain}/{TICKET-ID}-UC{N}-{slug}.feature`
 # @trace.title: <Feature name>
 # @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.platform: {active_platform — web | app | system | (omit in umbrella mode)}
+# @trace.service: {active_service — omit in spec repo mode}
+# @trace.module: {active_module in umbrella mode; "unknown" in spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated
 # @trace.created_at: {YYYY-MM-DD}
@@ -262,7 +458,7 @@ After generating all `.feature` files, create or update `{paths.trace_dir}/{UC-I
 
 **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
+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\tfe_phase\tstatus\tlast_updated
 ```
 
 **Rules:**
@@ -289,6 +485,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 | `tech_doc_revision` | `—` |
 | `prd_status` | read `\| **Status** \|` from PRD metadata |
 | `uc_status` | `draft` for new UCs; keep existing value for re-gen |
+| `fe_phase` | `—` (set by `/generate-code --phase` when FE implements) |
 | `status` | `UNTRACKED` |
 | `last_updated` | today `YYYY-MM-DD` |
 
@@ -298,16 +495,26 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tpr
 
 ```
 /generate-bdd Complete
+
+[Spec repo mode — platform: {active_platform}]
 Files:
-  {paths.specs_dir}/{domain}/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
-  {paths.specs_dir}/{domain}/{TICKET-ID}-UC2-{slug}.feature ({N} scenarios)
+  {paths.specs_dir}/{domain}/{active_platform}/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+  {paths.specs_dir}/{domain}/{active_platform}/{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: 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)
+Next (spec repo):
+  → Run /generate-bdd again for other platforms (web → app → system)
+  → After all platforms generated: commit + push + notify dev team
+  → Dev team reads BDD from spec submodule — no /generate-bdd on their side
+
+[Umbrella mode — service: {active_service}]
+Files:
+  {paths.specs_dir}/{domain}/{TICKET-ID}-UC1-{slug}.feature ({N} scenarios)
+Trace:
+  {paths.trace_dir}/{TICKET-ID}-UC1.tsv ({N} rows)
+Next (umbrella):
+  → /review-context {feature-file} to verify coverage
+  → /generate-tech-docs {feature-file}
+  → /generate-code {feature-file}
 ```

package/commands/generate-code.md

@@ -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`
@@ -142,11 +143,75 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `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`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -237,6 +302,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -252,6 +336,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -295,6 +382,39 @@ Read:
 
 ---
 
+## Phase Detection
+
+Parse `$ARGUMENTS` for a `--phase` flag:
+
+| Flag | Meaning |
+|---|---|
+| `--phase=ui` | FE Phase 1 — generate UI + mock API layer from System BDD contract |
+| `--phase=integration` | FE Phase 2 — replace mock adapter with real API calls from tech docs |
+| *(none)* | Default — full implementation (BE or full-stack without mock split) |
+
+**If `--phase` is set — confirm platform:**
+Read `@trace.platform` from the feature file header.
+- If `system` → warn: "`--phase` flag is not applicable for system BDD (BE-facing). Proceeding with default mode." Treat as no flag.
+- If `web` or `app` → continue with phase logic below.
+
+**If `--phase=ui`:**
+Load System BDD for this UC: find `{specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
+Extract all `Then` clauses → collect implied response shapes and error states.
+If System BDD not found → warn: "System BDD not found — mock layer will use placeholder fixtures." Continue.
+
+**If `--phase=integration`:**
+Read tech-doc `@trace.status` from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`.
+If `draft` or `in-review` → warn:
+```
+⚠ Tech docs for {UC-ID} are {status}.
+  BE may not have a stable API contract yet.
+  Proceeding — ensure BE endpoint is deployed or confirm contract manually.
+```
+Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
+If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
+
+---
+
 ## Read Trace State
 
 Read `{paths.trace_dir}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
@@ -339,6 +459,7 @@ Ticket   : {TICKET_ID if known}
 Domain   : {domain}
 UC       : {UC-ID} only  ← other feature files in this folder are NOT read
 Tech     : {language} / {framework}
+Phase    : {UI — mock layer | Integration — real API | Default — full}   ← omit if no --phase flag
 Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
 Layer    : {from CLAUDE.md §2}
 
@@ -385,6 +506,53 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **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.
 
+## Mock API Layer (`--phase=ui` only)
+
+*Skip this section entirely if `--phase` is not `ui`.*
+
+Using the System BDD `Then` clauses loaded in Phase Detection:
+
+1. **Extract fixture data** per scenario — success responses + error responses.
+2. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+   - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
+   - Each method returns fixture data matching the BDD `Then` clause
+   - Include both success and error states (map to error scenarios in BDD)
+   - Traceability tags:
+     ```
+     @trace.mock_for={UC-ID}
+     @trace.system_bdd={paths.specs_dir}/{domain}/system/{UC-ID}*.feature
+     ```
+3. **Wire into service/hook layer** via environment flag or DI:
+   ```
+   const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
+   ```
+   - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
+
+> Tester uses the mock adapter to test all FE scenarios without waiting for BE.
+> Mock fixture data is derived directly from System BDD — BDD is the source of truth.
+
+---
+
+## Integration Phase (`--phase=integration` only)
+
+*Skip this section entirely if `--phase` is not `integration`.*
+
+1. **Read tech-doc API contract** from `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` — extract endpoints, request/response shapes, error codes.
+2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
+3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
+   - Implements the same `{UC-ID}ApiPort` interface as mock adapter
+   - Makes real HTTP calls to endpoints from tech-doc contract
+   - Maps response fields to the same shapes the mock adapter returned
+   - Traceability tags:
+     ```
+     @trace.implements={UC-ID}-SC{N}
+     @trace.tech_doc_revision={read from tech-doc header}
+     ```
+4. **Flip wire-up**: switch DI binding / env flag so service/hook uses `{UC-ID}ApiAdapter` (real) instead of mock.
+5. **Do NOT delete mock adapter** — keep it for unit testing.
+
+---
+
 ## Self-Review (3 rounds)
 - [ ] Every scenario has a corresponding endpoint
 - [ ] @trace.implements on every endpoint
@@ -407,6 +575,7 @@ Update `{paths.trace_dir}/{UC-ID}.tsv` — for each implemented scenario, find t
 | `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 |
+| `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
 | `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.
@@ -452,7 +621,8 @@ Suggest the logical next command based on workflow phase:
 | /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}`        |
@@ -466,6 +636,11 @@ Suggest the logical next command based on workflow phase:
 | /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          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
 
 Format the footer as:
 ```
@@ -480,7 +655,20 @@ Next   : {suggested command with example arguments}
 /generate-code Complete — {UC-ID}
 Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
+Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
+fe_phase : {ui | integrated | —}
+
 Next:
-  First generation for this UC → /review-code {UC-ID}   ← code review required before tests
-  Re-generation (already reviewed) → /generate-tests {UC-ID}
+  --phase=ui done:
+    → Notify tester: FE is testable via mock adapter
+    → Collect BE sign-offs → /review-tech-docs {tech-design-file}
+    → When BE ready → /generate-code {feature-file} --phase=integration
+
+  --phase=integration done:
+    → /review-code {UC-ID}   ← code review required
+    → /generate-tests {UC-ID}  ← integration test suite
+
+  Default (no phase flag):
+    → /review-code {UC-ID}   ← code review required before tests
+    → /generate-tests {UC-ID}
 ```