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

package/commands/generate-design-spec.tmpl

@@ -0,0 +1,399 @@
+# /generate-design-spec — Generate Design Specification (FE / App)
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target file is a Business PRD in `{paths.prd_dir}/`. Resolve from `$ARGUMENTS` or list the directory and ask. Only FE and mobile PRDs are supported — BE PRDs will be rejected at the Platform Check step.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+*Additional context for this command: Read the full target PRD. Extract: **TICKET-ID**, **domain**, **feature name**, **Service** and **Module** from PRD metadata (rows `| **Service** |` and `| **Module** |`), User Flow (Section 4a), and Wireframe screen names (Section 4b).*
+
+*Service extraction rules (same as /generate-prd):*
+- *If PRD metadata has `| **Service** |` → use as `active_service` and `| **Module** |` as `active_module`.*
+- *If absent AND `services` defined in `project-context.yaml` → ask: "Which service is this Design Spec for?" (list FE/App services only, wait for selection).*
+- *If single-service project → `active_service = "default"`, `active_module = tech_stack.module`.*
+
+---
+
+## Platform Check
+
+Using `active_module` and `platform_type` derived from context loading:
+
+1. If `platform_type = "backend"` → **STOP**. Output:
+   ```
+   ❌ Design Spec is only for FE and mobile platforms.
+   For BE services, API contracts belong in the Business PRD (Use Case → Business Logic section).
+   ```
+
+2. If `platform_type = "web-frontend"` → set `active_platform = "web"`.
+
+3. If `platform_type = "mobile"`:
+   - `flutter` or `react-native` → set `active_platform = "app"`
+   - `ios-swiftui` → set `active_platform = "app-ios"`
+   - `android-compose` → set `active_platform = "app-android"`
+
+4. If `platform_type = "unknown"` → ask: "Which platform is this Design Spec for?"
+   ```
+   Options:
+     1 — web    (React / Next.js / Vue / Angular)
+     2 — app    (Flutter / React Native)
+     3 — app-ios     (iOS SwiftUI)
+     4 — app-android (Android Compose)
+   ```
+   Wait for selection. Map choice to `active_platform` and infer `active_module` if possible.
+
+---
+
+## Figma Check
+
+Ask:
+
+```
+Do you have a Figma link for this feature? (paste URL or press Enter to skip)
+```
+
+- If URL provided → store as `figma_url`.
+- If skipped → `figma_url = "TBD"`. Add AI Assumption: "Figma link not provided — all screen descriptions are text-based. Link must be added and verified before Design Spec sign-off."
+
+---
+
+## Screen Discovery
+
+From the PRD's Section 4 (User Flow + Wireframe), extract all screen / page / modal names mentioned.
+
+Present the list and ask PO to confirm:
+
+```
+Screens detected from PRD:
+  1. {Screen name 1}
+  2. {Screen name 2}
+  ...
+
+Are these all the screens for the {active_platform} platform?
+Add any missing, remove any that don't apply, or confirm with Y.
+```
+
+Wait for confirmation. Store the confirmed list as `screen_list`.
+
+---
+
+## CHECKPOINT
+
+```
+CHECKPOINT — Design Spec
+-------------------------
+Target PRD  : {prd-file-path}
+Platform    : {active_platform}
+Module      : {active_module}
+Service     : {active_service}
+Domain      : {domain}
+Screens     : {N} — {comma-separated screen_list}
+Figma       : {figma_url}
+Output path : {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md
+
+Generate? (Y/N)
+```
+
+Wait for explicit Y before proceeding.
+
+---
+
+## Generation Rules
+
+Apply these rules consistently when generating all sections:
+
+**Component mapping (C.M — mandatory):**
+- For each component referenced, check `figma-components/{active_module}.md` (loaded in context).
+- ✅ Matched → use the exact `Code Component` and `Import Path` from the catalog.
+- ⚠️ Matched but `[TODO]` → mark the component cell as `[TODO — implementation pending]`.
+- ❌ Not in catalog → mark as `[NEW — confirm with designer before generating code]`.
+- Never invent component names or import paths.
+
+**Platform-adaptive sections:**
+- Section 3 (Interaction Patterns) and Section 4 (Platform Considerations) adapt to `active_platform`:
+  - `web` → include responsive breakpoints, hover/focus states, keyboard navigation, accessibility.
+  - `app` / `app-ios` / `app-android` → include gestures, safe area, minimum touch targets, navigation pattern, deep links, permissions, offline behavior.
+  - Only generate the section relevant to `active_platform`. Omit the other platform's section entirely.
+
+**Screen states (mandatory per screen):**
+- Every screen must document at minimum: `default`, `loading`, `error`.
+- Add `empty` when the screen can display zero-data state.
+- Add `success` when a completed action produces a distinct confirmation state.
+- If a state does not apply → mark `N/A` with a short reason.
+
+---
+
+## Generate
+
+Write `{paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`:
+
+````markdown
+# {TICKET-ID} {Feature Name} — Design Spec [{active_platform}]
+
+---
+
+## Metadata
+
+| Field              | Value                                                         |
+|--------------------|---------------------------------------------------------------|
+| **Spec ID**        | {TICKET-ID}-DS-{active_platform}                              |
+| **Version**        | 1.0                                                           |
+| **Status**         | draft                                                         |
+| **Platform**       | {active_platform}                                             |
+| **Module**         | {active_module}                                               |
+| **Service**        | {active_service}                                              |
+| **Domain**         | {domain}                                                      |
+| **Business PRD**   | [{TICKET-ID}]({relative-path-to-prd.md})                      |
+| **Figma**          | {figma_url}                                                   |
+| **Author**         | {PO name or "AI-assisted"}                                    |
+| **Created**        | {YYYY-MM-DD}                                                  |
+| **Updated**        | {YYYY-MM-DD}                                                  |
+
+---
+
+# 1. Screen Inventory
+
+| # | Screen Name | Entry Point | Figma Frame | Notes |
+|---|-------------|-------------|-------------|-------|
+| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_url}#screen1) | |
+| 2 | {Screen 2}  | {entry point} | [Frame]({figma_url}#screen2) | |
+
+---
+
+# 2. Screen Specs
+
+<!--
+  Repeat this block for every screen in the Screen Inventory.
+  Each screen must have: Layout, Component Inventory, Screen States, Actions & Navigation.
+-->
+
+## Screen 1: {Screen Name}
+
+**Figma**: [{Frame name}]({figma_frame_url})
+
+### Layout
+
+{Describe the layout: grid columns, max-width container, section order, padding, key spacing values.
+ Reference design tokens where applicable (e.g., `spacing.md = 16px`, `color.surface`).}
+
+### Component Inventory
+
+| Component (Figma)   | Code Component  | Import Path            | States                          | Notes              |
+|---------------------|-----------------|------------------------|---------------------------------|--------------------|
+| {Figma/Button/Primary} | Button       | @/components/ui/Button | default, loading, disabled      |                    |
+| {Figma/Input/Text}  | TextInput       | @/components/ui/Input  | default, focus, error, disabled |                    |
+| {Figma/Card/Order}  | OrderCard       | @/features/{domain}/components/OrderCard | default, skeleton |           |
+
+### Screen States
+
+| State     | Trigger                             | UI Behavior                                                  |
+|-----------|-------------------------------------|--------------------------------------------------------------|
+| default   | Screen loaded, data available       | {Describe full rendered appearance}                          |
+| loading   | API call in flight                  | {Skeleton layout / spinner position — reference component}   |
+| error     | API failure or validation error     | {Toast / inline message / error screen — exact copy TBD}     |
+| empty     | API returns empty list / no data    | {Empty state illustration + CTA text — e.g., "No orders yet. Start shopping →"} |
+| success   | Action completed (if applicable)    | {Confirmation message / navigation / state change}           |
+
+### Actions & Navigation
+
+| Action          | Trigger                        | Result                                          |
+|-----------------|--------------------------------|-------------------------------------------------|
+| {Action name}   | Tap/click {element name}       | Navigate to {Screen N} / Open {Modal name}      |
+| {Action name}   | Swipe left on {list item}      | Show delete confirmation                        |
+| {Back / Cancel} | Back gesture / Cancel button   | Return to {previous screen} without saving      |
+
+---
+
+<!--  Repeat ## Screen N block for each additional screen  -->
+
+---
+
+# 3. Interaction Patterns
+
+<!--
+  Web platform: include sections A + B. Remove section C.
+  App platform: include section C. Remove sections A + B.
+-->
+
+<!-- ═══════════════════════════ WEB ONLY ═══════════════════════════ -->
+
+## A. Responsive Behavior  *(web only)*
+
+| Breakpoint | Width      | Layout Changes                                     |
+|------------|------------|----------------------------------------------------|
+| Mobile     | < 768px    | {Single column, bottom navigation bar, CTA full-width} |
+| Tablet     | 768–1279px | {2-column grid, sidebar collapsed, tab navigation} |
+| Desktop    | ≥ 1280px   | {Full layout, sidebar visible, max-width 1440px}   |
+
+## B. Hover / Focus / Keyboard  *(web only)*
+
+| Element        | Hover state                   | Focus state                     | Keyboard shortcut |
+|----------------|-------------------------------|---------------------------------|-------------------|
+| Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space     |
+| Text input     | Border → {color.border.hover} | Border → {color.primary}, label floats | Tab to focus |
+| Dropdown       | Background highlight          | Same as hover + ring            | Arrow keys to navigate |
+
+<!-- ═══════════════════════════ APP ONLY ═══════════════════════════ -->
+
+## C. Gestures & Navigation  *(app only)*
+
+| Gesture           | Screen / Element          | Behavior                                              |
+|-------------------|---------------------------|-------------------------------------------------------|
+| Back gesture (iOS swipe-right / Android back) | All screens | {Return to previous screen / Show "Discard changes?" dialog} |
+| Pull-to-refresh   | {Screen names}            | Refresh data, spinner at top                          |
+| Swipe left on row | {List item name}          | Reveal {Delete / Archive} action                      |
+| Long press        | {Element name}            | {Context menu / selection mode}                       |
+| Pinch / zoom      | {Image viewer}            | Scale image, double-tap to reset                      |
+
+### Navigation Pattern  *(app only)*
+
+```
+{Draw the navigation stack for this feature, e.g.:
+  BottomTab(Home) → FeatureListPage → FeatureDetailPage → EditPage
+  BottomTab(Home) → FeatureListPage ↘ (modal) CreatePage
+}
+```
+
+Entry: {how the user enters this feature — tab / deeplink / push from another screen}
+Exit: {how the user leaves — back stack / tab switch / deeplink out}
+
+### Platform Conventions  *(app only)*
+
+| Aspect                   | iOS behavior                            | Android behavior                        |
+|--------------------------|-----------------------------------------|-----------------------------------------|
+| Navigation bar           | {Back button top-left, title centered}  | {Up arrow top-left, title left-aligned} |
+| Sheet / bottom modal     | {UISheetPresentation, grabber visible}  | {BottomSheet, drag handle}              |
+| Alert / confirm dialog   | {UIAlertController, actions right-aligned} | {Material AlertDialog, actions left-aligned} |
+| Loading indicator        | {UIActivityIndicatorView, center}       | {CircularProgressIndicator}             |
+| Toast / snackbar         | {Custom toast, bottom center}           | {Material Snackbar, bottom}             |
+
+---
+
+# 4. Platform Considerations
+
+<!--
+  Web: include section A. App: include section B. Remove the non-applicable section.
+-->
+
+<!-- ═══════════════════════════ WEB ONLY ═══════════════════════════ -->
+
+## A. Accessibility  *(web only)*
+
+- [ ] All interactive elements reachable via Tab key — no keyboard traps
+- [ ] Focus trap inside modal dialogs (Tab cycles within modal only)
+- [ ] Icon-only buttons have `aria-label` describing the action
+- [ ] Dynamic content updates (loading → loaded) announce via `aria-live`
+- [ ] Color contrast meets WCAG AA: text ≥ 4.5:1, large text ≥ 3:1
+- [ ] Form inputs have visible labels (not placeholder-only)
+- [ ] Error messages linked to inputs via `aria-describedby`
+
+<!-- ═══════════════════════════ APP ONLY ═══════════════════════════ -->
+
+## B. Device & OS  *(app only)*
+
+- [ ] Safe area insets applied on all screens — top (status bar) and bottom (home indicator)
+- [ ] Minimum touch target: 44×44pt (iOS) / 48×48dp (Android)
+- [ ] Tested on small screen: 375pt wide (iPhone SE) / 360dp wide (common Android)
+- [ ] Deep link entry: `{scheme}://{host}/{path}` → lands on {screen name} with {param} pre-filled
+- [ ] Permission gates: {list permissions needed — Camera / Location / Notification}
+  - {Permission}: requested on {screen name} with rationale copy: "{copy TBD}"
+- [ ] Offline / no-network behavior:
+  - {Screen name}: show cached data + offline banner
+  - {Action name}: disable button, show tooltip "Requires connection"
+- [ ] Dark mode: all screens tested in dark mode — no hardcoded colors
+
+---
+
+# 5. AC-UI — Design Acceptance Criteria
+
+> Reviewed and signed off by **PO + Designer** together before BDD generation.
+> These complement (not replace) the business-level AC in the [Business PRD]({prd-path}).
+
+| ID     | Acceptance Criterion                                                           | Verified by     |
+|--------|--------------------------------------------------------------------------------|-----------------|
+| AC-UI1 | All screens match approved Figma frames within design-system tolerances        | Designer        |
+| AC-UI2 | Loading skeleton/spinner appears within 200ms of initiating any API call       | QA              |
+| AC-UI3 | All error messages are visible, descriptive, and include a recovery action     | PO              |
+| AC-UI4 | Empty states include an illustration and a clear call-to-action                | PO + Designer   |
+| AC-UI5 | {Platform-specific — e.g., web: "All screens pass WCAG AA contrast check"}    | QA              |
+| AC-UI6 | {Platform-specific — e.g., app: "Back gesture on all screens returns to correct previous screen"} | QA |
+| AC-UI7 | {Feature-specific UI criterion from Business PRD wireframe section}             | PO              |
+
+---
+
+# Appendix
+
+## Figma Summary
+
+| Screen          | Figma Frame                   | Designer Status        |
+|-----------------|-------------------------------|------------------------|
+| {Screen 1}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
+| {Screen 2}      | [Link]({figma_frame_url})     | ✅ Ready / ⏳ WIP / ❌ Missing |
+
+## Design Tokens Referenced
+
+| Token                 | Value         | Used in                         |
+|-----------------------|---------------|---------------------------------|
+| `color.primary`       | {#hex}        | Primary buttons, links, active states |
+| `color.surface`       | {#hex}        | Card backgrounds                |
+| `spacing.md`          | {16px / 4}    | Standard vertical gap           |
+| `typography.heading2` | {font/size}   | Screen titles                   |
+
+## References
+
+- [{TICKET-ID}]({prd-path}) — Business PRD (source of AC, UC, BR)
+- {[Other Design Spec](./other-ds.md) — if this feature shares screens}
+
+## AI Assumptions
+
+> Each assumption below was made because PO input was incomplete.
+> PO must review and confirm before sign-off.
+
+- {Assumption 1 — [AI DRAFT]}
+
+---
+
+## Changelog
+
+| Version | Date         | Changes         |
+|---------|--------------|-----------------|
+| 1.0     | {YYYY-MM-DD} | Initial version |
+
+<!--
+  NEXT STEPS:
+  1. Share with Designer — verify Figma links, update component inventory.
+  2. PO + Designer sign off: change Status → "approved".
+  3. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
+-->
+````
+
+---
+
+## Quality Checklist *(verify before writing)*
+
+- [ ] Every screen in Screen Inventory has a complete Screen Spec in Section 2
+- [ ] Every screen has at minimum: default, loading, error states defined
+- [ ] All Figma components mapped in Component Inventory — unmapped flagged as `[NEW]` or `[TODO]`
+- [ ] Only the platform-relevant section generated in Section 3 (no web section in app docs, and vice versa)
+- [ ] Only the platform-relevant section generated in Section 4
+- [ ] AC-UI items are testable (clear pass/fail, not "looks good")
+- [ ] Business PRD cross-reference link is valid relative path
+- [ ] If `figma_url = "TBD"` → AI Assumption added in Appendix
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-design-spec Complete — {TICKET-ID} [{active_platform}]
+---
+Status : ✅ Complete
+Output Artifacts:
+  created {paths.design_spec_dir}/{domain}/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
+Next   : Share with Designer → add Figma links → PO + Designer sign-off (Status: approved)
+         → /generate-bdd {prd-file}  (generates BDD per service; reads AC-UI from Design Spec)
+```

package/commands/generate-prd.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}
 ```
 
@@ -306,6 +393,27 @@ Never leave TICKET-ID as plain text if a corresponding PRD file exists in `{path
 
 ---
 
+## Platform Strategy — PRD is platform-agnostic (Option C)
+
+PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không phụ thuộc vào platform nào implement.
+Viết AC theo business outcome, không theo UI/API details:
+
+| ✅ Viết trong PRD (platform-agnostic) | ❌ Không viết trong PRD |
+|---|---|
+| "Đăng nhập thành công → truy cập được tính năng" | "Click button → show toast" ← Design Spec |
+| "Sai password 5 lần → khoá tài khoản 30 phút" | "API trả về JWT token" ← Tech Docs |
+| "Session hết hạn → yêu cầu xác thực lại" | "Hiển thị spinner khi loading" ← Design Spec |
+
+**Một PRD phục vụ tất cả platform:**
+- **FE/App team** → đọc PRD + Design Spec → `/generate-bdd` (UI-level scenarios)
+- **BE team** → đọc PRD trực tiếp → `/generate-bdd` (API-level scenarios)
+- Design Spec là tài liệu riêng cho FE/App — **không trộn vào PRD**
+
+Khi viết AC, nếu PO đề cập chi tiết UI (màu sắc, layout, animation) → nhắc nhở:
+*"Chi tiết UI này thuộc về Design Spec, không thuộc PRD. Ghi nhận lại để tạo Design Spec sau."*
+
+---
+
 ## Generate
 
 Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below.
@@ -328,6 +436,7 @@ Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below
 | **Domain**    | {domain}                         |
 | **Created**   | {YYYY-MM-DD}                     |
 | **Updated**   | {YYYY-MM-DD}                     |
+| **API Source** | *(bỏ trống nếu greenfield — thêm `existing` nếu API đã tồn tại trên hệ thống)* |
 
 ---
 
@@ -412,6 +521,23 @@ flowchart TD
 
 - {[TICKET-ID](./TICKET-ID-slug.md) — relationship description}
 
+## Existing API Contract *(chỉ điền khi API Source = existing)*
+
+> API đã tồn tại trên hệ thống. PO ghi lại contract để BDD generation dùng trực tiếp —
+> không cần tổng hợp từ FE/App BDD, không cần T7 sign-off gate.
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
+
+---
+
 ## AI Assumptions
 
 > Assumptions AI made when information was incomplete. Needs PO review and confirmation.
@@ -480,7 +606,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}`        |
@@ -494,6 +621,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:
 ```

package/commands/generate-prd.tmpl

@@ -41,6 +41,27 @@ Never leave TICKET-ID as plain text if a corresponding PRD file exists in `{path
 
 ---
 
+## Platform Strategy — PRD is platform-agnostic (Option C)
+
+PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không phụ thuộc vào platform nào implement.
+Viết AC theo business outcome, không theo UI/API details:
+
+| ✅ Viết trong PRD (platform-agnostic) | ❌ Không viết trong PRD |
+|---|---|
+| "Đăng nhập thành công → truy cập được tính năng" | "Click button → show toast" ← Design Spec |
+| "Sai password 5 lần → khoá tài khoản 30 phút" | "API trả về JWT token" ← Tech Docs |
+| "Session hết hạn → yêu cầu xác thực lại" | "Hiển thị spinner khi loading" ← Design Spec |
+
+**Một PRD phục vụ tất cả platform:**
+- **FE/App team** → đọc PRD + Design Spec → `/generate-bdd` (UI-level scenarios)
+- **BE team** → đọc PRD trực tiếp → `/generate-bdd` (API-level scenarios)
+- Design Spec là tài liệu riêng cho FE/App — **không trộn vào PRD**
+
+Khi viết AC, nếu PO đề cập chi tiết UI (màu sắc, layout, animation) → nhắc nhở:
+*"Chi tiết UI này thuộc về Design Spec, không thuộc PRD. Ghi nhận lại để tạo Design Spec sau."*
+
+---
+
 ## Generate
 
 Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below.
@@ -63,6 +84,7 @@ Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below
 | **Domain**    | {domain}                         |
 | **Created**   | {YYYY-MM-DD}                     |
 | **Updated**   | {YYYY-MM-DD}                     |
+| **API Source** | *(bỏ trống nếu greenfield — thêm `existing` nếu API đã tồn tại trên hệ thống)* |
 
 ---
 
@@ -147,6 +169,23 @@ flowchart TD
 
 - {[TICKET-ID](./TICKET-ID-slug.md) — relationship description}
 
+## Existing API Contract *(chỉ điền khi API Source = existing)*
+
+> API đã tồn tại trên hệ thống. PO ghi lại contract để BDD generation dùng trực tiếp —
+> không cần tổng hợp từ FE/App BDD, không cần T7 sign-off gate.
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
+
+---
+
 ## AI Assumptions
 
 > Assumptions AI made when information was incomplete. Needs PO review and confirmation.