@torus-engineering/tas-kit 1.9.0 → 1.11.1

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

@@ -1,171 +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=...
-```
+---
+paths:
+  - "**/*.cs"
+  - "**/ApiTests/**"
+  - "**/Api.Tests/**"
+---
+
+# C# API Automation Testing
+
+> Used by `/tas-api-test`. Extends [csharp/testing.md](./testing.md).
+
+## Tech Stack
+
+| Component | Choice |
+|---|---|
+| Framework | xUnit (default) — match project if already using 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 (no real secrets)
+  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: don't modify 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 (required)
+
+```csharp
+// ============================================================
+// {Resource} API Tests — v{N}
+// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Story: {ID}
+// APPEND-ONLY: don't modify existing methods.
+// ============================================================
+namespace ApiTests.V{N};
+public sealed class {Resource}ApiTests : TestBase
+{
+    // Inline DTOs — don't import from 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}
+```
+
+Example: `GetById_User_Returns200_WhenExists`, `Create_Order_Returns422_WhenEmailInvalid`
+
+AC test: comment `// AC: {text}` right below XML doc.
+
+## XML Doc (required on each test)
+
+```csharp
+/// <summary>Verify {METHOD} {path} → {status} when {condition}. Spec: {ref}</summary>
+[Fact]
+public async Task ...
+```
+
+## Coverage Matrix
+
+| Condition | Status | When |
+|---|---|---|
+| Valid, authenticated | 2xx | Always |
+| No token | 401 | Endpoint requires auth |
+| Insufficient permission | 403 | RBAC / ownership |
+| `{id}` doesn't exist | 404 | Has path param |
+| Required field missing/invalid | 400/422 | Has request body |
+| Business rule (from AC) | 4xx | Story has corresponding AC |
+
+## CI/CD Env Vars
+
+```
+ASPNETCORE_ENVIRONMENT=Test
+APITEST__AUTH__USERNAME=...   # double __ for nested key
+APITEST__AUTH__PASSWORD=...
+```

package/.claude/skills/ado-integration/SKILL.md

@@ -1,54 +1,54 @@
 ---
 name: ado-integration
 description: |
-  Azure DevOps integration. Auto-invoke khi user nhắc đến:
+  Azure DevOps integration. Auto-invoke when user mentions:
   sync ADO, push to board, pull work item, update status on ADO,
-  create work item on ADO, hoặc bất kỳ thao tác liên quan Azure DevOps.
+  create work item on ADO, or any Azure DevOps related operation.
 allowed-tools: Read, Write, Edit, Bash, Grep
 ---
 
 # ADO Integration Skill
 
-Cho phép đồng bộ hai chiều giữa file .md trong repo và work items trên Azure DevOps.
-ADO sync là **thao tác có chủ đích** — không tự động sau mỗi lần edit file.
+Enables bidirectional sync between .md files in repo and work items on Azure DevOps.
+ADO sync is **intentional operation** — not automatic after each file edit.
 
 ## When to Use
 
-- User yêu cầu sync, push, pull work item lên/từ ADO
-- User chạy `/ado-create`, `/ado-update`, `/ado-status`, `/ado-get`, `/ado-delete`
-- KHÔNG invoke khi: user chỉ edit file .md thông thường mà không nhắc đến ADO
+- User requests sync, push, pull work item to/from ADO
+- User runs `/ado-create`, `/ado-update`, `/ado-status`, `/ado-get`, `/ado-delete`
+- DO NOT invoke when: user only edits .md file normally without mentioning ADO
 
 ## Always / Ask / Never
 
-| | Hành động |
+| | Action |
 |---|---|
-| **Always** | Đọc `tas.yaml` và kiểm tra `ado.enabled` trước bất kỳ thao tác nào |
-| **Always** | Hiển thị ADO ID và URL sau mỗi create/update thành công |
-| **Always** | Cập nhật frontmatter `ado_id`, `ado_state`, `last_ado_sync` trong file .md sau sync |
-| **Ask** | Khi sync bulk nhiều items cùng lúc — confirm list trước khi chạy |
-| **Ask** | Khi phát hiện conflict giữa file .md và ADO item (ai là source of truth?) |
-| **Ask** | Khi delete work item — đây là thao tác không thể undo |
-| **Never** | Auto-sync mỗi khi file .md được edit (quá aggressive, dễ gây noise) |
-| **Never** | Xóa ADO item mà không có xác nhận rõ ràng từ user |
-| **Never** | Tạo duplicate work item nếu đã có `ado_id` trong frontmatter |
-
-## Bước đầu tiên — Kiểm tra ADO enabled
-
-Trước khi thực hiện bất kỳ thao tác nào, đọc `tas.yaml` tại root và kiểm tra `ado.enabled`:
-- Nếu `ado.enabled: false` hoặc field không tồn tại: thông báo "ADO integration bị tắt trong tas.yaml (`ado.enabled: false`). Bật lên nếu project dùng ADO." rồi dừng lại.
-- Nếu `ado.enabled: true`: tiếp tục bình thường.
+| **Always** | Read `tas.yaml` and check `ado.enabled` before any operation |
+| **Always** | Display ADO ID and URL after each successful create/update |
+| **Always** | Update frontmatter `ado_id`, `ado_state`, `last_ado_sync` in .md file after sync |
+| **Ask** | When syncing multiple items at once — confirm list before running |
+| **Ask** | When detecting conflict between .md file and ADO item (which is source of truth?) |
+| **Ask** | When deleting work item — this is irreversible operation |
+| **Never** | Auto-sync whenever .md file is edited (too aggressive, creates noise) |
+| **Never** | Delete ADO item without clear user confirmation |
+| **Never** | Create duplicate work item if `ado_id` already exists in frontmatter |
+
+## First Step — Check ADO Enabled
+
+Before performing any operation, read `tas.yaml` at root and check `ado.enabled`:
+- If `ado.enabled: false` or field doesn't exist: notify "ADO integration is disabled in tas.yaml (`ado.enabled: false`). Enable if project uses ADO." then stop.
+- If `ado.enabled: true`: continue normally.
 
 ## Prerequisites
 
-- Azure CLI + extension azure-devops: `az extension add --name azure-devops --upgrade`
-- Python 3.8+ với pyyaml: `pip install pyyaml`
-- PAT trong file .env: `AzureDevops_Personal_AccessToken=your-pat-here`
+- Azure CLI + azure-devops extension: `az extension add --name azure-devops --upgrade`
+- Python 3.8+ with pyyaml: `pip install pyyaml`
+- PAT in .env file: `AzureDevops_Personal_AccessToken=your-pat-here`
 
 ## Commands
 
-Tất cả ADO commands chạy qua: `python .tas/tools/tas-ado.py <command> [args]`
+All ADO commands run via: `python .tas/tools/tas-ado.py <command> [args]`
 
-Hoặc dùng slash commands:
+Or use slash commands:
 - `/ado-create <type> <temp-id> [--parent-id <id>]`
 - `/ado-get <ado-id>`
 - `/ado-update <type> <ado-id> [--assign <name>] [--status <state>]`
@@ -57,19 +57,19 @@ Hoặc dùng slash commands:
 
 ## File Convention
 
-- Tên file: `{type}-{ado_id}-{slug-title}.md`
-- Mỗi file có frontmatter YAML: `ado_id`, `ado_type`, `ado_state`, `last_ado_sync`
-- File .md là single source of truth, sync lên ADO khi cần
+- Filename: `{type}-{ado_id}-{slug-title}.md`
+- Each file has YAML frontmatter: `ado_id`, `ado_type`, `ado_state`, `last_ado_sync`
+- .md file is single source of truth, sync to ADO when needed
 
 ## Red Flags
 
-- File có `ado_id` nhưng state trong file khác ADO → confirm với user trước khi ghi đè
-- PAT hết hạn → hướng dẫn rotate, không log token ra stdout
-- `ado.enabled: true` nhưng project chưa setup Azure CLI → check prerequisites trước
+- File has `ado_id` but state in file differs from ADO → confirm with user before overwriting
+- PAT expired → guide to rotate, don't log token to stdout
+- `ado.enabled: true` but project hasn't set up Azure CLI → check prerequisites first
 
 ## Anti-Rationalization
 
 | Rationalization | Counter |
 |---|---|
-| "Auto-sync tiện hơn, không cần nhớ" | Hook auto-sync gây unintended pushes khi edit draft — sync phải có chủ đích |
-| "Delete chắc OK, mình biết mình đang làm gì" | ADO delete không có undo — luôn confirm, dù user trông có vẻ chắc chắn |
+| "Auto-sync is more convenient, no need to remember" | Hook auto-sync causes unintended pushes when editing draft — sync must be intentional |
+| "Delete is OK, I know what I'm doing" | ADO delete has no undo — always confirm, even if user seems confident |

package/.claude/skills/tas-conventions/SKILL.md

@@ -1,65 +1,65 @@
 ---
 name: tas-conventions
 description: |
-  Coding conventions và naming rules của dự án Torus. 
-  Auto-invoke khi viết code mới, review code, refactor, 
-  hoặc khi user hỏi về coding standards.
+  Coding conventions and naming rules for Torus projects. 
+  Auto-invoke when writing new code, reviewing code, refactoring, 
+  or when user asks about coding standards.
 allowed-tools: Read, Grep, Glob
 ---
 
 # TAS Conventions
 
-Khi generate hoặc review code, PHẢI tuân thủ conventions được định nghĩa trong `CLAUDE.md` của project.
+When generating or reviewing code, MUST follow conventions defined in project's `CLAUDE.md`.
 
 ## When to Use
 
-- Trước khi generate code mới (check conventions)
-- Khi review code của user (verify compliance)
-- Khi user hỏi "đặt tên thế nào?", "format như thế nào?"
-- KHÔNG invoke khi: đọc file thuần, không liên quan đến code output
+- Before generating new code (check conventions)
+- When reviewing user's code (verify compliance)
+- When user asks "what to name?", "what format?"
+- DO NOT invoke when: reading files only, not related to code output
 
 ## Always / Ask / Never
 
-| | Hành động |
+| | Action |
 |---|---|
-| **Always** | Đọc `CLAUDE.md` trước khi áp dụng convention |
-| **Always** | Chỉ ra file:line cụ thể khi phát hiện vi phạm |
-| **Ask** | Khi convention trong CLAUDE.md mơ hồ hoặc có conflict |
-| **Never** | Hardcode convention (naming, format) mà không đọc CLAUDE.md trước |
-| **Never** | Áp dụng convention từ project khác vào project hiện tại |
+| **Always** | Read `CLAUDE.md` before applying convention |
+| **Always** | Point to specific file:line when detecting violation |
+| **Ask** | When convention in CLAUDE.md is vague or has conflict |
+| **Never** | Hardcode convention (naming, format) without reading CLAUDE.md first |
+| **Never** | Apply convention from other project to current project |
 
 ## Checklist
 
-- Đọc `CLAUDE.md` để lấy naming conventions, branching, commit format, stack rules
-- Enforce các conventions đó trong code output
-- Nếu code vi phạm conventions, chỉ ra cụ thể: file:line + convention bị vi phạm + cách sửa
+- Read `CLAUDE.md` to get naming conventions, branching, commit format, stack rules
+- Enforce those conventions in code output
+- If code violates conventions, point specifically: file:line + violated convention + how to fix
 
-## Common Conventions (Default — override bằng CLAUDE.md)
+## Common Conventions (Default — override by CLAUDE.md)
 
-Các conventions mặc định này chỉ áp dụng khi `CLAUDE.md` không định nghĩa khác:
+These default conventions only apply when `CLAUDE.md` doesn't define otherwise:
 
 - Variables/functions: `camelCase`
 - Types/Interfaces/Components: `PascalCase`
 - Constants: `UPPER_SNAKE_CASE`
 - Boolean vars: prefix `is`, `has`, `should`, `can`
-- File naming: kebab-case cho files, PascalCase cho components
+- File naming: kebab-case for files, PascalCase for components
 - Commit format: `<type>: <description>` (feat, fix, refactor, docs, test, chore)
 
 ## Red Flags
 
-- Magic numbers trong code (e.g. `if (count > 50)`) → phải dùng named constant
-- Deep nesting >4 levels → dùng early return hoặc extract method
-- Function >50 lines → extract thành functions nhỏ hơn
-- File >800 lines → extract thành modules
-- Variable tên 1-2 ký tự (`x`, `t`, `d`) trong production code → đặt tên mô tả
-- `any` type trong TypeScript → dùng type cụ thể hoặc generic
-- Commented-out code block lớn → xóa nếu không cần, dùng git history thay thế
+- Magic numbers in code (e.g., `if (count > 50)`) → must use named constant
+- Deep nesting >4 levels → use early return or extract method
+- Function >50 lines → extract to smaller functions
+- File >800 lines → extract to modules
+- Variable with 1-2 char name (`x`, `t`, `d`) in production code → use descriptive name
+- `any` type in TypeScript → use specific type or generic
+- Large commented-out code block → delete if not needed, use git history instead
 
 ## Verification
 
-- [ ] CLAUDE.md đã được đọc trước khi review/generate code
-- [ ] Naming tuân thủ conventions trong CLAUDE.md
-- [ ] Không có magic numbers
-- [ ] Không có deep nesting (>4 levels)
+- [ ] CLAUDE.md has been read before reviewing/generating code
+- [ ] Naming follows conventions in CLAUDE.md
+- [ ] No magic numbers
+- [ ] No deep nesting (>4 levels)
 - [ ] Functions < 50 lines, files < 800 lines
-- [ ] Commit message theo format đã định nghĩa
+- [ ] Commit message follows defined format