@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.1

package/core/commands/generate-code.md

@@ -1,145 +1,145 @@
-# /generate-code — Generate Implementation Code
+# /generate-code — Sinh Implementation Code
 
 ## Gate
-# Gate — Universal Entry Procedure
+# Gate — Quy trình vào chuẩn cho mọi lệnh
 
-Every command must execute this gate before proceeding with its specific logic.
+Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
 
-## Step 0 — Sub-Agent Mode Check
+## Bước 0 — Kiểm tra chế độ Sub-Agent
 
-Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
 
-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).
+1. Thử parse `$ARGUMENTS` dưới dạng JSON.
+2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
+   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
+   - Đặt target file = `payload.target_file`
+   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
+   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
+   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đi thẳng tới phần logic riêng của lệnh.
+3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
-## Step 0-B — Model Check
+## Bước 0-B — Kiểm tra Model
 
-*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
 
-Complex generation and review commands require strong reasoning.
-Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
+Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
 
-Display and wait for response:
+Hiển thị và chờ phản hồi:
 
 ```
 ⚙️  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.
+  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
+                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
 
-  To switch in Claude Code:
-    • Settings → Model → select "claude-opus"
-    • or: /model → choose claude-opus
+  Cách đổi trong Claude Code:
+    • Settings → Model → chọn "claude-opus"
+    • hoặc: /model → chọn claude-opus
 
-  Running on claude-opus?
-    Y — yes, on claude-opus → proceed
-    S — skip check (I accept lower quality risk with current model)
+  Đang chạy claude-opus?
+    Y — đúng, đang dùng claude-opus → tiếp tục
+    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
-- "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."
+- "Y" → tiếp tục sang Bước 1.
+- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
 
-## Step 1 — Resolve Target File
+## Bước 1 — Xác định 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`.
+1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
+   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
+   - **Lệnh PRD** (target là `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh design-spec**: `{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.
+   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
+3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
+   - Chờ người dùng chọn rồi mới tiếp tục.
 
-## Step 2 — Execute Context Loader
+## Bước 2 — Chạy 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.
+Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
+Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
 
-## Step 3 — CHECKPOINT
+## Bước 3 — CHECKPOINT
 
-After completing Steps 1 and 2, display a summary and wait for confirmation:
+Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
 
 ```
 CHECKPOINT
 -----------
 Target     : {resolved file path}
-Project    : {project.name from project-context.yaml}
+Project    : {project.name từ project-context.yaml}
 Tech stack : {language} / {framework}
-Module     : {module if set, else "not configured"}
-Domains    : {comma-separated domain list}
+Module     : {module nếu có, else "not configured"}
+Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
 
-Proceed? (Y/N)
+Tiếp tục? (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.
+Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
+- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
+- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
 
 
-*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID. If `$ARGUMENTS` is a UC-ID, find the matching feature file by globbing `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` for the unknown prd-slug, recursive `**` to cover the `web/`·`app/`·`system/` platform subfolders); take `domain` + `prd_slug` from the matched path. Also check `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` for drift (new vs drifted vs synced).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một file `.feature` hoặc UC-ID. Nếu `$ARGUMENTS` là UC-ID, tìm file feature khớp bằng cách glob `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` (wildcard `*` cho prd-slug chưa biết, `**` đệ quy để phủ các thư mục con platform `web/`·`app/`·`system/`); lấy `domain` + `prd_slug` từ path khớp. Cũng kiểm tra `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` tìm drift (new vs drifted vs synced).*
 
 ## Context
-# Context Loader — Load All Project Context
+# Context Loader — Nạp toàn bộ context dự án
 
-Execute these steps in order. Store everything in memory for the duration of the command session.
+Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nhớ trong suốt phiên làm việc của lệnh.
 
-**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.
+**Hướng dẫn ưu tiên (chống lost-in-middle):**
+- Bước 1–2 là PROJECT-CONFIG — nạp trước, phân giải mọi path và metadata.
+- Bước 3 là CRITICAL — kiến trúc + coding standards, là các sự thật ưu tiên cao nhất khi sinh nội dung.
+- Bước 4 là SAFETY — quy tắc bảo vệ dữ liệu, thực thi ngầm suốt cả phiên.
+- Bước 5–6 là DOMAIN KNOWLEDGE — thuật ngữ và định nghĩa entity.
+- Bước 7 là WORKING MEMORY RECAP — chốt các sự thật quan trọng lên đầu bộ nhớ làm việc.
 
 ---
 
-## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml
 
-Read `.agent/project-context.yaml`. Extract and store:
+Đọc `.agent/project-context.yaml`. Trích xuất và lưu:
 
 **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)
+- `tech_stack.language` → ngôn ngữ đang dùng (vd: Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → framework đang dùng (vd: Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (vd: Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (vd: JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (vd: PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → module profile đang dùng (vd: 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)
+- `conventions.build_command` → cách compile/build
+- `conventions.test_command` → cách chạy test
+- `conventions.service_run` → cách khởi động service
+- `conventions.ticket_prefix` → tiền tố ticket ID (vd: 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:
+- `domains` → danh sách các business domain đang hoạt động
+
+**Paths (nếu có):**
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.refinement_dir` → thư mục output cho findings/review
+- `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
+- `paths.product_definitions_dir` → gốc product definition
+- `paths.domain_knowledge_dir` → gốc domain knowledge
+- `paths.business_dictionary` → path tới business-dictionary.md
+- `paths.core_entities` → path tới core-entities.md
+- `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
+
+Nếu không có section `paths`, dùng các giá trị mặc định:
 - `specs_dir` = `specs`
 - `refinement_dir` = `.agent/review`
 - `qc_dir` = `docs`
@@ -151,184 +151,184 @@ If `paths` section is absent, use these defaults:
 - `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.
+Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.
 
-**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:
+**Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
 - `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/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
+- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
+- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `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.
+Mọi artifact cùng cấp của một feature (PRD, BDD của từng platform, tech-docs BE + FE, design-spec, và trace TSV) đều phân giải về **cùng một `prd_slug`** — nên một BDD **system** hay tech-doc **system/BE** được tổng hợp sẽ nằm chung package `{specs_dir}/{domain}/{prd-slug}/` với các artifact web/app mà nó được suy ra từ đó.
 
-If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+Nếu `tech_stack.module` được đặt, đồng thời nạp `.agent/modules/{module}/stack-profile.yaml` nếu file tồn tại.
 
 ---
 
-## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella)
 
-*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+*Bỏ qua hoàn toàn bước này nếu `setup.mode` không phải `"umbrella"` và không có section `services` trong project-context.yaml.*
 
-If `services` section is present:
+Nếu có section `services`:
 
-**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`
+**1. Phát hiện active domain** (theo thứ tự ưu tiên):
+- Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
+- Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
+  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+- Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `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`)
+**2. Route tới service** — nếu active domain khớp với một key trong `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+- Lưu `active_service` = `services.{domain}.path`
+- Lưu `active_service_module` = `services.{domain}.module`
+- Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
 
-**3. Fallback** — if domain not detected or no matching service key:
-- Keep default paths from Step 1
-- Set `active_service = unresolved`
+**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
+- Giữ path mặc định từ Bước 1
+- Đặt `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.)*
+**4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
+- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt** (bước 2 không còn pin tech-docs theo service trong trường hợp này). Tech-docs nằm tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. Tech-design CHÍNH LÀ API contract liên team: BE viết ở đây, FE/App đọc nó từ cùng spec submodule tại `/generate-code --phase=integration`. *(tech-docs theo service chỉ xảy ra khi không có `spec_source` — repo BE thuần đa-service không có spec module dùng chung.)*
 - 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`.)*
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `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.
+> **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **và trạng thái coverage `.trace/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/` và `feedback/` là khu vực **ghi** của dev/QC trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo.
 
 ---
 
-## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
 
-When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
-**1. Locate service config** — try in priority order:
+**1. Định vị config của service** — thử theo thứ tự ưu tiên:
 - `{active_service}/.agent/project-context.yaml`
 - `{active_service}/project-context.yaml`
 
-**2. If found, override with service-specific values:**
+**2. Nếu tìm thấy, override bằng giá trị riêng của service:**
 
-| Variable | Source |
+| Biến | Nguồn |
 |----------|--------|
-| `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. |
+| `conventions.test_command` | `conventions.test_command` của service |
+| `conventions.build_command` | `conventions.build_command` của service |
+| `paths.trace_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.trace`); bỏ qua mọi `trace_dir` cấp service.** Chỉ khi không có `spec_source`: `{active_service}/{service paths.trace_dir}` (mặc định `{active_service}/.trace`). |
+| `paths.specs_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/specs`); bỏ qua mọi `specs_dir` cấp service** (mọi spec artifact đều liên team, không bao giờ theo service ở chế độ này). Chỉ khi không có `spec_source`: `{active_service}/{service paths.specs_dir}` nếu được set, else dùng override ở Bước 1.5. |
 
-**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/`).
+**3. Lưu** `service_root = {active_service}` làm mốc thư mục làm việc cho mọi lệnh phía sau:
+- Các lệnh shell (`/dev-run-test`, `/dev-gen-test`) chạy **bên trong** `service_root`
+- **File source/test** được ghi tương đối với `service_root`; **trace TSV** được ghi vào `{paths.trace_dir}` (là spec repo khi `spec_source` được đặt — một thao tác ghi liên-repo, commit/push vào spec submodule giống như `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).
+**4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override).
 
 ---
 
-## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
 
-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.
+Nếu `tech_stack.module` được đặt, đọc `.agent/modules/{module}/stack-profile.yaml`.
+Merge các convention riêng của framework (layer pattern, test pattern, quy tắc đặt tên) vào context đã nạp.
+Nếu file không tồn tại → bỏ qua âm thầm.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
+## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay)
 
-*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+*Đây là context ưu tiên cao nhất — nó định nghĩa CÁCH viết code và tài liệu cho dự án này.*
 
-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.
+CLAUDE.md được nạp theo **hai tầng** để các quy tắc toàn-umbrella và kiến trúc/coding standards
+riêng của service kết hợp đúng cách. Agent luôn đứng ở gốc umbrella, nhưng code triển khai nằm
+trong một service submodule với stack, kiến trúc, và convention RIÊNG của nó — nên CLAUDE.md của
+service phải thắng khi sinh code.
 
-**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.
+**Tầng 1 — [BASE] Root CLAUDE.md (toàn umbrella).**
+Đọc `CLAUDE.md` ở gốc repo. Coi nội dung của nó là **nền tảng dùng chung** cho cả umbrella —
+git convention, tư thế bảo vệ dữ liệu, quy tắc xuyên suốt, và (ở chế độ single-service) là
+kiến trúc + coding standards duy nhất của dự án.
 
-**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.
+**Tầng 2 — [OVERLAY] Service CLAUDE.md (chỉ chế độ umbrella).**
+*Chỉ chạy nếu `service_root` đã được set ở Bước 1.6 (tức đã route tới một service thật).*
+Đọc `{service_root}/CLAUDE.md`. File này định nghĩa kiến trúc + coding standards của **stack
+thực sự đang được triển khai** (vd: `user-service` = java-spring, `web` = nextjs).
+Overlay nó lên trên Tầng 1: **khi có xung đột, giá trị của service THẮNG** cho kiến trúc,
+coding standards, và error handling. Các giá trị Tầng 1 mà service không định nghĩa lại
+(vd: git convention, banned pattern dùng chung toàn tổ chức) vẫn có hiệu lực.
 
-From the **merged** result, extract and store:
+Từ kết quả **đã merge**, trích xuất và lưu:
 
-- **§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*
+- **§1 Project Overview** → tên dự án, ngôn ngữ, framework, lệnh build/test, domains
+- **§2 Architecture** → thứ tự layer (vd: Controller → Facade → Service → Repository), quy tắc kiến trúc — *service overlay thắng*
+- **§3 Coding Standards** → quy tắc đặt tên (class, method), kiểu response wrapper, pattern bị cấm — *service overlay thắng*
+- **§5 Error Handling** → kiểu exception, mapping HTTP status code, tên class not-found exception — *service overlay thắng*
+- **§7 Git Conventions** → pattern đặt tên branch, format commit message — *lấy theo root trừ khi service định nghĩa lại*
 
-**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.
+**Quy tắc phân giải:**
+- Nếu cả hai tầng tồn tại → merge như trên; ghi `claude_md_source = root + {service_root}`.
+- Nếu chỉ có service overlay (không có root CLAUDE.md) → dùng file service một mình; `claude_md_source = {service_root}`.
+- Nếu `service_root` được set nhưng `{service_root}/CLAUDE.md` **thiếu** → fallback về root CLAUDE.md và gắn cờ ⚠️ trong recap Bước 7 (service không có định nghĩa kiến trúc/coding-standards — việc sinh code sẽ dùng mặc định umbrella, có thể sai stack).
+- Nếu cả hai đều không tồn tại → ghi nhận CLAUDE.md thiếu và tiếp tục chỉ với dữ liệu từ project-context.yaml.
 
 ---
 
-## Step 4 — [SAFETY] Load Data Protection Rules
+## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
 
-Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
 
-Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+Lưu các pattern file nhạy cảm — bạn **tuyệt đối không** đọc, ghi, hiển thị, hay tham chiếu nội dung từ các file khớp những pattern đó trong suốt cả phiên.
 
-If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+Nếu cả hai file đều không tồn tại → áp dụng mặc định built-in: không bao giờ truy cập `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
 
 ---
 
-## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
 
-Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+Kiểm tra file business dictionary có tồn tại không (dùng `paths.business_dictionary` đã phân giải ở Bước 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
+Nếu tồn tại, đọc và trích xuất:
+- **Canonical Terms** → danh sách đầy đủ các thuật ngữ chuẩn và định nghĩa
+- **Banned Terms** → danh sách đầy đủ các thuật ngữ bị cấm và bản thay thế chuẩn
+- **Status / Enum Registry** → các giá trị enum được phép theo từng 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
+Lưu danh sách banned term để **thực thi chủ động** suốt phiên làm việc của lệnh:
+- Khi sinh bất kỳ văn bản nào (PRD, BDD, comment code, tech docs), kiểm tra không có banned term nào xuất hiện
+- Tự động thay banned term bằng bản chuẩn tương đương
 
-If the file does not exist → skip silently. Do not warn or block.
+Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
 
 ---
 
-## Step 6 — [DOMAIN] Load Core Entities (conditional)
+## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
 
-Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
-Default path: `specs/domain-knowledge/core-entities.md`.
+Kiểm tra file core entities có tồn tại tại `paths.core_entities` không (đã phân giải ở Bước 1).
+Path mặc định: `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.)
+Nếu tồn tại, đọc và lưu:
+- **Entity catalog** → với mỗi entity: tên, mục đích, service sở hữu, các field chính (tên + kiểu), business invariant, và quan hệ
+- **Field name registry** → tên field chuẩn dùng trong code và tài liệu được sinh ra
+- **Relationship map** → cách các entity liên hệ với nhau (1:N, N:N, embedded, v.v.)
 
-**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
+**Cách dùng catalog này:**
+- Khi sinh code: dùng tên field, kiểu, và quan hệ định nghĩa ở đây — KHÔNG suy đoán từ code có sẵn
+- Khi sinh PRD/BDD: tham chiếu tên entity từ catalog này để nhất quán
+- Khi sinh tech-docs: dùng catalog này làm nguồn chân lý cho định nghĩa entity
 
-If the file does not exist → skip silently.
+Nếu file không tồn tại → bỏ qua âm thầm.
 
 ---
 
-## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
 
-Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+Dùng `tech_stack.module` đã nạp ở Bước 1, suy ra và lưu hai biến để mọi lệnh phía sau dùng:
 
 ```
-active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
 ```
 
 | `platform_type` | Modules |
@@ -337,400 +337,398 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 | `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.
+Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
 
-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).
+Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
-## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
 
-*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`.*
+*Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn`
+hoặc được chấp nhận trong `/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`
+Phân giải path file lessons:
+- Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6)
+- Else mặc định `specs/domain-knowledge/lessons-learned.md`
+- Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{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.
+Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
+- Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
+- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
+- Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
 
-If the file does not exist → skip silently (no lessons captured yet).
+Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
 
 ---
 
-## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+## Bước 7 — [RECAP] Working Memory Recap (chống 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).
+Sau khi nạp toàn bộ context, tổng hợp và xuất một khối tóm tắt gọn.
+Recap này đảm bảo các sự thật quan trọng nhất được nêu ở CUỐI quá trình nạp context
+(hiệu ứng recency — tươi mới nhất trong bộ nhớ làm việc khi bắt đầu task).
 
-Output exactly this block:
+Xuất đúng khối này:
 ```
 [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}
+Layers    : {thứ tự layer từ CLAUDE.md §2 đã merge, vd: Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️ service overlay THIẾU — dùng 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}
+Lessons   : {loaded — N guardrails | chưa có}
 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}
+Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
+Status    : {FULL | PARTIAL — thiếu: 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.
+Nếu bất kỳ file CRITICAL nào thiếu (CLAUDE.md), gắn cờ rõ ràng để người dùng quyết định có tiếp tục hay không.
 
 ---
 
-## Context Load Complete
+## Hoàn tất nạp Context
 
-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
+Sau khi hoàn thành tất cả các bước, bạn đã nạp:
+- Định danh dự án, tech stack, convention module
+- Quy tắc kiến trúc và thứ tự layer  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
+- Coding standards và quy tắc đặt tên  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
+- Quy tắc bảo vệ dữ liệu (pattern file nhạy cảm không bao giờ truy cập)
+- Quy tắc thuật ngữ kèm danh sách banned term  ← **[DOMAIN — áp dụng cho mọi từ được sinh ra]**
+- Entity catalog (tên field, kiểu, invariant)  ← **[DOMAIN — dùng khi sinh code]**
+- Toàn bộ path đã cấu hình
 
-Proceed to the next step of the calling command.
+Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
 ---
 
 ## Scope Lock
 
-This command is strictly scoped to the **single feature file** passed as `$ARGUMENTS`:
+Lệnh này giới hạn nghiêm ngặt trong **một file feature** được truyền qua `$ARGUMENTS`:
 
-- Feature file: `{exact path from $ARGUMENTS}`
-- UC: `{UC-ID}` (read from `@trace.id` in that file's header)
+- File feature: `{path chính xác từ $ARGUMENTS}`
+- UC: `{UC-ID}` (đọc từ `@trace.id` trong header file đó)
 
-**Do NOT read or implement scenarios from any other `.feature` file** in the same domain folder, even if they share the same entity, domain concept, or service name.
+**KHÔNG đọc hay implement scenario từ bất kỳ file `.feature` nào khác** trong cùng folder domain, kể cả khi chúng dùng chung entity, khái niệm domain, hay tên service.
 
 ---
 
-## Context Load (additional)
+## Context Load (bổ sung)
 
-Read:
-1. The scoped `.feature` file only
-2. Tech-doc at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (if exists)
+Đọc:
+1. Chỉ file `.feature` đã giới hạn scope
+2. Tech-doc tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (nếu tồn tại)
 3. CLAUDE.md §architecture + §coding_standards
-4. **(FE/App only)** Design Spec at `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (if exists) — source of screens, component inventory, and the per-screen Figma frame links.
+4. **(chỉ FE/App)** Design Spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (nếu tồn tại) — nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
 ---
 
 ## Phase Detection
 
-Parse `$ARGUMENTS` for a `--phase` flag:
+Parse `$ARGUMENTS` tìm flag `--phase`:
 
-| Flag | Meaning |
+| Flag | Ý nghĩa |
 |---|---|
-| `--phase=ui` | FE Phase 1 — generate UI + mock API layer from System BDD contract |
-| `--phase=integration` | FE Phase 2 — replace mock adapter with real API calls from tech docs |
-| *(none)* | Default — full implementation (BE or full-stack without mock split) |
-
-**If `--phase` is set — confirm platform:**
-Read `@trace.platform` from the feature file header.
-- If `system` → warn: "`--phase` flag is not applicable for system BDD (BE-facing). Proceeding with default mode." Treat as no flag.
-- If `web` or `app` → continue with phase logic below.
-
-**If `--phase=ui`:**
-Resolve the **mock shape source** (hybrid — prefer the real contract, fall back to System BDD):
-- **BE contract** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` — if it exists, the mock adapter's port/DTO **shape** (request/response fields, types, error codes) comes from here → `mock_source = contract`. Most accurate; no shape rework at integration.
-- **System BDD** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature` — always load `Then` clauses for **behavior + fixture values**. If no BE contract, the shape is inferred from these too → `mock_source = system-bdd`, and WARN:
+| `--phase=ui` | FE Phase 1 — sinh UI + layer mock API từ System BDD contract |
+| `--phase=integration` | FE Phase 2 — thay mock adapter bằng lời gọi API thật từ tech docs |
+| *(không có)* | Default — full implementation (BE hoặc full-stack không tách mock) |
+
+**Nếu `--phase` được set — xác nhận platform:**
+Đọc `@trace.platform` từ header file feature.
+- Nếu `system` → cảnh báo: "Flag `--phase` không áp dụng cho system BDD (hướng BE). Tiếp tục với chế độ default." Coi như không có flag.
+- Nếu `web` hoặc `app` → tiếp tục logic phase bên dưới.
+
+**Nếu `--phase=ui`:**
+Phân giải **nguồn shape của mock** (hybrid — ưu tiên contract thật, fallback về System BDD):
+- **BE contract** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` — nếu tồn tại, **shape** port/DTO của mock adapter (field request/response, type, error code) lấy từ đây → `mock_source = contract`. Chính xác nhất; không phải rework shape lúc integration.
+- **System BDD** `{paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{TICKET-ID}*.feature` — luôn nạp mệnh đề `Then` để lấy **behavior + giá trị fixture**. Nếu không có BE contract, shape cũng được infer từ đây → `mock_source = system-bdd`, và WARN:
   ```
-  ⚠ BE contract not found — mock shape inferred from System BDD only.
-    System BDD describes behavior, not full request/response shape — the mock
-    may differ from the real API; expect adjustment at --phase=integration.
-    (Recommended: have BE publish {prd-slug}/tech-docs/{UC-ID}-tech-design.md first for an accurate mock.)
+  ⚠ Không tìm thấy BE contract — shape mock được infer chỉ từ System BDD.
+    System BDD mô tả behavior, không phải full request/response shape — mock
+    có thể khác API thật; dự kiến điều chỉnh ở --phase=integration.
+    (Khuyến nghị: để BE publish {prd-slug}/tech-docs/{UC-ID}-tech-design.md trước để có mock chính xác.)
   ```
-- If System BDD is also missing → warn "System BDD not found — mock layer will use placeholder fixtures." Continue.
+- Nếu System BDD cũng thiếu → cảnh báo "Không tìm thấy System BDD — layer mock sẽ dùng fixture placeholder." Tiếp tục.
 
-Store `mock_source` (`contract` | `system-bdd`) for the mock tags below.
+Lưu `mock_source` (`contract` | `system-bdd`) cho các tag mock bên dưới.
 
-**Then run the Figma Dev Mode MCP Check below** before generating any UI — the Design
-Spec's frame links are the visual contract, and the local MCP reads them with far more
-fidelity than a plain web link.
+**Rồi chạy Figma Dev Mode MCP Check bên dưới** trước khi sinh UI — link frame của Design
+Spec là visual contract, và MCP local đọc chúng với độ trung thực cao hơn nhiều so với link web trần.
 
 ---
 
-## Figma Dev Mode MCP Check *(FE/App UI generation only)*
+## Figma Dev Mode MCP Check *(chỉ sinh UI FE/App)*
 
-*Run this only when `platform` is `web`/`app` AND generating UI (`--phase=ui`, or default
-mode for an FE/App feature). Skip entirely for BE / `system` platform.*
+*Chỉ chạy khi `platform` là `web`/`app` VÀ đang sinh UI (`--phase=ui`, hoặc chế độ default
+cho feature FE/App). Bỏ qua hoàn toàn với BE / platform `system`.*
 
-The PO authored the Design Spec from **Figma web links** (read-only, limited). For
-codegen, the **local Figma Dev Mode MCP server** (built into the Figma **desktop app**)
-gives far more: exact layout, design **variables/tokens**, **Code Connect** component
-mappings, selection context, and code snippets — things a web URL alone cannot return.
+PO viết Design Spec từ **link web Figma** (read-only, giới hạn). Để codegen,
+**Figma Dev Mode MCP server local** (tích hợp trong **app desktop** Figma) cho nhiều hơn
+nhiều: layout chính xác, **variable/token** design, mapping component **Code Connect**,
+selection context, và code snippet — những thứ một URL web đơn không trả về được.
 
-**Step 1 — Detect the local MCP.** Check whether a Figma Dev Mode MCP server is connected
-(a `get_design_context` / `get_code` style Figma tool is available via MCP).
+**Step 1 — Phát hiện MCP local.** Kiểm tra xem Figma Dev Mode MCP server có kết nối không
+(một Figma tool kiểu `get_design_context` / `get_code` sẵn có qua MCP).
 
-**Step 2 — If NOT connected → suggest the dev enable it, then wait:**
+**Step 2 — Nếu CHƯA kết nối → gợi ý dev bật nó, rồi chờ:**
 
 ```
-🎨 Figma Dev Mode MCP not detected.
-   For accurate FE code (real tokens, components, Code Connect), use the LOCAL server:
-
-   1. Open the Figma DESKTOP app (not the browser)
-   2. Open the file/frame for this feature
-   3. Enable the Dev Mode MCP server:
-        Figma menu → Preferences → "Enable Dev Mode MCP Server"
-        (requires Dev or Full seat; server runs at http://127.0.0.1:3845)
-   4. Make sure this MCP server is added in your Claude Code MCP config
-   5. Select the frame for the screen you're implementing, then continue
-
-   Type C to continue once enabled, or S to skip (fall back to web links + text spec).
+🎨 Không phát hiện Figma Dev Mode MCP.
+   Để có code FE chính xác (token, component, Code Connect thật), dùng server LOCAL:
+
+   1. Mở app Figma DESKTOP (không phải browser)
+   2. Mở file/frame của feature này
+   3. Bật Dev Mode MCP server:
+        Menu Figma → Preferences → "Enable Dev Mode MCP Server"
+        (cần Dev hoặc Full seat; server chạy ở http://127.0.0.1:3845)
+   4. Đảm bảo MCP server này đã được thêm vào config MCP của Claude Code
+   5. Chọn frame của màn bạn đang implement, rồi tiếp tục
+
+   Gõ C để tiếp tục khi đã bật, hoặc S để skip (fallback về link web + text spec).
 ```
 
-- `C` → re-detect; if now connected → proceed using the local MCP.
-- `S` → proceed in **fallback mode**: use the Design Spec's web frame links + textual spec
-  only; add a ⚠️ note in the final report that UI was generated without local Figma fidelity.
+- `C` → phát hiện lại; nếu giờ đã kết nối → tiếp tục dùng MCP local.
+- `S` → tiếp tục ở **fallback mode**: chỉ dùng link frame web + text spec của Design Spec;
+  thêm note ⚠️ trong report cuối rằng UI được sinh mà không có độ trung thực Figma local.
 
-**Step 3 — When the local MCP IS connected:** for each screen being implemented, pull the
-selected frame via the Figma MCP and ground the UI on the returned layout, variables, and
-Code Connect mappings. Prefer Code-Connect-mapped components over inventing markup; use the
-real token names, not hardcoded values.
+**Step 3 — Khi MCP local ĐÃ kết nối:** với mỗi màn đang implement, pull frame được chọn
+qua Figma MCP và ground UI trên layout, variable, và mapping Code Connect trả về. Ưu tiên
+component được map Code-Connect hơn là bịa markup; dùng tên token thật, không phải giá trị hardcode.
 
-**If `--phase=integration`:**
-Resolve the design that drives the adapter (two layers):
-- **FE tech-design** (preferred — the port→endpoint→DTO mapping): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` §4, produced by `/generate-tech-docs` (FE path).
-- **BE API contract** (endpoint/shape source): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`.
+**Nếu `--phase=integration`:**
+Phân giải design điều khiển adapter (hai tầng):
+- **FE tech-design** (ưu tiên — mapping port→endpoint→DTO): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` §4, sinh bởi `/generate-tech-docs` (path FE).
+- **BE API contract** (nguồn endpoint/shape): `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`.
 
-Read `@trace.status` of whichever drives the adapter (the FE doc if present, else the BE contract).
-If `draft` or `in-review` → warn:
+Đọc `@trace.status` của cái nào điều khiển adapter (doc FE nếu có, else BE contract).
+Nếu `draft` hoặc `in-review` → cảnh báo:
 ```
-⚠ Tech design for {UC-ID} ({platform}) is {status}.
-  Contract / adapter mapping may still change.
-  Proceeding — ensure BE endpoint is deployed or confirm the mapping manually.
+⚠ Tech design cho {UC-ID} ({platform}) đang {status}.
+  Contract / mapping adapter còn có thể đổi.
+  Tiếp tục — đảm bảo BE endpoint đã deploy hoặc confirm mapping thủ công.
 ```
-If the FE tech-design is **missing** → warn: "No FE tech-design found — falling back to the BE contract directly (adapter mapping inferred). Recommended: run `/generate-tech-docs {web|app .feature}` first."
-Locate existing mock adapter from `--phase=ui` run (search for `{UC-ID}MockApiAdapter` in `{paths.src_dir}/{domain}/`).
-If not found → warn: "Mock adapter not found — generating real API adapter from scratch using tech-doc contract."
+Nếu FE tech-design **thiếu** → cảnh báo: "Không tìm thấy FE tech-design — fallback về BE contract trực tiếp (mapping adapter được infer). Khuyến nghị: chạy `/generate-tech-docs {web|app .feature}` trước."
+Định vị mock adapter có sẵn từ lần chạy `--phase=ui` (tìm `{UC-ID}MockApiAdapter` trong `{paths.src_dir}/{domain}/`).
+Nếu không tìm thấy → cảnh báo: "Không tìm thấy mock adapter — sinh real API adapter từ đầu dùng contract tech-doc."
 
 ---
 
 ## Read Trace State
 
-Read `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` if it exists. For each scenario row, note its current `status`:
+Đọc `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` nếu tồn tại. Với mỗi scenario row, ghi nhận `status` hiện tại:
 
-| Status | Meaning | Action in this run |
+| Status | Ý nghĩa | Hành động trong lần chạy này |
 |--------|---------|-------------------|
-| `UNTRACKED` | `implemented_by == —` | Generate — scenario has no code yet |
-| `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario updated since last codegen |
-| `OK` | implemented + tested | Skip unless explicitly re-generating |
-| `GAP` | implemented, no tests | Skip codegen — already coded; run `/dev-gen-test` instead |
+| `UNTRACKED` | `implemented_by == —` | Generate — scenario chưa có code |
+| `DRIFT` | `spec_ver != gen_ver` | Regenerate — scenario đã cập nhật từ lần codegen trước |
+| `OK` | đã implement + test | Skip trừ khi gen lại tường minh |
+| `GAP` | đã implement, chưa test | Skip codegen — đã code rồi; chạy `/dev-gen-test` thay vì |
 
-Use these statuses to populate the **Scenarios** count in the CHECKPOINT plan (`{X} new, {Y} drifted, {Z} synced-skip`).
-If `.tsv` does not exist → treat all scenarios as `UNTRACKED`.
+Dùng các status này để điền số **Scenarios** trong plan CHECKPOINT (`{X} new, {Y} drifted, {Z} synced-skip`).
+Nếu `.tsv` không tồn tại → coi mọi scenario là `UNTRACKED`.
 
 ---
 
 ## File Scan
 
-Before generating, determine which files will be needed for this UC's scenarios. Check whether each file already exists on disk.
+Trước khi sinh, xác định file nào cần cho các scenario của UC này. Kiểm tra mỗi file đã tồn tại trên disk chưa.
 
-Classify each file:
+Phân loại mỗi file:
 
-| Status | Meaning | Action |
+| Status | Ý nghĩa | Hành động |
 |--------|---------|--------|
-| `CREATE` | File does not exist | Generate full new file |
-| `EXTEND` | File exists, new methods needed | Add new methods only — do NOT rewrite existing code |
-| `SKIP` | File exists and already covers all UC scenarios | Leave untouched |
+| `CREATE` | File chưa tồn tại | Sinh file mới đầy đủ |
+| `EXTEND` | File tồn tại, cần method mới | Chỉ thêm method mới — KHÔNG viết lại code có sẵn |
+| `SKIP` | File tồn tại và đã phủ tất cả scenario của UC | Để nguyên |
 
-> **EXTEND rule:** Read the existing file fully. Locate the correct class/interface. Add only the methods required by `{UC-ID}` scenarios. Preserve all existing methods, fields, and annotations exactly as-is. Attach `@trace.implements={UC-ID}-SC{N}` on each new method.
+> **Quy tắc EXTEND:** Đọc file có sẵn đầy đủ. Định vị đúng class/interface. Chỉ thêm các method mà scenario `{UC-ID}` cần. Giữ nguyên mọi method, field, annotation hiện có y như cũ. Gắn `@trace.implements={UC-ID}-SC{N}` lên mỗi method mới.
 
 ---
 
 ## CHECKPOINT — Code Generation Plan
 
-Before generating any code, show:
+Trước khi sinh code, hiện:
 
 ```
 Code Generation Plan — {UC-ID}
 ──────────────────────────────────────────────────────
 Feature  : {name}
-Ticket   : {TICKET_ID if known}
+Ticket   : {TICKET_ID nếu biết}
 Domain   : {domain}
-UC       : {UC-ID} only  ← other feature files in this folder are NOT read
+UC       : chỉ {UC-ID}  ← các file feature khác trong folder này KHÔNG được đọc
 Tech     : {language} / {framework}
-Phase    : {UI — mock layer | Integration — real API | Default — full}   ← omit if no --phase flag
+Phase    : {UI — mock layer | Integration — real API | Default — full}   ← bỏ nếu không có flag --phase
 Scenarios: {N} total ({X} new, {Y} drifted, {Z} synced-skip)
-Layer    : {from CLAUDE.md §2}
+Layer    : {từ CLAUDE.md §2}
 
 Files:
-  CREATE  {N} new files
+  CREATE  {N} file mới
     + {path/FileName.ext}
-  EXTEND  {M} existing files  (add methods only)
-    ~ {path/FileName.ext}  — adding: {methodA}, {methodB}
-  SKIP    {K} files  (no change needed)
+  EXTEND  {M} file có sẵn  (chỉ thêm method)
+    ~ {path/FileName.ext}  — thêm: {methodA}, {methodB}
+  SKIP    {K} file  (không cần đổi)
     = {path/FileName.ext}
 ──────────────────────────────────────────────────────
 Proceed? (Y/N)
 ```
 
-Wait for explicit "Y" before generating.
+Chờ "Y" rõ ràng trước khi sinh.
 
 ## Branch
 ```bash
 git checkout -b feature/{TICKET_ID}-{slug}
 ```
 
-## Generate (layer order from CLAUDE.md §2)
+## Generate (thứ tự layer từ CLAUDE.md §2)
 
-Default order (override from CLAUDE.md if different):
-DTOs → Entity/Model → Repository → Service interface → Service impl → Facade (if applicable) → Controller
+Thứ tự mặc định (override từ CLAUDE.md nếu khác):
+DTOs → Entity/Model → Repository → Service interface → Service impl → Facade (nếu áp dụng) → Controller
 
-**For `CREATE` files:** generate the full file.
+**Với file `CREATE`:** sinh file đầy đủ.
 
-**For `EXTEND` files:** open the existing file → add only the new methods for `{UC-ID}` → do not touch anything else.
+**Với file `EXTEND`:** mở file có sẵn → chỉ thêm method mới cho `{UC-ID}` → không đụng gì khác.
 
-**Traceability tags on controller/handler (adapt to your language's comment syntax):**
+**Tag traceability trên controller/handler (theo cú pháp comment của ngôn ngữ bạn):**
 ```
 @trace.implements={UC-ID}-SC{N}
-@trace.prd_version={read @trace.prd_version from the .feature file header}
-@trace.bdd_version={read @trace.bdd_version from the .feature file header}
-@trace.tech_doc_revision={read @trace.revision from tech-doc header, or omit if no tech-doc}
+@trace.prd_version={đọc @trace.prd_version từ header file .feature}
+@trace.bdd_version={đọc @trace.bdd_version từ header file .feature}
+@trace.tech_doc_revision={đọc @trace.revision từ header tech-doc, hoặc bỏ nếu không có tech-doc}
 @trace.source={paths.specs_dir}/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature
 ```
 
-`@trace.prd_version` records which PRD version this code was written against.
-`@trace.bdd_version` records which BDD version this code was generated from.
-`@trace.tech_doc_revision` records which tech-design revision this code follows.
-`/validate-traces` will flag drift if any upstream artifact is updated to a newer version.
+`@trace.prd_version` ghi code này được viết theo version PRD nào.
+`@trace.bdd_version` ghi code này được sinh từ version BDD nào.
+`@trace.tech_doc_revision` ghi code này theo revision tech-design nào.
+`/validate-traces` sẽ gắn cờ drift nếu bất kỳ artifact upstream nào được cập nhật lên version mới hơn.
 
-> **Entry-point rule:** `@trace.implements` must appear on the **entry-point layer** as defined in `CLAUDE.md §2`. For REST APIs → Controller. For event-driven modules → event handler / consumer class. For context-engineering → the prompt orchestration function. Never put it only on an inner layer.
+> **Quy tắc entry-point:** `@trace.implements` phải xuất hiện ở **layer entry-point** như định nghĩa trong `CLAUDE.md §2`. Với REST API → Controller. Với module event-driven → event handler / consumer class. Với context-engineering → hàm orchestration prompt. Không bao giờ chỉ đặt ở layer trong.
 
-### Test Selectors — emit stable element IDs *(FE/App UI only)*
+### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
-*Applies when `platform` is `web`/`app` and generating UI (`--phase=ui`, or default FE/App mode). Skip for BE.*
+*Áp dụng khi `platform` là `web`/`app` và đang sinh UI (`--phase=ui`, hoặc chế độ default FE/App). Bỏ qua với BE.*
 
-Every **actionable** element (button, input, link, select, toggle, form-submit) MUST carry a **stable test-id** so QC locates it directly (no runtime scan):
+Mỗi element **có action** (button, input, link, select, toggle, form-submit) PHẢI mang một **test-id ổn định** để QC định vị trực tiếp (không scan runtime):
 
-1. **Source the id.** If the FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` exists, take ids **verbatim** from its §2b Test Selectors table (the contract). If it does not exist yet (e.g. `--phase=ui` before the FE tech-design), **generate ids by the convention** `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`) so QC still has stable handles — they will be reconciled to the tech-design's §2b at integration.
-2. **Emit via the platform attribute** (from `@trace.testid_attr`, or by module):
+1. **Nguồn id.** Nếu FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` tồn tại, lấy id **nguyên văn** từ bảng §2b Test Selectors của nó (contract). Nếu chưa tồn tại (vd `--phase=ui` trước FE tech-design), **sinh id theo quy ước** `{uc-lower}-{screen}-{element}-{type}` (vd `ft001-login-submit-btn`) để QC vẫn có handle ổn định — chúng sẽ được đối chiếu với §2b của tech-design lúc integration.
+2. **Emit qua attribute platform** (từ `@trace.testid_attr`, hoặc theo module):
    - web (`react`/`nextjs`/`vue`/`angular`) → `data-testid="..."`
    - React Native → `testID="..."`
-   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` where the action needs it)
+   - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` khi action cần)
    - native iOS → `accessibilityIdentifier = "..."`
-3. Only actionable elements; do not spam ids on static text. Keep ids identical to the tech-design map so QC Page Objects match on the first try.
-4. **Reused catalog component?** Pass the id via its **forwarding prop** (see the catalog `## Test-ID Forwarding` section — e.g. `<Button testId="ft001-login-submit-btn">`), not a raw attribute. If the component does not forward a test-id, or you are backfilling **existing/brownfield** screens (not freshly generated here), that is `/map-testids {UC-ID}`'s job — run it instead of editing shared components inline.
+3. Chỉ element có action; đừng spam id lên text tĩnh. Giữ id giống hệt map của tech-design để QC Page Object khớp ngay lần đầu.
+4. **Component catalog tái dùng?** Truyền id qua **forwarding prop** của nó (xem section catalog `## Test-ID Forwarding` — vd `<Button testId="ft001-login-submit-btn">`), không phải attribute thô. Nếu component không forward test-id, hoặc bạn đang backfill màn **existing/brownfield** (không phải sinh mới ở đây), đó là việc của `/map-testids {UC-ID}` — chạy nó thay vì sửa component dùng chung inline.
 
-## Mock API Layer (`--phase=ui` only)
+## Mock API Layer (chỉ `--phase=ui`)
 
-*Skip this section entirely if `--phase` is not `ui`.*
+*Bỏ qua hoàn toàn section này nếu `--phase` không phải `ui`.*
 
-Build the mock from the `mock_source` resolved in Phase Detection — **shape** from the BE contract when present, **fixture values + behavior** always from System BDD `Then` clauses:
+Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape** từ BE contract khi có, **giá trị fixture + behavior** luôn từ mệnh đề `Then` của System BDD:
 
-1. **Define the port shape** `{UC-ID}ApiPort` (request/response DTOs + error codes):
-   - `mock_source = contract` → field names / types / error codes taken **verbatim from the BE contract** §2 (API Endpoints) / §3 (Data Model) — the real shape.
-   - `mock_source = system-bdd` → shape **inferred** from System BDD `Then` clauses (provisional — see warning above).
-2. **Extract fixture data** per scenario from System BDD `Then` clauses — success + error responses (BDD is the source of truth for *values / behavior*, regardless of shape source).
-3. **Generate mock adapter** at `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
-   - Implements interface `{UC-ID}ApiPort` (same interface the real adapter will implement)
-   - Each method returns fixture data matching the BDD `Then` clause, in the port shape
-   - Include both success and error states (map to error scenarios in BDD)
-   - Traceability tags:
+1. **Định nghĩa shape port** `{UC-ID}ApiPort` (DTO request/response + error code):
+   - `mock_source = contract` → tên field / type / error code lấy **nguyên văn từ BE contract** §2 (API Endpoints) / §3 (Data Model) — shape thật.
+   - `mock_source = system-bdd` → shape **infer** từ mệnh đề `Then` của System BDD (tạm — xem cảnh báo ở trên).
+2. **Trích dữ liệu fixture** theo từng scenario từ mệnh đề `Then` của System BDD — response success + error (BDD là source of truth cho *giá trị / behavior*, bất kể nguồn shape).
+3. **Sinh mock adapter** tại `{paths.src_dir}/{domain}/{UC-ID}MockApiAdapter.{ext}`:
+   - Implements interface `{UC-ID}ApiPort` (cùng interface mà real adapter sẽ implement)
+   - Mỗi method trả về fixture data khớp mệnh đề `Then` của BDD, theo shape của port
+   - Gồm cả trạng thái success và error (map sang các error scenario trong BDD)
+   - Tag traceability:
      ```
      @trace.mock_for={UC-ID}
      @trace.mock_source={contract | system-bdd}
      @trace.system_bdd={paths.specs_dir}/{domain}/{prd-slug}/bdd/system/{UC-ID}*.feature
-     {@trace.be_contract={UC-ID}-tech-design.md   # only when mock_source=contract}
+     {@trace.be_contract={UC-ID}-tech-design.md   # chỉ khi mock_source=contract}
      ```
-4. **Wire into service/hook layer** via environment flag or DI:
+4. **Wire vào layer service/hook** qua environment flag hoặc DI:
    ```
    const adapter = IS_MOCK ? new {UC-ID}MockApiAdapter() : new {UC-ID}ApiAdapter()
    ```
-   - `IS_MOCK` defaults to `true` in development/test env until real adapter is generated.
+   - `IS_MOCK` mặc định `true` ở môi trường development/test cho tới khi real adapter được sinh.
 
-> Tester uses the mock adapter to test all FE scenarios without waiting for BE to **deploy**.
-> Shape comes from the BE contract when available (accurate, no integration rework); else from System BDD (provisional — adjust at `--phase=integration`). Fixture *values* always come from System BDD — BDD is the source of truth for behavior.
+> Tester dùng mock adapter để test mọi FE scenario mà không cần đợi BE **deploy**.
+> Shape lấy từ BE contract khi có (chính xác, không rework integration); else từ System BDD (tạm — điều chỉnh ở `--phase=integration`). Giá trị fixture luôn từ System BDD — BDD là source of truth cho behavior.
 
 ---
 
-## Integration Phase (`--phase=integration` only)
+## Integration Phase (chỉ `--phase=integration`)
 
-*Skip this section entirely if `--phase` is not `integration`.*
+*Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
-1. **Read the integration design.** Prefer the FE tech-design §4 (port→endpoint→DTO→error mapping) at `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`, using the BE API contract `{UC-ID}-tech-design.md` as the endpoint / request-response / error-code source. If no FE tech-design exists, extract endpoints + shapes + error codes directly from the BE contract.
-2. **Read existing mock adapter** interface (`{UC-ID}ApiPort`) from the `--phase=ui` output.
-3. **Generate real API adapter** at `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
-   - Implements the same `{UC-ID}ApiPort` interface as mock adapter
-   - Makes real HTTP calls to endpoints from tech-doc contract
-   - Maps response fields to the same shapes the mock adapter returned
-   - Traceability tags:
+1. **Đọc integration design.** Ưu tiên FE tech-design §4 (mapping port→endpoint→DTO→error) tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`, dùng BE API contract `{UC-ID}-tech-design.md` làm nguồn endpoint / request-response / error-code. Nếu không có FE tech-design, trích endpoint + shape + error code trực tiếp từ BE contract.
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+3. **Sinh real API adapter** tại `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
+   - Implements cùng interface `{UC-ID}ApiPort` như mock adapter
+   - Gọi HTTP thật tới endpoint từ contract tech-doc
+   - Map field response sang cùng shape mà mock adapter trả về
+   - Tag traceability:
      ```
      @trace.implements={UC-ID}-SC{N}
-     @trace.tech_doc_revision={read from tech-doc header}
+     @trace.tech_doc_revision={đọc từ header tech-doc}
      ```
-4. **Flip wire-up**: switch DI binding / env flag so service/hook uses `{UC-ID}ApiAdapter` (real) instead of mock.
-5. **Do NOT delete mock adapter** — keep it for unit testing.
+4. **Lật wire-up**: chuyển DI binding / env flag để service/hook dùng `{UC-ID}ApiAdapter` (thật) thay vì mock.
+5. **KHÔNG xoá mock adapter** — giữ lại cho unit test.
 
 ---
 
-## Self-Review (3 rounds)
-- [ ] Every scenario has a corresponding endpoint
-- [ ] @trace.implements on every endpoint
-- [ ] Architecture layer rules respected (CLAUDE.md §2)
-- [ ] Error handling matches CLAUDE.md §5
-- [ ] No magic numbers, no debug logging
+## Self-Review (3 vòng)
+- [ ] Mỗi scenario có endpoint tương ứng
+- [ ] @trace.implements trên mọi endpoint
+- [ ] Tôn trọng quy tắc layer kiến trúc (CLAUDE.md §2)
+- [ ] Error handling khớp CLAUDE.md §5
+- [ ] Không magic number, không debug logging
 
 ## Build Verify
 ```bash
-{conventions.build_command}   # from project-context.yaml, max 3 retries
+{conventions.build_command}   # từ project-context.yaml, tối đa 3 retry
 ```
 
 ## Write Trace State
 
-Update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — for each implemented scenario, find the existing row by `sc_id` and update only these columns. *(Umbrella + `spec_source`: `trace_dir` resolves to `{spec_source}/.trace` — this command runs from `service_root` but writes the trace row into the **spec repo** (cross-repo); commit/push the spec submodule for the trace update, alongside the 2-tier code push.)*
+Cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — với mỗi scenario đã implement, tìm row có sẵn theo `sc_id` và chỉ cập nhật các cột sau. *(Umbrella + `spec_source`: `trace_dir` phân giải về `{spec_source}/.trace` — lệnh này chạy từ `service_root` nhưng ghi trace row vào **spec repo** (liên-repo); commit/push spec submodule cho lần cập nhật trace, cùng với push code 2 tầng.)*
 
-| Column | Value |
+| Cột | Giá trị |
 |--------|-------|
-| `gen_ver` | copy `spec_ver` from the current `.tsv` row (= scenario version at time of codegen) |
+| `gen_ver` | copy `spec_ver` từ row `.tsv` hiện tại (= version scenario tại thời điểm codegen) |
 | `implemented_by` | `{ControllerClass}.{methodName}` |
-| `bdd_version` | `@trace.bdd_version` from `.feature` header |
-| `tech_doc_revision` | `@trace.revision` from the **BE** contract `{UC-ID}-tech-design.md`, or `—` if none |
-| `fe_tech_doc_revision` | `@trace.revision` from the **FE** tech-design `{UC-ID}-tech-design-{platform}.md` when generating FE with `--phase=integration` (the doc whose §4 drove this adapter); `—` for BE, or for FE `--phase=ui` / no FE tech-design |
-| `fe_phase` | `ui` if `--phase=ui` \| `integrated` if `--phase=integration` \| `—` if no phase flag |
-| `last_updated` | today `YYYY-MM-DD` |
+| `bdd_version` | `@trace.bdd_version` từ header `.feature` |
+| `tech_doc_revision` | `@trace.revision` từ **BE** contract `{UC-ID}-tech-design.md`, hoặc `—` nếu không có |
+| `fe_tech_doc_revision` | `@trace.revision` từ **FE** tech-design `{UC-ID}-tech-design-{platform}.md` khi sinh FE với `--phase=integration` (doc có §4 điều khiển adapter này); `—` cho BE, hoặc cho FE `--phase=ui` / không có FE tech-design |
+| `fe_phase` | `ui` nếu `--phase=ui` \| `integrated` nếu `--phase=integration` \| `—` nếu không có flag phase |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
 
-Leave all other columns (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`) unchanged.
-`status` is computed by `/validate-traces` — do not set here.
+Giữ nguyên mọi cột khác (`sc_title`, `spec_ver`, `prd_version`, `prd_status`, `uc_status`, `test_count`, `test_classes`, `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`, `qc_owner`, `qc_blocked_by`).
+`status` được tính bởi `/validate-traces` — không set ở đây.
 
 ## Refresh Panel Mirror
-# Refresh Living Docs panel mirror *(local, umbrella mode)*
+# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
 
-*Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
-the repo's own `.trace/` IS the panel location, so nothing to mirror.*
+*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
+`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
 
-After updating the authoritative TSV(s) at `{paths.trace_dir}`:
+Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
-**When `setup.spec_source` is set (consolidated trace — the common case):**
-`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
-This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
-commit/push the spec submodule for the trace update (same as `feedback/`).
-1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
-2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
-   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
-   No per-service namespacing — there is one trace set; the owning service is carried in each
-   row's `@trace.service`.
+**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
+`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
+Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
+commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
+1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
+2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+   `{UC-ID}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}.tsv` (tạo thư mục; ghi đè).
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
+   `@trace.service` của từng row.
 
-**Legacy (no `spec_source` — per-service trace):**
-Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
-(namespaced by `active_service`).
+**Legacy (không có `spec_source` — trace theo service):**
+Copy mỗi `{UC-ID}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespace theo `active_service`).
 
-This keeps the open workspace's Living Docs panel current **between syncs** — it is a
-**local convenience mirror only**. The merged `trace-report.json` (canonical, in
-`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
-commands, do this once in the orchestrator after all sub-agents return — not inside each
-sub-agent.
+Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
+một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
+`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
+được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
+bên trong từng sub-agent.
 
 
 ## Commit
@@ -741,38 +739,38 @@ git commit -m "{commit_format}: {description}"
 
 ## Output
 
-# Report Footer — Standard Command Output Format
+# Report Footer — Định dạng output chuẩn cho mọi lệnh
 
-Every command report must end with this standard footer section.
+Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
 ## 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
+Chọn một theo kết quả:
+- `✅ Complete` — mọi bước thành công, không có vấn đề
+- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
+- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
 
 ## Output Artifacts
 
-List every file created or modified by this command:
+Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
 ```
 Output Artifacts:
-  {created|updated} {file-path} ({brief description})
-  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({mô tả ngắn})
+  {created|updated} {file-path} ({mô tả ngắn})
 ```
 
-If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `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:
+In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
+để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
 
 ```
 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:
+Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
 
 | Phase | Commands |
 |-------|----------|
@@ -786,84 +784,84 @@ Find the current command in this phase legend and mark **its** phase in the map
 | 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ới **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
 `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).
+**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
+**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
 
-## Next Command Suggestion
+## Gợi ý lệnh tiếp theo
 
-Suggest the logical next command based on workflow phase:
+Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 
-| Current command         | Suggest next                                  |
+| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
 |-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` to start your first feature |
+| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /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) |
+| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
 | /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) |
+| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
+| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` để làm mới 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}` |
+| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
+| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/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:
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
+| /dev-smoke-test             | Tạo PR và link tới ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
+| /fix-bug                | Tạo PR và link tới ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
+| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
+| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
+
+Định dạng footer như sau:
 ```
 ---
 Status   : {badge}
-{Output Artifacts block}
+{khối Output Artifacts}
 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}
+           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {lệnh gợi ý kèm ví dụ tham số}
 ```
-*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
 ```
-/generate-code Complete — {UC-ID}
+/generate-code Hoàn tất — {UC-ID}
 Files: created={N}, extended={M}, skipped={K} | Build: SUCCESS
 Branch: feature/{TICKET_ID}-{slug}
 Phase    : {UI (mock layer) | Integration (real API) | Default (full)}
 fe_phase : {ui | integrated | —}
-Figma    : {local Dev Mode MCP (grounded) | ⚠️ web links + text spec only (no local MCP) | n/a for BE}   ← FE/App UI only
+Figma    : {Dev Mode MCP local (grounded) | ⚠️ chỉ link web + text spec (không có MCP local) | n/a cho BE}   ← chỉ UI FE/App
 
 Next:
-  --phase=ui done:
-    → Notify tester: FE is testable via mock adapter
-    → Collect BE sign-offs → /review-tech-docs {tech-design-file}
-    → When BE ready → /generate-code {feature-file} --phase=integration
+  --phase=ui xong:
+    → Báo tester: FE test được qua mock adapter
+    → Thu sign-off BE → /review-tech-docs {tech-design-file}
+    → Khi BE sẵn sàng → /generate-code {feature-file} --phase=integration
 
-  --phase=integration done:
-    → /review-code {UC-ID}   ← code review required
-    → /dev-gen-test {UC-ID}  ← integration test suite
+  --phase=integration xong:
+    → /review-code {UC-ID}   ← cần code review
+    → /dev-gen-test {UC-ID}  ← bộ integration test
 
-  Default (no phase flag):
-    → /review-code {UC-ID}   ← code review required before tests
+  Default (không có flag phase):
+    → /review-code {UC-ID}   ← cần code review trước khi test
     → /dev-gen-test {UC-ID}
 
-📊 Living Docs: run /validate-traces (or /sync) to push this trace to the spec-module dashboard.
+📊 Living Docs: chạy /validate-traces (hoặc /sync) để push trace này lên dashboard spec-module.
 ```