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

package/commands/generate-code.tmpl

@@ -30,6 +30,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`:
@@ -74,6 +107,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}
 
@@ -120,6 +154,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
@@ -142,6 +223,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.
@@ -161,7 +243,20 @@ git commit -m "{commit_format}: {description}"
 /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}
 ```