@torus-engineering/tas-kit 1.5.1 → 1.7.0

package/.claude/commands/tas-adr.md

@@ -1,24 +1,25 @@
-# /tas-adr $ARGUMENTS
+# /tas-adr $ARGUMENTS
 
 Vai trò: SE - Software Engineer
 Tạo mới hoặc cập nhật Architecture Decision Record.
 
 ## Hành động
-1. Cần context từ root/tas.yaml
-2. Cần context từ .tas/templates/ADR.md
-3. Quét docs/adr/ để xác định các ADR hiện có
-4. Xác định chế độ dựa vào $ARGUMENTS:
+1. Cần context từ .tas/templates/ADR.md
+2. Quét docs/adr/ để xác định các ADR hiện có
+3. Xác định chế độ dựa vào $ARGUMENTS:
 
 ### Chế độ CREATE ($ARGUMENTS là tiêu đề mới, ví dụ: "Use CQRS for Order Service"):
-5. Xác định số thứ tự tiếp theo (ADR-001, ADR-002...)
-6. Nếu docs/sad.md tồn tại, cần context từ SAD để đảm bảo ADR consistent
-7. Tạo file docs/adr/ADR-{NNN}-{slug}.md
+4. Xác định số thứ tự tiếp theo (ADR-001, ADR-002...)
+5. Nếu docs/sad.md tồn tại, cần context từ SAD để đảm bảo ADR consistent
+6. Tạo file docs/adr/ADR-{NNN}-{slug}.md
+7. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm entry vào `adrs`.
 
 ### Chế độ UPDATE ($ARGUMENTS là ADR ID, ví dụ: "ADR-001"):
-5. Cần context từ file ADR hiện tại
-6. Hỏi user cần thay đổi gì (cập nhật status, thêm consequences, supersede...)
-7. Cập nhật file, thêm changelog
-8. Nếu supersede: cập nhật status ADR cũ thành "Superseded by ADR-{NNN}"
+4. Cần context từ file ADR hiện tại
+5. Hỏi user cần thay đổi gì (cập nhật status, thêm consequences, supersede...)
+6. Cập nhật file, thêm changelog
+7. Nếu supersede: cập nhật status ADR cũ thành "Superseded by ADR-{NNN}"
+8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `adrs.{ADR_ID}.status`.
 
 ## Nguyên tắc
 - ADR phải có: Context, Decision, Rationale, Consequences, Alternatives Considered

package/.claude/commands/tas-bug.md

@@ -1,62 +1,109 @@
-# /tas-bug $ARGUMENTS
+# /tas-bug $ARGUMENTS
 
 Quản lý toàn bộ lifecycle của bug: tạo, phân tích, fix, verify.
-Vai trò thay đổi theo status của bug.
+Status của bug xác định bước tiếp theo — không cần khai báo role.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Hiển thị status hiện tại và action tiếp theo trước khi làm gì |
+| **Always** | Viết regression test TRƯỚC khi fix |
+| **Always** | Launch review agent độc lập sau khi fix — không review trong cùng session |
+| **Ask** | Khi cần đọc thêm file ngoài Bug file (Status = Committed) |
+| **Never** | Patch symptom — phải fix root cause |
+| **Never** | Bỏ qua bước review sau khi fix |
+| **Never** | Tự commit hay push — đợi user test thủ công trước |
+
+## Stack Detection
+Đọc `.claude/rules/common/stack-detection.md`.
 
 ## Hành động
-1. Cần context từ root/tas.yaml
-2. Cần context từ .tas/templates/Bug.md
-3. Xác định chế độ dựa vào $ARGUMENTS:
 
-### Chế độ CREATE ($ARGUMENTS là mô tả bug mới):
+### Bước 1 — Xác định chế độ
+
+`$ARGUMENTS` là mô tả bug mới → **Chế độ CREATE**
+`$ARGUMENTS` là Bug ID (ví dụ: `Bug-001`) → **Chế độ UPDATE**
+
+---
+
+### Chế độ CREATE
+
 Vai trò: PE hoặc SE (ai phát hiện bug)
-4. Đọc project.code từ root/tas.yaml (ví dụ: "MP"). Hỏi user:
-   - Bug thuộc Feature nào? (ghi vào frontmatter để tham chiếu)
-   - Severity: Critical | High | Medium | Low
+
+1. Đọc `project.code` từ root/`tas.yaml`
+2. Hỏi user:
+   - Bug thuộc Feature nào?
+   - Severity: `Critical` | `High` | `Medium` | `Low`
    - Steps to reproduce
    - Expected vs Actual behavior
-   - Môi trường phát hiện (Test | Staging | Production)
-5. Quét docs/bugs/ để xác định số thứ tự Bug
-6. Tạo file docs/bugs/{code}-Bug-{NNN}-{slug}.md
-7. Bug status ban đầu: New
-8. Cập nhật root/project-status.yaml
-
-### Chế độ UPDATE ($ARGUMENTS là Bug ID, ví dụ: "Bug-001"):
-Tìm file Bug trong docs/bugs/ (dùng glob), detect status hiện tại:
-
-**Status = New -> Phân tích (SE)**
-4. SE phân tích root cause:
-   - Đọc error logs/stack trace
-   - Trace code flow
-   - Xác định file và dòng gây lỗi
-5. Ghi Root Cause Analysis vào Bug file
-6. Viết Regression Test Cases (test reproduce bug)
-7. Cập nhật status: New -> Committed
-8. Cập nhật project-status.yaml
-
-**Status = Committed -> Fix (SE)**
-4. CHỈ đọc DUY NHẤT Bug file. KHÔNG đọc PRD, SAD, ADR, Design-Spec.
-   KHÔNG list thư mục, KHÔNG quét project structure.
-   Nếu cần tra cứu thêm, PHẢI hỏi user xác nhận trước khi đọc bất kỳ file nào.
-5. Workflow:
-   a. Chạy regression test case, xác nhận FAIL (reproduce bug)
-   b. Fix code đúng root cause
-   c. Chạy regression test, xác nhận PASS
-   d. Chạy toàn bộ test suite, đảm bảo không regression mới
-7. Cập nhật status: Committed -> In Progress -> Deploy Test
-8. Cập nhật project-status.yaml
-9. Commit message format: "fix: [mô tả] - resolves Bug-{NNN}"
-
-**Status = Verify Test/Verify Stag -> Verify (PE)**
-4. PE verify trên môi trường tương ứng:
-   - Chạy lại Steps to Reproduce, xác nhận bug không còn
+   - Môi trường phát hiện: Test | Staging | Production
+3. Tạo `docs/bugs/{code}-Bug-{NNN}-{slug}.md` từ template `.tas/templates/Bug.md`
+4. Bug status ban đầu: `New`
+
+---
+
+### Chế độ UPDATE
+
+Tìm file Bug qua glob `docs/bugs/*-Bug-{ID}-*.md`, đọc status hiện tại.
+
+**Hiển thị trước khi làm gì:**
+> "Bug-{NNN} đang ở status: **{status}** — bước tiếp theo là {action}. Tiếp tục không?"
+
+---
+
+#### Status = `New` — Phân tích (SE)
+
+1. Đọc error logs/stack trace từ Bug file
+2. Trace code flow, xác định file và dòng gây lỗi
+3. Ghi Root Cause Analysis vào Bug file
+4. Viết Regression Test Cases (test reproduce bug)
+5. Cập nhật status: `New` → `Committed`
+
+---
+
+#### Status = `Committed` — Fix (SE)
+
+**Quy tắc đọc file:** CHỈ đọc Bug file. KHÔNG đọc PRD, SAD, ADR, Design-Spec, KHÔNG quét thư mục.
+Nếu cần thêm file → hỏi user xác nhận trước.
+
+Trước khi fix, đọc:
+- `.claude/rules/common/security.md` — fix không tạo security risk mới
+- `.claude/rules/common/testing.md` — pattern viết regression test
+- `.claude/rules/[lang_agent stack]/coding-style.md` — tuân thủ conventions
+
+**Fix workflow:**
+a. Chạy regression test case → xác nhận **FAIL** (reproduce bug)
+b. Fix code đúng root cause
+c. Chạy regression test → xác nhận **PASS**
+d. Chạy toàn bộ test suite → không có regression mới
+→ Nếu build fail hoặc test lỗi compile: launch `build-resolver` agent với error output trước khi tiếp tục.
+
+**Sau khi fix — Post-Fix Review (Isolated Agent):**
+
+Thực hiện theo `.claude/rules/common/post-review-agent.md`.
+Truyền vào: Bug file path, danh sách changed files, stack (từ CLAUDE.md), lang_agent.
+
+Sau khi review pass:
+- Cập nhật status: `Committed` → `Deploy Test`
+- Output commit message gợi ý: `fix: {mô tả ngắn} - resolves Bug-{NNN}`
+- Hỏi: "Bạn đã test thủ công chưa? Muốn commit và deploy lên Test không?"
+
+---
+
+#### Status = `Verify Test` / `Verify Stag` — Verify (PE)
+
+1. PE verify trên môi trường tương ứng:
+   - Chạy lại Steps to Reproduce → xác nhận bug không còn
    - Kiểm tra regression test case đã pass
-5. Nếu Pass: cập nhật status tiếp theo trong flow (Deploy Stag hoặc Done)
-6. Nếu Fail: ghi lý do, cập nhật status quay lại Committed, SE phải fix lại
-7. Cập nhật project-status.yaml
+2. **Pass** → cập nhật status tiếp theo (`Deploy Stag` hoặc `Done`)
+3. **Fail** → ghi lý do, cập nhật status về `Committed`, SE fix lại
+
+---
 
 ## Nguyên tắc
-- KHÔNG patch symptom, phải fix root cause
+- KHÔNG patch symptom — phải fix root cause
 - PHẢI có regression test case TRƯỚC khi fix
-- Bug status theo cùng flow Story: New -> Committed -> In Progress -> Deploy Test -> Verify Test -> Deploy Stag -> Verify Stag -> Deploy Prod -> Verify Prod -> Done
-- Bug Critical/High phải fix trước khi Feature được Verified
+- Review phải chạy qua Agent độc lập — không inline trong session hiện tại
+- Bug `Critical`/`High` phải fix trước khi Feature được Verified
+- Flow: `New` → `Committed` → `Deploy Test` → `Verify Test` → `Deploy Stag` → `Verify Stag` → `Deploy Prod` → `Verify Prod` → `Done`

package/.claude/commands/tas-design.md

@@ -1,4 +1,4 @@
-# /tas-design $ARGUMENTS
+# /tas-design $ARGUMENTS
 
 Vai trò: PE - Product Engineer
 Tạo hoặc cập nhật Design Specification document (UI/UX flows, wireframe descriptions).
@@ -19,11 +19,13 @@ Tạo hoặc cập nhật Design Specification document (UI/UX flows, wireframe
    - Navigation structure
    - Interaction patterns
    - Responsive behavior notes
+6. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm `artifacts.design_spec`.
 
 ### Chế độ UPDATE (file đã tồn tại):
 3. Cần context từ docs/design-spec.md hiện tại
 4. $ARGUMENTS là mô tả thay đổi. Nếu không có, hỏi user cần cập nhật section nào.
 5. Cập nhật file, thêm changelog
+6. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `artifacts.design_spec`.
 
 ## Nguyên tắc
 - Focus vào flows và behavior, không vào pixel-perfect design

package/.claude/commands/tas-dev.md

@@ -0,0 +1,115 @@
+# /tas-dev $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Implement một User Story theo Technical Plan đã được duyệt.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Kiểm tra `plan_status` trước khi implement |
+| **Always** | Follow tasks trong `## Technical Plan` của Story |
+| **Always** | Launch review agent độc lập sau khi implement — không review trong cùng session |
+| **Ask** | Khi phát hiện plan cần thay đổi đáng kể trong lúc code |
+| **Ask** | Khi cần đọc thêm file ngoài scope của plan |
+| **Never** | Implement ngoài scope Story |
+| **Never** | Skip bước review sau khi implement |
+
+## QUAN TRỌNG - Quy tắc đọc file
+- CHỈ đọc Story file — Technical Plan đã có đủ context kỹ thuật.
+- Không tự đọc PRD, SAD, ADR, Design-Spec trừ khi user xác nhận.
+- Không list thư mục, không quét project structure.
+- Không đọc `.tas/checklists/story-done.md` ở bước đầu (chỉ đọc ở bước cuối).
+
+## Stack Detection
+Đọc `.claude/rules/common/stack-detection.md`.
+
+## Hành động
+
+### Bước 1 — Xác định Story
+
+`$ARGUMENTS` là Story ID hoặc file path.
+Nếu không có: đọc `project-status.yaml`, tìm stories có `status: Committed` hoặc `status: In Progress`. Nếu nhiều hơn một, liệt kê để user chọn.
+Đọc Story file.
+
+### Bước 1.5 — Gate: Kiểm tra plan_status
+
+Đọc `plan_status` từ frontmatter của Story.
+
+**Nếu `plan_status: pending`:**
+Đọc `require_plan` từ root/`tas.yaml`:
+- `require_plan: true` (hoặc field không tồn tại) → **DỪNG LẠI**:
+  > "Story này chưa có Technical Plan. Chạy `/tas-plan {Story-ID}` trước khi implement."
+- `require_plan: false` → tiếp tục, hiển thị warning và chờ xác nhận:
+  > "⚠️ Quick mode: Story chưa có Technical Plan. Tiếp tục implement không?"
+
+**Nếu `plan_status: completed`:** tiếp tục bình thường.
+
+### Bước 2 — Đọc Technical Plan
+
+Từ Story file, đọc section `## Technical Plan`:
+- Approach đã chọn
+- Files to Change / Files to Create
+- Database Changes, Config Changes
+- Tasks list (checklist thực hiện theo thứ tự)
+
+Nếu không có Technical Plan (quick mode) → phân tích AC và implement trực tiếp theo AC.
+
+### Bước 3 — Implement
+
+#### Nếu `use_tdd = true` trong `tas.yaml`:
+a. **Red phase** — Viết test cases TRƯỚC theo AC trong Story. Chạy tests, xác nhận FAIL.
+b. **Green phase** — Viết code tối thiểu để pass tests.
+c. **Refactor** — Clean up, đảm bảo tests vẫn pass.
+
+#### Nếu `use_tdd = false`:
+a. Implement code theo AC + Tasks trong Technical Plan
+b. Viết unit tests cover các cases trong `## Unit Test Cases`
+c. Chạy tests, fix nếu fail
+→ Nếu tests vẫn fail sau 1 lần tự fix: launch `build-resolver` agent với error output để diagnose.
+
+Trong quá trình implement, tick từng task hoàn thành trong Story file: `- [x] Task 1: ...`
+
+Nếu phát hiện plan cần thay đổi đáng kể → thông báo user trước khi thay đổi hướng.
+
+### Bước 4 — Post-Implementation Review (Isolated Agent)
+
+Thực hiện theo `.claude/rules/common/post-review-agent.md`.
+Truyền vào: Story file path, danh sách changed files, stack (từ CLAUDE.md), lang_agent.
+
+### Bước 5 — Definition of Done
+
+Đọc `.tas/checklists/story-done.md`, verify từng mục, tick vào Story:
+- `- [x] Technical plan completed` — nếu plan_status: completed (hoặc quick mode xác nhận)
+- `- [x] Code implemented` — nếu implement xong
+- `- [x] Unit tests pass` — nếu tests đã pass
+- `- [x] No regression` — nếu toàn bộ test suite pass
+- `- [x] Documentation updated (if needed)` — nếu đã cập nhật
+- `- [x] Code review passed` — nếu review gate pass (không có Critical/High)
+- `- [ ] Acceptance criteria verified` — KHÔNG tick, để PE verify
+
+**Optional — nếu Story thay đổi API public, database schema, hoặc setup:**
+Launch `doc-updater` agent: cập nhật docs liên quan (README, SAD section, API docs).
+> Scope: [danh sách changed files]. Story: [Story ID + title].
+> Chỉ cập nhật phần docs đã lỗi thời — không viết lại từ đầu.
+
+### Bước 6 — Wrap up
+
+Cập nhật Story status → `In Progress` (nếu chưa).
+Tạo commit message theo conventions trong `CLAUDE.md`.
+Hỏi: "Tests OK và review passed rồi — bạn đã test thủ công chưa? Muốn chuyển sang Deploy Test không?"
+
+Nếu Yes:
+- Cập nhật Story status → `Deploy Test`
+- Thêm Changelog entry
+- Cập nhật `project-status.yaml`
+- Gợi ý: `/ado-update story {ado-id} --status "Deploy Test"` nếu dùng ADO
+
+## Nguyên tắc
+- KHÔNG implement ngoài scope của Story
+- Mỗi public method PHẢI có XML doc comment (C#) hoặc JSDoc (TypeScript) hoặc docstring (Python)
+- Review phải chạy qua Agent độc lập — không inline trong session hiện tại
+- **Khi nào cần tạo ADR** (nếu Technical Plan chưa đề cập):
+  - Thay đổi kiến trúc ảnh hưởng nhiều components
+  - Thêm mới design pattern hoặc framework
+  - Quyết định trade-off kỹ thuật quan trọng

package/.claude/commands/tas-epic.md

@@ -1,4 +1,4 @@
-# /tas-epic $ARGUMENTS
+# /tas-epic $ARGUMENTS
 
 Vai trò: PE - Product Engineer
 Tạo mới hoặc cập nhật Epic document.
@@ -13,15 +13,17 @@ Tạo mới hoặc cập nhật Epic document.
 
 ### Chế độ CREATE ($ARGUMENTS là mô tả Epic mới, hoặc không có $ARGUMENTS):
 4. Nếu không có $ARGUMENTS, hỏi user mô tả Epic.
-5. Đọc project.code từ root/tas.yaml (ví dụ: "MP"). Quét docs/epics/ để xác định số thứ tự.
+5. Đọc project.code từ root/tas.yaml. Quét docs/epics/ để xác định số thứ tự.
 6. Tạo thư mục docs/epics/{code}-Epic-{NNN}-{slug}/
 7. Tạo file docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Epic-{NNN}-{slug}.md
+8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm entry vào `epics`.
 
 ### Chế độ UPDATE ($ARGUMENTS là Epic ID, ví dụ: "Epic-001"):
 4. Tìm thư mục docs/epics/{code}-Epic-001-*/
 5. Cần context từ file Epic hiện tại
 6. Hỏi user cần thay đổi gì (cập nhật scope, thêm feature, đổi status...)
 7. Cập nhật file, thêm changelog
+8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `epics.{EPIC_ID}.status`.
 
 ## Nguyên tắc
 - Mỗi Epic map với một business capability trong PRD

package/.claude/commands/tas-feature.md

@@ -1,4 +1,4 @@
-# /tas-feature $ARGUMENTS
+# /tas-feature $ARGUMENTS
 
 Vai trò: PE - Product Engineer
 Tạo mới hoặc cập nhật Feature document, bao gồm thiết kế Integration Test và E2E/Acceptance Test.
@@ -12,8 +12,8 @@ Tạo mới hoặc cập nhật Feature document, bao gồm thiết kế Integra
 3. Xác định chế độ dựa vào $ARGUMENTS:
 
 ### Chế độ CREATE ($ARGUMENTS là mô tả Feature mới, hoặc không có $ARGUMENTS):
-4. Đọc project.code từ root/tas.yaml (ví dụ: "MP"). Liệt kê các Epic hiện có (quét docs/epics/{code}-Epic-*/), hỏi user Feature này thuộc Epic nào
-5. Quét thư mục Epic đã chọn để xác định số thứ tự Feature
+4. Đọc project.code từ root/tas.yaml. Liệt kê các Epic hiện có, hỏi user Feature này thuộc Epic nào.
+5. Quét thư mục Epic đã chọn để xác định số thứ tự Feature.
 6. Tạo thư mục docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/
 7. Tạo file {code}-Feature-{NNN}-{slug}.md trong thư mục đó
 8. Sau khi PE điền mô tả và acceptance criteria, TỰ ĐỘNG chuyển sang thiết kế test:
@@ -27,12 +27,14 @@ Tạo mới hoặc cập nhật Feature document, bao gồm thiết kế Integra
       - "Có scenario nào cần test với data thật hoặc gần thật?"
       - "Acceptance criteria nào cần PE verify thủ công?"
       Ghi vào section E2E Test Cases. Đây là checklist PE dùng ở Phase 2 khi chạy /tas-verify.
+9. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm entry vào `epics.{EPIC_ID}.features`.
 
 ### Chế độ UPDATE ($ARGUMENTS là Feature ID, ví dụ: "Feature-003"):
 4. Tìm file Feature trong cây docs/epics/ (dùng glob)
 5. Cần context từ file Feature hiện tại
 6. Hỏi user cần thay đổi gì (thêm story, cập nhật AC, thêm test cases, đổi status...)
 7. Cập nhật file, thêm changelog
+8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `epics.{EPIC_ID}.features.{FEATURE_ID}.status`.
 
 ## Nguyên tắc
 - Feature là một chức năng cụ thể, có thể demo được

package/.claude/commands/tas-fix.md

@@ -0,0 +1,47 @@
+# /tas-fix $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Quick fix cho bug nhỏ hoặc lỗi rõ ràng — không cần tạo ticket, không cần full lifecycle.
+Dùng khi: solo dev, hotfix nhanh, bug tìm thấy trong lúc dev.
+Khác với /tas-bug: không tạo Bug file, không track status, không deploy flow.
+
+## Stack Detection
+Đọc `.claude/rules/common/stack-detection.md`.
+
+## Hành động
+
+### 1. Hiểu bug
+$ARGUMENTS là mô tả lỗi, error message, hoặc file:line_number.
+- Nếu có error message/stack trace: parse ngay, xác định file và dòng lỗi
+- Nếu chỉ có mô tả: hỏi 1 câu duy nhất để làm rõ (reproduce steps hoặc expected vs actual)
+- KHÔNG hỏi nhiều hơn 1 câu
+
+### 2. Diagnose (tối đa 3 file đọc)
+- Đọc file lỗi và các file liên quan trực tiếp
+- Xác định root cause trong 1-2 câu ngắn
+- KHÔNG đọc toàn bộ project, KHÔNG quét cấu trúc folder
+- Nếu cần đọc thêm file ngoài 3 file đầu tiên: hỏi user xác nhận
+
+### 3. Fix với regression test
+
+Trước khi fix, đọc các rules liên quan:
+- `.claude/rules/common/security.md` — kiểm tra fix có tạo ra security risk không
+- `.claude/rules/common/testing.md` — pattern viết regression test
+- `.claude/rules/[lang_rules]/coding-style.md` — conventions của stack hiện tại (nếu xác định được)
+
+Sau đó:
+a. Viết 1 test case tối thiểu reproduce bug (nếu project có test framework)
+b. Xác nhận test FAIL
+c. Fix code đúng root cause
+d. Xác nhận test PASS
+e. Chạy nhanh test suite nếu có (để check regression)
+
+### 4. Wrap up
+- Output commit message: `fix: <mô tả ngắn gọn>`
+- Nhắc: "Nếu bug này có khả năng tái phát hoặc ảnh hưởng production, cân nhắc dùng /tas-bug để track đầy đủ."
+
+## Nguyên tắc
+- Tổng số file đọc ≤ 3 trừ khi được cho phép
+- Fix đúng root cause, KHÔNG patch symptom
+- Nếu fix kéo theo thay đổi architecture → dừng, gợi ý dùng /tas-bug + /tas-adr
+- Nếu bug thuộc production và severity cao → dừng, gợi ý dùng /tas-bug với severity Critical/High

package/.claude/commands/tas-plan.md

@@ -0,0 +1,184 @@
+# /tas-plan $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Cầu nối giữa nghiệp vụ (Story) và kỹ thuật (code).
+Phân tích Story, lập kế hoạch kỹ thuật, break tasks — trước khi bắt đầu implement.
+
+**Output bắt buộc:** Technical Plan được ghi vào Story file + `plan_status: completed`.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Đọc Story file trước khi làm bất cứ điều gì |
+| **Always** | Chờ user approve plan trước khi ghi vào Story |
+| **Always** | Ghi Technical Plan vào Story file sau khi approved |
+| **Ask** | Khi cần tham khảo SAD/ADR — xác nhận với user trước khi đọc |
+| **Ask** | Khi Story scope > 8 giờ — gợi ý tách Story |
+| **Never** | Bắt đầu implement ở command này |
+| **Never** | Tự đọc SAD/ADR mà không hỏi user trước |
+| **Never** | Ghi plan vào Story mà chưa có approval |
+
+## Hành động
+
+### Bước 1 — Xác định Story
+
+`$ARGUMENTS` có thể là: Story ID (`Story-005`), file path, hoặc mô tả Story.
+
+- Nếu là Story ID: tìm file qua glob `docs/epics/**/*-Story-{ID}-*.md`
+- Nếu là file path: đọc trực tiếp
+- Nếu là mô tả: hỏi user Story ID/file cụ thể
+- Đọc Story file
+
+**Check re-plan:** Nếu `plan_status: completed` → hỏi user:
+> "Story này đã có Technical Plan rồi. Bạn muốn lập lại kế hoạch không?"
+Nếu user xác nhận → tiếp tục. Nếu không → dừng.
+
+### Bước 2 — Parallel Context Gathering
+
+Launch 2 agents ĐỒNG THỜI:
+
+**Agent 1 — `code-explorer`** (luôn chạy):
+> Khảo sát codebase liên quan đến Story: "{Story title + tóm tắt AC}".
+> Tìm: entry points, files có khả năng thay đổi, existing patterns, dependencies.
+> Đọc tối đa 10 files liên quan nhất.
+> Trả về: map ngắn gọn — what exists, what needs to change, potential conflicts.
+
+**Agent 2 — `architect`** (chỉ chạy khi Story có dấu hiệu thay đổi kiến trúc:
+thêm service/module mới, thay đổi data flow, tích hợp external system,
+thay đổi database schema, thêm mới design pattern):
+> Đánh giá architectural implications của Story: "{Story title}".
+> Đọc `docs/sad.md` (nếu tồn tại) và files trong `docs/adr/`.
+> Đọc `.claude/rules/common/patterns.md`.
+> Trả về: ADR nào liên quan, patterns cần follow, rủi ro kiến trúc, constraints.
+
+Chờ TẤT CẢ agents xong, tổng hợp findings.
+
+### Bước 3 — Hỏi về SAD/ADR (nếu chưa rõ)
+
+Sau khi xem findings từ agents, nếu cần tham khảo thêm SAD hoặc ADR cụ thể:
+> "Tôi cần đọc thêm [SAD / ADR-XXX] để làm rõ [lý do]. Được không?"
+
+Chỉ đọc sau khi user xác nhận.
+
+### Bước 4 — Phân tích kỹ thuật
+
+Dựa trên Story + agent findings, liệt kê rõ:
+
+**Files sẽ thay đổi:**
+| File | Thay đổi gì | Lý do |
+|------|-------------|-------|
+
+**Files mới cần tạo** (nếu có):
+| File | Mục đích |
+|------|----------|
+
+**Database changes** (nếu có): migration, schema changes, seed data
+
+**Config/Infrastructure changes** (nếu có): env vars, feature flags, dependencies mới
+
+**Cần cập nhật SAD?** Yes/No + lý do ngắn gọn
+
+**Cần tạo ADR mới?** Yes/No + lý do ngắn gọn
+
+### Bước 5 — Đề xuất approach
+
+Nếu có nhiều cách làm khả thi, liệt kê 2-3 options:
+```
+Option A: [mô tả ngắn]
+  + [ưu điểm]
+  - [nhược điểm]
+
+Option B: [mô tả ngắn]
+  + [ưu điểm]
+  - [nhược điểm]
+```
+Đề xuất option tốt nhất và lý do. Nếu chỉ có 1 cách → trình bày trực tiếp.
+
+### Bước 6 — Break Tasks
+
+Breakdown thành tasks theo thứ tự implement. Mỗi task ~1-2 giờ:
+```
+- [ ] Task 1: [hành động cụ thể — file nào, thay đổi gì]
+- [ ] Task 2: [hành động cụ thể]
+- [ ] Task 3: Viết unit tests cho [AC-1, AC-2...]
+- [ ] Task 4: [nếu cần] Tạo ADR / cập nhật SAD
+```
+
+Nếu tổng estimate > 8 giờ → gợi ý tách Story trước khi tiếp tục.
+
+### Bước 7 — Chờ approval
+
+**DỪNG LẠI.** Hiển thị toàn bộ plan và hỏi:
+> "Technical Plan trên có OK không? Muốn điều chỉnh gì không?"
+
+- Nếu user approve → Bước 8
+- Nếu user có feedback → cập nhật plan, hỏi lại
+- KHÔNG ghi gì vào Story trước khi có approval
+
+### Bước 8 — Ghi Technical Plan vào Story
+
+Sau khi approved, cập nhật Story file:
+
+**1. Thêm section `## Technical Plan`** vào Story (thay thế comment placeholder):
+
+```markdown
+## Technical Plan
+> **Plan by:** {SE name} | **Date:** {ngày hiện tại}
+
+### Approach
+{Mô tả ngắn về approach đã chọn và lý do}
+
+### Files to Change
+| File | Change | Reason |
+|------|--------|--------|
+
+### Files to Create
+| File | Purpose |
+|------|---------|
+
+### Database Changes
+{Nếu không có: "None"}
+
+### Config Changes
+{Nếu không có: "None"}
+
+### Architecture Notes
+- SAD update needed: Yes/No
+- New ADR needed: Yes/No — {tiêu đề nếu Yes}
+
+### Tasks
+- [ ] Task 1: ...
+- [ ] Task 2: ...
+- [ ] Task 3: Viết unit tests
+```
+
+**2. Cập nhật frontmatter:**
+- `plan_status: completed`
+- `plan_date: {ngày giờ hiện tại}`
+
+**3. Cập nhật `project-status.yaml`:**
+- `last_updated: {ngày hiện tại}`
+- `epics.{EPIC_ID}.features.{FEATURE_ID}.stories.{STORY_ID}.plan_status: completed`
+
+**4. Nếu cần ADR:** chạy `/tas-adr "{Tiêu đề quyết định}"` ngay sau khi ghi plan xong.
+
+### Bước 9 — Thông báo next step
+> "Technical Plan đã ghi vào Story. SE có thể bắt đầu implement với `/tas-dev {Story-ID}`."
+
+---
+
+## Quick Mode (require_plan: false trong tas.yaml)
+
+Dành cho: solo dev, prototype, spike, hotfix khẩn.
+
+- `/tas-dev` sẽ KHÔNG bắt buộc chạy `/tas-plan` trước
+- `/tas-plan` vẫn có thể chạy tự nguyện khi Story phức tạp
+- Trade-off: tốc độ cao hơn, traceability thấp hơn
+
+## Nguyên tắc
+- Technical Plan sống trong Story file — không tạo file plan riêng
+- Mỗi task ~1-2 giờ; cả Story ~4-8 giờ
+- Nếu estimate > 8 giờ → tách Story
+- Nếu task ảnh hưởng architecture → suggest ADR
+- Giữ plan ngắn gọn, actionable — không viết essay

package/.claude/commands/tas-prd.md

@@ -1,4 +1,4 @@
-# /tas-prd $ARGUMENTS
+# /tas-prd $ARGUMENTS
 
 Vai trò: PE - Product Engineer
 Tạo hoặc cập nhật Product Requirements Document.
@@ -16,12 +16,14 @@ Tạo hoặc cập nhật Product Requirements Document.
    - Các tính năng cốt lõi?
    - Ràng buộc kỹ thuật/kinh doanh?
 6. Tạo file docs/prd.md theo template
+7. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm `artifacts.prd`.
 
 ### Chế độ UPDATE (file đã tồn tại):
 3. Cần context từ docs/prd.md hiện tại
 4. $ARGUMENTS là mô tả thay đổi. Nếu không có, hỏi user cần cập nhật section nào.
 5. Cập nhật file, giữ nguyên các section không thay đổi
 6. Thêm dòng vào section Changelog cuối file: ngày, mô tả thay đổi
+7. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `artifacts.prd`.
 
 ## Nguyên tắc
 - Viết ở mức đủ chi tiết để SE có thể hiểu và thiết kế kiến trúc