spec-lite 1.1.4 → 1.1.6

package/bin/cli.js

@@ -17,6 +17,10 @@ if (command === 'install') {
   cpSync(join(pkgRoot, 'skills'), join(claudeDir, 'skills'), { recursive: true })
   console.log('✓ skills  →  .claude/skills/')
 
+  // Copy skills-overview.md → .claude/skills/skills-overview.md
+  cpSync(join(pkgRoot, 'skills-overview.md'), join(claudeDir, 'skills', 'skills-overview.md'))
+  console.log('✓ skills-overview.md  →  .claude/skills/skills-overview.md')
+
   // Copy templates → .claude/templates/
   cpSync(join(pkgRoot, 'templates'), join(claudeDir, 'templates'), { recursive: true })
   console.log('✓ templates  →  .claude/templates/')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/ado-config/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: ado-config
+description: Tạo hoặc cập nhật .claude/ado.yaml — lưu thông tin Azure DevOps project (org, project, team members, epic ticket). Dùng khi bắt đầu làm việc với một ADO project hoặc khi cần cập nhật thông tin team.
+---
+
+# ado-config
+
+## Overview
+
+Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO project dùng chung cho tất cả các skill `/ado-*`.
+
+## When to Use
+
+- Lần đầu setup ADO cho project
+- Cần cập nhật thông tin project, thành viên team, hoặc Epic ticket
+
+## When NOT to Use
+
+- Đã có `.claude/ado.yaml` và không cần thay đổi gì → dùng trực tiếp các skill `/ado-*` khác
+
+---
+
+## Process
+
+### Bước 1: Kiểm tra file hiện tại
+
+Kiểm tra xem `.claude/ado.yaml` đã tồn tại chưa.
+
+**Nếu chưa tồn tại** → tiến hành collect toàn bộ từ Bước 2.
+
+**Nếu đã tồn tại** → đọc file, hiển thị tóm tắt nội dung hiện tại:
+
+```
+.claude/ado.yaml đã tồn tại:
+
+  organization: torus-engineering
+  project_name: Galaxy GCC  (project_code: GAL-GCC)
+  team:    PE: 1 người  |  SE: 2 người  |  DE: 1 người
+  epic:    [42] [GAL-GCC] Spec Lite Kit
+           https://dev.azure.com/torus-engineering/Galaxy GCC/_workitems/edit/42
+```
+
+Sau đó **bắt buộc** gọi `AskUserQuestion`:
+
+```
+question: "Bạn muốn cập nhật phần nào?"
+options:
+  - label: "Toàn bộ từ đầu"
+    description: "Chạy lại tất cả các bước — project, team, epic, environments"
+  - label: "Thông tin project"
+    description: "Cập nhật organization, project, project_id, project_code"
+  - label: "Team members"
+    description: "Cập nhật danh sách PE / SE / DE"
+  - label: "Epic ticket"
+    description: "Tạo mới hoặc thay Epic ticket đang được lưu"
+  - label: "Môi trường"
+    description: "Cập nhật danh sách environments (dev / stag / prod)"
+```
+
+Tuỳ theo lựa chọn:
+- **"Toàn bộ từ đầu"** → chạy Bước 2 → 3 → 4 → 5 → 6 → 7
+- **"Thông tin project"** → chỉ chạy Bước 2, bỏ qua Bước 3, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `team`, `epic`, `environments` từ file cũ)
+- **"Team members"** → chỉ chạy Bước 3, bỏ qua Bước 2, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `epic`, `environments` từ file cũ)
+- **"Epic ticket"** → chỉ chạy Bước 4, bỏ qua Bước 2, 3, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `team`, `environments` từ file cũ)
+- **"Môi trường"** → chỉ chạy Bước 5, bỏ qua Bước 2, 3, 4, nhảy thẳng đến Bước 6 → 7 (giữ nguyên tất cả từ file cũ)
+
+---
+
+### Bước 2: Connect ADO và chọn project
+
+**Organization:**
+
+**Bắt buộc** gọi tool `AskUserQuestion` — không hỏi bằng plain text. Cấu hình:
+- question: `"Azure DevOps organization name?"`
+- options:
+  - label `torus-engineering`, description `Org mặc định — nhấn Enter để chọn`
+  - label `ats-technology`
+- System tự thêm option "Type something" cho phép nhập tên org khác hoặc paste full URL
+
+Kết quả:
+- User nhấn Enter → chọn `torus-engineering`
+- User dùng ↓ → chọn "Type something" → nhập tên org hoặc paste URL
+
+Nếu user nhập full URL (ví dụ `https://dev.azure.com/my-org/...`) → tự extract phần org sau `dev.azure.com/`, bỏ mọi path phía sau.
+
+**List projects qua MCP:**
+
+Sau khi có organization, gọi MCP tool `mcp__azure-devops__core_list_projects` để lấy danh sách projects trong org đó.
+
+Hiển thị numbered list và chờ user nhập số:
+
+```
+Các project trong org "torus-engineering":
+
+  1. T-Lead    (ID: f95c3b00-b3a8-4405-b062-8471a57cabd6)
+  2. C-Blok    (ID: 5d57bc02-c656-4be7-981f-4ee5ecf4ba0a)
+  3. C-GAL     (ID: be587215-de0a-4ea2-952a-d5b635b5d748)
+  4. C-GTEL    (ID: 06e852f7-83f5-48b6-a83f-81bd665e0187)
+  ...
+
+Nhập số thứ tự project:
+```
+
+Sau khi user nhập số → tự điền `project_name` và `project_id` từ kết quả MCP. Không hỏi user nhập tay.
+
+Nếu MCP call thất bại → thông báo lỗi rõ ràng và hỏi user nhập `project_name` và `project_id` thủ công.
+
+**Project Code:**
+> Project code là gì? Đây sẽ là prefix cho mọi ticket trong project.
+> (Ví dụ: `GAL-GCC`, `TORUS-BE`, `VNG-APP` — thường là 2–3 từ viết tắt, ngăn cách bởi dấu gạch ngang)
+
+Gợi ý: đề xuất project code dựa trên tên project đã chọn (ví dụ "Galaxy GCC" → `GAL-GCC`). User có thể chấp nhận hoặc nhập lại.
+
+---
+
+### Bước 3: Nhập team members
+
+Hỏi lần lượt từng role. Với mỗi role, nhập email hợp lệ, mỗi người một dòng, Enter trống khi xong:
+
+```
+PE (Product Engineer) [bắt buộc]:
+> anh.le@atstechnology.vn
+> minh.ngo@atstechnology.vn
+>
+
+SE (Software Engineer):
+> b@atstechnology.vn
+>
+
+DE (Data Engineer):
+>
+```
+
+Một người có thể đóng nhiều role — nhập lại ở role tương ứng.
+
+**PE là bắt buộc** — nếu user để trống, nhắc lại và yêu cầu nhập ít nhất 1 email hợp lệ trước khi tiếp tục.
+
+SE và DE không có ai → để trống (ghi array rỗng `[]`).
+
+---
+
+### Bước 4: Cấu hình Epic Ticket
+
+Epic Ticket là ticket đại diện cho toàn bộ project/product đang được code. Mọi Feature/Story sẽ được link vào Epic này.
+
+Hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Epic Ticket cho project {project_name} ({project_code})?"
+options:
+  - label: "Tạo Epic mới"
+    description: "Nhập title và mô tả — Claude sẽ tạo Epic trên ADO với prefix [{project_code}]"
+  - label: "Nhập ID ticket có sẵn"
+    description: "Nhập ID của Epic đã tồn tại trên ADO để validate và lưu vào config"
+```
+
+---
+
+#### Option A: Tạo Epic mới
+
+**1. Nhập title:**
+> Epic title? (sẽ được prefix thành `[{project_code}] <title>`)
+
+Ví dụ user nhập `Spec Lite Kit` → title cuối là `[SDLC-TEST] Spec Lite Kit`.
+
+**2. Nhập mô tả:**
+
+Hỏi bằng `AskUserQuestion`:
+```
+question: "Mô tả Epic?"
+options:
+  - label: "Tự nhập mô tả"
+    description: "Nhập nội dung mô tả thủ công"
+  - label: "Dùng nội dung từ spec artifact"
+    description: "Chỉ định đường dẫn file spec.md / prd.md — Claude sẽ đọc và dùng làm mô tả"
+```
+
+Nếu user chọn **"Dùng nội dung từ spec artifact"**:
+- Hỏi đường dẫn file (ví dụ `specs/integrations/001-implement-auth/spec.md`)
+- Đọc file → dùng toàn bộ nội dung làm description của Epic (format Markdown)
+
+Nếu user chọn **"Tự nhập mô tả"**:
+- Hỏi plain text mô tả, có thể để trống
+
+**3. Tạo Epic qua MCP:**
+
+Trước khi tạo, resolve email của PE đầu tiên thành ADO identity ID bằng `mcp__azure-devops__core_get_identity_ids` (dùng email từ `team.PE[0]`).
+
+Gọi `mcp__azure-devops__wit_create_work_item` với:
+- `type`: `Epic`
+- `title`: `[{project_code}] <user_title>`
+- `description`: nội dung đã nhập/đọc
+- `assignedTo`: identity ID của PE đầu tiên trong danh sách
+
+Sau khi tạo thành công → lưu `id`, `title`, và `url` vào config. URL được tạo theo format:
+
+```
+https://dev.azure.com/{organization}/{project_name}/_workitems/edit/{id}
+```
+
+Nếu resolve identity thất bại → tạo Epic không có assignee, thông báo để user tự assign thủ công trên ADO.
+
+Nếu MCP call tạo Epic thất bại → thông báo lỗi và cho phép retry hoặc bỏ qua bước này.
+
+---
+
+#### Option B: Nhập ID ticket có sẵn
+
+Hỏi user:
+> Nhập ID của Epic ticket (chỉ số, ví dụ: `42`):
+
+Sau khi user nhập → **bắt buộc validate qua MCP** bằng `mcp__azure-devops__wit_get_work_item`:
+
+**Kiểm tra các điều kiện sau:**
+1. Work item tồn tại trong ADO project đã chọn
+2. `workItemType` phải là `Epic`
+3. Title phải có prefix `[{project_code}]` — nếu không có thì cảnh báo nhưng vẫn cho phép user xác nhận tiếp tục
+
+Nếu validation fail (không tồn tại hoặc không phải Epic) → thông báo lỗi cụ thể và cho phép nhập lại.
+
+Nếu validation thành công → hiển thị thông tin ticket để user xác nhận:
+
+```
+Tìm thấy Epic:
+  ID:    42
+  Title: [SDLC-TEST] Spec Lite Kit
+  State: New
+  URL:   https://dev.azure.com/torus-engineering/Common/_workitems/edit/42
+
+Dùng Epic này? (yes/no)
+```
+
+Sau khi user confirm → lưu `id`, `title`, và `url` vào config. URL được tạo theo format:
+
+```
+https://dev.azure.com/{organization}/{project_name}/_workitems/edit/{id}
+```
+
+---
+
+### Bước 5: Cấu hình môi trường
+
+**Bắt buộc** hỏi user bằng `AskUserQuestion` — không cho phép bỏ qua:
+
+```
+question: "Project này có bao nhiêu môi trường deploy?"
+options:
+  - label: "Production only"
+    description: "1 môi trường: prod"
+  - label: "Development + Production"
+    description: "2 môi trường: dev + prod"
+  - label: "Development + Staging + Production"
+    description: "3 môi trường: dev + stag + prod"
+```
+
+Lưu kết quả dưới dạng array theo thứ tự từ thấp đến cao:
+
+| Lựa chọn | Giá trị lưu |
+|---|---|
+| Production only | `["prod"]` |
+| Development + Production | `["dev", "prod"]` |
+| Development + Staging + Production | `["dev", "stag", "prod"]` |
+
+Nếu user chọn "Other" (nhập tay) → parse chuỗi nhập vào (phân cách bởi dấu phẩy, space, hoặc `+`) → normalize thành lowercase array. Ví dụ: `"dev, staging, prod"` → `["dev", "staging", "prod"]`.
+
+---
+
+### Bước 6: Preview và xác nhận
+
+Hiển thị preview YAML sẽ được ghi — **chưa ghi file**:
+
+```
+Sẽ ghi vào .claude/ado.yaml:
+
+organization: torus-engineering
+project_name: Galaxy GCC
+project_code: GAL-GCC
+project_id: "2074c422-31ea-4b9c-9b61-fe0f749fa28d"
+
+team:
+  PE:
+    - anh.le@atstechnology.vn
+    - minh.ngo@atstechnology.vn
+  SE:
+    - b@atstechnology.vn
+    - c@atstechnology.vn
+  DE:
+    - d@atstechnology.vn
+
+epic:
+  id: 42
+  title: "[GAL-GCC] Spec Lite Kit"
+  url: "https://dev.azure.com/torus-engineering/Galaxy GCC/_workitems/edit/42"
+
+environments:
+  - dev
+  - stag
+  - prod
+
+Xác nhận ghi file? (yes/no)
+```
+
+Nếu user yêu cầu chỉnh sửa → cập nhật preview → hỏi lại.
+
+Nếu user bỏ qua bước Epic (không muốn cấu hình ngay) → bỏ qua key `epic` trong YAML, không ghi `epic: null`.
+
+**Bước 5 (môi trường) là bắt buộc** — không cho phép bỏ qua. Nếu user chưa chọn, nhắc lại trước khi tiếp tục.
+
+---
+
+### Bước 7: Ghi file
+
+Ghi nội dung đã confirm vào `.claude/ado.yaml`.
+
+**Kiểm tra .gitignore:**
+
+Đọc `.gitignore` ở root project (nếu tồn tại). Nếu có pattern nào match `.claude/ado.yaml` hoặc `.claude/` → **xóa hoặc thêm exception** để đảm bảo file được track bởi git:
+
+- Nếu `.gitignore` có dòng `.claude/` → thêm dòng `!.claude/ado.yaml` ngay bên dưới
+- Nếu `.gitignore` có dòng `.claude/ado.yaml` → xóa dòng đó
+
+Thông báo kết quả:
+
+```
+✓ .claude/ado.yaml đã được tạo/cập nhật
+
+{nếu có thay đổi .gitignore}
+✓ .gitignore — đã đảm bảo .claude/ado.yaml được track bởi git
+
+Bước tiếp theo:
+  - Commit .claude/ado.yaml để share config với team
+  - /ado-init → khởi tạo ADO project (tạo boards, iteration, areas...)
+```
+
+---
+
+## Verification
+
+Trước khi ghi file, kiểm tra:
+
+- [ ] `organization` đã được extract — chỉ là tên org, không phải full URL
+- [ ] `project_name` đã được lưu từ kết quả MCP (tên project gốc từ ADO)
+- [ ] `project_id` có dạng GUID (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)
+- [ ] Mỗi email hợp lệ (có dấu `@`)
+- [ ] `team.PE` có ít nhất 1 email — không được để trống
+- [ ] SE và DE có thể là array rỗng `[]`
+- [ ] Nếu có Epic: `epic.id` là số nguyên, `epic.title` có prefix `[{project_code}]`, `epic.url` là full URL dạng `https://dev.azure.com/{org}/{project_name}/_workitems/edit/{id}`
+- [ ] `environments` là array ít nhất 1 phần tử (bắt buộc), mỗi phần tử là lowercase string không có khoảng trắng, luôn có `prod` ở cuối
+- [ ] User đã confirm preview trước khi ghi file

package/skills/ado-create/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: ado-create
+description: Tạo Feature và User Story tickets trên ADO từ spec.md của một integration. Set parent là Epic từ ado.yaml, assign cho current user, cập nhật ticket references vào spec.md và frd.md tương ứng.
+---
+
+# ado-create
+
+## Overview
+
+Đọc `spec.md` của một integration, tạo Feature và User Story tickets trên ADO, rồi ghi ticket ID/title/URL trở lại vào `spec.md` và `frd.md` tương ứng.
+
+## Prerequisites
+
+- `.claude/ado.yaml` phải tồn tại và có `epic.id` (chạy `/ado-config` nếu chưa có)
+- `frd.md` tương ứng phải tồn tại trong `specs/main/features/` cho mỗi feature
+
+---
+
+## Process
+
+### Bước 1: Load config và xác định current user
+
+Đọc `.claude/ado.yaml`. Nếu không tồn tại → dừng và báo lỗi:
+
+```
+Chưa có .claude/ado.yaml. Hãy chạy /ado-config trước.
+```
+
+**Xác định current user:** Đọc `git config user.email`. Tìm email này trong toàn bộ `team.PE + team.SE + team.DE` của ado.yaml.
+
+**Nếu tìm thấy** → dùng email đó làm assignee.
+
+**Nếu không tìm thấy** → hỏi bằng `AskUserQuestion`:
+
+```
+question: "Bạn là ai trong team? (dùng để assign ticket)"
+options: [mỗi email trong team.PE + team.SE + team.DE thành 1 option]
+```
+
+Sau khi xác định email, resolve thành ADO identity ID bằng `mcp__azure-devops__core_get_identity_ids`.
+
+Nếu resolve thất bại → tiếp tục nhưng không set assignee; thông báo để user tự assign trên ADO sau.
+
+---
+
+### Bước 2: Chọn integration
+
+List tất cả thư mục trong `specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
+
+Hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Chọn integration để tạo ADO tickets:"
+options:
+  - label: "001-implement-auth — Implement Authentication"
+    description: "status: draft | features: F-001"
+  - label: "002-implement-todo — Implement Todo Management"
+    description: "status: draft | features: F-002, F-003"
+  - ...
+```
+
+Sau khi user chọn → đọc toàn bộ `spec.md` của integration đó.
+
+---
+
+### Bước 3: Parse spec.md
+
+Extract từ spec.md:
+
+**Features:** Tìm các heading theo pattern `### Feature: <name> (<ID>)`.
+Ví dụ: `### Feature: Đăng ký / Đăng nhập (F-001)` → `{id: "F-001", name: "Đăng ký / Đăng nhập"}`
+
+**User Stories:** Tìm các heading theo pattern `#### US-FXXX-YYY — <title>`.
+Ví dụ: `#### US-F001-001 — Đăng ký` → `{code: "US-F001-001", title: "Đăng ký", feature_id: "F-001"}`
+
+Với mỗi User Story, thu thập thêm:
+- Câu story: dòng `**<role>** muốn **<want>** để **<goal>**.`
+- `Priority`
+- Tất cả ACs bên dưới (từ `**Acceptance Criteria:**` đến heading tiếp theo)
+
+**Kiểm tra đã có ADO ticket chưa:** Ngay sau heading của mỗi Feature / User Story, tìm dòng có format `**ADO:**`. Nếu có → đánh dấu `already_created: true`, lưu lại ID/URL hiện có.
+
+---
+
+### Bước 4: Preview và xác nhận
+
+Hiển thị kế hoạch trước khi tạo — **chưa tạo gì**:
+
+```
+Integration: 001-implement-auth — Implement Authentication
+Assignee:    anh.le@torus.vn
+
+Sẽ tạo các tickets sau:
+
+  Feature Tickets (parent: Epic #24241 — [SDLC-TEST] Spec Lite Kit):
+  ✦ F-001 — Đăng ký / Đăng nhập         [NEW]
+
+  User Story Tickets:
+  ✦ US-F001-001 — Đăng ký               [NEW] → parent: F-001
+  ✦ US-F001-002 — Đăng nhập             [NEW] → parent: F-001
+  ✦ US-F001-003 — Đăng xuất             [NEW] → parent: F-001
+
+  Skip (đã có ADO ticket):
+  ✓ F-002 — ...  #12345 (đã tạo trước)
+
+Tiếp tục tạo? (yes/no)
+```
+
+Nếu user từ chối → dừng không tạo gì.
+
+---
+
+### Bước 5: Tạo Feature Tickets
+
+Thực hiện tuần tự với từng Feature chưa có ADO ticket:
+
+**5.1 Tìm frd.md:**
+
+Map `F-NNN` → tìm thư mục `specs/main/features/` bắt đầu bằng `NNN-`. Đọc `frd.md` trong thư mục đó.
+
+Nếu không tìm thấy `frd.md` → cảnh báo, dùng phần mô tả Feature từ `spec.md` làm description thay thế.
+
+**5.2 Tạo ticket:**
+
+Gọi `mcp__azure-devops__wit_create_work_item` với:
+- `type`: `Feature`
+- `title`: `[{project_code}] [{feature_id}] {feature_name}` — ví dụ: `[SDLC-TEST] [F-001] Đăng ký / Đăng nhập`
+- `description`: toàn bộ nội dung `frd.md` (giữ nguyên format Markdown)
+- `assignedTo`: ADO identity ID của current user (nếu resolve thành công)
+
+Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Epic ID, child = Feature ticket ID). Nếu tool này không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
+- `sourceId`: Feature ticket ID vừa tạo
+- `targetId`: Epic ID từ ado.yaml
+- `relationType`: `System.LinkTypes.Hierarchy-Reverse`
+
+**Nếu link parent thất bại:**
+1. Retry một lần
+2. Nếu vẫn fail → đánh dấu Feature này là `orphan` (KHÔNG xóa ticket), ghi vào danh sách cần xử lý thủ công, tiếp tục với Feature tiếp theo. Ticket orphan sẽ được báo cáo nổi bật ở Bước 10.
+
+Lưu lại `{id, title, url}`. URL format:
+```
+https://dev.azure.com/{organization}/{project_name}/_workitems/edit/{id}
+```
+
+Nếu tạo ticket thất bại → log lỗi, đánh dấu Feature này là `failed`, skip toàn bộ User Stories thuộc Feature đó, tiếp tục với Feature tiếp theo.
+
+---
+
+### Bước 6: Tạo User Story Tickets
+
+Thực hiện tuần tự với từng User Story chưa có ADO ticket:
+
+**6.1 Xác định parent Feature ticket ID:**
+
+Lấy Feature ticket ID theo thứ tự ưu tiên:
+1. Feature vừa tạo ở Bước 5 → dùng ID từ kết quả MCP
+2. Feature đã `already_created` → parse ID từ dòng `**ADO:** [#<ID> — ...](url)` trong `spec.md`
+
+Nếu Feature đó là `failed` → skip toàn bộ User Stories thuộc Feature đó, báo cáo ở Bước 10.
+Nếu Feature là `orphan` (tạo thành công nhưng link Epic thất bại) → vẫn dùng Feature ID đó làm parent cho User Stories, nhưng đánh dấu chuỗi này cần review thủ công.
+Nếu không đọc được Feature ticket ID từ bất kỳ nguồn nào → skip User Story này với cảnh báo.
+
+**6.2 Build description:**
+
+```markdown
+**{role}** muốn **{want}** để **{goal}**.
+
+**Priority:** {priority}
+
+**Acceptance Criteria:**
+
+- AC-code
+  - **Given** ...
+  - **When** ...
+  - **Then** ...
+```
+
+**6.3 Tạo ticket:**
+
+Gọi `mcp__azure-devops__wit_create_work_item` với:
+- `type`: `User Story`
+- `title`: `[{project_code}] [{feature_name}] - {US-code} — {story_title}` — ví dụ: `[SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-001 — Đăng ký`
+- `description`: description đã build ở 6.2
+- `assignedTo`: ADO identity ID của current user
+
+Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Feature ticket ID, child = User Story ticket ID). Nếu không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
+- `sourceId`: User Story ticket ID vừa tạo
+- `targetId`: Feature ticket ID
+- `relationType`: `System.LinkTypes.Hierarchy-Reverse`
+
+**Nếu link parent thất bại:**
+1. Retry một lần
+2. Nếu vẫn fail → đánh dấu User Story này là `orphan` (KHÔNG xóa ticket), ghi vào danh sách cần xử lý thủ công, tiếp tục với User Story tiếp theo.
+
+Lưu lại `{id, title, url}`.
+
+---
+
+### Bước 7: Cập nhật spec.md
+
+Sau khi tất cả tickets đã được tạo, cập nhật `spec.md`:
+
+**Với Feature ticket thành công:** Thêm dòng `**ADO:**` ngay sau heading feature, trên dòng trống đầu tiên:
+
+```markdown
+### Feature: Đăng ký / Đăng nhập (F-001)
+**ADO:** [#12345 — [SDLC-TEST] Đăng ký / Đăng nhập](https://dev.azure.com/...)
+
+**Feature-level Acceptance Criteria:**
+```
+
+**Với User Story ticket thành công:** Thêm dòng `**ADO:**` ngay sau heading user story:
+
+```markdown
+#### US-F001-001 — Đăng ký
+**ADO:** [#12346 — US-F001-001 — Đăng ký](https://dev.azure.com/...)
+
+**Nhân viên mới** muốn ...
+```
+
+---
+
+### Bước 8: Cập nhật prd.md
+
+Mở `specs/main/prd.md`. Tìm bảng `## Features`.
+
+**Nếu bảng chưa có cột `ADO`:** Thêm cột vào header và separator row:
+
+```markdown
+| ID | Feature | Mô tả | Priority | Status | ADO |
+| --- | --- | --- | --- | --- | --- |
+```
+
+Với mỗi Feature ticket vừa tạo thành công, tìm row tương ứng theo `ID` (ví dụ `F-001`) và thêm link vào cột `ADO`:
+
+```markdown
+| F-001 | Đăng ký / Đăng nhập | ... | Must | In Progress | [#12345](url) |
+```
+
+Nếu cột `ADO` đã tồn tại và row đã có giá trị → **không ghi đè**, bỏ qua.
+
+---
+
+### Bước 9: Cập nhật frd.md
+
+Với mỗi `frd.md` thuộc integration này:
+
+Tìm section `## ADO Tickets` trong file.
+
+**Nếu chưa có:** Append vào cuối file:
+
+```markdown
+
+## ADO Tickets
+
+| Type | Code | Ticket |
+|------|------|--------|
+| Feature | F-001 | [#12345 — [SDLC-TEST] Đăng ký / Đăng nhập](url) |
+| User Story | US-F001-001 | [#12346 — US-F001-001 — Đăng ký](url) |
+| User Story | US-F001-002 | [#12347 — US-F001-002 — Đăng nhập](url) |
+| User Story | US-F001-003 | [#12348 — US-F001-003 — Đăng xuất](url) |
+```
+
+**Nếu đã có:** Append các row mới (tickets vừa tạo) vào cuối bảng. Không xóa row cũ.
+
+---
+
+### Bước 10: Tóm tắt kết quả
+
+```
+✓ ADO tickets đã tạo — integration: 001-implement-auth
+
+  Feature Tickets:
+  ✓ #12345 — [SDLC-TEST] [F-001] Đăng ký / Đăng nhập
+    https://dev.azure.com/torus-engineering/Common/_workitems/edit/12345
+
+  User Story Tickets:
+  ✓ #12346 — [SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-001 — Đăng ký    → F-001 #12345
+  ✓ #12347 — [SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-002 — Đăng nhập  → F-001 #12345
+  ✓ #12348 — [SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-003 — Đăng xuất  → F-001 #12345
+
+  Files đã cập nhật:
+  ✓ specs/integrations/001-implement-auth/spec.md
+  ✓ specs/main/features/001-auth/frd.md
+  ✓ specs/main/prd.md
+
+  {nếu có lỗi tạo ticket}
+  ✗ US-F001-004 — ... → tạo thất bại: <lý do>
+
+  {nếu có orphan — cần xử lý thủ công NGAY}
+  ⚠ ORPHAN — ticket tồn tại nhưng CHƯA có parent:
+    #12349 — US-F001-005 — ...
+    → Cần link thủ công: parent = Feature #12345
+    → https://dev.azure.com/torus-engineering/Common/_workitems/edit/12349
+```
+
+---
+
+## Verification Checklist
+
+Trước khi tạo ticket:
+- [ ] `.claude/ado.yaml` tồn tại và `epic.id` là số nguyên hợp lệ
+- [ ] Integration được chọn có `spec.md` chứa ít nhất 1 Feature
+- [ ] `frd.md` tìm được cho mỗi Feature (cảnh báo nếu thiếu, không dừng)
+
+Khi tạo ticket:
+- [ ] Feature type là `Feature` — không phải `Epic` hay `User Story`
+- [ ] User Story type là `User Story`
+- [ ] Parent link được thực hiện **ngay sau khi tạo ticket** — không để cuối batch
+- [ ] Nếu parent link fail: retry 1 lần, nếu vẫn fail → đánh dấu `orphan`, báo cáo ở Bước 10, KHÔNG im lặng bỏ qua
+- [ ] `already_created` Feature: lấy ticket ID từ `**ADO:**` trong spec.md để dùng làm parent cho User Stories
+- [ ] Title Feature theo format `[{project_code}] [{feature_id}] {feature_name}`
+- [ ] Title User Story theo format `[{project_code}] [{feature_name}] - {US-code} — {story_title}`
+
+Khi cập nhật file:
+- [ ] `**ADO:**` được thêm vào đúng vị trí trong `spec.md` (ngay sau heading, trước nội dung)
+- [ ] Chỉ ghi khi ticket tạo **thành công** — không ghi nếu failed
+- [ ] `frd.md` section `## ADO Tickets` không duplicate row đã tồn tại
+- [ ] `prd.md` cột `ADO` chỉ thêm vào feature row tương ứng — không ghi đè nếu đã có giá trị

package/skills/ado-update/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: ado-update
+description: Cập nhật trạng thái (state) cho tất cả User Story và Feature tickets trên ADO theo tiến trình deploy/verify qua từng môi trường được cấu hình trong ado.yaml.
+---
+
+# ado-update
+
+## Overview
+
+Đọc `spec.md` của một integration, kiểm tra ADO tickets đã tồn tại chưa, sau đó cho phép user chọn trạng thái mới để cập nhật đồng loạt toàn bộ User Story tickets — và tuỳ chọn cả Feature tickets.
+
+---
+
+## Prerequisites
+
+- `.claude/ado.yaml` phải tồn tại và có `environments` (chạy `/ado-config` nếu chưa có)
+- Tất cả Feature và User Story trong integration phải đã có ADO ticket (chạy `/ado-create` nếu chưa có)
+
+---
+
+## State Source
+
+State names **không được generate từ `environments`** — chúng được lấy trực tiếp từ ADO bằng `mcp__azure-devops__wit_get_work_item_type`. Mỗi project có thể đặt tên state khác nhau (ví dụ: `dev` có thể là `Deploy Test` thay vì `Deploy Dev`).
+
+- **User Story states**: fetch từ ADO work item type `User Story`
+- **Feature states**: fetch từ ADO work item type `Feature`
+
+State list hiển thị cho user là danh sách `states` thực tế từ ADO response, **đã qua bước filter theo environments được cấu hình**.
+
+---
+
+## Environment-State Filtering
+
+ADO thường định nghĩa state cho mọi environment có thể có (dev, stag, prod). Sau khi fetch, **filter bớt các state không tương ứng với environments trong `.claude/ado.yaml`** trước khi hiển thị cho user.
+
+### Quy tắc filter
+
+**Bước 1 — Tách state thành 2 nhóm:**
+
+- **Nhóm environment-specific**: state khớp pattern `Deploy *` hoặc `Verify *` (ví dụ: Deploy Test, Verify Test, Deploy Stag, Verify Stag, Deploy Prod, Verify Prod)
+- **Nhóm general**: tất cả state còn lại (New, Pending, In Progress, Done, Removed, v.v.) — giữ nguyên, không filter
+
+**Bước 2 — Group environment-specific states thành pairs:**
+
+Sắp xếp theo thứ tự xuất hiện trong ADO response, group thành cặp `(Deploy X, Verify X)` theo thứ tự:
+- Pair 0 → tương ứng `environments[0]`
+- Pair 1 → tương ứng `environments[1]`
+- Pair N → tương ứng `environments[N]`
+
+**Bước 3 — Giữ chỉ các pairs có index nằm trong danh sách environments:**
+
+Environments trong config có bao nhiêu phần tử → giữ bấy nhiêu pairs (theo đúng thứ tự). Pairs thừa (tương ứng env không có trong config) → loại bỏ.
+
+### Ví dụ
+
+Config: `environments: [dev, prod]` → 2 environments
+
+ADO trả về states (theo thứ tự): New, Pending, In Progress, Deploy Test, Verify Test, Deploy Stag, Verify Stag, Deploy Prod, Verify Prod, Done, Removed
+
+Environment-specific pairs (theo thứ tự ADO):
+- Pair 0: (Deploy Test, Verify Test) → `environments[0]` = dev ✓ giữ
+- Pair 1: (Deploy Stag, Verify Stag) → `environments[1]` = prod ✗ nhưng config[1] = prod, không phải stag → loại
+- Pair 2: (Deploy Prod, Verify Prod) → `environments[2]` = không có (chỉ có 2 env) → loại
+
+Vì config có 2 environments → giữ 2 pairs đầu tiên: Pair 0 (dev) và Pair 2 (prod):
+- Pair 0: (Deploy Test, Verify Test) → env[0] = dev ✓
+- Pair 2: (Deploy Prod, Verify Prod) → env[1] = prod ✓
+
+State list sau filter: New, Pending, In Progress, Deploy Test, Verify Test, Deploy Prod, Verify Prod, Done, Removed
+
+> **Lưu ý về mapping positional:** Tổng số pairs ADO trả về có thể nhiều hơn số environments trong config. Map theo vị trí index trong danh sách pairs: pair thứ 0 → env thứ 0, pair thứ 1 → env thứ 1. Pairs có index ≥ số environments trong config → loại bỏ.
+
+---
+
+## Process
+
+### Bước 1: Load config
+
+Đọc `.claude/ado.yaml`. Nếu không tồn tại → dừng:
+
+```
+Chưa có .claude/ado.yaml. Hãy chạy /ado-config trước.
+```
+
+Nếu `environments` trống hoặc không tồn tại trong file → dừng:
+
+```
+.claude/ado.yaml chưa có danh sách environments. Hãy chạy /ado-config để cập nhật.
+```
+
+---
+
+### Bước 2: Chọn integration
+
+List tất cả thư mục trong `specs/integrations/` trừ `000-scaffold`. Với mỗi thư mục, đọc frontmatter của `spec.md` để lấy `title` và `status`.
+
+Hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Chọn integration để cập nhật ADO ticket status:"
+options:
+  - label: "001-implement-auth — Implement Authentication"
+    description: "status: draft | features: F-001"
+  - label: "002-implement-todo — Implement Todo Management"
+    description: "status: draft | features: F-002, F-003"
+  ...
+```
+
+Sau khi user chọn → đọc toàn bộ `spec.md` của integration đó.
+
+---
+
+### Bước 3: Parse và kiểm tra ADO tickets
+
+**Parse spec.md** để extract:
+
+**Features:** Tìm heading `### Feature: <name> (<ID>)` hoặc heading Feature tương đương. Sau mỗi heading, tìm dòng `**ADO F-XXX:**` hoặc `**ADO:**` để lấy ticket ID.
+
+**User Stories:** Tìm heading `#### US-FXXX-YYY — <title>`. Sau mỗi heading, tìm dòng `**ADO:**` để lấy ticket ID.
+
+**Quy tắc parse ADO ticket ID:** Tìm pattern `[#(\d+)` trong dòng `**ADO**` và extract số đó làm ticket ID.
+
+**Kiểm tra đầy đủ tickets:**
+
+- Nếu **bất kỳ** Feature hoặc User Story nào **chưa có** dòng `**ADO:**` → dừng và báo:
+
+```
+Integration "002-implement-todo" chưa có đầy đủ ADO tickets.
+
+  Thiếu tickets:
+  ✗ F-002 — Quản lý todo (chưa có Feature ticket)
+  ✗ US-F002-003 — Xóa task (chưa có User Story ticket)
+
+Hãy chạy /ado-create trước để tạo đầy đủ tickets.
+```
+
+- Nếu **tất cả** đều có → tiếp tục Bước 4.
+
+---
+
+### Bước 4: Fetch states từ ADO và hiển thị tickets hiện tại
+
+Thực hiện **song song**:
+
+1. Gọi `mcp__azure-devops__wit_get_work_items_batch_by_ids` với tất cả ticket IDs (Feature + User Story) để lấy state hiện tại.
+2. Gọi `mcp__azure-devops__wit_get_work_item_type` với `workItemType: "User Story"` để lấy danh sách states thực tế.
+3. Gọi `mcp__azure-devops__wit_get_work_item_type` với `workItemType: "Feature"` để lấy danh sách Feature states thực tế.
+
+Extract `states[].name` từ response của mỗi work item type — đây là danh sách state hợp lệ sẽ dùng ở Bước 5 và 7.
+
+Hiển thị tóm tắt trạng thái hiện tại:
+
+```
+Integration: 002-implement-todo — Implement Todo Management
+
+  User Story Tickets:
+  • #24255 — US-F003-001 — Xem Shared Kanban Board       [New]
+  • #24256 — US-F002-001 — Tạo task mới                  [New]
+  • #24257 — US-F002-002 — Sửa task                      [Deploy Test]
+  • #24258 — US-F002-003 — Xóa task                      [Verify Test]
+
+  Feature Tickets:
+  • #24253 — F-002 — Quản lý todo                        [In Development]
+  • #24254 — F-003 — Shared dashboard                    [In Design]
+```
+
+---
+
+### Bước 5: Chọn state mới cho User Story tickets
+
+Dùng danh sách `states[].name` đã fetch từ ADO ở Bước 4, **áp dụng Environment-State Filtering** (xem phần trên) để loại bỏ các state không tương ứng với environments được cấu hình.
+
+In ra danh sách đánh số dạng plain text — **không dùng `AskUserQuestion`** vì số state có thể vượt quá 4 options.
+
+Ví dụ output với `environments: [dev, prod]` (đã filter bỏ Deploy Stag, Verify Stag):
+
+```
+Chọn state mới cho tất cả User Story tickets:
+
+  1. New
+  2. Pending
+  3. Committed
+  4. In Progress
+  5. Deploy Test
+  6. Verify Test
+  7. Deploy Prod
+  8. Verify Prod
+  9. Done
+  10. Removed
+
+Nhập số (1–10):
+```
+
+Chờ user nhập số. Nếu input không hợp lệ → in lại danh sách và nhắc nhập lại.
+
+---
+
+### Bước 6: Xác nhận và cập nhật User Story tickets
+
+Hiển thị preview trước khi cập nhật:
+
+```
+Sẽ cập nhật 4 User Story tickets → "Verify Dev":
+
+  • #24255 — US-F003-001 — Xem Shared Kanban Board       [New] → [Verify Dev]
+  • #24256 — US-F002-001 — Tạo task mới                  [New] → [Verify Dev]
+  • #24257 — US-F002-002 — Sửa task                      [Deploy Dev] → [Verify Dev]
+  • #24258 — US-F002-003 — Xóa task                      [Verify Dev] → (không đổi)
+
+Tiếp tục? (yes/no)
+```
+
+Các ticket đã ở đúng state rồi → hiển thị "(không đổi)", không gọi API update.
+
+Nếu user xác nhận → gọi `mcp__azure-devops__wit_update_work_item` tuần tự cho từng ticket cần cập nhật:
+- `id`: ticket ID
+- `state`: state mới đã chọn
+
+Nếu update thất bại → log lỗi, tiếp tục với ticket tiếp theo, báo cáo ở Bước 8.
+
+---
+
+### Bước 7: Hỏi về Feature tickets
+
+Sau khi hoàn tất User Story, hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Bạn có muốn cập nhật state cho Feature tickets không?"
+options:
+  - label: "Có, cập nhật Feature tickets"
+    description: "Chọn state mới và cập nhật tất cả Feature tickets của integration này"
+  - label: "Không, bỏ qua"
+    description: "Giữ nguyên state hiện tại của Feature tickets"
+```
+
+**Nếu user chọn "Không"** → nhảy thẳng đến Bước 8.
+
+**Nếu user chọn "Có":**
+
+In danh sách đánh số dạng plain text — **không dùng `AskUserQuestion`** — dùng Feature states đã fetch từ ADO ở Bước 4:
+
+```
+Chọn state mới cho tất cả Feature tickets:
+
+  1. New
+  2. In Design
+  3. In Development
+  4. Done
+  5. Removed
+
+Nhập số (1–5):
+```
+
+Chờ user nhập số. Nếu input không hợp lệ → in lại danh sách và nhắc nhập lại.
+
+Hiển thị preview giống Bước 6 cho Feature tickets, xác nhận rồi gọi `mcp__azure-devops__wit_update_work_item` cho từng ticket cần cập nhật.
+
+---
+
+### Bước 8: Tóm tắt kết quả
+
+```
+✓ Cập nhật ADO ticket status — integration: 002-implement-todo
+
+  User Story Tickets → "Verify Dev":
+  ✓ #24255 — US-F003-001 — Xem Shared Kanban Board
+  ✓ #24256 — US-F002-001 — Tạo task mới
+  ✓ #24257 — US-F002-002 — Sửa task
+  — #24258 — US-F002-003 — Xóa task  (không đổi — đã là Verify Dev)
+
+  Feature Tickets → "In Development":
+  ✓ #24253 — F-002 — Quản lý todo
+  — #24254 — F-003 — Shared dashboard  (không đổi — đã là In Development)
+
+  {nếu có lỗi}
+  ✗ #24260 — US-F002-004 — ... → cập nhật thất bại: <lý do>
+```
+
+---
+
+## Verification Checklist
+
+Trước khi cập nhật:
+- [ ] `.claude/ado.yaml` tồn tại và có `environments` là array không rỗng
+- [ ] Tất cả Features và User Stories trong `spec.md` đều có dòng `**ADO:**` với ticket ID hợp lệ
+- [ ] State list lấy từ ADO qua `wit_get_work_item_type` — **không generate từ `environments`**, không hardcode
+- [ ] State list đã qua **Environment-State Filtering**: chỉ hiển thị Deploy/Verify pairs tương ứng với environments trong config; general states giữ nguyên
+- [ ] State selection dùng numbered list plain text — **không dùng `AskUserQuestion`** (số options vượt giới hạn 4)
+- [ ] User đã xem preview và xác nhận trước khi gọi API
+
+Khi cập nhật:
+- [ ] Chỉ gọi API update cho ticket **chưa ở đúng state** — không update nếu state không đổi
+- [ ] Gọi tuần tự, không batch update (để xử lý lỗi từng ticket riêng lẻ)
+- [ ] Nếu 1 ticket fail → tiếp tục với ticket tiếp theo, không dừng toàn bộ
+- [ ] Feature tickets chỉ update khi user **chủ động chọn "Có"** ở Bước 7

package/skills/spec-brownfield-feature/SKILL.md

@@ -95,7 +95,16 @@ Sau khi confirm, assign F-XXX IDs theo thứ tự tăng dần.
 
 ### Bước 4: Scan sâu từng feature
 
-**4a. User stories — infer từ:**
+**4a. User flows — infer từ:**
+- Test file chains nhiều request liên tiếp → detect luồng thao tác có thứ tự
+- Navigation / router config trong UI code (`steps`, `wizard`, `onNext`) → detect bước chuyển màn
+- State machine hoặc status enum (`pending → processing → done`) → detect nhánh edge case
+- Error handling branches trong use case → detect luồng thất bại
+
+Đánh dấu source: `(inferred from tests)` hoặc `(inferred from UI navigation)`.
+Nếu không detect được → User Flows section sẽ là NEEDS_CLARIFY.
+
+**4b. User stories — infer từ:**
 - Use case class names và public methods → action descriptions
 - Route names + HTTP methods → "As a user, I want to POST /auth/register..."
 - Test `describe` / `it` blocks → `it('should register a new user', ...)` → user story
@@ -149,11 +158,13 @@ Với mỗi feature, generate 2 files dùng templates tương ứng:
 
 **`frd.md`** — WHAT (dùng `.claude/templates/main/feature/frd-template.md`):
 - Description và business goal (infer từ feature name + use case, NEEDS_CLARIFY nếu không rõ)
+- User flows: Mermaid flowchart cho happy case và edge cases (infer từ test chains / UI navigation, NEEDS_CLARIFY nếu không detect được)
 - User stories (đánh dấu source)
 - Acceptance criteria (extract từ tests nếu có, NEEDS_CLARIFY nếu không)
 - Scope: In scope từ detected routes/actions; Out of scope → NEEDS_CLARIFY
-- Components consumed: list C-XXX từ Component Index
-- Dependencies: feature-to-feature dependencies nếu detect được
+- Dependencies:
+  - Feature Dependencies: feature-to-feature dependencies nếu detect được
+  - Components Used: list C-XXX từ Component Index (infer từ import statements)
 
 **`fdd.md`** — HOW / inter-component (dùng `.claude/templates/main/feature/fdd-template.md`):
 - Inter-component data flow: sequence diagram từ detected call chain (Mermaid hoặc ASCII)

package/skills/spec-new/SKILL.md

@@ -65,10 +65,11 @@ frd.md — F-001 Authentication đã tồn tại.
 Sections hiện có:
 
   [1] Overview
-  [2] Feature-level Acceptance Criteria
-  [3] User Stories
-  [4] Scope (In Scope / Out of Scope)
-  [5] Dependencies
+  [2] User Flows
+  [3] Feature-level Acceptance Criteria
+  [4] User Stories
+  [5] Scope (In Scope / Out of Scope)
+  [6] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
   [S] Lên spec từ frd.md hiện tại — frd.md đã đầy đủ, không cần chỉnh
 
@@ -86,7 +87,7 @@ Lưu lại lựa chọn section.
 
 Từ raw requirement, agent xác định features và components liên quan, rồi load các file sau:
 
-- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index
+- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index; **đặc biệt ghi nhận cột `ADO` trong bảng Features** — nếu feature đã có ticket ID thì lưu lại `{feature_id → ado_ticket_id, ado_ticket_title, ado_ticket_url}`
 - `specs/main/domain.md` — đọc Glossary và Shared Entities
 - `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
 - `specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
@@ -162,6 +163,15 @@ Tổng hợp và viết draft `spec.md`:
 
 **Cấu trúc file**: dùng `.claude/templates/integrations/spec-template.md` làm skeleton, điền nội dung từ interview vào.
 
+**ADO references từ prd.md:** Với mỗi Feature heading (`### Feature: <name> (<ID>)`) trong spec.md, nếu feature đó đã có ADO ticket trong `prd.md` → thêm ngay dòng `**ADO:**` bên dưới heading:
+
+```markdown
+### Feature: Đăng ký / Đăng nhập (F-001)
+**ADO:** [#12345 — [SDLC-TEST] Đăng ký / Đăng nhập](https://dev.azure.com/...)
+```
+
+Điều này đảm bảo `/ado-create` nhận biết feature đã có ticket và không tạo duplicate.
+
 **Cascade Proposals** — agent đề xuất delta cho main artifacts theo các targets sau (chỉ điền nếu thực sự có thay đổi, không thì ghi "Không có thay đổi đề xuất."):
 
 ### prd.md
@@ -223,11 +233,11 @@ frd.md — F-001 Authentication đã tồn tại.
 Sections hiện có:
 
   [1] Overview
-  [2] Components Consumed
+  [2] User Flows
   [3] Feature-level Acceptance Criteria
   [4] User Stories
   [5] Scope (In Scope / Out of Scope)
-  [6] Dependencies
+  [6] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
 
 Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):

package/templates/main/feature/frd-template.md

@@ -15,13 +15,29 @@ referenced_by:
 
 {Mô tả feature này giải quyết vấn đề gì cho user nào, trong 2-3 câu.}
 
-## Components Consumed
+## User Flows
 
-Các component mà feature này dùng — tham chiếu đến `specs/main/component/{C-XXX}-...`.
+{Mô tả các luồng thao tác của user để hoàn thành mục tiêu của feature này.}
+{Mỗi flow là một Mermaid flowchart riêng, bao gồm happy case và tất cả edge cases quan trọng.}
 
-| Component | Vai trò trong feature |
-| --- | --- |
-| `{C-XXX}-{component-name}` | {component này phục vụ cái gì cho feature này} |
+### Flow 1: {Tên luồng chính}
+
+```mermaid
+flowchart TD
+    A([{Điểm bắt đầu}]) --> B[{Bước 1}]
+    B --> C{Điều kiện?}
+    C -- Happy case --> D[{Bước 2 — thành công}]
+    C -- Edge case --> E[{Xử lý lỗi / nhánh phụ}]
+    D --> F([{Kết thúc thành công}])
+    E --> G([{Kết thúc thất bại / fallback}])
+```
+
+### Flow 2: {Tên luồng phụ / edge case lớn} *(nếu có)*
+
+```mermaid
+flowchart TD
+    A([{Điểm bắt đầu}]) --> B[{...}]
+```
 
 ## Feature-level Acceptance Criteria
 
@@ -83,6 +99,16 @@ US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature.
 
 ## Dependencies
 
+### Feature Dependencies
+
 | Feature | Loại | Ghi chú |
 | --- | --- | --- |
 | {feature-name} | required before / parallel | {lý do} |
+
+### Components Used
+
+Tham chiếu đến `specs/main/component/{C-XXX}-...`.
+
+| Component | Vai trò trong feature |
+| --- | --- |
+| `{C-XXX}-{component-name}` | {component này phục vụ cái gì cho feature này} |