spec-lite 1.1.6 → 1.1.8

package/skills-overview.md

@@ -0,0 +1,462 @@
+# Skills Overview
+
+---
+
+## Getting Started — Greenfield
+
+Dùng khi bắt đầu dự án mới chưa có code. Mục tiêu: bootstrap `prd.md`, `domain.md`, `sad.md` thông qua interview có cấu trúc, sau đó chuyển vào **Integration Pipeline** để implement.
+
+| Command | Reads | Writes |
+| --- | --- | --- |
+| `/spec-prd` | — | `specs/main/prd.md`, `specs/main/domain.md` *(skeleton)* |
+| `/spec-sad` | `prd.md`, `domain.md` | `specs/main/sad.md` |
+
+### `/spec-prd`
+
+Tạo hoặc cập nhật `specs/main/prd.md` thông qua interview có cấu trúc. Ngoài ra **scaffold luôn `specs/main/domain.md` skeleton** (Glossary placeholder + Shared Entities rỗng) — domain mọc dần qua cascade từ integrations.
+
+**Sections template** (7): Problem Statement · Target Users · Scope · Features · Components · Non-Functional Requirements · Business Constraints
+
+**Khi file chưa tồn tại hoặc là template rỗng** → full interview tuần tự từng section.
+
+**Khi file đã có nội dung** → quét tất cả `##` headings theo thứ tự xuất hiện trong file, hiển thị menu:
+- Section thuộc template: `✓ đã có` hoặc `✗ chưa có — cần bổ sung`
+- Section thừa (không có trong template): `⚠ không có trong template`
+- Option `[A]` để interview tất cả sections thuộc template
+
+Chọn số section thuộc template → interview rồi merge vào file.
+Chọn số section thừa → xoá ngay.
+Chọn `A` → interview tuần tự 7 sections template (sections thừa không bị đụng tới).
+
+---
+
+### `/spec-sad`
+
+Tạo hoặc cập nhật `specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại (cả hai do `/spec-prd` scaffold).
+
+Trước khi interview, đọc `prd.md` (NFRs, constraints) và `domain.md` (glossary, shared entities) để surface assumptions và đề xuất options phù hợp khi user chưa quyết định.
+
+**Sections template** (7): Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails
+
+**Khi file chưa tồn tại** → full interview tuần tự từng section.
+
+**Khi file đã có nội dung** → cùng cơ chế quét + menu như `/spec-prd`.
+
+Nếu `prd.md` chưa có → dừng, yêu cầu chạy `/spec-prd` trước.
+
+> **Lưu ý:** Architectural Guardrails là phần quan trọng nhất của SAD — skill luôn hỏi riêng về phần này khi review, vì đây là constraints mà mọi agent phải tuân theo khi sinh `tech.md`.
+
+---
+
+### Thứ tự thực hiện
+
+```
+/spec-prd → /spec-sad
+                │
+                │ (có thể chạy /scaffold để khởi tạo project structure)
+                │
+                ▼
+        → Integration Pipeline
+```
+
+---
+
+## Getting Started — Brownfield
+
+Dùng khi onboarding một project đã có code vào SDD. Mục tiêu: extract main artifacts từ codebase hiện có, sau đó chuyển vào **Integration Pipeline** để implement.
+
+**Thứ tự bắt buộc:** `init` → `component` → `feature`
+
+| Command | Scan | Reads | Writes |
+| --- | --- | --- | --- |
+| `/spec-brownfield-init [path]` | tech stack, README, auth, infra | attachments | `prd.md` *(no indexes)*, `domain.md` *(glossary only)*, `sad.md` |
+| `/spec-brownfield-component [path]` | module dirs, service/controller/entity files | `prd.md`, `domain.md` | `component/{C-XXX}-*/crd.md + cdd.md`; update `prd.md` Component Index; cascade Shared Entities → `domain.md` |
+| `/spec-brownfield-feature [path]` | use cases, routes, test files | `prd.md`, `domain.md`, `component/*/crd.md` | `feature/{F-XXX}-*/frd.md + fdd.md`; update `prd.md` Feature Index |
+
+### Phân chia trách nhiệm
+
+Mỗi skill chịu trách nhiệm duy nhất cho phần nó scan — **không có scan nào bị lặp lại**:
+
+| | init | component | feature |
+|---|---|---|---|
+| Discover what exists | product/arch level | scan module dirs → discover components | scan routes/use cases → discover features |
+| Deep code scan | ✗ | ✓ files bên trong từng component | ✓ use cases, tests, call chains |
+| Write back to prd.md | skeleton (no indexes) | Component Index | Feature Index |
+| Cascade to domain.md | Glossary skeleton | Shared Entities | ✗ |
+
+### Điểm khác biệt so với greenfield
+
+- **Scan trước, hỏi sau** — agent build structural picture từ code trước khi đặt câu hỏi.
+- **Pre-filled options** — user confirm/adjust, không nhập từ đầu. Luôn có `[0] Chưa rõ → NEEDS_CLARIFY`.
+- **Batch generation** — component/feature artifacts generate theo batch, review ở cuối.
+- **NEEDS_CLARIFY** không block flow — có thể fill in dần sau.
+
+---
+
+### `/spec-brownfield-init [path]`
+
+**Mục tiêu:** `prd.md` (product context, không có Component/Feature Index), `domain.md` (Glossary only), `sad.md`
+
+**Scan**: package files → tech stack · README/docs → business context · top-level dir structure → architecture style · auth/middleware → cross-cutting concerns · docker-compose/infra → deployment info
+
+**prd.md interview** (5 phần): Problem Statement · Target Users · Scope · NFRs · Business Constraints
+
+Component Index và Feature Index **để placeholder** — sẽ được điền bởi skill component và feature.
+
+**domain.md**: chỉ Glossary từ README/docs terms. Shared Entities trống — sẽ được cascade từ skill component.
+
+**sad.md**: auto-fill từ scan + hỏi 2 câu (Guardrails + additional constraints).
+
+---
+
+### `/spec-brownfield-component [path]`
+
+**Mục tiêu:** `crd.md` + `cdd.md` cho mỗi component + điền prd.md Component Index + cascade Shared Entities vào domain.md
+
+**Precondition:** `prd.md` tồn tại (init đã chạy).
+
+**Bước 1 — Discover:** scan module dirs (`src/modules/`, `services/`, `packages/`, `apps/`) → detect component candidates → present cho user confirm/adjust → assign C-XXX IDs.
+
+**Bước 2 — Deep scan từng component:** responsibilities (service methods) · owned entities (entity files) · public interface (controller routes + events) · dependencies (imports) · business rules (validators/guards) · internal design (cho cdd.md).
+
+**Bước 3 — Identify cross-component entities:** entities được import bởi 2+ components → candidate Shared Entities.
+
+**Bước 4 — Generate batch:** crd.md + cdd.md cho tất cả. Batch clarification tối đa 5 câu.
+
+**Bước 5 — Write back:** update prd.md Component Index + cascade Shared Entities vào domain.md (nếu có).
+
+---
+
+### `/spec-brownfield-feature [path]`
+
+**Mục tiêu:** `frd.md` + `fdd.md` cho mỗi feature + điền prd.md Feature Index
+
+**Precondition:** `prd.md` Component Index đã có entries (component skill đã chạy). fdd.md cần C-XXX IDs để mô tả inter-component flows — nếu Component Index trống thì skill dừng và yêu cầu chạy component skill trước.
+
+**Bước 1 — Discover:** scan use case files, route groups, test describe blocks, page/screen dirs → detect feature candidates → present cho user confirm/adjust → assign F-XXX IDs.
+
+**Bước 2 — Deep scan từng feature:** user stories (infer từ use case + routes + tests) · AC (extract từ test assertions, đánh dấu source) · components consumed (map sang C-XXX) · inter-component call chain (cho fdd.md).
+
+**Bước 3 — Generate batch:** frd.md + fdd.md cho tất cả. Batch clarification tối đa 5 câu.
+
+**Bước 4 — Write back:** update prd.md Feature Index.
+
+---
+
+### Thứ tự thực hiện
+
+```
+/spec-brownfield-init [path]
+         │
+         ▼
+/spec-brownfield-component [path]
+         │
+         ▼
+/spec-brownfield-feature [path]
+         │
+         ▼
+(fill in NEEDS_CLARIFY items khi có thêm context)
+         │
+         ▼
+→ Integration Pipeline
+```
+
+---
+
+## Integration Pipeline — dùng cho cả greenfield và brownfield
+
+Sau khi main artifacts đã sẵn sàng (từ greenfield hoặc brownfield), mọi requirement mới đều đi qua pipeline này.
+
+| Command | Reads | Writes |
+| --- | --- | --- |
+| `/spec-new [requirement]` | `prd.md`, `domain.md`, frd(s), crd(s) | `specs/integrations/{slug}/spec.md` |
+| `/spec-tech [number]` | `sad.md`, `domain.md`, cdd(s), fdd(s), `spec.md` | `specs/integrations/{slug}/tech.md` |
+| `/plan` | `spec.md`, `tech.md`, `domain.md` | `plan.md`, `todo.md` |
+| `/build` | `plan.md`, `todo.md` | *(source code)* |
+| `/review` | `spec.md`, `tech.md`, `plan.md`, `todo.md`, *(source code)* | *(findings report)* |
+| `/archive` | `specs/integrations/` | `specs/archive/` |
+
+### `/spec-new [requirement]`
+
+Tạo `specs/integrations/{slug}/spec.md` cho một integration mới. Chạy bởi BA.
+
+**Nếu không có argument** → đọc `prd.md`, hiển thị danh sách features có `Status = TODO`, user chọn số.
+
+**Nếu có argument** → argument là raw requirement, dùng trực tiếp làm input.
+
+Context load: `prd.md` + `domain.md` + `frd.md` (cho mỗi feature liên quan) + `crd.md` (cho mỗi component bị touched). Frontmatter `features` và `components` được điền theo những gì agent xác định.
+
+**Interview** (4 phần, tuần tự): Problem Statement · Requirements · Acceptance Criteria · Out of Scope
+
+AC tự nhóm theo bản chất integration: Feature → US → AC, hoặc Component → AC, hoặc mix.
+
+**Cascade Proposals** đề xuất delta cho: `prd.md`, `domain.md`, `component/{C-XXX}/crd.md`, `feature/{F-XXX}/frd.md`. Component và feature mới có thể được đề xuất tạo cùng cascade (auto-pick ID + slug).
+
+Sau khi confirm → ghi `spec.md`, cập nhật `prd.md`: Status `TODO → In Progress` (nếu liên quan feature).
+
+---
+
+### `/spec-tech [number]`
+
+Tạo `specs/integrations/{slug}/tech.md` cho một integration. Chạy bởi DEV sau khi `spec.md` đã được approve.
+
+**Luôn hiển thị danh sách tất cả integrations** trong `specs/integrations/`, đánh dấu `✓` những cái đã có `tech.md`. Nếu có argument → argument là số thứ tự (`1`, `001`...), chọn luôn không cần hiển thị.
+
+Nếu integration đã có `tech.md` → hỏi confirm trước khi ghi đè.
+
+Context load: `spec.md` + `sad.md` + `domain.md` + `cdd.md` (cho mỗi component bị touched) + `fdd.md` (cho mỗi feature liên quan).
+
+**Interview** (4 phần, tuần tự): Solution Overview · Data Model Changes · Interface Changes · Implementation Notes
+
+**Cascade Proposals** đề xuất delta cho: `sad.md`, `domain.md`, `component/{C-XXX}/cdd.md`, `feature/{F-XXX}/fdd.md`.
+
+---
+
+### `/plan`
+
+Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`. Là SDD wrapper quanh `planning-and-task-breakdown`.
+
+**Bước 1: Xác định integration**
+Quét `specs/integrations/`, hiển thị danh sách với trạng thái `spec✓/—`, `tech✓/—`, `plan✓/—`. Nếu có argument → chọn luôn. Nếu `plan.md`/`todo.md` đã tồn tại → hỏi trước khi ghi đè.
+
+**Bước 2: Load và surface context**
+Đọc `spec.md`, `tech.md`, `domain.md`. Surface tóm tắt (features, components, AC IDs, thay đổi kỹ thuật, shared entities) và assumptions để user confirm. Plan mode từ đây — chỉ đọc, không viết code.
+
+**Bước 3: Handoff → `planning-and-task-breakdown`**
+Delegate toàn bộ breakdown (dependency graph, vertical slicing, sizing) sang `planning-and-task-breakdown`. Output phải theo Output Format định nghĩa trong `skills/plan/SKILL.md`.
+
+**Không có Cascade Proposals** — nếu phát hiện delta cần cập nhật `sad.md`/`domain.md`/component/feature artifacts → dừng, báo user, đề xuất tạo integration riêng.
+
+---
+
+### `/build`
+
+Implement từng task trong `todo.md` theo vòng lặp TDD incremental. Chạy bởi DEV sau khi `plan.md` đã được approve.
+
+Với mỗi task `[ ]` trong `todo.md`, lặp lại:
+
+1. **Load context** — đọc code, types, patterns liên quan. Hỏi: cách đơn giản nhất có thể làm việc là gì?
+2. **UI/UX check** — nếu task liên quan đến UI/UX → invoke `frontend-design` + `frontend-ui-engineering` trước khi implement.
+3. **RED** — viết test trước, chạy và xác nhận nó fail.
+4. **GREEN** — implement code tối thiểu để test pass.
+5. **Verify** — chạy `npm test` (toàn bộ suite). Nếu regression → invoke `debugging-and-error-recovery`.
+6. **Build** — chạy `npm run build`. Nếu fail → invoke `debugging-and-error-recovery`.
+7. **Commit** — atomic commit trong phạm vi task này.
+8. **Đánh dấu** — check `[x]` trong `todo.md`, chuyển task tiếp theo.
+
+**Scope discipline** — chỉ chạm vào những gì task yêu cầu. Không refactor code liền kề, không implement task tương lai.
+
+**Quan hệ với các skill khác:** delegates to `incremental-implementation` + `test-driven-development` · invokes `frontend-design` + `frontend-ui-engineering` (UI/UX tasks) · escalates to `debugging-and-error-recovery` (test/build failures).
+
+---
+
+### `/review`
+
+Review implementation sau `/build` theo năm trục: correctness, readability, architecture, security, performance. Đối chiếu trực tiếp với `spec.md` và `tech.md`. Delegates to `code-review-and-quality`.
+
+**Findings** phân loại theo severity:
+
+| Severity | Ý nghĩa | Action |
+|----------|---------|--------|
+| **Critical** | Blocks merge | Security vulnerability, data loss, chức năng vỡ |
+| **Important** | Phải sửa | Bug logic, vi phạm spec, architecture sai |
+| **Suggestion** | Tuỳ chọn | Readability, style nhẹ |
+
+**Verdict:**
+- Có Critical/Important → dừng, không tiếp tục `/build`, sửa và re-review.
+- Chỉ Suggestion hoặc không có finding → approve, tiếp tục `/build` task tiếp theo.
+
+---
+
+### `/archive`
+
+Di chuyển integration đã hoàn thành hoặc không còn active từ `specs/integrations/` sang `specs/archive/` để dọn dẹp thư mục làm việc chính.
+
+**Bước 1 — Kiểm tra thư mục:** Tự động tạo `specs/archive/` nếu chưa tồn tại.
+
+**Bước 2 — Liệt kê:** Quét `specs/integrations/`, hiển thị numbered list kèm status (đọc từ `spec.md` nếu có). Nếu không có integration nào → thông báo và dừng.
+
+**Bước 3 — Xác nhận:** Hiển thị preview mapping `integrations/{slug}/ → archive/{slug}/` trước khi di chuyển. Chờ user confirm.
+
+**Bước 4 — Di chuyển:** Move toàn bộ thư mục, giữ nguyên cấu trúc bên trong. Nếu slug đã tồn tại trong `specs/archive/` → bỏ qua và cảnh báo để tránh ghi đè.
+
+**Bước 5 — Kết quả:** Liệt kê integrations đã archive, integrations bị bỏ qua (nếu có), và số integration còn lại trong `specs/integrations/`.
+
+---
+
+### Thứ tự thực hiện
+
+```
+        /spec-new [requirement]
+   (human review + apply cascade proposals + approve)
+                │
+        /spec-tech
+   (human review + apply cascade proposals + approve)
+                │
+        /plan
+   (human approve)
+                │
+        /build ←──────────────┐
+                │              │
+        /review               │ (nếu Critical/Important)
+                │              │
+           [approve] ──────────┘ (nếu Suggestion only)
+                │
+        /archive  (khi integration Done, dọn dẹp khỏi integrations/)
+```
+
+---
+
+## Cross-cutting skills
+
+Không nằm trong pipeline chính — được `build` tự động invoke khi gặp task phù hợp.
+
+| Skill | Vai trò | Invoke khi |
+| --- | --- | --- |
+| `frontend-design` | Aesthetic direction | Task tạo/sửa UI, chưa có design system |
+| `frontend-ui-engineering` | Component architecture & engineering standards | Mọi task UI/UX |
+
+### `frontend-design`
+
+Xác định hướng aesthetic trước khi implement. Trả lời câu hỏi: *interface này trông như thế nào và cảm giác như thế nào?*
+
+- Chọn aesthetic direction rõ ràng và táo bạo (minimalist, brutalist, editorial, luxury...) — không để mặc định
+- Typography: font đặc trưng, không dùng Inter/Roboto/Arial
+- Color: palette nhất quán với accent mạnh, dùng CSS variables
+- Motion: animation có chủ đích tại các điểm quan trọng (page load, hover, transition)
+- Layout: bất đối xứng, overlap, grid-breaking — tránh card grid đều nhau kiểu AI
+
+**Mục tiêu:** UI memorable và unmistakably designed — không phải AI-generated look.
+
+---
+
+### `frontend-ui-engineering`
+
+Đảm bảo engineering quality cho mọi UI được implement. Trả lời câu hỏi: *interface này có đúng kỹ thuật không?*
+
+- **Component architecture**: colocate file, composition over configuration, tách container/presentation
+- **Accessibility (WCAG 2.1 AA)**: keyboard navigation, ARIA labels, focus management, đủ contrast
+- **State management**: chọn cách đơn giản nhất (useState → lifted state → context → server state → global store)
+- **Responsive**: mobile-first, test tại 320px / 768px / 1024px / 1440px
+- **Loading/error/empty states**: bắt buộc — không để blank screen
+
+**Mục tiêu:** UI production-quality — accessible, performant, không có AI aesthetic.
+
+---
+
+## ADO Integration
+
+Nhóm skill kết nối SDD workflow với Azure DevOps — từ setup project đến tạo tickets tự động từ spec.
+
+> `/ado-create` và `/ado-update` thực hiện **một integration mỗi lần chạy** — chọn integration ở đầu skill, toàn bộ thao tác chỉ trong phạm vi integration đó.
+
+| Command | Reads | Writes |
+| --- | --- | --- |
+| `/ado-config` | `.claude/ado.yaml` *(nếu đã có)* | `.claude/ado.yaml`, `.gitignore` *(nếu cần)* |
+| `/ado-create` | `.claude/ado.yaml`, `spec.md`, `frd.md` | ADO tickets, `spec.md`, `frd.md`, `prd.md` |
+| `/ado-update` | `.claude/ado.yaml`, `spec.md` | ADO ticket states *(via MCP)* |
+
+### Thứ tự thực hiện
+
+```
+/ado-config   (một lần per project)
+      │
+      ▼
+/ado-create   (mỗi lần có integration mới được approve)
+      │
+      ▼
+/ado-update   (mỗi lần deploy/verify qua môi trường)
+```
+
+---
+
+### `/ado-config`
+
+Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO dùng chung cho tất cả skill `/ado-*`.
+
+**Khi file chưa tồn tại** → collect toàn bộ tuần tự.
+
+**Khi file đã tồn tại** → hiển thị tóm tắt nội dung hiện tại, hỏi user muốn cập nhật phần nào:
+- Toàn bộ từ đầu
+- Thông tin project
+- Team members
+- Epic ticket
+- Môi trường
+
+**Bước 2 — Project:**
+- Hỏi organization (tự extract nếu user paste full URL)
+- Gọi MCP `core_list_projects` để list projects trong org → user chọn số thứ tự → tự điền `project_name` và `project_id`
+- Đề xuất `project_code` từ tên project (ví dụ `Galaxy GCC` → `GAL-GCC`), user confirm hoặc nhập lại
+
+**Bước 3 — Team:** Collect PE / SE / DE, mỗi role nhập email, mỗi người một dòng. PE là bắt buộc.
+
+**Bước 4 — Epic Ticket:** Tạo Epic mới qua MCP (title được prefix `[{project_code}]`, assignee là PE đầu tiên) hoặc nhập ID ticket có sẵn (validate qua MCP: phải là type `Epic`). Lưu `id`, `title`, `url` vào config.
+
+**Bước 5 — Environments:** Collect danh sách môi trường (dev / stag / prod).
+
+**Cuối:** Ghi `.claude/ado.yaml`, đảm bảo file không bị ignore bởi `.gitignore` (thêm `!.claude/ado.yaml` nếu `.claude/` đang bị ignore).
+
+---
+
+### `/ado-create`
+
+Đọc `spec.md` của một integration, tạo Feature và User Story tickets trên ADO, ghi ticket references trở lại vào spec artifacts.
+
+**Prerequisite:** `.claude/ado.yaml` phải có `epic.id` (chạy `/ado-config` trước).
+
+**Bước 1 — Current user:** Đọc `git config user.email`, tìm trong `team.*` của `ado.yaml`. Nếu không khớp → hỏi user chọn. Resolve email → ADO identity ID để dùng làm assignee.
+
+**Bước 2 — Chọn integration:** List tất cả `specs/integrations/` kèm title và status từ frontmatter `spec.md`.
+
+**Bước 3 — Parse spec.md:** Extract Features (`### Feature: <name> (<ID>)`) và User Stories (`#### US-FXXX-YYY — <title>`). Detect ticket đã tồn tại qua dòng `**ADO:**` ngay sau heading — đánh dấu `already_created`, bỏ qua khi tạo.
+
+**Bước 4 — Preview:** Hiển thị kế hoạch đầy đủ (Feature và User Story sẽ tạo, skip list) trước khi tạo bất kỳ ticket nào. Chờ user confirm.
+
+**Bước 5-6 — Tạo tickets:**
+- Feature ticket: type `Feature`, title `[{project_code}] [{feature_id}] {feature_name}`, description từ `frd.md`. Link parent → Epic ngay sau khi tạo.
+- User Story ticket: type `User Story`, title `[{project_code}] [{feature_name}] - {US-code} — {story_title}`, description gồm câu story + ACs. Link parent → Feature ngay sau khi tạo.
+- Nếu link parent fail → retry 1 lần → nếu vẫn fail: đánh dấu `orphan` (KHÔNG xóa ticket), báo cáo cuối.
+
+**Bước 7-9 — Ghi lại references:**
+- `spec.md`: thêm dòng `**ADO:** [#ID — title](url)` ngay sau heading của mỗi Feature và User Story đã tạo thành công
+- `frd.md`: append section `## ADO Tickets` (bảng Feature + User Story) hoặc append row vào bảng đã có
+- `prd.md`: thêm/cập nhật cột `ADO` trong bảng Features
+
+**Bước 10 — Tóm tắt:** Liệt kê tickets đã tạo (kèm URL), files đã cập nhật, tickets thất bại, và orphans cần link thủ công.
+
+---
+
+### `/ado-update`
+
+Cập nhật state đồng loạt cho User Story (và tuỳ chọn Feature) tickets của một integration theo tiến trình deploy/verify qua các môi trường.
+
+**Prerequisites:** `.claude/ado.yaml` có `environments`, tất cả tickets đã được tạo qua `/ado-create`.
+
+**Bước 1 — Load config:** Đọc `ado.yaml`. Dừng nếu thiếu file hoặc `environments` rỗng.
+
+**Bước 2 — Chọn integration:** List `specs/integrations/` kèm title và status.
+
+**Bước 3 — Parse & validate:** Extract tất cả Feature và User Story tickets từ dòng `**ADO:**` trong `spec.md`. Nếu bất kỳ ticket nào chưa có → dừng, báo danh sách thiếu, yêu cầu chạy `/ado-create` trước.
+
+**Bước 4 — Fetch state hiện tại:** Gọi song song: batch fetch state hiện tại của tất cả tickets + fetch danh sách states hợp lệ từ ADO work item type `User Story` và `Feature`. State list lấy thực tế từ ADO — **không hardcode**, **không generate từ `environments`**.
+
+**Environment-State Filtering:** Sau khi fetch, filter bớt các state `Deploy *` / `Verify *` không tương ứng với environments trong config. ADO trả về pairs theo thứ tự (Deploy X, Verify X) — map positional: pair thứ N → `environments[N]`. Pairs có index ≥ số environments → loại. General states (New, In Progress, Done...) giữ nguyên.
+
+**Bước 5 — Chọn state mới (User Story):** Hiển thị numbered list plain text (không dùng `AskUserQuestion` — số options có thể vượt 4). Chờ user nhập số.
+
+**Bước 6 — Preview & cập nhật User Story:** Hiển thị từng ticket với state cũ → mới, đánh dấu "(không đổi)" cho ticket đã đúng state. Chỉ gọi API update cho ticket thực sự thay đổi. Gọi tuần tự, không dừng nếu 1 ticket fail.
+
+**Bước 7 — Feature tickets (tuỳ chọn):** Hỏi user có muốn cập nhật Feature tickets không. Nếu có → hiển thị Feature state list, chọn, preview, cập nhật tương tự.
+
+**Bước 8 — Tóm tắt:** Liệt kê tickets đã cập nhật, tickets không đổi, và tickets thất bại.
+
+---
+
+## Ghi chú
+
+- Cascade proposals trong `spec.md` và `tech.md` do human review và apply thủ công — không có skill riêng.
+- **Greenfield**: Component và Feature artifacts mọc dần qua cascade từ integrations — không có skill chuyên biệt để tạo.
+- **Brownfield**: Component và Feature artifacts được bootstrap bởi `spec-brownfield-component` và `spec-brownfield-feature` — sau đó tiếp tục mọc qua cascade như bình thường.
+- Thứ tự trong một integration: `spec-new` → `spec-tech` → `plan` → `build`.
+- `frontend-design` và `frontend-ui-engineering` được `build` invoke tự động — không cần gọi thủ công.
+- `**[NEEDS_CLARIFY]**` items trong brownfield artifacts không block workflow — có thể proceed và fill in dần khi có thêm context.