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

package/core/commands/setup-ai-first.md

@@ -1,198 +1,198 @@
-# /setup-ai-first — Initialize Spec-Driven Docs in a Project
+# /setup-ai-first — Khởi tạo Spec-Driven Docs trong một dự án
 
-Walk the user through a one-time setup that creates all required directories, installs CLAUDE.md, and verifies the environment.
+Dẫn người dùng qua một setup một-lần tạo mọi thư mục cần thiết, cài CLAUDE.md, và verify môi trường.
 
 ## 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à file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
+   - **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/*/*/*.md` — file PRD ở gốc mỗi feature folder — 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 — **skip Gate Steps 1, 2, and 3** (there is no input file and no project context yet). Only run Step 0-B (model check). The project root is the **current working directory**. Proceed directly to the Precondition Check below.*
+*Lưu ý: Với lệnh này — **bỏ qua Gate Step 1, 2, và 3** (chưa có file input và chưa có project context). Chỉ chạy Step 0-B (model check). Project root là **thư mục làm việc hiện tại**. Đi thẳng tới Precondition Check bên dưới.*
 
 ---
 
 ## Precondition Check
 
-Check if already set up:
-- If `CLAUDE.md` **and** `.agent/project-context.yaml` both exist → ask: "This project is already initialized. Re-run setup to regenerate config files? (Y/N)"
-  - N → stop
-  - Y → continue (existing files will be preserved — each step will offer merge/skip)
-- If only `specs/` exists or only partial setup detected → continue normally (safe to re-run)
+Kiểm tra đã setup chưa:
+- Nếu cả `CLAUDE.md` **và** `.agent/project-context.yaml` đều tồn tại → hỏi: "Dự án này đã được khởi tạo. Chạy lại setup để regenerate file config? (Y/N)"
+  - N → dừng
+  - Y → tiếp tục (file có sẵn được giữ — mỗi bước sẽ đề nghị merge/skip)
+- Nếu chỉ có `specs/` hoặc phát hiện setup một phần → tiếp tục bình thường (an toàn chạy lại)
 
-## Step 0.5 — Project Type
+## Step 0.5 — Loại dự án
 
-Ask the user:
+Hỏi người dùng:
 
 ```
-What type of project is this?
-  1. Single-service  — one codebase, one platform (standard setup)
-  2. Umbrella repo   — this repo contains multiple service submodules (microservices / multi-app)
-  3. PO Spec repo    — docs only, no runnable code (PRD + design-spec only)
+Dự án này thuộc loại nào?
+  1. Single-service  — một codebase, một platform (setup chuẩn)
+  2. Umbrella repo   — repo này chứa nhiều service submodule (microservices / multi-app)
+  3. PO Spec repo    — chỉ docs, không có code chạy được (chỉ PRD + design-spec)
 ```
 
-Store the answer as `project_type`. Default to `1` if user does not answer.
+Lưu câu trả lời thành `project_type`. Mặc định `1` nếu user không trả lời.
 
-Based on answer:
+Dựa trên câu trả lời:
 
-**project_type = 1 (Single-service):** Continue standard setup below.
+**project_type = 1 (Single-service):** Tiếp tục setup chuẩn bên dưới.
 
-**project_type = 2 (Umbrella):** Ask two follow-up questions:
-- "Path to spec submodule (e.g. `free-trial-specs`)? Press Enter to skip."
-- "List services as `domain:module` pairs, comma-separated
-  (e.g. `user:java-spring,order:java-spring`). Press Enter to skip."
+**project_type = 2 (Umbrella):** Hỏi hai câu follow-up:
+- "Path tới spec submodule (vd `free-trial-specs`)? Nhấn Enter để skip."
+- "Liệt kê các service dạng cặp `domain:module`, ngăn cách bởi dấu phẩy
+  (vd `user:java-spring,order:java-spring`). Nhấn Enter để skip."
 
-Then:
-- Skip creating any `specs/` artifacts (all specs — PRD, BDD, tech-docs, design-spec — live in the spec submodule under the feature-package layout `specs/{domain}/{prd-slug}/`)
-- Create only: `.trace/`, `.agent/review/` at umbrella level
-  *(Unless user explicitly asks to create the full structure)*
-- Generate `.agent/project-context.yaml` in umbrella mode with the services and spec_source provided
-- Skip creating `CLAUDE.md` (umbrella has no single tech stack)
-- After setup, remind: "Open each service submodule separately in Claude Code to install the framework there if needed."
+Rồi:
+- Skip tạo bất kỳ artifact `specs/` nào (mọi spec — PRD, BDD, tech-docs, design-spec — sống trong spec submodule theo bố cục feature-package `specs/{domain}/{prd-slug}/`)
+- Chỉ tạo: `.trace/`, `.agent/review/` ở cấp umbrella
+  *(Trừ khi user yêu cầu rõ tạo cấu trúc đầy đủ)*
+- Sinh `.agent/project-context.yaml` ở umbrella mode với services và spec_source đã cung cấp
+- Skip tạo `CLAUDE.md` (umbrella không có một tech stack đơn)
+- Sau setup, nhắc: "Mở từng service submodule riêng trong Claude Code để cài framework ở đó nếu cần."
 
 **project_type = 3 (PO Spec repo):**
-- Create base dirs: `specs/product-definition/`, `specs/domain-knowledge/`, `feedback/`, `.agent/review/`
-- Per-feature artifacts (`specs/{domain}/{prd-slug}/{prd.md, bdd/, tech-docs/, design-spec/}`) are created on demand by the generate commands — do NOT pre-create them
-- Skip: `.trace/` (per-service, lives beside code in each service submodule)
-- Generate minimal `CLAUDE.md` with only §1 (project overview) and §7 (git conventions)
-- Ask the user: **"List your business domains (e.g. auth, payment, loyalty):"** — store as domain list for `project-context.yaml` and remind PO these names must be used consistently as `@trace.domain` in every PRD
-- Inform:
-  - Commands for PO repo: `/define-product`, `/generate-prd`, `/review-context`, `/generate-design-spec`
-  - **Critical for dev team handoff:** Every PRD must have `@trace.domain: {domain}` in its frontmatter. Dev team uses this to route generated BDD/code to the correct service submodule. Inconsistent domain names will break routing.
-  - Recommended PRD frontmatter:
+- Tạo base dir: `specs/product-definition/`, `specs/domain-knowledge/`, `feedback/`, `.agent/review/`
+- Artifact theo từng feature (`specs/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md, bdd/, tech-docs/, design-spec/}`) được tạo on demand bởi các lệnh generate — ĐỪNG tạo trước
+- Skip: `.trace/` (theo service, sống cạnh code trong mỗi service submodule)
+- Sinh `CLAUDE.md` tối thiểu chỉ với §1 (project overview) và §7 (git conventions)
+- Hỏi người dùng: **"Liệt kê các business domain của bạn (vd auth, payment, loyalty):"** — lưu thành domain list cho `project-context.yaml` và nhắc PO các tên này phải được dùng nhất quán làm `@trace.domain` trong mọi PRD
+- Thông báo:
+  - Lệnh cho PO repo: `/define-product`, `/generate-prd`, `/review-context`, `/generate-design-spec`
+  - **Quan trọng cho handoff team dev:** Mọi PRD phải có `@trace.domain: {domain}` trong frontmatter. Team dev dùng nó để route BDD/code sinh ra tới đúng service submodule. Tên domain không nhất quán sẽ phá routing.
+  - Frontmatter PRD khuyến nghị:
     ```
-    @trace.domain: {domain}    ← must match a key in dev team's services config
+    @trace.domain: {domain}    ← phải khớp một key trong services config của team dev
     @trace.id: {TICKET-ID}
     @trace.status: draft | approved
     ```
 
-## Step 1 — Create Directory Structure
+## Step 1 — Tạo cấu trúc thư mục
 
-Create these directories (skip if they exist):
+Tạo các thư mục này (skip nếu đã tồn tại):
 
 ```
 {project-root}/
 ├── specs/
-│   ├── product-definition/   ← Output of /define-product
+│   ├── product-definition/   ← Output của /define-product
 │   └── domain-knowledge/     ← business dictionary & domain context
 ├── .trace/                   ← .trace/{domain}/{prd-slug}/{UC-ID}.tsv
 └── .agent/
     └── review/
 ```
 
-**Feature-package layout** — per-feature spec artifacts are NOT pre-created. Each generate
-command creates its own folder on demand under `specs/{domain}/{prd-slug}/`:
+**Bố cục feature-package** — artifact spec theo từng feature KHÔNG được tạo trước. Mỗi lệnh generate
+tự tạo folder của nó on demand dưới `specs/{domain}/{prd-slug}/`:
 
 ```
 specs/{domain}/{prd-slug}/
-├── prd.md                    ← /generate-prd
-├── bdd/                      ← /generate-bdd (.feature files)
+├── {TICKET-ID}-{prd-slug}.md ← /generate-prd  (vd SEG01-segment-scoring-service.md)
+├── bdd/                      ← /generate-bdd (file .feature)
 ├── tech-docs/                ← /generate-tech-docs
-└── design-spec/              ← /generate-design-spec (FE/App platforms only)
+└── design-spec/              ← /generate-design-spec (chỉ platform FE/App)
 ```
 
-*Which base dirs to create varies by `project_type` set in Step 0.5:*
+*Tạo base dir nào tuỳ theo `project_type` set ở Step 0.5:*
 
-| project_type | Create | Skip |
+| project_type | Tạo | Skip |
 |---|---|---|
-| **1 — Single-service** | Base structure above (`specs/product-definition/`, `specs/domain-knowledge/`, `.trace/`, `.agent/review/`) | per-feature folders (created on demand) |
-| **2 — Umbrella** | `.trace/` + `.agent/review/` only (at umbrella root) | Everything else — **all specs live in the spec submodule (`spec_source`)** under `specs/{domain}/{prd-slug}/`; service submodules hold only **code + `.trace/`** |
-| **3 — PO Spec repo** | `specs/product-definition/`, `specs/domain-knowledge/`, **`feedback/`**, `.agent/review/` (per-feature `specs/{domain}/{prd-slug}/` folders created on demand) | `.trace/` (per-service, lives beside code in each service submodule) |
+| **1 — Single-service** | Cấu trúc base ở trên (`specs/product-definition/`, `specs/domain-knowledge/`, `.trace/`, `.agent/review/`) | folder theo feature (tạo on demand) |
+| **2 — Umbrella** | Chỉ `.trace/` + `.agent/review/` (ở umbrella root) | Mọi thứ khác — **toàn bộ spec sống trong spec submodule (`spec_source`)** dưới `specs/{domain}/{prd-slug}/`; service submodule chỉ chứa **code + `.trace/`** |
+| **3 — PO Spec repo** | `specs/product-definition/`, `specs/domain-knowledge/`, **`feedback/`**, `.agent/review/` (folder `specs/{domain}/{prd-slug}/` theo feature tạo on demand) | `.trace/` (theo service, sống cạnh code trong mỗi service submodule) |
 
-## Step 2 — Create CLAUDE.md
+## Step 2 — Tạo CLAUDE.md
 
-*Skip this step entirely if `project_type = 2` (Umbrella) — umbrella has no single tech stack.*
-*For `project_type = 3` (PO Spec repo) — create a minimal CLAUDE.md with only §1 (project overview) and §7 (git conventions). Skip §2–§6.*
+*Bỏ qua hoàn toàn step này nếu `project_type = 2` (Umbrella) — umbrella không có một tech stack đơn.*
+*Với `project_type = 3` (PO Spec repo) — tạo CLAUDE.md tối thiểu chỉ với §1 (project overview) và §7 (git conventions). Skip §2–§6.*
 
-Check if `CLAUDE.md` exists:
-- Yes → ask "Merge template or skip?"
-- No → create from the template below
+Kiểm tra `CLAUDE.md` tồn tại chưa:
+- Có → hỏi "Merge template hay skip?"
+- Không → tạo từ template bên dưới
 
-After creating, instruct: "Open CLAUDE.md and fill in the `{{PLACEHOLDER}}` values with your project information."
+Sau khi tạo, hướng dẫn: "Mở CLAUDE.md và điền các giá trị `{{PLACEHOLDER}}` bằng thông tin dự án của bạn."
 
 ### CLAUDE.md Template
 
@@ -242,27 +242,27 @@ branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
 commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
 ```
 
-## Step 3 — Create project-context.yaml
+## Step 3 — Tạo project-context.yaml
 
-*For `project_type = 2` (Umbrella):*
-- *If `.agent/project-context.yaml` was already generated by `--init --umbrella` → open it and verify/edit the `services` section (domain keys, paths, modules). Skip template copy below.*
-- *If not yet generated → ask: "Spec submodule path?" and "Services (domain:module pairs)?" then generate umbrella config (see Step 0.5 for format).*
+*Với `project_type = 2` (Umbrella):*
+- *Nếu `.agent/project-context.yaml` đã được sinh bởi `--init --umbrella` → mở nó và verify/sửa section `services` (domain key, path, module). Skip copy template bên dưới.*
+- *Nếu chưa sinh → hỏi: "Path spec submodule?" và "Services (cặp domain:module)?" rồi sinh config umbrella (xem Step 0.5 cho format).*
 
-Create `.agent/project-context.yaml` using `.agent/templates/project-context.yaml` as the source template.
+Tạo `.agent/project-context.yaml` dùng `.agent/templates/project-context.yaml` làm template nguồn.
 
-Copy the template and instruct: "Open `.agent/project-context.yaml` and fill in all `{{PLACEHOLDER}}` values. The `paths` section is pre-configured with sensible defaults — adjust if your project uses different directory names."
+Copy template và hướng dẫn: "Mở `.agent/project-context.yaml` và điền mọi giá trị `{{PLACEHOLDER}}`. Section `paths` đã được cấu hình sẵn với default hợp lý — chỉnh nếu dự án dùng tên thư mục khác."
 
-## Step 4 — Create business-dictionary.md
+## Step 4 — Tạo business-dictionary.md
 
-*Skip Steps 4 and 5 if `project_type = 2` (Umbrella) — business dictionary and core entities live in the spec submodule and are managed by the PO team. Dev team reads them from `{spec_source}/specs/domain-knowledge/`.*
+*Skip Step 4 và 5 nếu `project_type = 2` (Umbrella) — business dictionary và core entities sống trong spec submodule và do team PO quản lý. Team dev đọc chúng từ `{spec_source}/specs/domain-knowledge/`.*
 
 
-Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
+Tạo `specs/domain-knowledge/business-dictionary.md` nếu chưa tồn tại:
 
 ```markdown
 # Business Dictionary — {{PROJECT_NAME}}
 
-> Canonical terminology for this project. All PRDs, BDD specs, and code must follow these terms.
+> Thuật ngữ chuẩn cho dự án này. Mọi PRD, BDD spec, và code phải theo các thuật ngữ này.
 > Managed by: PO / SA team.
 
 ## Canonical Terms
@@ -284,17 +284,17 @@ Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
 | {Entity} | status | {value1, value2} |
 ```
 
-Instruct: "Open `specs/domain-knowledge/business-dictionary.md` and add your project terminology. This file will be read by all commands to enforce consistent naming."
+Hướng dẫn: "Mở `specs/domain-knowledge/business-dictionary.md` và thêm thuật ngữ dự án của bạn. File này sẽ được mọi lệnh đọc để enforce naming nhất quán."
 
-## Step 5 — Create core-entities.md
+## Step 5 — Tạo core-entities.md
 
-Create `specs/domain-knowledge/core-entities.md` if it does not exist:
+Tạo `specs/domain-knowledge/core-entities.md` nếu chưa tồn tại:
 
 ```markdown
 # Core Entities — {{PROJECT_NAME}}
 
-> Machine-readable entity glossary for AI-assisted development.
-> Loaded by all commands so AI knows your domain model without reading source code.
+> Glossary entity máy-đọc-được cho phát triển có AI hỗ trợ.
+> Được mọi lệnh nạp để AI biết domain model của bạn mà không cần đọc source code.
 > Managed by: Tech Lead / Architect.
 >
 > HOW TO USE:
@@ -332,89 +332,89 @@ Create `specs/domain-knowledge/core-entities.md` if it does not exist:
 *(Add more entities following the same pattern above)*
 ```
 
-Instruct: "Open `specs/domain-knowledge/core-entities.md` and define your key domain entities. Start with aggregate roots. This file is loaded by every AI command — good definitions here save significant back-and-forth during code generation."
+Hướng dẫn: "Mở `specs/domain-knowledge/core-entities.md` và định nghĩa các domain entity chính. Bắt đầu với aggregate root. File này được mọi lệnh AI nạp — định nghĩa tốt ở đây tiết kiệm đáng kể qua-lại khi sinh code."
 
-## Step 6 — Install VS Code Extension (Recommended)
+## Step 6 — Cài VS Code Extension (Khuyến nghị)
 
-Recommend the user install the **Spec Driven Docs Tools** VS Code extension — it provides Review Board + Living Documentation panels that integrate with this workflow.
+Khuyến nghị user cài extension VS Code **Spec Driven Docs Tools** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
 
 ```bash
 code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
 ```
 
-Or: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → search **Spec Driven Docs Tools**.
+Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **Spec Driven Docs Tools**.
 
-**What it does:**
-- 📋 **Review Board** — visual UI to review findings from `/refine-prd`, `/review-context`, `/review-tech-docs`
-- 📊 **Living Documentation** — traceability dashboard driven by `.trace/*.tsv`
+**Nó làm gì:**
+- 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
+- 📊 **Living Documentation** — dashboard traceability dựa trên `.trace/*.tsv`
 
 ## Step 7 — Verify
 
-Checklist varies by `project_type`:
+Checklist tuỳ theo `project_type`:
 
 **project_type = 1 (Single-service):**
-- [ ] `specs/` exists
-- [ ] `specs/product-definition/` exists
-- [ ] `specs/domain-knowledge/` exists
-- [ ] `.trace/` exists
-  *(per-feature `specs/{domain}/{prd-slug}/` folders are created on demand — not checked here)*
-- [ ] `.agent/project-context.yaml` exists
-- [ ] `CLAUDE.md` exists
-- [ ] `specs/domain-knowledge/business-dictionary.md` exists
-- [ ] `specs/domain-knowledge/core-entities.md` exists
+- [ ] `specs/` tồn tại
+- [ ] `specs/product-definition/` tồn tại
+- [ ] `specs/domain-knowledge/` tồn tại
+- [ ] `.trace/` tồn tại
+  *(folder `specs/{domain}/{prd-slug}/` theo feature tạo on demand — không check ở đây)*
+- [ ] `.agent/project-context.yaml` tồn tại
+- [ ] `CLAUDE.md` tồn tại
+- [ ] `specs/domain-knowledge/business-dictionary.md` tồn tại
+- [ ] `specs/domain-knowledge/core-entities.md` tồn tại
 
 **project_type = 2 (Umbrella):**
-- [ ] `.agent/project-context.yaml` exists with `setup.mode: umbrella`
-- [ ] `services` section has at least one entry with correct domain keys
-- [ ] `spec_source` path exists (e.g., `my-project-specs/` directory is present)
-- [ ] `.agent/review/` exists
-- [ ] Spec submodule initialized: `git submodule status` shows no `-` prefix
+- [ ] `.agent/project-context.yaml` tồn tại với `setup.mode: umbrella`
+- [ ] Section `services` có ít nhất một entry với đúng domain key
+- [ ] Path `spec_source` tồn tại (vd thư mục `my-project-specs/` có mặt)
+- [ ] `.agent/review/` tồn tại
+- [ ] Spec submodule đã init: `git submodule status` không hiện prefix `-`
 
 **project_type = 3 (PO Spec repo):**
-- [ ] `specs/product-definition/` exists
-- [ ] `specs/domain-knowledge/` exists
-- [ ] `feedback/` exists
-  *(per-feature `specs/{domain}/{prd-slug}/` folders are created on demand — not checked here)*
-- [ ] `.agent/review/` exists
-- [ ] `.agent/project-context.yaml` exists
-- [ ] `CLAUDE.md` exists (minimal)
-- [ ] `specs/domain-knowledge/business-dictionary.md` exists
-- [ ] `specs/domain-knowledge/core-entities.md` exists
+- [ ] `specs/product-definition/` tồn tại
+- [ ] `specs/domain-knowledge/` tồn tại
+- [ ] `feedback/` tồn tại
+  *(folder `specs/{domain}/{prd-slug}/` theo feature tạo on demand — không check ở đây)*
+- [ ] `.agent/review/` tồn tại
+- [ ] `.agent/project-context.yaml` tồn tại
+- [ ] `CLAUDE.md` tồn tại (tối thiểu)
+- [ ] `specs/domain-knowledge/business-dictionary.md` tồn tại
+- [ ] `specs/domain-knowledge/core-entities.md` tồn tại
 
 ## 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 |
 |-------|----------|
@@ -428,118 +428,118 @@ 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.)*
 
 
 ```
-/setup-ai-first Complete ✅
+/setup-ai-first Hoàn tất ✅
 ```
 
-Output varies by `project_type`:
+Output tuỳ theo `project_type`:
 
 **Single-service:**
 ```
 Next:
-  1. Fill CLAUDE.md (replace {{PLACEHOLDER}} values)
-  2. Fill .agent/project-context.yaml
-  3. Fill specs/domain-knowledge/business-dictionary.md
-  4. Fill specs/domain-knowledge/core-entities.md
-  5. git add and commit those 4 files
-  6. Install VS Code extension:
+  1. Điền CLAUDE.md (thay các giá trị {{PLACEHOLDER}})
+  2. Điền .agent/project-context.yaml
+  3. Điền specs/domain-knowledge/business-dictionary.md
+  4. Điền specs/domain-knowledge/core-entities.md
+  5. git add và commit 4 file đó
+  6. Cài VS Code extension:
      code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
-  7. /define-product to start your first feature
+  7. /define-product để bắt đầu feature đầu tiên
 ```
 
 **Umbrella:**
 ```
 Next:
   1. Review .agent/project-context.yaml:
-     - Update services[].path to match actual submodule directory names
-     - Update services domain keys to match @trace.domain in your PRD files
-     - Confirm spec_source path is correct
+     - Cập nhật services[].path khớp tên thư mục submodule thực tế
+     - Cập nhật domain key của services khớp @trace.domain trong các file PRD
+     - Xác nhận path spec_source đúng
 
-  2. Run /sync — one command that handles everything else:
+  2. Chạy /sync — một lệnh lo mọi thứ còn lại:
      /sync
      → git pull + submodule init + spec submodule update
-     → Auto-create .agent/project-context.yaml for each service submodule
-       (detects module from pom.xml / go.mod / package.json / pubspec.yaml etc.)
+     → Tự tạo .agent/project-context.yaml cho mỗi service submodule
+       (phát hiện module từ pom.xml / go.mod / package.json / pubspec.yaml v.v.)
      → Sync Living Docs panel
      → Refresh spec-manifest.yaml
 
-  3. Start generating:
-     /generate-bdd {spec_source}/specs/{domain}/{prd-slug}/prd.md
+  3. Bắt đầu sinh:
+     /generate-bdd {spec_source}/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
 ```
 
 **PO Spec repo:**
 ```
 Next:
-  1. Fill .agent/project-context.yaml:
-     - domains: [list all business domains — these become @trace.domain values in PRDs]
+  1. Điền .agent/project-context.yaml:
+     - domains: [liệt kê mọi business domain — chúng thành giá trị @trace.domain trong PRD]
      - project.name, project.description
-  2. Fill specs/domain-knowledge/business-dictionary.md  ← canonical terms
-  3. Fill specs/domain-knowledge/core-entities.md        ← entity glossary
-  4. git add and commit those files
-  5. Install VS Code extension:
+  2. Điền specs/domain-knowledge/business-dictionary.md  ← canonical terms
+  3. Điền specs/domain-knowledge/core-entities.md        ← entity glossary
+  4. git add và commit các file đó
+  5. Cài VS Code extension:
      code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
-  6. /define-product to start your first feature
+  6. /define-product để bắt đầu feature đầu tiên
 
-⚠️  Dev team handoff reminder:
-  - Each PRD must have @trace.domain matching one of your domains list
-  - When dev team sets up their umbrella repo, they map these domain names
-    to service submodule paths in their project-context.yaml services section
-  - Share domain names with dev team before they configure their umbrellas
+⚠️  Nhắc handoff team dev:
+  - Mỗi PRD phải có @trace.domain khớp một trong domains list của bạn
+  - Khi team dev setup umbrella repo của họ, họ map các tên domain này
+    tới path service submodule trong section services của project-context.yaml
+  - Chia sẻ tên domain với team dev trước khi họ cấu hình umbrella
 ```