@torus-engineering/tas-kit 1.9.0 → 1.11.1

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

@@ -1,143 +1,143 @@
-# /tas-apitest $ARGUMENTS
-
-Vai trò: SE - Software Engineer
-Generate .NET xUnit automation test project cho REST API từ API Test Spec file (Markdown).
-
-## Always / Ask / Never
-
-| | Hành động |
-|---|---|
-| **Always** | Đọc toàn bộ API Test Spec file 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 test 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 Input
-
-`$ARGUMENTS` là path đến API Test Spec file: `docs/tests/API-Test-Spec-{slug}.md`.
-
-Nếu không có → hỏi user:
-```
-Nhập path đến API Test Spec file (vd: docs/tests/API-Test-Spec-users.md)
-```
-
-### Bước 2 — Parse API Test Spec
-
-Đọc `.claude/rules/csharp/api-testing.md` để nắm convention trước khi generate.
-
-Từ API Test Spec file, thu thập:
-- API version
-- Endpoints với method, path, params
-- Test cases theo từng endpoint (TC-XXX)
-- Request/response schemas
-- Auth requirements
-- Test data requirements
-- Setup/teardown notes
-
-### 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 — Get API Version from Spec
-
-Đọc version từ API Test Spec file (tìm frontmatter `api_version` hoặc section headers `## v{N}`).
-
-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` với values từ spec
-- `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 từ Spec
-
-Nhóm endpoints theo resource. Mỗi nhóm → `tests/ApiTests/{version}/{Resource}ApiTests.cs`.
-
-Với mỗi test case (TC-XXX) trong spec:
-1. Đọc test case details
-2. Map sang test method với naming: `{HttpMethod}_{Resource}_Returns{Status}_When{Condition}`
-3. Generate XML doc từ test case title
-4. Generate assertions từ expected response
-5. Add AC reference comment nếu có
-
-Test class header comment:
-```csharp
-// ============================================================
-// {Resource} API Tests — v{N}
-// Spec: docs/tests/API-Test-Spec-{slug}.md
-// Generated: {YYYY-MM-DD}
-// Story: {ID} (if applicable)
-// APPEND-ONLY: không sửa methods đã tồn tại.
-// ============================================================
-```
-
-### 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 đã có** trong version folder → check từng test method:
-  - Method đã tồn tại (cùng tên) → **SKIP**, không ghi đè
-  - Method chưa có → append vào cuối class
-
-### Bước 8 — Generate Test Data Files (nếu spec yêu cầu)
-
-Nếu spec có `test-data.{env}.json` references:
-- Tạo `tests/ApiTests/data/test-data.Test.json` với sample data từ spec
-- Hướng dẫn user tạo `test-data.Staging.json` và `test-data.local.json`
-
-### Bước 9 — 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 10 — Summary
-
-Hiển thị:
-1. Test project path
-2. Number of test classes generated
-3. Number of test methods generated
-4. Coverage matrix (so với spec)
-5. Next steps để chạy tests
-
-```
-## API Tests Generated
-
-**Project**: `tests/ApiTests/`
-**Version**: v{N}
-**Test Classes**: {N}
-**Test Methods**: {N}
-
-### Generated Files
-- tests/ApiTests/{version}/{Resource}ApiTests.cs
-- tests/ApiTests/Shared/TestBase.cs (if new project)
-
-### Coverage (vs Spec)
-[Print coverage table: spec test cases vs generated methods]
-
-### Next Steps
-1. Configure test environment: edit tests/ApiTests/appsettings.Test.json
-2. Add test data: tests/ApiTests/data/test-data.Test.json
-3. Run tests: `dotnet test tests/ApiTests/`
-```
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào API Test Spec file.
+# /tas-apitest $ARGUMENTS
+
+Role: SE - Software Engineer
+Generate .NET xUnit automation test project for REST API from API Test Spec file (Markdown).
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read entire API Test Spec file before generating any test |
+| **Always** | Organize tests by API version — each version separate folder |
+| **Always** | Append-only: don't modify files in existing old version folder |
+| **Always** | URL and credentials in `appsettings.json` — not hardcoded in code |
+| **Always** | XML doc comment on each test method |
+| **Ask** | When test spec unclear about expected response schema |
+| **Never** | Modify or delete old version test files |
+| **Never** | Hardcode base URL, API key, credentials in test code |
+| **Never** | Skip error path — each endpoint needs ≥1 happy path + ≥1 error path |
+
+## Actions
+
+### Step 1 — Locate Input
+
+`$ARGUMENTS` is path to API Test Spec file: `docs/tests/API-Test-Spec-{slug}.md`.
+
+If not provided → ask user:
+```
+Enter path to API Test Spec file (e.g., docs/tests/API-Test-Spec-users.md)
+```
+
+### Step 2 — Parse API Test Spec
+
+Read `.claude/rules/csharp/api-testing.md` for conventions before generating.
+
+From API Test Spec file, collect:
+- API version
+- Endpoints with method, path, params
+- Test cases per endpoint (TC-XXX)
+- Request/response schemas
+- Auth requirements
+- Test data requirements
+- Setup/teardown notes
+
+### Step 3 — Detect Existing Test Project
+
+Glob find `**/ApiTests/*.csproj`, `**/Api.Tests/*.csproj`, `**/IntegrationTests/*.csproj`.
+
+- **Found**: Read current framework (xUnit/NUnit/MSTest), glob `v*/` folders to know existing versions.
+- **Not found**: Create new at `tests/ApiTests/` with xUnit + FluentAssertions (per `csharp/testing.md`).
+
+### Step 4 — Get API Version from Spec
+
+Read version from API Test Spec file (find frontmatter `api_version` or section headers `## v{N}`).
+
+Version folder: lowercase, no dot — `v1`, `v2` (not `v1.0`).
+
+### Step 5 — Generate Infrastructure (only when creating new project)
+
+Read `.claude/rules/csharp/api-testing.md` section **Project Structure** and **Config Pattern** to generate:
+- `ApiTests.csproj` with standard packages
+- `appsettings.json` (base) + `appsettings.Test.json` + `appsettings.Staging.json` with values from spec
+- `Shared/TestBase.cs` — load config, HttpClient, helper methods
+- `Shared/ApiTestSettings.cs` — strongly typed settings
+- `.gitignore` for `appsettings.*.local.json`
+
+### Step 6 — Generate Test Classes from Spec
+
+Group endpoints by resource. Each group → `tests/ApiTests/{version}/{Resource}ApiTests.cs`.
+
+For each test case (TC-XXX) in spec:
+1. Read test case details
+2. Map to test method with naming: `{HttpMethod}_{Resource}_Returns{Status}_When{Condition}`
+3. Generate XML doc from test case title
+4. Generate assertions from expected response
+5. Add AC reference comment if any
+
+Test class header comment:
+```csharp
+// ============================================================
+// {Resource} API Tests — v{N}
+// Spec: docs/tests/API-Test-Spec-{slug}.md
+// Generated: {YYYY-MM-DD}
+// Story: {ID} (if applicable)
+// APPEND-ONLY: don't modify existing methods.
+// ============================================================
+```
+
+### Step 7 — Append-Only Guard
+
+Before writing file: check if file already exists.
+- **File doesn't exist** → create normally.
+- **File exists** in version folder → check each test method:
+  - Method exists (same name) → **SKIP**, don't overwrite
+  - Method doesn't exist → append to end of class
+
+### Step 8 — Generate Test Data Files (if spec requires)
+
+If spec has `test-data.{env}.json` references:
+- Create `tests/ApiTests/data/test-data.Test.json` with sample data from spec
+- Guide user to create `test-data.Staging.json` and `test-data.local.json`
+
+### Step 9 — Post-Generate Review
+
+Launch `csharp-reviewer` agent:
+> Review `tests/ApiTests/{version}/`. Read `.claude/rules/csharp/testing.md` + `.claude/rules/csharp/api-testing.md`.
+> Focus: async/await, HttpClient disposal, assertion completeness, XML doc coverage.
+> Format: Critical / High / Medium / Low with file:line.
+
+Gate: Critical/High → fix immediately. Medium/Low → list suggestions.
+
+### Step 10 — Summary
+
+Display:
+1. Test project path
+2. Number of test classes generated
+3. Number of test methods generated
+4. Coverage matrix (vs spec)
+5. Next steps to run tests
+
+```
+## API Tests Generated
+
+**Project**: `tests/ApiTests/`
+**Version**: v{N}
+**Test Classes**: {N}
+**Test Methods**: {N}
+
+### Generated Files
+- tests/ApiTests/{version}/{Resource}ApiTests.cs
+- tests/ApiTests/Shared/TestBase.cs (if new project)
+
+### Coverage (vs Spec)
+[Print coverage table: spec test cases vs generated methods]
+
+### Next Steps
+1. Configure test environment: edit tests/ApiTests/appsettings.Test.json
+2. Add test data: tests/ApiTests/data/test-data.Test.json
+3. Run tests: `dotnet test tests/ApiTests/`
+```
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to API Test Spec file.

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

@@ -1,19 +1,19 @@
 # /tas-brainstorm $ARGUMENTS
 
-Vai trò: Bất kỳ
-Brainstorm có cấu trúc trước khi code hoặc thiết kế.
+Role: Any
+Structured brainstorming before coding or designing.
 
-## Hành động
-1. $ARGUMENTS là chủ đề brainstorm
-2. Dẫn dắt qua 4 bước:
-   a. **Clarify**: Hỏi 3-5 câu hỏi làm rõ vấn đề
-   b. **Explore**: Đưa ra 3+ hướng giải quyết, mỗi hướng có pros/cons
-   c. **Evaluate**: So sánh các hướng theo tiêu chí: complexity, maintainability, cost, time
-   d. **Decide**: Đề xuất hướng tốt nhất và lý do
+## Actions
+1. $ARGUMENTS is the brainstorming topic
+2. Guide through 4 steps:
+   a. **Clarify**: Ask 3-5 questions to clarify the problem
+   b. **Explore**: Propose 3+ solution directions, each with pros/cons
+   c. **Evaluate**: Compare directions by criteria: complexity, maintainability, cost, time
+   d. **Decide**: Recommend best direction and reasoning
 
-3. Nếu kết quả brainstorm dẫn đến quyết định kiến trúc, gợi ý user chạy /tas-adr
+3. If brainstorming result leads to architecture decision, suggest user run /tas-adr
 
-## Nguyên tắc
-- KHÔNG nhảy thẳng vào giải pháp
-- Hỏi trước, suggest sau
-- Luôn xem xét ít nhất 2 alternatives
+## Principles
+- DO NOT jump straight to solution
+- Ask first, suggest later
+- Always consider at least 2 alternatives

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

@@ -1,113 +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`
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Bug đang làm việc.
+# /tas-bug $ARGUMENTS
+
+Manage entire bug lifecycle: create, analyze, fix, verify.
+Bug status determines next step — no role declaration needed.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Display current status and next action before doing anything |
+| **Always** | Write regression test BEFORE fixing |
+| **Always** | Launch independent review agent after fix — no review in same session |
+| **Ask** | When needing to read files outside Bug file (Status = Committed) |
+| **Never** | Patch symptom — must fix root cause |
+| **Never** | Skip review step after fix |
+| **Never** | Auto-commit or push — wait for user manual testing first |
+
+## Stack Detection
+Read `.claude/rules/common/stack-detection.md`.
+
+## Actions
+
+### Step 1 — Determine mode
+
+`$ARGUMENTS` is new bug description → **CREATE mode**
+`$ARGUMENTS` is Bug ID (e.g., `Bug-001`) → **UPDATE mode**
+
+---
+
+### CREATE mode
+
+Role: PE or SE (whoever discovered the bug)
+
+1. Read `project.code` from root/`tas.yaml`
+2. Ask user:
+   - Which Feature does this bug belong to?
+   - Severity: `Critical` | `High` | `Medium` | `Low`
+   - Steps to reproduce
+   - Expected vs Actual behavior
+   - Environment where discovered: Test | Staging | Production
+3. Create `docs/bugs/{code}-Bug-{NNN}-{slug}.md` from template `.tas/templates/Bug.md`
+4. Initial bug status: `New`
+
+---
+
+### UPDATE mode
+
+Find Bug file via glob `docs/bugs/*-Bug-{ID}-*.md`, read current status.
+
+**Display before acting:**
+> "Bug-{NNN} is currently at status: **{status}** — next step is {action}. Continue?"
+
+---
+
+#### Status = `New` — Analyze (SE)
+
+1. Read error logs/stack trace from Bug file
+2. Trace code flow, identify file and line causing error
+3. Write Root Cause Analysis into Bug file
+4. Write Regression Test Cases (test that reproduces bug)
+5. Update status: `New` → `Committed`
+
+---
+
+#### Status = `Committed` — Fix (SE)
+
+**File reading rule:** ONLY read Bug file. DO NOT read PRD, SAD, ADR, Design-Spec, DO NOT scan directories.
+If additional files needed → ask user confirmation first.
+
+Before fixing, read:
+- `.claude/rules/common/security.md` — fix must not create new security risks
+- `.claude/rules/common/testing.md` — regression test writing patterns
+- `.claude/rules/[lang_agent stack]/coding-style.md` — follow conventions
+
+**Fix workflow:**
+a. Run regression test case → confirm **FAIL** (reproduces bug)
+b. Fix code at root cause
+c. Run regression test → confirm **PASS**
+d. Run full test suite → no new regressions
+→ If build fails or test compile errors: launch `build-resolver` agent with error output before continuing.
+
+**After fix — Post-Fix Review (Isolated Agent):**
+
+Follow `.claude/rules/common/post-review-agent.md`.
+Pass in: Bug file path, changed files list, stack (from CLAUDE.md), lang_agent.
+
+After review passes:
+- Update status: `Committed` → `Deploy Test`
+- Output suggested commit message: `fix: {short description} - resolves Bug-{NNN}`
+- Ask: "Have you tested manually? Want to commit and deploy to Test?"
+
+---
+
+#### Status = `Verify Test` / `Verify Stag` — Verify (PE)
+
+1. PE verifies on corresponding environment:
+   - Run Steps to Reproduce again → confirm bug no longer exists
+   - Check regression test case has passed
+2. **Pass** → update to next status (`Deploy Stag` or `Done`)
+3. **Fail** → document reason, update status back to `Committed`, SE fixes again
+
+---
+
+## Principles
+- DO NOT patch symptom — must fix root cause
+- MUST have regression test case BEFORE fixing
+- Review must run through independent Agent — not inline in current session
+- `Critical`/`High` bugs must be fixed before Feature is Verified
+- Flow: `New` → `Committed` → `Deploy Test` → `Verify Test` → `Deploy Stag` → `Verify Stag` → `Deploy Prod` → `Verify Prod` → `Done`
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to working Bug file.

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

@@ -1,37 +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 ()
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào `docs/design-spec.md`.
+# /tas-design $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Design Specification document (UI/UX flows, wireframe descriptions).
+
+## Prerequisite
+- docs/prd.md must exist
+
+## Actions
+1. Need context from root/tas.yaml and docs/prd.md
+2. Check if docs/design-spec.md already exists:
+
+### CREATE mode (file doesn't exist):
+3. Need context from .tas/templates/Design-Spec.md
+4. $ARGUMENTS is design scope description. If not provided, base on PRD.
+5. Create file docs/design-spec.md containing:
+   - User flows (Mermaid flowchart)
+   - Screen descriptions
+   - Navigation structure
+   - Interaction patterns
+   - Responsive behavior notes
+6. Update `project-status.yaml` per `.claude/rules/common/project-status.md` — add `artifacts.design_spec`.
+
+### UPDATE mode (file exists):
+3. Need context from current docs/design-spec.md
+4. $ARGUMENTS is change description. If not provided, ask user which section to update.
+5. Update file, add changelog
+6. Update `project-status.yaml` per `.claude/rules/common/project-status.md` — update `artifacts.design_spec`.
+
+## Principles
+- Focus on flows and behavior, not pixel-perfect design
+- Each screen needs: purpose, key elements, actions available
+- Mermaid compliance: :::mermaid wrapper, no () in node labels
+
+## Final Step — Token Log
+
+Invoke skill `token-logger`: write AI Usage Log to `docs/design-spec.md`.