@torus-engineering/tas-kit 1.9.0 → 1.11.1

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

@@ -1,200 +1,198 @@
-# /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.
+# /tas-plan $ARGUMENTS
+
+Role: SE - Software Engineer
+Bridge between business (Story) and technical (code).
+Analyze Story, create technical plan, break tasks — before implementing.
+
+**Required output:** Technical Plan written to Story file + `plan_status: completed`.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read Story file before doing anything |
+| **Always** | Wait for user to approve plan before writing to Story |
+| **Always** | Write Technical Plan to Story file after approval |
+| **Ask** | When need to reference SAD/ADR — confirm with user before reading |
+| **Ask** | When Story scope > 8 hours — suggest splitting Story |
+| **Never** | Start implementing in this command |
+| **Never** | Read SAD/ADR without asking user first |
+| **Never** | Write plan to Story without approval |
+
+## Actions
+
+### Step 1 — Identify Story
+
+`$ARGUMENTS` can be: Story ID (`Story-005`), file path, or Story description.
+
+- If Story ID: find file via glob `docs/epics/**/*-Story-{ID}-*.md`
+- If file path: read directly
+- If description: ask user for specific Story ID/file
+- Read Story file
+
+**Check re-plan:** If `plan_status: completed` → ask user:
+> "This Story already has a Technical Plan. Do you want to re-plan?"
+If user confirms → continue. If not → stop.
+
+### Step 2 — Parallel Context Gathering
+
+Launch 2 agents SIMULTANEOUSLY:
+
+**Agent 1 — `code-explorer`** (always run):
+> Survey codebase related to Story: "{Story title + AC summary}".
+> Find: entry points, files likely to change, existing patterns, dependencies.
+> Read max 10 most relevant files.
+> Return: concise map — what exists, what needs to change, potential conflicts.
+
+**Agent 2 — `architect`** (only run if Story shows architectural changes:
+new service/module, data flow changes, external system integration,
+database schema changes, new design pattern):
+> Evaluate architectural implications of Story: "{Story title}".
+> Read `docs/sad.md` (if exists) and files in `docs/adr/`.
+> Read `.claude/rules/common/patterns.md`.
+> Return: which ADRs relate, patterns to follow, architectural risks, constraints.
+
+Wait for ALL agents to finish, synthesize findings.
+
+### Step 3 — Ask about SAD/ADR (if still unclear)
+
+After seeing agent findings, if need to reference specific SAD or ADR:
+> "I need to read [SAD / ADR-XXX] to clarify [reason]. OK?"
+
+Only read after user confirms.
+
+### Step 4 — API Design (if Story involves backend API)
+
+**If Story shows API design** (new endpoint, API contract change, exposing service):
+Invoke skill `api-design` to design API Spec before planning:
+- URL structure, HTTP methods, status codes
+- Request/response payload shape
+- Pagination, filtering if needed
+- Error response format
+
+Attach API Spec to **Technical Plan → API Contract** section in Story.
+If Story not API-related → skip this step.
+
+### Step 5 — Technical Analysis
+
+Based on Story + agent findings, list clearly:
+
+**Files to change:**
+| File | What change | Why |
+
+**Files to create** (if any):
+| File | Purpose |
+
+**Database changes** (if any): migration, schema changes, seed data
+
+**Config/Infrastructure changes** (if any): env vars, feature flags, new dependencies
+
+**Need to update SAD?** Yes/No + brief reason
+
+**Need new ADR?** Yes/No + brief reason
+
+### Step 6 — Propose approach
+
+If multiple feasible approaches, list 2-3 options:
+```
+Option A: [short description]
+  + [pro]
+  - [con]
+
+Option B: [short description]
+  + [pro]
+  - [con]
+```
+Recommend best option and reason. If only 1 approach → present directly.
+
+### Step 7 — Break Tasks
+
+Break down into implementation-order tasks. Each task ~1-2 hours:
+```
+- [ ] Task 1: [specific action — which file, what change]
+- [ ] Task 2: [specific action]
+- [ ] Task 3: Write unit tests for [AC-1, AC-2...]
+- [ ] Task 4: [if needed] Create ADR / update SAD
+```
+
+If total estimate > 8 hours → suggest splitting Story before continuing.
+
+### Step 8 — Wait for approval
+
+**STOP.** Display entire plan and ask:
+> "Does the Technical Plan above look OK? Any adjustments?"
+
+- If user approves → Step 9
+- If user has feedback → update plan, ask again
+- DO NOT write anything to Story before approval
+
+### Step 9 — Write Technical Plan to Story
+
+After approval, update Story file:
+
+**1. Add section `## Technical Plan`** to Story (replace comment placeholder):
+
+```markdown
+## Technical Plan
+> **Plan by:** {SE name} | **Date:** {current date}
+
+### Approach
+{Brief description of chosen approach and reason}
+
+### Files to Change
+| File | Change | Reason |
+|------|--------|--------|
+
+### Files to Create
+| File | Purpose |
+|------|---------|
+
+### Database Changes
+{If none: "None"}
+
+### Config Changes
+{If none: "None"}
+
+### Architecture Notes
+- SAD update needed: Yes/No
+- New ADR needed: Yes/No — {title if Yes}
+
+### Tasks
+- [ ] Task 1: ...
+- [ ] Task 2: ...
+- [ ] Task 3: Write unit tests
+```
+
+**2. Update frontmatter:**
+- `plan_status: completed`
+- `plan_date: {current datetime}`
+
+**3. Update `project-status.yaml`:**
+- `last_updated: {current date}`
+- `epics.{EPIC_ID}.features.{FEATURE_ID}.stories.{STORY_ID}.plan_status: completed`
+
+**4. If ADR needed:** run `/tas-adr "{Decision title}"` immediately after writing plan.
+
+### Step 10 — Notify next step
+> "Technical Plan written to Story. SE can start implementing with `/tas-dev {Story-ID}`."
+
+---
+
+## Quick Mode (require_plan: false in tas.yaml)
+
+For: solo dev, prototype, spike, urgent hotfix.
+
+- `/tas-dev` will NOT require running `/tas-plan` first
+- `/tas-plan` can still be run voluntarily when Story is complex
+- Trade-off: higher speed, lower traceability
+
+## Principles
+- Technical Plan lives in Story file — no separate plan file
+- Each task ~1-2 hours; whole Story ~4-8 hours
+- If estimate > 8 hours → split Story
+- If task affects architecture → suggest ADR
+- Keep plan concise, actionable — don't write essays
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to working Story file.

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

@@ -1,37 +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ự ()
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào `docs/prd.md`.
+# /tas-prd $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Product Requirements Document.
+
+## Actions
+1. Need context from root/tas.yaml for project context
+2. Check if docs/prd.md already exists:
+
+### CREATE mode (file doesn't exist):
+3. Need context from .tas/templates/PRD.md
+4. If $ARGUMENTS has content, use as product description input
+5. If no $ARGUMENTS, ask user:
+   - What problem does the product solve?
+   - Who are the main users?
+   - What are core features?
+   - Any technical/business constraints?
+6. Create file docs/prd.md per template
+7. Update `project-status.yaml` per `.claude/rules/common/project-status.md` — add `artifacts.prd`.
+
+### UPDATE mode (file exists):
+3. Need context from current docs/prd.md
+4. $ARGUMENTS is change description. If not provided, ask user which section to update.
+5. Update file, keep unchanged sections as-is
+6. Add line to Changelog section at end: date, change description
+7. Update `project-status.yaml` per `.claude/rules/common/project-status.md` — update `artifacts.prd`.
+
+## Principles
+- Write at sufficient detail for SE to understand and design architecture
+- Classify requirements by MoSCoW: Must/Should/Could/Won't
+- Each requirement has unique ID: FR-001, NFR-001
+- Always include Non-Goals section to limit scope
+- Mermaid diagrams must use :::mermaid wrapper, NO () characters
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to `docs/prd.md`.