@anhth2/spec-driven-dev-plugin 0.12.0 → 0.14.0

package/commands/generate-tech-docs.md

@@ -187,7 +187,7 @@ If `services` section is present:
 - 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.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -198,6 +198,7 @@ If `services` section is present:
 - 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.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -207,8 +208,9 @@ If `services` section is present:
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -228,12 +230,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `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) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **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).
 
@@ -410,10 +412,57 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## Step 0 — Detect Platform & Route Output
+
+Read `@trace.platform` from the feature file header (`web` | `app` | `system`). If absent, fall back to `platform_type` from context (`web-frontend`/`mobile` → FE; `backend` → BE).
+
+| Platform | `active_tech_design` | Output file |
+|----------|----------------------|-------------|
+| `system` / backend | **`be`** — the cross-team **API contract** (authoritative) | `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` |
+| `web` / `app` (web-frontend / mobile) | **`fe`** — the **client technical design** (consumes the BE contract) | `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md` |
+
+Store `active_tech_design` and `tech_design_path`. The `-{platform}` suffix (mirroring design-spec) keeps the FE doc from colliding with the BE contract — both live in the shared spec repo when `spec_source` is set.
+
+---
+
+## Step 0.5 — FE/App Precondition Gate
+
+*Skip this entire step for BE (`active_tech_design = be`).*
+
+An FE/App technical design is a **derived** artifact: its API-integration layer maps onto the locked BE contract, and its state/error model comes from the system behavior. Both upstream inputs MUST exist first — **HALT** if either is missing:
+
+1. **System BDD** — locate `{paths.specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
+   If not found → HALT:
+   ```
+   ❌ Cannot generate FE tech-design — System BDD not found for {TICKET-ID}.
+   The FE design needs the system-level (BE-facing) behavior first.
+   → PO/BE: /generate-bdd {prd-file}  (produces the `system/` platform BDD)
+   ```
+2. **BE tech-docs (API contract)** — locate the BE doc `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` and read its `@trace.status`.
+   - Not found → HALT:
+     ```
+     ❌ Cannot generate FE tech-design — BE API contract not found.
+     The FE integration layer maps to the BE contract; it must exist first.
+     → BE: /generate-tech-docs {system .feature} → /review-tech-docs (approve) → publish to spec repo
+     ```
+   - Found but `@trace.status` ≠ `approved` → WARN and ask:
+     ```
+     ⚠️  BE contract {UC-ID}-tech-design.md is status: {status} (not approved) — it may still change.
+     Designing the FE integration against a non-final contract risks rework.
+     Continue anyway? (Y/N)
+     ```
+     - Y → proceed (accept risk) · N → stop, wait for BE to approve.
+
+Store `system_bdd_path` and `be_contract_path` — they are the primary inputs for the FE §3/§4 below.
+
 ---
 
 ## Brownfield Check
 
+*BE (`active_tech_design = be`) only — for FE the "existing contract" is the BE doc loaded in Step 0.5.*
+
 Read the source `.feature` file header for `@trace.api_source`.
 Also check the source PRD Metadata table for `| **API Source** | existing |`.
 
@@ -430,10 +479,11 @@ If `active_mode = reverse-document` → load bảng "Existing API Contract" từ
 
 ## CHECKPOINT — Tech Design Plan
 
-Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display and wait for Y:
+Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display the plan for the resolved `active_tech_design` and wait for Y:
 
+**If `active_tech_design = be`:**
 ```
-Tech Design Plan — {UC-ID}
+Tech Design Plan — {UC-ID}  (BE · API contract)
 ──────────────────────────────────────────────────────
 UC       : {UC-ID} — {feature title}
 Service  : {trace.service}
@@ -457,12 +507,42 @@ Sections to generate:
 Proceed? (Y/N)
 ```
 
+**If `active_tech_design = fe`:**
+```
+Tech Design Plan — {UC-ID}  (FE · {platform} · client design)
+──────────────────────────────────────────────────────
+UC        : {UC-ID} — {feature title}
+Service   : {trace.service}    Module: {trace.module} ({platform})
+Inputs    : System BDD  → {system_bdd_path}
+            BE contract → {be_contract_path}  (status: {be status})
+Scenarios : {N} FE scenarios   |   BDD ver: {trace.bdd_version}
+Output    : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md
+
+Sections to generate:
+  §1 Overview            (FE scope of this UC)
+  §2 Component Architecture  (tree + reuse from figma-components catalog)
+  §2b Test Selectors     (stable test-id cho element có action — QC contract, attr theo platform)
+  §3 State Management    (store/slices/state shape ← System BDD Then-clauses)
+  §4 API Integration Layer   (port/adapter: each BE endpoint → FE service → DTO/model)
+  §5 Routing / Navigation
+  §6 Data Fetching & Client Caching  (query keys, invalidation, optimistic updates)
+  §7 Error & Loading States  (per scenario)
+  §8 Cross-Cutting       (auth token, i18n, feature flags)
+  {§9 Offline / platform specifics — app only}
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
 Wait for explicit "Y" before generating.
 
 ---
 
 ## Generate
 
+Generate the document for the resolved `active_tech_design`.
+
+### Path A — BE API contract  (`active_tech_design = be`)
+
 Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 
 ```markdown
@@ -533,17 +613,111 @@ External calls, events produced/consumed.
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
-## Publish — share the contract (umbrella + shared spec repo)
+### Path B — FE/App client technical design  (`active_tech_design = fe`)
+
+Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md`. The §4 integration layer maps **directly onto the BE contract** loaded in Step 0.5 — every FE service method must trace to a real endpoint in `{be_contract_path}` (no invented endpoints). State and error models in §3/§7 derive from the **System BDD** `Then` clauses.
+
+```markdown
+# FE Technical Design — {UC-ID} ({platform}): {Feature}
+
+---
+@trace.id: {UC-ID}
+@trace.domain: {domain}
+@trace.platform: {web | app}
+@trace.service: {read @trace.service from the .feature file header}
+@trace.module: {read @trace.module — e.g. react / nextjs / vue / angular / flutter}
+@trace.prd: {TICKET-ID}
+@trace.bdd_version: {read @trace.bdd_version from the FE .feature header}
+@trace.system_bdd: {system_bdd_path}
+@trace.be_contract: {UC-ID}-tech-design.md   # the BE API contract this design consumes
+@trace.testid_attr: {data-testid (web) | testID (react-native) | Key/Semantics (flutter) | accessibilityIdentifier (native-ios)}
+@trace.revision: 1
+@trace.status: draft
+@trace.generated_at: {YYYY-MM-DD}
+---
+
+## §1. Overview
+
+{FE scope của UC: màn hình/luồng nào, render gì, tích hợp API nào. Nêu rõ design này map theo BE contract {UC-ID}-tech-design.md.}
+
+## §2. Component Architecture
+
+Component tree (container vs presentational). Ưu tiên tái dùng từ figma-components catalog (Step 6-B context); chỉ tạo mới khi không có sẵn.
+
+| Component | Type | Reuse (catalog) / New | Responsibility |
+|-----------|------|-----------------------|----------------|
+| {Name} | container/presentational | {catalog name \| NEW} | {what it renders / handles} |
+
+## §2b. Test Selectors — Element IDs cho element CÓ ACTION (QC contract)
+
+Mỗi element tương tác (button, input, link, select, toggle, form-submit…) được gán **test-id ổn định** để QC locate **trực tiếp** — không scan/giả lập runtime. Đây là contract giữa FE code (emit id) và QC Page Object (đọc id).
+
+- **Quy ước (semantic-stable):** `{uc-lower}-{screen}-{element}-{type}` — vd `ft001-login-submit-btn`, `ft001-login-email-input`. **KHÔNG** nhúng số scenario (đổi khi renumber).
+- **Attribute theo platform** (`@trace.testid_attr`): web `data-testid` · React Native `testID` · Flutter `Key('id')` + `Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
+- **Cross-platform (web ↔ app):** cùng một element logic dùng **CÙNG test-id value** trên cả web và app — chỉ *attribute* khác theo platform. Mỗi platform có file tech-design riêng (`-web.md` / `-app.md`) với §2b riêng, nhưng id value phải khớp để QC tái dùng logic test và 2 doc không lệch. Khi gen platform thứ hai, **đọc §2b của file platform kia** và tái dùng id đã có; chỉ thêm id cho element mà platform này có riêng.
+- Chỉ gán cho element **có action**; element tĩnh (label, text thuần) không cần.
+
+| Test-ID | Element | Component (§2) | Action | Serves SC |
+|---------|---------|----------------|--------|-----------|
+| `{uc}-{screen}-{element}-{type}` | {Submit button} | {LoginForm} | {submit login} | SC1, SC3 |
+
+> QC: Page Object locator lấy test-id từ bảng này (ưu tiên `data-testid`/attribute tương ứng). Element có action mà **chưa** có test-id ở đây → QC fallback role/text (chậm hơn) và nên bổ sung vào bảng này.
+>
+> **Element từ component reuse / code có sẵn (brownfield):** id sống ở **usage site**, component dùng chung phải *forward* được test-id. Đừng tự bịa ở đây — chạy `/map-testids {UC-ID}` để reverse-document id đang có, gán id còn thiếu, patch forwarding + ghi catalog, rồi điền §2b này. Lệnh này chỉ tự gán id cho component **mới**.
+
+## §3. State Management
+
+State shape suy ra từ System BDD `Then` clauses + response shapes trong BE contract. Nêu store/slices, server-state vs UI-state.
+
+| Slice / Key | Shape | Nguồn (BE field / local) | Updated by |
+|-------------|-------|--------------------------|------------|
+
+## §4. API Integration Layer (port/adapter)
+
+**Mỗi method phải map tới một endpoint CÓ THẬT trong BE contract `{UC-ID}-tech-design.md`.** Đây là hợp đồng thay thế mock adapter của `/generate-code --phase=ui`.
+
+| FE service method | BE endpoint (từ contract) | Request map | Response → model | Error → UI |
+|-------------------|---------------------------|-------------|------------------|-----------|
+| {svc.getX()} | {GET /api/v1/...} | {params} | {DTO → ViewModel} | {4xx/5xx → state/toast} |
+
+## §5. Routing / Navigation
+
+Routes / màn hình, params, guards (auth/role), lazy-load.
+
+## §6. Data Fetching & Client Caching
+
+Query keys, cache invalidation triggers, optimistic updates, refetch policy (client-side — KHÔNG phải server cache).
+
+## §7. Error & Loading States
+
+| Scenario (BDD) | Loading UI | Error UI | Empty state |
+|----------------|-----------|----------|-------------|
+
+## §8. Cross-Cutting
+
+Auth token injection/refresh, i18n keys, feature flags, analytics events.
+
+{## §9. Offline / Platform Specifics   — app only}
+{Cached-data behavior, offline banner, background sync, platform permissions.}
+
+## Changelog
+
+| Revision | Date | Changes |
+|----------|------|---------|
+| 1 | {YYYY-MM-DD} | Initial FE design from {UC-ID} ({platform}) BDD v{bdd_version}, mapping BE contract {UC-ID}-tech-design.md |
+```
+
+## Publish — share the doc (umbrella + shared spec repo)
 
-If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the tech-doc was just written **inside the spec submodule**. It is the cross-team **API contract** — FE/App read it via their own `/sync`. Publish it so they can (2-layer commit):
+If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the doc was just written **inside the spec submodule**. Publish it (2-layer commit) so the rest of the team reads it via `/sync` — the BE doc is the cross-team **API contract**; the FE doc is the **client design** other FE/App devs (and reviewers) consume:
 
 ```bash
 cd {spec_source}
-git add specs/tech-docs/{domain}/{UC-ID}-tech-design.md
-git commit -m "docs({UC-ID}): tech design / API contract"
-git push origin {spec_branch}          # the branch FE/App track in .gitmodules
+git add {tech_design_path}              # be: {UC-ID}-tech-design.md · fe: {UC-ID}-tech-design-{platform}.md
+git commit -m "docs({UC-ID}): {be: tech design / API contract | fe: FE tech design ({platform})}"
+git push origin {spec_branch}          # the branch teammates track in .gitmodules
 cd -
-git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} tech design)"
+git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} {be|fe} tech design)"
 ```
 
 If `tech_docs_dir` is **local** — i.e. no `setup.spec_source` (single-repo, or a pure multi-service BE repo with no shared spec module) — skip this; no cross-repo publish needed. Whenever `spec_source` is set, tech-docs route to the spec submodule and this publish step applies.
@@ -572,6 +746,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
 
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -613,17 +817,22 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
 
 ```
-/generate-tech-docs Complete — {UC-ID}
-File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
-Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+/generate-tech-docs Complete — {UC-ID}  ({active_tech_design: BE API contract | FE {platform} client design})
+File: {tech_design_path}
+Next: /review-tech-docs {tech_design_path}
       ← SA/Lead review required before code generation
-      → if tech-docs live in the shared spec repo: commit + push to the spec submodule (see Publish above) so FE/App `/sync` can read the contract
-      → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
+      → if it lives in the shared spec repo: commit + push to the spec submodule (see Publish above) so teammates `/sync` can read it
+      → after approved:
+          BE → /generate-code {system .feature}
+          FE → /generate-code {web|app .feature} --phase=integration   (wires real API per §4 of this doc)
 ```

package/commands/generate-tech-docs.tmpl

@@ -31,8 +31,55 @@
 
 ---
 
+## Step 0 — Detect Platform & Route Output
+
+Read `@trace.platform` from the feature file header (`web` | `app` | `system`). If absent, fall back to `platform_type` from context (`web-frontend`/`mobile` → FE; `backend` → BE).
+
+| Platform | `active_tech_design` | Output file |
+|----------|----------------------|-------------|
+| `system` / backend | **`be`** — the cross-team **API contract** (authoritative) | `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` |
+| `web` / `app` (web-frontend / mobile) | **`fe`** — the **client technical design** (consumes the BE contract) | `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md` |
+
+Store `active_tech_design` and `tech_design_path`. The `-{platform}` suffix (mirroring design-spec) keeps the FE doc from colliding with the BE contract — both live in the shared spec repo when `spec_source` is set.
+
+---
+
+## Step 0.5 — FE/App Precondition Gate
+
+*Skip this entire step for BE (`active_tech_design = be`).*
+
+An FE/App technical design is a **derived** artifact: its API-integration layer maps onto the locked BE contract, and its state/error model comes from the system behavior. Both upstream inputs MUST exist first — **HALT** if either is missing:
+
+1. **System BDD** — locate `{paths.specs_dir}/{domain}/system/{TICKET-ID}*.feature`.
+   If not found → HALT:
+   ```
+   ❌ Cannot generate FE tech-design — System BDD not found for {TICKET-ID}.
+   The FE design needs the system-level (BE-facing) behavior first.
+   → PO/BE: /generate-bdd {prd-file}  (produces the `system/` platform BDD)
+   ```
+2. **BE tech-docs (API contract)** — locate the BE doc `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md` and read its `@trace.status`.
+   - Not found → HALT:
+     ```
+     ❌ Cannot generate FE tech-design — BE API contract not found.
+     The FE integration layer maps to the BE contract; it must exist first.
+     → BE: /generate-tech-docs {system .feature} → /review-tech-docs (approve) → publish to spec repo
+     ```
+   - Found but `@trace.status` ≠ `approved` → WARN and ask:
+     ```
+     ⚠️  BE contract {UC-ID}-tech-design.md is status: {status} (not approved) — it may still change.
+     Designing the FE integration against a non-final contract risks rework.
+     Continue anyway? (Y/N)
+     ```
+     - Y → proceed (accept risk) · N → stop, wait for BE to approve.
+
+Store `system_bdd_path` and `be_contract_path` — they are the primary inputs for the FE §3/§4 below.
+
+---
+
 ## Brownfield Check
 
+*BE (`active_tech_design = be`) only — for FE the "existing contract" is the BE doc loaded in Step 0.5.*
+
 Read the source `.feature` file header for `@trace.api_source`.
 Also check the source PRD Metadata table for `| **API Source** | existing |`.
 
@@ -49,10 +96,11 @@ If `active_mode = reverse-document` → load bảng "Existing API Contract" từ
 
 ## CHECKPOINT — Tech Design Plan
 
-Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display and wait for Y:
+Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display the plan for the resolved `active_tech_design` and wait for Y:
 
+**If `active_tech_design = be`:**
 ```
-Tech Design Plan — {UC-ID}
+Tech Design Plan — {UC-ID}  (BE · API contract)
 ──────────────────────────────────────────────────────
 UC       : {UC-ID} — {feature title}
 Service  : {trace.service}
@@ -76,12 +124,42 @@ Sections to generate:
 Proceed? (Y/N)
 ```
 
+**If `active_tech_design = fe`:**
+```
+Tech Design Plan — {UC-ID}  (FE · {platform} · client design)
+──────────────────────────────────────────────────────
+UC        : {UC-ID} — {feature title}
+Service   : {trace.service}    Module: {trace.module} ({platform})
+Inputs    : System BDD  → {system_bdd_path}
+            BE contract → {be_contract_path}  (status: {be status})
+Scenarios : {N} FE scenarios   |   BDD ver: {trace.bdd_version}
+Output    : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md
+
+Sections to generate:
+  §1 Overview            (FE scope of this UC)
+  §2 Component Architecture  (tree + reuse from figma-components catalog)
+  §2b Test Selectors     (stable test-id cho element có action — QC contract, attr theo platform)
+  §3 State Management    (store/slices/state shape ← System BDD Then-clauses)
+  §4 API Integration Layer   (port/adapter: each BE endpoint → FE service → DTO/model)
+  §5 Routing / Navigation
+  §6 Data Fetching & Client Caching  (query keys, invalidation, optimistic updates)
+  §7 Error & Loading States  (per scenario)
+  §8 Cross-Cutting       (auth token, i18n, feature flags)
+  {§9 Offline / platform specifics — app only}
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
 Wait for explicit "Y" before generating.
 
 ---
 
 ## Generate
 
+Generate the document for the resolved `active_tech_design`.
+
+### Path A — BE API contract  (`active_tech_design = be`)
+
 Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 
 ```markdown
@@ -152,17 +230,111 @@ External calls, events produced/consumed.
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
-## Publish — share the contract (umbrella + shared spec repo)
+### Path B — FE/App client technical design  (`active_tech_design = fe`)
+
+Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design-{platform}.md`. The §4 integration layer maps **directly onto the BE contract** loaded in Step 0.5 — every FE service method must trace to a real endpoint in `{be_contract_path}` (no invented endpoints). State and error models in §3/§7 derive from the **System BDD** `Then` clauses.
+
+```markdown
+# FE Technical Design — {UC-ID} ({platform}): {Feature}
+
+---
+@trace.id: {UC-ID}
+@trace.domain: {domain}
+@trace.platform: {web | app}
+@trace.service: {read @trace.service from the .feature file header}
+@trace.module: {read @trace.module — e.g. react / nextjs / vue / angular / flutter}
+@trace.prd: {TICKET-ID}
+@trace.bdd_version: {read @trace.bdd_version from the FE .feature header}
+@trace.system_bdd: {system_bdd_path}
+@trace.be_contract: {UC-ID}-tech-design.md   # the BE API contract this design consumes
+@trace.testid_attr: {data-testid (web) | testID (react-native) | Key/Semantics (flutter) | accessibilityIdentifier (native-ios)}
+@trace.revision: 1
+@trace.status: draft
+@trace.generated_at: {YYYY-MM-DD}
+---
+
+## §1. Overview
+
+{FE scope của UC: màn hình/luồng nào, render gì, tích hợp API nào. Nêu rõ design này map theo BE contract {UC-ID}-tech-design.md.}
+
+## §2. Component Architecture
+
+Component tree (container vs presentational). Ưu tiên tái dùng từ figma-components catalog (Step 6-B context); chỉ tạo mới khi không có sẵn.
+
+| Component | Type | Reuse (catalog) / New | Responsibility |
+|-----------|------|-----------------------|----------------|
+| {Name} | container/presentational | {catalog name \| NEW} | {what it renders / handles} |
+
+## §2b. Test Selectors — Element IDs cho element CÓ ACTION (QC contract)
+
+Mỗi element tương tác (button, input, link, select, toggle, form-submit…) được gán **test-id ổn định** để QC locate **trực tiếp** — không scan/giả lập runtime. Đây là contract giữa FE code (emit id) và QC Page Object (đọc id).
+
+- **Quy ước (semantic-stable):** `{uc-lower}-{screen}-{element}-{type}` — vd `ft001-login-submit-btn`, `ft001-login-email-input`. **KHÔNG** nhúng số scenario (đổi khi renumber).
+- **Attribute theo platform** (`@trace.testid_attr`): web `data-testid` · React Native `testID` · Flutter `Key('id')` + `Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
+- **Cross-platform (web ↔ app):** cùng một element logic dùng **CÙNG test-id value** trên cả web và app — chỉ *attribute* khác theo platform. Mỗi platform có file tech-design riêng (`-web.md` / `-app.md`) với §2b riêng, nhưng id value phải khớp để QC tái dùng logic test và 2 doc không lệch. Khi gen platform thứ hai, **đọc §2b của file platform kia** và tái dùng id đã có; chỉ thêm id cho element mà platform này có riêng.
+- Chỉ gán cho element **có action**; element tĩnh (label, text thuần) không cần.
+
+| Test-ID | Element | Component (§2) | Action | Serves SC |
+|---------|---------|----------------|--------|-----------|
+| `{uc}-{screen}-{element}-{type}` | {Submit button} | {LoginForm} | {submit login} | SC1, SC3 |
+
+> QC: Page Object locator lấy test-id từ bảng này (ưu tiên `data-testid`/attribute tương ứng). Element có action mà **chưa** có test-id ở đây → QC fallback role/text (chậm hơn) và nên bổ sung vào bảng này.
+>
+> **Element từ component reuse / code có sẵn (brownfield):** id sống ở **usage site**, component dùng chung phải *forward* được test-id. Đừng tự bịa ở đây — chạy `/map-testids {UC-ID}` để reverse-document id đang có, gán id còn thiếu, patch forwarding + ghi catalog, rồi điền §2b này. Lệnh này chỉ tự gán id cho component **mới**.
+
+## §3. State Management
+
+State shape suy ra từ System BDD `Then` clauses + response shapes trong BE contract. Nêu store/slices, server-state vs UI-state.
+
+| Slice / Key | Shape | Nguồn (BE field / local) | Updated by |
+|-------------|-------|--------------------------|------------|
+
+## §4. API Integration Layer (port/adapter)
+
+**Mỗi method phải map tới một endpoint CÓ THẬT trong BE contract `{UC-ID}-tech-design.md`.** Đây là hợp đồng thay thế mock adapter của `/generate-code --phase=ui`.
+
+| FE service method | BE endpoint (từ contract) | Request map | Response → model | Error → UI |
+|-------------------|---------------------------|-------------|------------------|-----------|
+| {svc.getX()} | {GET /api/v1/...} | {params} | {DTO → ViewModel} | {4xx/5xx → state/toast} |
+
+## §5. Routing / Navigation
+
+Routes / màn hình, params, guards (auth/role), lazy-load.
+
+## §6. Data Fetching & Client Caching
+
+Query keys, cache invalidation triggers, optimistic updates, refetch policy (client-side — KHÔNG phải server cache).
+
+## §7. Error & Loading States
+
+| Scenario (BDD) | Loading UI | Error UI | Empty state |
+|----------------|-----------|----------|-------------|
+
+## §8. Cross-Cutting
+
+Auth token injection/refresh, i18n keys, feature flags, analytics events.
+
+{## §9. Offline / Platform Specifics   — app only}
+{Cached-data behavior, offline banner, background sync, platform permissions.}
+
+## Changelog
+
+| Revision | Date | Changes |
+|----------|------|---------|
+| 1 | {YYYY-MM-DD} | Initial FE design from {UC-ID} ({platform}) BDD v{bdd_version}, mapping BE contract {UC-ID}-tech-design.md |
+```
+
+## Publish — share the doc (umbrella + shared spec repo)
 
-If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the tech-doc was just written **inside the spec submodule**. It is the cross-team **API contract** — FE/App read it via their own `/sync`. Publish it so they can (2-layer commit):
+If `paths.tech_docs_dir` resolved **under `setup.spec_source`** (e.g. `{spec_source}/specs/tech-docs`), the doc was just written **inside the spec submodule**. Publish it (2-layer commit) so the rest of the team reads it via `/sync` — the BE doc is the cross-team **API contract**; the FE doc is the **client design** other FE/App devs (and reviewers) consume:
 
 ```bash
 cd {spec_source}
-git add specs/tech-docs/{domain}/{UC-ID}-tech-design.md
-git commit -m "docs({UC-ID}): tech design / API contract"
-git push origin {spec_branch}          # the branch FE/App track in .gitmodules
+git add {tech_design_path}              # be: {UC-ID}-tech-design.md · fe: {UC-ID}-tech-design-{platform}.md
+git commit -m "docs({UC-ID}): {be: tech design / API contract | fe: FE tech design ({platform})}"
+git push origin {spec_branch}          # the branch teammates track in .gitmodules
 cd -
-git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} tech design)"
+git add {spec_source} && git commit -m "chore: bump spec pointer ({UC-ID} {be|fe} tech design)"
 ```
 
 If `tech_docs_dir` is **local** — i.e. no `setup.spec_source` (single-repo, or a pure multi-service BE repo with no shared spec module) — skip this; no cross-repo publish needed. Whenever `spec_source` is set, tech-docs route to the spec submodule and this publish step applies.
@@ -172,10 +344,12 @@ If `tech_docs_dir` is **local** — i.e. no `setup.spec_source` (single-repo, or
 {{include:steps/report-footer.md}}
 
 ```
-/generate-tech-docs Complete — {UC-ID}
-File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
-Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+/generate-tech-docs Complete — {UC-ID}  ({active_tech_design: BE API contract | FE {platform} client design})
+File: {tech_design_path}
+Next: /review-tech-docs {tech_design_path}
       ← SA/Lead review required before code generation
-      → if tech-docs live in the shared spec repo: commit + push to the spec submodule (see Publish above) so FE/App `/sync` can read the contract
-      → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
+      → if it lives in the shared spec repo: commit + push to the spec submodule (see Publish above) so teammates `/sync` can read it
+      → after approved:
+          BE → /generate-code {system .feature}
+          FE → /generate-code {web|app .feature} --phase=integration   (wires real API per §4 of this doc)
 ```