@torus-engineering/tas-kit 1.7.0 → 1.9.0

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

@@ -1,87 +1,91 @@
-# /tas-story $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo mới hoặc cập nhật User Story document.
-
-**Phạm vi:** Nghiệp vụ, trải nghiệm người dùng, acceptance criteria, test cases.
-**Không thuộc phạm vi:** Kỹ thuật implement, files cần sửa, database schema — đó là việc của `/tas-plan`.
-
-## Always / Ask / Never
-
-| | Hành động |
-|---|---|
-| **Always** | Viết AC dạng Given/When/Then |
-| **Always** | Set `plan_status: pending` cho Story mới |
-| **Ask** | Khi Story > 8h — gợi ý tách nhỏ |
-| **Never** | Đọc SAD, ADR — kỹ thuật là việc của `/tas-plan` |
-
-## Prerequisite
-- Ít nhất một Feature phải tồn tại
-
-## Hành động
-
-### Chế độ CREATE ($ARGUMENTS là mô tả Story mới, hoặc không có $ARGUMENTS)
-
-**Bước 1 — Xác định Feature**
-- Đọc `project.code` từ root/`tas.yaml`
-- Ưu tiên theo thứ tự:
-  1. Nếu `$ARGUMENTS` chứa Feature ID → dùng luôn
-  2. Nếu context có `parent_id` → dùng luôn
-  3. Hỏi user: "Story này thuộc Feature nào?" — không quét thư mục
-
-**Bước 2 — Thu thập context nghiệp vụ**
-- Đọc file Feature đã xác định (lấy business context, scope, danh sách Stories hiện có)
-- Đọc PRD (nếu có) — chỉ lấy business requirements, user goals
-
-**Bước 3 — Xác định Story ID**
-- Đọc section Stories trong Feature file → xác định index tiếp theo từ danh sách đó
-- KHÔNG quét thư mục
-
-**Bước 4 — Soạn Story với user**
-
-Thảo luận để điền đầy đủ:
-
-a) **User Story**: "As a [role], I want [goal], so that [benefit]"
-
-b) **Business Requirements** (nếu có): business rules đặc thù, constraints từ stakeholders
-
-c) **Design Notes** (nếu có): UI/UX specs, mockup links, flow diagrams
-
-d) **Prerequisites** (nếu có): Stories khác phải done trước
-
-e) **Acceptance Criteria**: mỗi AC một kịch bản Given/When/Then rõ ràng
-
-**Bước 5 — Test Case Prompting**
-
-Sau khi AC được xác nhận, hỏi thêm:
-- "Ngoài happy path, có edge case nào cần test không?" (input rỗng, giá trị biên, concurrent)
-- "Có negative case nào cần cover?" (unauthorized, invalid data, timeout, not found)
-- "Có external dependency nào cần mock khi test?" (API bên ngoài, database state)
-
-Ghi tất cả vào section `## Unit Test Cases`.
-
-**Bước 6 — Tạo file**
-- Đọc `.tas/templates/Story.md` để lấy format
-- Tạo `docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/{code}-Story-{NNN}-{slug}.md`
-- Frontmatter: `plan_status: pending`, `plan_date:` để trống
-
-**Bước 7 — Cập nhật project-status.yaml**
-Theo `.claude/rules/common/project-status.md` — thêm entry vào `epics.{EPIC_ID}.features.{FEATURE_ID}.stories`.
-
-**Bước 8 — Thông báo next step**
-> "Story đã tạo. Trước khi SE bắt đầu code, cần chạy `/tas-plan {Story-ID}` để lập kế hoạch kỹ thuật."
-
----
-
-### Chế độ UPDATE ($ARGUMENTS là Story ID, ví dụ: "Story-005")
-
-1. Tìm file qua glob `docs/epics/**/{code}-Story-{ID}-*.md`
-2. Đọc file Story hiện tại
-3. Hỏi user cần thay đổi gì (cập nhật AC, đổi status, thêm test cases, sửa business rule...)
-4. Cập nhật file, thêm entry vào Changelog
-5. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md`.
-
-## Nguyên tắc
-- Story phải đủ nhỏ để hoàn thành trong **4-8 giờ**; nếu lớn hơn → tách thành nhiều Stories
-- Story file = **product artifact**: mô tả *what* và *why*, không phải *how*
-- Story status: New → Committed → In Progress → Deploy Test → Verify Test → Deploy Stag → Verify Stag → Deploy Prod → Verify Prod → Done
+# /tas-story $ARGUMENTS
+
+Vai trò: PE - Product Engineer
+Tạo mới hoặc cập nhật User Story document.
+
+**Phạm vi:** Nghiệp vụ, trải nghiệm người dùng, acceptance criteria, test cases.
+**Không thuộc phạm vi:** Kỹ thuật implement, files cần sửa, database schema — đó là việc của `/tas-plan`.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Viết AC dạng Given/When/Then |
+| **Always** | Set `plan_status: pending` cho Story mới |
+| **Ask** | Khi Story > 8h — gợi ý tách nhỏ |
+| **Never** | Đọc SAD, ADR — kỹ thuật là việc của `/tas-plan` |
+
+## Prerequisite
+- Ít nhất một Feature phải tồn tại
+
+## Hành động
+
+### Chế độ CREATE ($ARGUMENTS là mô tả Story mới, hoặc không có $ARGUMENTS)
+
+**Bước 1 — Xác định Feature**
+- Đọc `project.code` từ root/`tas.yaml`
+- Ưu tiên theo thứ tự:
+  1. Nếu `$ARGUMENTS` chứa Feature ID → dùng luôn
+  2. Nếu context có `parent_id` → dùng luôn
+  3. Hỏi user: "Story này thuộc Feature nào?" — không quét thư mục
+
+**Bước 2 — Thu thập context nghiệp vụ**
+- Đọc file Feature đã xác định (lấy business context, scope, danh sách Stories hiện có)
+- Đọc PRD (nếu có) — chỉ lấy business requirements, user goals
+
+**Bước 3 — Xác định Story ID**
+- Đọc section Stories trong Feature file → xác định index tiếp theo từ danh sách đó
+- KHÔNG quét thư mục
+
+**Bước 4 — Soạn Story với user**
+
+Thảo luận để điền đầy đủ:
+
+a) **User Story**: "As a [role], I want [goal], so that [benefit]"
+
+b) **Business Requirements** (nếu có): business rules đặc thù, constraints từ stakeholders
+
+c) **Design Notes** (nếu có): UI/UX specs, mockup links, flow diagrams
+
+d) **Prerequisites** (nếu có): Stories khác phải done trước
+
+e) **Acceptance Criteria**: mỗi AC một kịch bản Given/When/Then rõ ràng
+
+**Bước 5 — Test Case Prompting**
+
+Sau khi AC được xác nhận, hỏi thêm:
+- "Ngoài happy path, có edge case nào cần test không?" (input rỗng, giá trị biên, concurrent)
+- "Có negative case nào cần cover?" (unauthorized, invalid data, timeout, not found)
+- "Có external dependency nào cần mock khi test?" (API bên ngoài, database state)
+
+Ghi tất cả vào section `## Unit Test Cases`.
+
+**Bước 6 — Tạo file**
+- Đọc `.tas/templates/Story.md` để lấy format
+- Tạo `docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/{code}-Story-{NNN}-{slug}.md`
+- Frontmatter: `plan_status: pending`, `plan_date:` để trống
+
+**Bước 7 — Cập nhật project-status.yaml**
+Theo `.claude/rules/common/project-status.md` — thêm entry vào `epics.{EPIC_ID}.features.{FEATURE_ID}.stories`.
+
+**Bước 8 — Thông báo next step**
+> "Story đã tạo. Trước khi SE bắt đầu code, cần chạy `/tas-plan {Story-ID}` để lập kế hoạch kỹ thuật."
+
+---
+
+### Chế độ UPDATE ($ARGUMENTS là Story ID, ví dụ: "Story-005")
+
+1. Tìm file qua glob `docs/epics/**/{code}-Story-{ID}-*.md`
+2. Đọc file Story hiện tại
+3. Hỏi user cần thay đổi gì (cập nhật AC, đổi status, thêm test cases, sửa business rule...)
+4. Cập nhật file, thêm entry vào Changelog
+5. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md`.
+
+## Nguyên tắc
+- Story phải đủ nhỏ để hoàn thành trong **4-8 giờ**; nếu lớn hơn → tách thành nhiều Stories
+- Story file = **product artifact**: mô tả *what* và *why*, không phải *how*
+- Story status: New → Committed → In Progress → 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 Story đang làm việc.

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

@@ -1,41 +1,51 @@
-# /tas-verify $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Verify Feature trên môi trường Staging (Phase 2).
-
-## Prerequisite
-- Feature phải có status "Ready To Verify"
-- Môi trường Staging phải sẵn sàng
-
-## Hành động
-1. Cần context từ root/tas.yaml
-2. $ARGUMENTS là Feature ID. Nếu không có, liệt kê features có status "Ready To Verify".
-3. Tìm file Feature trong cây docs/epics/ (dùng glob)
-4. Cần context từ file Feature hiện tại (đặc biệt section Integration Test Cases và E2E Test Cases)
-
-### Workflow verify:
-4.5. **Launch `e2e-runner`** (nếu Feature có E2E / Acceptance Test Cases):
-> E2E verification cho Feature {ID}.
-> Đọc section `## E2E / Acceptance Test Cases` từ Feature file — list từng test case.
-> Chạy các test cases đó, báo cáo kết quả: Pass/Fail per test case với lý do nếu Fail.
-> Không tự động fix lỗi — chỉ báo cáo kết quả để PE xác nhận.
-
-Dùng kết quả từ `e2e-runner` làm input cho bước 5.
-
-5. Hiển thị checklist từ 2 section test trong Feature:
-   a. **Integration Test Cases**: Liệt kê từng test case, hỏi PE kết quả (Pass/Fail)
-   b. **E2E / Acceptance Test Cases**: Liệt kê từng test case, hỏi PE kết quả (Pass/Fail)
-6. Với mỗi test case FAIL:
-   - Hỏi PE mô tả lỗi
-   - Tự động tạo Bug trong thư mục Feature đó (dùng logic /tas-bug)
-   - Bug có reference đến test case gốc
-7. Cập nhật file Feature:
-   - Ghi kết quả test (Pass/Fail + ngày) vào từng test case
-   - Nếu tất cả Pass: cập nhật Feature status thành "Verified"
-   - Nếu có Fail: giữ Feature status "Ready To Verify", liệt kê bugs
-8. Cập nhật root/project-status.yaml
-
-## Nguyên tắc
-- KHÔNG skip test case nào, phải verify hết
-- Bug phát hiện ở Phase 2 PHẢI được ghi thành Bug để track
-- Feature chỉ được chuyển sang Phase 3 (Deploy) khi status = "Verified"
+# /tas-verify $ARGUMENTS
+
+Vai trò: PE - Product Engineer
+Verify Feature trên môi trường Staging (Phase 2).
+
+## Prerequisite
+- Feature phải có status "Ready To Verify"
+- Môi trường Staging phải sẵn sàng
+
+## Hành động
+1. Cần context từ root/tas.yaml
+2. $ARGUMENTS là Feature ID. Nếu không có, liệt kê features có status "Ready To Verify".
+3. Tìm file Feature trong cây docs/epics/ (dùng glob)
+4. Cần context từ file Feature hiện tại (đặc biệt section Integration Test Cases và E2E Test Cases)
+
+### Workflow verify:
+4.5. **Chạy Automated Tests** (nếu có):
+
+   **Functional Tests** (Layer 2):
+   - Kiểm tra `docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md` đã có chưa
+   - Nếu có, hỏi PE: "Chạy functional test suite? Command: `yarn functest:mobile:{feature-slug}` (hoặc `yarn functest:web:{feature-slug}`)"
+   - Ghi nhận pass/fail của func suite
+
+   **E2E Tests** (Layer 3 - nếu Feature có E2E / Acceptance Test Cases):
+   > Launch `e2e-runner`: E2E verification cho Feature {ID}.
+   > Đọc section `## E2E / Acceptance Test Cases` từ Feature file — list từng test case.
+   > Chạy các test cases đó, báo cáo kết quả: Pass/Fail per test case với lý do nếu Fail.
+   > Không tự động fix lỗi — chỉ báo cáo kết quả để PE xác nhận.
+
+5. **Tổng hợp kết quả và xác nhận với PE**:
+   - Hiển thị summary automated test results (Functional + E2E)
+   - Hỏi PE: "Automated tests đã pass. Trên Staging thực có vấn đề nào mà automated tests không catch được không? (UX, business logic, edge case thực tế...)"
+
+6. Với mỗi issue PE báo cáo hoặc test case FAIL:
+   - Hỏi PE mô tả lỗi
+   - Tự động tạo Bug trong thư mục Feature đó (dùng logic /tas-bug)
+   - Bug có reference đến test case gốc (FT ID hoặc E2E ID), hoặc ghi rõ "phát hiện qua manual verify Staging"
+7. Cập nhật file Feature:
+   - Ghi kết quả test (Pass/Fail + ngày) vào từng test case
+   - Nếu tất cả Pass: cập nhật Feature status thành "Verified"
+   - Nếu có Fail: giữ Feature status "Ready To Verify", liệt kê bugs
+8. Cập nhật root/project-status.yaml
+
+## Nguyên tắc
+- KHÔNG skip test case nào, phải verify hết
+- Bug phát hiện ở Phase 2 PHẢI được ghi thành Bug để track
+- Feature chỉ được chuyển sang Phase 3 (Deploy) khi status = "Verified"
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào file Feature đang verify.

package/.claude/rules/common/post-review-agent.md

@@ -1,39 +1,49 @@
-# Post-Implementation Review (Isolated Agent)
-
-Sau khi implement hoặc fix xong, chạy review qua **Agent độc lập** — không dùng session hiện tại để tránh reviewer bias từ quá trình implement.
-
-## Cách dùng
-
-Gọi `Agent` tool với prompt sau (thay thế các placeholder `{}`):
-
-```
-Bạn là code reviewer. Không có context từ session trước — hãy review hoàn toàn khách quan.
-
-Artifact: {path-to-artifact-file}
-Changed files: {danh sách files vừa thay đổi}
-Stack: {stack từ CLAUDE.md}
-
-Thực hiện:
-1. Hygiene scan: debug code còn sót (console.log, debugger, print), secrets hardcoded,
-   commented-out blocks lớn (>5 dòng).
-2. Chạy tests: detect test runner (package.json → npm test / *.csproj → dotnet test /
-   pytest.ini → python -m pytest), report kết quả.
-3. Parallel review — launch đồng thời:
-   - code-reviewer: đọc .tas/checklists/code-review.md + .claude/rules/common/code-review.md.
-     Tập trung: naming, architecture, error handling, DRY, function size, nesting depth.
-   - security-reviewer: đọc .claude/rules/common/security.md.
-     Tập trung: OWASP Top 10, injection, hardcoded secrets, auth/authz.
-   - {lang_agent}: đọc .claude/rules/[stack]/coding-style.md + .claude/rules/[stack]/patterns.md.
-     Tập trung: async/await, null handling, type safety, anti-patterns của stack.
-4. Tổng hợp findings: Critical / High / Medium / Low với file:line và fix cụ thể.
-
-Trả về Review Summary đầy đủ.
-```
-
-## Gate Rule
-
-| Kết quả | Hành động |
-|---|---|
-| Có **Critical** hoặc **High** | List findings, **DỪNG**, yêu cầu fix trước khi tiếp tục |
-| Chỉ có **Medium** / **Low** | List gợi ý, hỏi user có muốn fix không, sau đó tiếp tục |
-| Không có findings | Tiếp tục bình thường |
+# Post-Implementation Review (Isolated Agent)
+
+Sau khi implement hoặc fix xong, chạy review qua **Agent độc lập** — không dùng session hiện tại để tránh reviewer bias từ quá trình implement.
+
+## Cách dùng
+
+Gọi `Agent` tool với prompt sau (thay thế các placeholder `{}`):
+
+```
+Bạn là code reviewer. Không có context từ session trước — hãy review hoàn toàn khách quan.
+
+Artifact: {path-to-artifact-file}
+Changed files: {danh sách files vừa thay đổi}
+Stack: {stack từ CLAUDE.md}
+
+Thực hiện:
+1. Hygiene scan: debug code còn sót (console.log, debugger, print), secrets hardcoded,
+   commented-out blocks lớn (>5 dòng).
+1b. Silent failure scan — tìm các pattern sau:
+   - Swallowed exceptions: empty catch {}, catch chỉ log nhưng tiếp tục chạy như không có lỗi
+   - Silent async failures: fire-and-forget (unawaited task/Promise), async void (.NET),
+     .catch(() => {}) không xử lý gì
+   - Null blindspots: .FirstOrDefault() dùng trực tiếp không null-check (.NET),
+     optional chaining thiếu trên deeply nested object access (TS/JS),
+     dict.get() result dùng như non-None (Python)
+   - Error propagation sai: HTTP calls không check status trước khi parse,
+     hàm return bool/null khi lỗi thay vì throw (caller bỏ qua kết quả)
+   - Config reads không check existence
+2. Chạy tests: detect test runner (package.json → npm test / *.csproj → dotnet test /
+   pytest.ini → python -m pytest), report kết quả.
+3. Parallel review — launch đồng thời:
+   - code-reviewer: đọc .tas/checklists/code-review.md + .claude/rules/common/code-review.md.
+     Tập trung: naming, architecture, error handling, DRY, function size, nesting depth.
+   - security-reviewer: đọc .claude/rules/common/security.md.
+     Tập trung: OWASP Top 10, injection, hardcoded secrets, auth/authz.
+   - {lang_agent}: đọc .claude/rules/[stack]/coding-style.md + .claude/rules/[stack]/patterns.md.
+     Tập trung: async/await, null handling, type safety, anti-patterns của stack.
+4. Tổng hợp findings: Critical / High / Medium / Low với file:line và fix cụ thể.
+
+Trả về Review Summary đầy đủ.
+```
+
+## Gate Rule
+
+| Kết quả | Hành động |
+|---|---|
+| Có **Critical** hoặc **High** | List findings, **DỪNG**, yêu cầu fix trước khi tiếp tục |
+| Chỉ có **Medium** / **Low** | List gợi ý, hỏi user có muốn fix không, sau đó tiếp tục |
+| Không có findings | Tiếp tục bình thường |

package/.claude/rules/common/testing.md

@@ -28,6 +28,30 @@ MANDATORY workflow:
 
 - **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
 
+## PR Test Gap Analysis
+
+Before merging, identify missing tests by categorizing each changed file:
+
+| Change type | Tests required |
+|-------------|---------------|
+| New logic added | New unit tests |
+| Logic modified | Updated/new unit tests + regression check |
+| New API endpoint | Integration test (happy path + validation + error) |
+| Bug fix | Regression test that reproduces the bug |
+| Refactor only | Verify existing tests still pass — no new tests needed |
+| Config/infra change | Manual verification step — document it |
+
+### How to find gaps
+
+1. Run `git diff main...HEAD --name-only` to get changed files
+2. For each changed source file, find its test file (grep for class/function name in test dirs)
+3. Check: happy path covered? edge cases (null, empty, boundary)? failure/error path?
+4. List specific missing test cases with method name and scenario
+
+### Regression test rule
+
+Every bug fix must include a test that **fails before the fix and passes after**. No exceptions.
+
 ## Test Structure (AAA Pattern)
 
 Prefer Arrange-Act-Assert structure for tests:

package/.claude/rules/common/token-logging.md

@@ -0,0 +1,27 @@
+# Token Usage Logging
+
+Ghi `## AI Usage Log` vào cuối artifact file khi TAS command hoàn thành.
+
+## Token Estimation
+
+Ước tính từ session awareness: số ký tự mỗi file đã `Read` ÷ 4 ≈ tokens (English/code), ÷ 2 (Vietnamese).
+Số ký tự output artifact ÷ 4. Luôn append `(est.)`. User verify bằng `/cost` (CLI) hoặc `/context` (Desktop app).
+
+## Format
+
+```markdown
+---
+
+## AI Usage Log
+
+| # | Date | Command | Input (est.) | Output (est.) |
+|---|------|---------|-------------|---------------|
+| 1 | YYYY-MM-DD | /tas-{name} | ~{N}k | ~{N}k |
+| 2 | YYYY-MM-DD | /tas-{name} (revision) | ~{N}k | ~{N}k |
+| **Total** | | | **~{N}k** | **~{N}k** |
+```
+
+## Update Rules
+
+- **Lần đầu**: section chưa tồn tại → append toàn bộ section với row đầu tiên và row Total
+- **Lần sau**: append row mới trước row Total, cập nhật Total (cộng dồn)

package/.claude/rules/csharp/api-testing.md

@@ -0,0 +1,171 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/ApiTests/**"
+  - "**/Api.Tests/**"
+---
+
+# C# API Automation Testing
+
+> Dùng bởi `/tas-api-test`. Extends [csharp/testing.md](./testing.md).
+
+## Tech Stack
+
+| Thành phần | Lựa chọn |
+|---|---|
+| Framework | xUnit (default) — match project nếu đã dùng MSTest/NUnit |
+| Assertions | FluentAssertions |
+| HTTP | System.Net.Http.HttpClient |
+| Config | Microsoft.Extensions.Configuration + JSON/EnvVars |
+
+```xml
+<!-- ApiTests.csproj packages -->
+<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
+<PackageReference Include="xunit" Version="2.*" />
+<PackageReference Include="xunit.runner.visualstudio" Version="2.*" />
+<PackageReference Include="FluentAssertions" Version="6.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration" Version="8.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.*" />
+```
+
+## Project Structure
+
+```
+tests/ApiTests/
+  appsettings.json          # base (không có secrets thật)
+  appsettings.Test.json     # Test env override
+  appsettings.Staging.json  # Staging env override
+  .gitignore                # appsettings.*.local.json
+  Shared/
+    ApiTestSettings.cs
+    TestBase.cs
+  v1/
+    UsersApiTests.cs
+  v2/                       # APPEND-ONLY: không sửa v1
+    UsersApiTests.cs
+```
+
+## Config
+
+```json
+// appsettings.json
+{
+  "ApiTest": {
+    "BaseUrl": "https://localhost:5001",
+    "TimeoutSeconds": 30,
+    "Auth": { "Type": "Bearer", "TokenEndpoint": "/api/auth/token", "Username": "", "Password": "" }
+  }
+}
+```
+
+```csharp
+// ApiTestSettings.cs
+public sealed class ApiTestSettings
+{
+    public required string BaseUrl { get; init; }
+    public int TimeoutSeconds { get; init; } = 30;
+    public required AuthSettings Auth { get; init; }
+}
+public sealed class AuthSettings
+{
+    public string Type { get; init; } = "Bearer";
+    public string TokenEndpoint { get; init; } = "/api/auth/token";
+    public string Username { get; init; } = "";
+    public string Password { get; init; } = "";
+}
+```
+
+```csharp
+// TestBase.cs
+public abstract class TestBase : IAsyncLifetime
+{
+    protected HttpClient Client { get; private set; } = null!;
+    protected ApiTestSettings Settings { get; private set; } = null!;
+
+    public async Task InitializeAsync()
+    {
+        var env = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Test";
+        Settings = new ConfigurationBuilder()
+            .AddJsonFile("appsettings.json")
+            .AddJsonFile($"appsettings.{env}.json", optional: true)
+            .AddEnvironmentVariables("APITEST_")
+            .Build()
+            .GetRequiredSection("ApiTest").Get<ApiTestSettings>()!;
+
+        Client = new HttpClient { BaseAddress = new Uri(Settings.BaseUrl),
+            Timeout = TimeSpan.FromSeconds(Settings.TimeoutSeconds) };
+
+        if (!string.IsNullOrEmpty(Settings.Auth.Username))
+            await AuthenticateAsync();
+    }
+
+    public Task DisposeAsync() { Client.Dispose(); return Task.CompletedTask; }
+
+    protected async Task AuthenticateAsync(string? username = null, string? password = null)
+    {
+        var res = await Client.PostAsJsonAsync(Settings.Auth.TokenEndpoint,
+            new { username = username ?? Settings.Auth.Username, password = password ?? Settings.Auth.Password });
+        res.EnsureSuccessStatusCode();
+        var token = (await res.Content.ReadFromJsonAsync<TokenResponse>())!.AccessToken;
+        Client.DefaultRequestHeaders.Authorization =
+            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+    }
+
+    private sealed record TokenResponse(string AccessToken);
+}
+```
+
+## Test Class Header (bắt buộc)
+
+```csharp
+// ============================================================
+// {Resource} API Tests — v{N}
+// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Story: {ID}
+// APPEND-ONLY: không sửa methods đã tồn tại.
+// ============================================================
+namespace ApiTests.V{N};
+public sealed class {Resource}ApiTests : TestBase
+{
+    // Inline DTOs — không import từ production code
+    private sealed record {Resource}Dto(Guid Id, string Name);
+    private sealed record ListResponse<T>(IReadOnlyList<T> Data, int Total);
+}
+```
+
+## Test Naming
+
+```
+{HttpMethod}_{Resource}_Returns{Status}_When{Condition}
+```
+
+Ví dụ: `GetById_User_Returns200_WhenExists`, `Create_Order_Returns422_WhenEmailInvalid`
+
+AC test: comment `// AC: {text}` ngay dưới XML doc.
+
+## XML Doc (bắt buộc trên mỗi test)
+
+```csharp
+/// <summary>Verify {METHOD} {path} → {status} khi {condition}. Spec: {ref}</summary>
+[Fact]
+public async Task ...
+```
+
+## Coverage Matrix
+
+| Điều kiện | Status | Khi nào |
+|---|---|---|
+| Valid, authenticated | 2xx | Luôn |
+| Không có token | 401 | Endpoint yêu cầu auth |
+| Không đủ quyền | 403 | RBAC / ownership |
+| `{id}` không tồn tại | 404 | Có path param |
+| Required field thiếu/sai | 400/422 | Có request body |
+| Business rule (từ AC) | 4xx | Story có AC tương ứng |
+
+## CI/CD Env Vars
+
+```
+ASPNETCORE_ENVIRONMENT=Test
+APITEST__AUTH__USERNAME=...   # double __ cho nested key
+APITEST__AUTH__PASSWORD=...
+```

package/.claude/rules/csharp/patterns.md

@@ -48,3 +48,13 @@ public sealed class PaymentsOptions
 - Depend on interfaces at service boundaries
 - Keep constructors focused; if a service needs too many dependencies, split responsibilities
 - Register lifetimes intentionally: singleton for stateless/shared services, scoped for request data, transient for lightweight pure workers
+
+## Performance Anti-Patterns
+
+Avoid these in hot paths and async contexts:
+
+- **Blocking async**: `.Result` or `.Wait()` in async methods — use `await` instead
+- **EF Core N+1**: loading related entities in a loop — use `.Include()` or explicit batch queries
+- **Missing `AsNoTracking()`**: use on read-only queries to reduce EF overhead
+- **Missing `CancellationToken`**: propagate through all public async APIs to enable early exit
+- **Large allocations in hot paths**: prefer `ArrayPool<T>` or `Span<T>` over `new T[]` in frequently called code

package/.claude/rules/python/patterns.md

@@ -34,6 +34,16 @@ class CreateUserRequest:
 - Use context managers (`with` statement) for resource management
 - Use generators for lazy evaluation and memory-efficient iteration
 
+## Performance Anti-Patterns
+
+Avoid these in Python services:
+
+- **Sync I/O in async handlers**: blocking DB/HTTP calls inside `async def` FastAPI/Django routes — use `await` with async drivers
+- **Missing connection pooling**: configure `pool_size` and `max_overflow` in SQLAlchemy; never create a new engine per request
+- **Heavy computation in request handlers**: offload to Celery background tasks or `asyncio.run_in_executor`
+- **Missing cache on expensive queries**: wrap slow aggregations with Redis (e.g., `aiocache` or `fastapi-cache`)
+- **Loading full querysets when only counts or IDs needed**: use `.values_list()` / `.scalar()` instead of full ORM objects
+
 ## Reference
 
 See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization.

package/.claude/rules/typescript/patterns.md

@@ -50,3 +50,13 @@ interface Repository<T> {
   delete(id: string): Promise<void>
 }
 ```
+
+## Performance Anti-Patterns
+
+Avoid these in Node.js backends:
+
+- **Sequential awaits that could be parallel**: use `Promise.all()` when calls are independent
+- **CPU-blocking on event loop**: offload heavy computation to worker threads
+- **Missing connection pooling**: never create a new DB connection per request — use pooled clients
+- **ORM N+1**: missing `include`/`select` in Prisma/Sequelize — use eager loading or DataLoader for GraphQL
+- **Large file reads without streaming**: avoid `fs.readFile` on large files — use streams instead