@torus-engineering/tas-kit 1.7.0 → 1.8.0

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

@@ -1,29 +1,33 @@
-# /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ừ .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"):
-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"):
-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
-- Status: Proposed | Accepted | Deprecated | Superseded
-- Mỗi ADR độc lập, tự chứa đủ context để hiểu
-- Link sang ADR liên quan nếu có (Supersedes, Related to)
-- Sơ đồ Mermaid tuân thủ quy tắc: :::mermaid wrapper, không dùng ()
+# /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ừ .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"):
+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"):
+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
+- Status: Proposed | Accepted | Deprecated | Superseded
+- Mỗi ADR độc lập, tự chứa đủ context để hiểu
+- Link sang ADR liên quan nếu có (Supersedes, Related to)
+- Sơ đồ Mermaid tuân thủ quy tắc: :::mermaid wrapper, không dùng ()
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào file ADR đang làm việc.

package/.claude/commands/tas-api-test.md

@@ -0,0 +1,95 @@
+# /tas-api-test $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Generate .NET xUnit automation test project cho REST API từ spec (OpenAPI 3.0, Markdown, YAML).
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Đọc toàn bộ spec trước khi generate bất kỳ test nào |
+| **Always** | Tổ chức tests theo API version — mỗi version một folder riêng |
+| **Always** | Append-only: không sửa files trong version folder cũ đã tồn tại |
+| **Always** | URL và credentials ra `appsettings.json` — không hardcode trong code |
+| **Always** | XML doc comment trên mỗi test method |
+| **Ask** | Khi spec không rõ expected response schema |
+| **Never** | Sửa hoặc xóa test files của version cũ hơn |
+| **Never** | Hardcode base URL, API key, credentials trong test code |
+| **Never** | Bỏ qua error path — mỗi endpoint cần ≥1 happy path + ≥1 error path |
+
+## Hành động
+
+### Bước 1 — Locate Inputs
+
+`$ARGUMENTS` là path đến spec file hoặc Story ID. Nếu không có → hỏi user.
+
+Nếu là Story ID: glob tìm `docs/epics/**/Story-{ID}*.md`, đọc Story để tìm link spec trong `## Technical Plan` hoặc `## Acceptance Criteria`.
+
+### Bước 2 — Parse API Spec
+
+Đọc `.claude/rules/csharp/api-testing.md` để nắm convention trước khi generate.
+
+Từ spec, thu thập cho mỗi endpoint:
+- HTTP method + path, path/query params, request body schema
+- Response schemas theo từng status code
+- Auth requirement, description/summary
+
+Nếu có Story: đọc thêm `## Acceptance Criteria` để bổ sung business rule test cases.
+
+### Bước 3 — Detect Existing Test Project
+
+Glob tìm `**/ApiTests/*.csproj`, `**/Api.Tests/*.csproj`, `**/IntegrationTests/*.csproj`.
+
+- **Tìm thấy**: Đọc framework đang dùng (xUnit/NUnit/MSTest), glob `v*/` folders để biết versions đã có.
+- **Không tìm thấy**: Tạo mới tại `tests/ApiTests/` với xUnit + FluentAssertions (per `csharp/testing.md`).
+
+### Bước 4 — Detect API Version
+
+Ưu tiên theo thứ tự: `info.version` trong OpenAPI → prefix trong URL path → hỏi user.
+Version folder: lowercase, không có dot — `v1`, `v2` (không phải `v1.0`).
+
+### Bước 5 — Generate Infrastructure (chỉ khi tạo project mới)
+
+Đọc `.claude/rules/csharp/api-testing.md` section **Project Structure** và **Config Pattern** để generate:
+- `ApiTests.csproj` với packages chuẩn
+- `appsettings.json` (base) + `appsettings.Test.json` + `appsettings.Staging.json`
+- `Shared/TestBase.cs` — load config, HttpClient, helper methods
+- `Shared/ApiTestSettings.cs` — strongly typed settings
+- `.gitignore` cho `appsettings.*.local.json`
+
+### Bước 6 — Generate Test Classes
+
+Nhóm endpoints theo resource/tag. Mỗi nhóm → `tests/ApiTests/{version}/{Resource}ApiTests.cs`.
+
+Với mỗi endpoint, generate tối thiểu:
+1. Happy path (2xx)
+2. Unauthorized (401) — nếu endpoint yêu cầu auth
+3. Not found (404) — nếu có path param
+4. Validation error (400/422) — nếu có required fields
+
+Từ Story ACs: thêm test methods tương ứng, comment rõ `// AC: {AC text}`.
+
+Đầu mỗi file: block comment ghi `Spec`, `Generated date`, `Story ID`, và nhắc **APPEND-ONLY rule**.
+
+### Bước 7 — Append-Only Guard
+
+Trước khi ghi file: kiểm tra file đã tồn tại chưa.
+- File chưa có → tạo mới bình thường.
+- File đã tồn tại trong version folder → **DỪNG**, thông báo tên file cho user tự edit thủ công.
+
+### Bước 8 — Post-Generate Review
+
+Launch `csharp-reviewer` agent:
+> Review `tests/ApiTests/{version}/`. Đọc `.claude/rules/csharp/testing.md` + `.claude/rules/csharp/api-testing.md`.
+> Tập trung: async/await, HttpClient disposal, assertion completeness, XML doc coverage.
+> Format: Critical / High / Medium / Low với file:line.
+
+Gate: Critical/High → fix ngay. Medium/Low → list gợi ý.
+
+### Bước 9 — Summary
+
+Hiển thị bảng coverage (endpoint × test type: ✓/—) và next steps để chạy tests.
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào spec file hoặc Story đang làm việc.

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

@@ -1,109 +1,113 @@
-# /tas-bug $ARGUMENTS
-
-Quản lý toàn bộ lifecycle của bug: tạo, phân tích, fix, verify.
-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
-
-### 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)
-
-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
-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
-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
-- PHẢI có regression test case TRƯỚC khi fix
-- 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`
+# /tas-bug $ARGUMENTS
+
+Quản lý toàn bộ lifecycle của bug: tạo, phân tích, fix, verify.
+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
+
+### 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)
+
+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
+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
+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
+- PHẢI có regression test case TRƯỚC khi fix
+- 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`
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào file Bug đang làm việc.

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

@@ -1,33 +1,37 @@
-# /tas-design $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo hoặc cập nhật Design Specification document (UI/UX flows, wireframe descriptions).
-
-## Prerequisite
-- docs/prd.md phải tồn tại
-
-## Hành động
-1. Cần context từ root/tas.yaml và docs/prd.md
-2. Kiểm tra docs/design-spec.md đã tồn tại chưa:
-
-### Chế độ CREATE (file chưa tồn tại):
-3. Cần context từ .tas/templates/Design-Spec.md
-4. $ARGUMENTS là mô tả scope của design. Nếu không có, dựa vào PRD.
-5. Tạo file docs/design-spec.md chứa:
-   - User flows (Mermaid flowchart)
-   - Screen descriptions
-   - 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
-- Mỗi screen cần mô tả: purpose, key elements, actions available
-- Mermaid tuân thủ: :::mermaid wrapper, không dùng ()
+# /tas-design $ARGUMENTS
+
+Vai trò: PE - Product Engineer
+Tạo hoặc cập nhật Design Specification document (UI/UX flows, wireframe descriptions).
+
+## Prerequisite
+- docs/prd.md phải tồn tại
+
+## Hành động
+1. Cần context từ root/tas.yaml và docs/prd.md
+2. Kiểm tra docs/design-spec.md đã tồn tại chưa:
+
+### Chế độ CREATE (file chưa tồn tại):
+3. Cần context từ .tas/templates/Design-Spec.md
+4. $ARGUMENTS là mô tả scope của design. Nếu không có, dựa vào PRD.
+5. Tạo file docs/design-spec.md chứa:
+   - User flows (Mermaid flowchart)
+   - Screen descriptions
+   - 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
+- Mỗi screen cần mô tả: purpose, key elements, actions available
+- Mermaid tuân thủ: :::mermaid wrapper, không dùng ()
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào `docs/design-spec.md`.