@edupia-tutor/spec-driven-docs 0.14.0

package/commands/generate-code.tmpl

@@ -0,0 +1,349 @@
+# /generate-code — Generate Implementation Code
+
+## Gate
+{{include:steps/gate.md}}
+
+*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 by globbing `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` for the unknown prd-slug, recursive `**` to cover the `web/`·`app/`·`system/` platform subfolders); take `domain` + `prd_slug` from the matched path. Also check `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` for drift (new vs drifted vs synced).*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## 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}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (if exists)
+3. CLAUDE.md §architecture + §coding_standards
+4. **(FE/App only)** Design Spec at `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
+
+---
+
+## 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`:**
+Resolve the **mock shape source** (hybrid — prefer the real contract, fall back to System BDD):
+- **BE contract** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` — if it exists, the mock adapter's port/DTO **shape** (request/response fields, types, error codes) comes from here → `mock_source = contract`. Most accurate; no shape rework at integration.
+- **System BDD** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature` — always load `Then` clauses for **behavior + fixture values**. If no BE contract, the shape is inferred from these too → `mock_source = system-bdd`, and WARN:
+  ```
+  ⚠ BE contract not found — mock shape inferred from System BDD only.
+    System BDD describes behavior, not full request/response shape — the mock
+    may differ from the real API; expect adjustment at --phase=integration.
+    (Recommended: have BE publish {prd-slug}/tech-docs/{UC-ID}-tech-design.md first for an accurate mock.)
+  ```
+- If System BDD is also missing → warn "System BDD not found — mock layer will use placeholder fixtures." Continue.
+
+Store `mock_source` (`contract` | `system-bdd`) for the mock tags below.
+
+**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
+Spec's frame links are the visual contract, and the local MCP reads them with far more
+fidelity than a plain web link.
+
+---
+
+## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+
+*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
+mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+
+The PO authored the Design Spec from **Figma web links** (read-only, limited). For
+codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
+gives far more: exact layout, design **variables/tokens**, **Code Connect** component
+mappings, selection context, and code snippets — things a web URL alone cannot return.
+
+**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
+(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+
+**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+
+```
+🎨 Figma Dev Mode MCP not detected.
+   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
+
+   1. Open the Figma DESKTOP app (not the browser)
+   2. Open the file/frame for this feature
+   3. Enable the Dev Mode MCP server:
+        Figma menu → Preferences → "Enable Dev Mode MCP Server"
+        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
+   4. Make sure this MCP server is added in your Claude Code MCP config
+   5. Select the frame for the screen you're implementing, then continue
+
+   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+```
+
+- `C` → re-detect; if now connected → proceed using the local MCP.
+- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
+  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+
+**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
+selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
+Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
+real token names, not hardcoded values.
+
+**If `--phase=integration`:**
+Resolve the design that drives the adapter (two layers):
+- **FE tech-design** (preferred — the port→endpoint→DTO mapping): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` §4, produced by `/generate-tech-docs` (FE path).
+- **BE API contract** (endpoint/shape source): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`.
+
+Read `@trace.status` of whichever drives the adapter (the FE doc if present, else the BE contract).
+If `draft` or `in-review` → warn:
+```
+⚠ Tech design for {UC-ID} ({platform}) is {status}.
+  Contract / adapter mapping may still change.
+  Proceeding — ensure BE endpoint is deployed or confirm the mapping manually.
+```
+If the FE tech-design is **missing** → warn: "No FE tech-design found — falling back to the BE contract directly (adapter mapping inferred). Recommended: run `/generate-tech-docs {web|app .feature}` first."
+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}/{domain}/{prd-slug}/{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 `/dev-gen-test` 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:
+
+```
+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}
+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}
+
+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.
+
+## 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
+
+**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}/{prd-slug}/bdd/{UC-ID}-{slug}.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.
+
+> **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.
+
+### Test Selectors — emit stable element IDs *(FE/App UI only)*
+
+*Applies when `platform` is `web`/`app` and generating UI (`--phase=ui`, or default FE/App mode). Skip for BE.*
+
+Every **actionable** element (button, input, link, select, toggle, form-submit) MUST carry a **stable test-id** so QC locates it directly (no runtime scan):
+
+1. **Source the id.** If the FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` exists, take ids **verbatim** from its §2b Test Selectors table (the contract). If it does not exist yet (e.g. `--phase=ui` before the FE tech-design), **generate ids by the convention** `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`) so QC still has stable handles — they will be reconciled to the tech-design's §2b at integration.
+2. **Emit via the platform attribute** (from `@trace.testid_attr`, or by module):
+   - web (`react`/`nextjs`/`vue`/`angular`) → `data-testid="..."`
+   - React Native → `testID="..."`
+   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` where the action needs it)
+   - native iOS → `accessibilityIdentifier = "..."`
+3. Only actionable elements; do not spam ids on static text. Keep ids identical to the tech-design map so QC Page Objects match on the first try.
+4. **Reused catalog component?** Pass the id via its **forwarding prop** (see the catalog `## Test-ID Forwarding` section — e.g. `<Button testId="ft001-login-submit-btn">`), not a raw attribute. If the component does not forward a test-id, or you are backfilling **existing/brownfield** screens (not freshly generated here), that is `/map-testids {UC-ID}`'s job — run it instead of editing shared components inline.
+
+## Mock API Layer (`--phase=ui` only)
+
+*Skip this section entirely if `--phase` is not `ui`.*
+
+Build the mock from the `mock_source` resolved in Phase Detection — **shape** from the BE contract when present, **fixture values + behavior** always from System BDD `Then` clauses:
+
+1. **Define the port shape** `{UC-ID}ApiPort` (request/response DTOs + error codes):
+   - `mock_source = contract` → field names / types / error codes taken **verbatim from the BE contract** §2 (API Endpoints) / §3 (Data Model) — the real shape.
+   - `mock_source = system-bdd` → shape **inferred** from System BDD `Then` clauses (provisional — see warning above).
+2. **Extract fixture data** per scenario from System BDD `Then` clauses — success + error responses (BDD is the source of truth for *values / behavior*, regardless of shape source).
+3. **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, in the port shape
+   - Include both success and error states (map to error scenarios in BDD)
+   - Traceability tags:
+     ```
+     @trace.mock_for={UC-ID}
+     @trace.mock_source={contract | system-bdd}
+     @trace.system_bdd={paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{UC-ID}*.feature
+     {@trace.be_contract={UC-ID}-tech-design.md   # only when mock_source=contract}
+     ```
+4. **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 to **deploy**.
+> Shape comes from the BE contract when available (accurate, no integration rework); else from System BDD (provisional — adjust at `--phase=integration`). Fixture *values* always come from System BDD — BDD is the source of truth for behavior.
+
+---
+
+## Integration Phase (`--phase=integration` only)
+
+*Skip this section entirely if `--phase` is not `integration`.*
+
+1. **Read the integration design.** Prefer the FE tech-design §4 (port→endpoint→DTO→error mapping) at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`, using the BE API contract `{UC-ID}-tech-design.md` as the endpoint / request-response / error-code source. If no FE tech-design exists, extract endpoints + shapes + error codes directly from the BE contract.
+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
+- [ ] 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}/{domain}/{prd-slug}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns. *(Umbrella + `spec_source`: `trace_dir` resolves to `{spec_source}/.trace` — this command runs from `service_root` but writes the trace row into the **spec repo** (cross-repo); commit/push the spec submodule for the trace update, alongside the 2-tier code push.)*
+
+| 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 the **BE** contract `{UC-ID}-tech-design.md`, or `—` if none |
+| `fe_tech_doc_revision` | `@trace.revision` from the **FE** tech-design `{UC-ID}-tech-design-{platform}.md` when generating FE with `--phase=integration` (the doc whose §4 drove this adapter); `—` for BE, or for FE `--phase=ui` / no FE tech-design |
+| `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`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`) unchanged.
+`status` is computed by `/validate-traces` — do not set here.
+
+## Refresh Panel Mirror
+{{include:steps/trace-mirror.md}}
+
+## Commit
+```bash
+git add {files}
+git commit -m "{commit_format}: {description}"
+```
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/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 | —}
+Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
+
+Next:
+  --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
+    → /dev-gen-test {UC-ID}  ← integration test suite
+
+  Default (no phase flag):
+    → /review-code {UC-ID}   ← code review required before tests
+    → /dev-gen-test {UC-ID}
+
+📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+```