@edupia-tutor/spec-driven-docs 0.14.0

package/skills/design-spec/SKILL.md

@@ -0,0 +1,589 @@
+---
+description: Generates a Design Specification document for FE or App platforms from a Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
+---
+
+# /generate-design-spec — Generate Design Specification (FE / App)
+
+This skill generates a platform-specific Design Spec from a Business PRD.
+Design Spec captures screen-level UI requirements, component inventory, platform interactions,
+and design-level AC-UI for PO + Designer sign-off — separate from the business-level PRD.
+
+**Supported platforms:** web (react / nextjs / vue / angular), app (flutter / react-native / ios-swiftui / android-compose)
+**Not supported:** backend services — API contracts belong in the Business PRD.
+
+---
+
+## Gate
+
+<!-- Directory: specs/*/*/prd.md -->
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4 (or latest Opus model)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
+   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
+   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
+   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+---
+
+## Context
+
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → spec artifacts root — PRD, BDD, tech-docs, design-spec. Structure: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root (merged with specs_dir in feature-package layout — tech-docs live under `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.trace_dir` → trace state directory; structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs`
+- `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
+- `product_definitions_dir` = `specs/product-definition`
+- `domain_knowledge_dir` = `specs/domain-knowledge`
+- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
+- `core_entities` = `specs/domain-knowledge/core-entities.md`
+- `tech_docs_dir` = `specs`
+- `trace_dir` = `.trace`
+
+Note: In the feature-package layout, `specs_dir` is the unified root. All spec artifact types (PRD, BDD, tech-docs, design-spec) live under `{specs_dir}/{domain}/{prd-slug}/`. The `prd-slug` is the feature-package folder name, not a separate config variable.
+
+**How to extract `prd_slug` (works for ANY target file, regardless of nesting depth):** given a target path of the form `{specs_dir}/{domain}/{prd-slug}/...`, take the **first path segment after `{specs_dir}/{domain}/`** — i.e. the `{prd-slug}` position. Do NOT use the file's immediate parent folder, because BDD/tech-docs/design-spec artifacts are nested one or two levels deeper inside the package. Examples:
+- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `system`)*
+- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `web`)*
+- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(NOT `tech-docs`)*
+- `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice`
+
+All sibling artifacts of one feature (PRD, every platform's BDD, the BE + FE tech-docs, the design-spec, and the trace TSV) therefore resolve to the **same `prd_slug`** — so a synthesized **system** BDD or **system/BE** tech-doc lands in the same `{specs_dir}/{domain}/{prd-slug}/` package as the web/app artifacts it was derived from.
+
+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: `domain` = the first segment after the `specs_dir` base path; `prd_slug` = the next segment (the feature-package folder). This holds for any target depth — see the `prd_slug` extraction rule in Step 1.  
+  *(e.g., `specs/user/create-account/prd.md` **and** `specs/user/create-account/bdd/system/UC1.feature` both → domain = `user`, prd_slug = `create-account`)*
+- If `$ARGUMENTS` contains a path, extract the domain segment after `specs_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- 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`
+- 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.specs_dir` → `{spec_source}/specs` — **always when `spec_source` is set.** All spec artifacts (PRD, BDD, tech-docs, design-spec) live under the unified spec root in the shared spec repo using the feature-package layout: `{spec_source}/specs/{domain}/{prd-slug}/`. Every umbrella (FE/App/BE) reads from here. *(Per-service `specs/` only when there is no `spec_source`.)*
+- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). Tech-docs live at `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. 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.)*
+- 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`
+- 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. Internal structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace/{domain}/{prd-slug}/`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
+
+> **Why under `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** using the feature-package layout so every umbrella (FE/App/BE) and the PM read one source via `/sync`. In the feature-package layout, a single `specs/{domain}/{prd-slug}/` folder groups all artifact types for one PRD, making the spec repo self-contained and navigable by feature. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo. In single-service mode (no `spec_source`), everything defaults under the repo root — still one 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` | **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`); ignore any service-level `specs_dir`** (all spec artifacts are 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`
+- **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).
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
+
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
+
+---
+
+## 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.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
+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}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.
+
+
+*Read the target PRD. Extract: TICKET-ID, domain, feature name, Service, Module from metadata, User Flow (Section 4a), Wireframe screen names (Section 4b).*
+
+---
+
+## Platform Check
+
+- `platform_type = "backend"` → **STOP**: "Design Spec is only for FE/App. BE API contracts go in the Business PRD."
+- `platform_type = "web-frontend"` → `active_platform = "web"`
+- `platform_type = "mobile"` → `active_platform = "app"` (or `"app-ios"` / `"app-android"` for native)
+- `platform_type = "unknown"` → ask user to select platform
+
+---
+
+## Figma Check
+
+Ask: "Do you have a Figma link? (paste URL or Enter to skip)"
+
+Store as `figma_url` or set to `"TBD"` with AI Assumption noted.
+
+---
+
+## Screen Discovery
+
+Extract screen names from PRD Section 4. Present list for PO to confirm/add before generating.
+
+---
+
+## Generate
+
+Write `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`.
+
+Structure:
+1. **Metadata** — Spec ID, platform, module, service, Business PRD link, Figma link
+2. **Screen Inventory** — table of all screens with entry points and Figma frame links
+3. **Screen Specs** (per screen):
+   - Layout (grid, spacing, design tokens)
+   - Component Inventory (Figma → code component, import path, states)
+   - Screen States (default / loading / error / empty / success)
+   - Actions & Navigation (triggers → results)
+4. **Interaction Patterns** (platform-adaptive):
+   - Web: responsive breakpoints table, hover/focus/keyboard table
+   - App: gesture table, navigation stack diagram, iOS vs Android conventions table
+5. **Platform Considerations** (platform-adaptive):
+   - Web: accessibility checklist (WCAG, keyboard, ARIA)
+   - App: safe area, touch targets, deep links, permissions, offline, dark mode
+6. **AC-UI** — design acceptance criteria table (Verified by: Designer / PO / QA)
+7. **Appendix** — Figma summary, design tokens, references, AI assumptions, changelog
+
+Component mapping rules:
+- Check `figma-components/{active_module}.md` (loaded in context) for every component
+- ✅ Found → use exact Code Component + Import Path
+- ⚠️ TODO → mark `[TODO — implementation pending]`
+- ❌ Not found → mark `[NEW — confirm with designer]`
+
+---
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+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:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /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)   | 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 |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {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:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+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-design-spec Complete — {TICKET-ID} [{active_platform}]
+---
+Status : ✅ Complete
+Output Artifacts:
+  created specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
+Next   : Share with Designer → add Figma links → PO + Designer sign-off
+         → /generate-bdd {prd-file}
+```