@torus-engineering/tas-kit 1.7.0 → 1.9.0

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

@@ -1,184 +1,200 @@
-# /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
+# /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 — API Design (nếu Story liên quan đến backend API)
+
+**Nếu Story có dấu hiệu thiết kế API** (thêm endpoint mới, thay đổi API contract, expose service ra ngoài):
+Invoke skill `api-design` để thiết kế API Spec trước khi lập plan:
+- URL structure, HTTP methods, status codes
+- Request/response payload shape
+- Pagination, filtering nếu cần
+- Error response format
+
+Gắn API Spec vào section **Technical Plan → API Contract** trong Story.
+Nếu Story không liên quan API → bỏ qua bước này.
+
+### Bước 5 — 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 6 — Đề 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 7 — 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 8 — 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 9
+- 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 9 — 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 10 — 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
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào file Story đang làm việc.

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

@@ -1,33 +1,37 @@
-# /tas-prd $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo hoặc cập nhật Product Requirements Document.
-
-## Hành động
-1. Cần context từ root/tas.yaml để lấy project context
-2. Kiểm tra docs/prd.md đã tồn tại chưa:
-
-### Chế độ CREATE (file chưa tồn tại):
-3. Cần context từ .tas/templates/PRD.md
-4. Nếu $ARGUMENTS có nội dung, dùng làm input mô tả sản phẩm
-5. Nếu không có $ARGUMENTS, hỏi user:
-   - Sản phẩm giải quyết vấn đề gì?
-   - Đối tượng người dùng chính?
-   - 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
-- Phân loại requirements theo MoSCoW: Must/Should/Could/Won't
-- Mỗi requirement có ID duy nhất: FR-001, NFR-001
-- Luôn có section Non-Goals để giới hạn scope
-- Sơ đồ Mermaid phải dùng :::mermaid wrapper, KHÔNG dùng ký tự ()
+# /tas-prd $ARGUMENTS
+
+Vai trò: PE - Product Engineer
+Tạo hoặc cập nhật Product Requirements Document.
+
+## Hành động
+1. Cần context từ root/tas.yaml để lấy project context
+2. Kiểm tra docs/prd.md đã tồn tại chưa:
+
+### Chế độ CREATE (file chưa tồn tại):
+3. Cần context từ .tas/templates/PRD.md
+4. Nếu $ARGUMENTS có nội dung, dùng làm input mô tả sản phẩm
+5. Nếu không có $ARGUMENTS, hỏi user:
+   - Sản phẩm giải quyết vấn đề gì?
+   - Đối tượng người dùng chính?
+   - 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
+- Phân loại requirements theo MoSCoW: Must/Should/Could/Won't
+- Mỗi requirement có ID duy nhất: FR-001, NFR-001
+- Luôn có section Non-Goals để giới hạn scope
+- Sơ đồ Mermaid phải dùng :::mermaid wrapper, KHÔNG dùng ký tự ()
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào `docs/prd.md`.