@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/.tas/README.md

@@ -1,45 +1,45 @@
-# TAS Kit
+# TAS Kit
 
-**Torus Agentic SDLC Kit** — Bộ công cụ AI-assisted SDLC cho Claude Code, được thiết kế theo triết lý Spec-Driven Development và Context-Aware Architecture.
+**Torus Agentic SDLC Kit** — AI-assisted SDLC toolkit, designed following Spec-Driven Development philosophy and Context-Aware Architecture.
 
 ---
 
-## Mục đích
+## Purpose
 
-TAS Kit giúp các team phát triển phần mềm:
-- **Chuẩn hóa quy trình SDLC** với các artifacts rõ ràng (PRD, SAD, ADR, Epic, Feature, Story)
-- **Tối ưu hóa token usage** thông qua Context Layer — đầu tư ở phase thiết kế, tiết kiệm ở phase code
-- **Hỗ trợ nhiều mô hình làm việc**: từ solo developer đến full team với các role PE/SE/DSE
-- **Tự động hóa** với Hybrid và Autonomous agents hoạt động 24/7
+TAS Kit helps software development teams:
+- **Standardize SDLC process** with clear artifacts (PRD, SAD, ADR, Epic, Feature, Story)
+- **Optimize token usage** through Context Layer — invest in design phase, save in code phase
+- **Support multiple workflows**: from solo developer to full team with PE/SE/DSE roles
+- **Automate** with Hybrid and Autonomous agents operating 24/7
 
 ---
 
-## Triết lý thiết kế
+## Design Philosophy
 
 ### Spec-Driven Development
-Tất cả code bắt đầu từ spec. Story.md là "context digest" đã hấp thụ toàn bộ thông tin từ PRD, SAD, ADR, Feature. Mỗi session implement chỉ cần đọc CLAUDE.md + Story.md — không cần load lại toàn bộ artifacts.
+All code starts from spec. Story.md is "context digest" that has absorbed all information from PRD, SAD, ADR, Feature. Each implementation session only needs to read CLAUDE.md + Story.md — no need to reload all artifacts.
 
 ### Human-Led, AI-Powered
-- **Con người chủ đạo**: Quyết định architecture, approve design, review code
-- **AI hỗ trợ**: Tạo draft, implement theo spec, chạy tests, phát hiện bugs
+- **Human-led**: Architecture decisions, design approval, code review
+- **AI-assisted**: Draft creation, implementation per spec, test execution, bug detection
 
 ### Dual Mode Operation
-- **Hybrid Mode**: Developer và AI làm việc cùng nhau trong session
-- **Autonomous Mode**: AI tự động develop 24/7, report kết quả khi xong
+- **Hybrid Mode**: Developer and AI work together in session
+- **Autonomous Mode**: AI automatically develops 24/7, reports results when done
 
 ### Lightweight & Context-Aware
-- Mỗi skill < 3KB, tổng kit < 50KB
-- Context Layer: đầu tư token ở phase thiết kế để tiết kiệm gấp nhiều lần ở phase code
-- Khi code: PHẢI bắt đầu session mới (không tận dụng session cũ đã load PRD/SAD vì sẽ phình Window Context)
+- Each skill < 3KB, total kit < 50KB
+- Context Layer: invest tokens in design phase to save many times in code phase
+- When coding: MUST start new session (don't reuse old session that loaded PRD/SAD to avoid Window Context bloat)
 
 ### Role-Based & Template-Driven
-- 3 role thực tế của Torus: PE (Product Engineer), SE (Software Engineer), DSE (DevOps Engineer)
-- Templates riêng cho PRD, SAD, ADR, Epic, Feature, Story theo chuẩn Torus
-- Flow configurable qua file `tas.yaml`
+- 3 actual roles at Torus: PE (Product Engineer), SE (Software Engineer), DSE (DevOps Engineer)
+- Separate templates for PRD, SAD, ADR, Epic, Feature, Story per Torus standards
+- Flow configurable via `tas.yaml` file
 
 ### Azure DevOps Compatible
-- Output Markdown tương thích Azure DevOps Wiki
-- Mermaid diagrams không dùng ký tự `()` (tránh conflict với ADO syntax)
+- Markdown output compatible with Azure DevOps Wiki
+- Mermaid diagrams don't use `()` characters (avoid conflict with ADO syntax)
 
 ---
 
@@ -152,29 +152,29 @@ graph TD
 | **Phase 3: Implementation** | PE, SE, AI | `/tas-plan`, `/tas-dev`, `/tas-fix`, `/tas-apitest`, `/tas-e2e`, `/tas-functest-web`, `/tas-functest-mobile`, `/tas-e2e-web`, `/tas-e2e-mobile`, `/tas-bug`, `/tas-review` | Plan.md, Source Code, API Testing Script, E2E Test Scenarios, Functional Test Scripts, Bug Report, Code Review Report |
 | **Phase 4: Quality & Deploy** | PE, DSE | `/tas-security`, Pipeline/CLI | Security Report, Test Report, Production |
 
-### Chi tiết từng Phase
+### Phase Details
 
 #### Phase 1: Discovery
-- **PE**: Tạo PRD với `/tas-prd`, tạo design-spec với `/tas-design`
-- **SE**: Tạo SAD với `/tas-sad`, tạo ADR với `/tas-adr`
+- **PE**: Create PRD with `/tas-prd`, create design-spec with `/tas-design`
+- **SE**: Create SAD with `/tas-sad`, create ADR with `/tas-adr`
 
 #### Phase 2: Planning
-- **PE**: Breakdown Epic với `/tas-epic`, Feature với `/tas-feature`, Story với `/tas-story`
+- **PE**: Breakdown Epic with `/tas-epic`, Feature with `/tas-feature`, Story with `/tas-story`
 
 #### Phase 3: Implementation
-- **SE**: Tạo Plan với `/tas-plan`, Implement với `/tas-dev`, Fix bug với `/tas-fix`
-- **SE**: Review code với `/tas-review`
-- **PE**: Tạo Functional Testing Spec với `/tas-functest`
-- **SE**: Tạo API Testing Script với `/tas-apitest`
-- **PE**: Tạo E2E Test Scenarios với `/tas-e2e`
-- **SE**: Tạo Functional Test Scripts với `/tas-functest-web`, `/tas-functest-mobile`
-- **PE**: Tạo E2E Test Scripts với `/tas-e2e-web`, `/tas-e2e-mobile`
-- **PE**: Tạo Bug Report với `/tas-bug`
+- **SE**: Create Plan with `/tas-plan`, Implement with `/tas-dev`, Fix bug with `/tas-fix`
+- **SE**: Review code with `/tas-review`
+- **PE**: Create Functional Testing Spec with `/tas-functest`
+- **SE**: Create API Testing Script with `/tas-apitest`
+- **PE**: Create E2E Test Scenarios with `/tas-e2e`
+- **SE**: Create Functional Test Scripts with `/tas-functest-web`, `/tas-functest-mobile`
+- **PE**: Create E2E Test Scripts with `/tas-e2e-web`, `/tas-e2e-mobile`
+- **PE**: Create Bug Report with `/tas-bug`
 
 #### Phase 4: Quality & Deploy
-- **DSE**: Security Review với `/tas-security`
-- **PE**: Chạy Pipeline/CLI để execute Automation Tests
-- **DSE**: Deploy lên Production
+- **DSE**: Security Review with `/tas-security`
+- **PE**: Run Pipeline/CLI to execute Automation Tests
+- **DSE**: Deploy to Production
 
 ---
 
@@ -193,13 +193,13 @@ npx @torus-engineering/tas-kit install --yes    # skip confirmation prompts
 
 ---
 
-## Thiết lập quan trọng
+## Important Setup
 
 ### CLAUDE.md
 
-File cấu hình quan trọng nhất — Claude đọc file này đầu tiên trong mọi session.
+Most important configuration file — Claude reads this file first in every session.
 
-**Cấu trúc:**
+**Structure:**
 ```markdown
 # Project Name
 
@@ -217,9 +217,9 @@ File cấu hình quan trọng nhất — Claude đọc file này đầu tiên tr
 
 ### tas.yaml
 
-Điều khiển flow của TAS Kit theo từng dự án.
+Controls TAS Kit flow per project.
 
-**Cấu trúc:**
+**Structure:**
 ```yaml
 project:
   name: "My Project"
@@ -238,9 +238,9 @@ flow:
 
 ### project-status.yaml
 
-Index tổng hợp trạng thái dự án — được cập nhật tự động sau mỗi thay đổi artifact.
+Project status index — automatically updated after each artifact change.
 
-**Cấu trúc:**
+**Structure:**
 ```yaml
 last_updated: 2025-01-15
 
@@ -262,7 +262,7 @@ epics:
 
 ### .env
 
-Environment variables cho Azure DevOps integration.
+Environment variables for Azure DevOps integration.
 
 ```bash
 AZURE_DEVOPS_PAT=your_pat_here
@@ -281,7 +281,7 @@ AZURE_DEVOPS_PROJECT=your_project
   agents/     29 specialized subagents
 .tas/
   templates/  Markdown templates (PRD, SAD, ADR, Epic, Feature, Story...)
-  checklists/ Code review, story done, security checklists
+  rules/      Coding standards + workflow rules (code-review, story-done, security...)
   tools/      ADO integration script (tas-ado.py)
 CLAUDE.md     Project context template (edit this for your project)
 tas.yaml      Flow configuration template (edit this for your project)
@@ -292,31 +292,31 @@ tas.yaml      Flow configuration template (edit this for your project)
 
 ## Commands Reference
 
-| Command | Mô tả | Role |
-|---------|-------|------|
-| `/tas-init` | Khởi tạo TAS cho dự án mới | All |
-| `/tas-status` | Hiển thị trạng thái hiện tại của dự án | All |
-| `/tas-prd` | Tạo/cập nhật Product Requirements Document | PE |
-| `/tas-sad` | Tạo/cập nhật Solution Architecture Document | SE |
-| `/tas-adr` | Tạo Architecture Decision Record | SE |
-| `/tas-design` | Tạo Design Specification | SE |
-| `/tas-epic` | Tạo/cập nhật Epic | SE |
-| `/tas-feature` | Tạo/cập nhật Feature | SE |
-| `/tas-story` | Tạo/cập nhật Story | SE |
-| `/tas-functest` | Tạo Functional Testing Specification | SE |
+| Command | Description | Role |
+|---------|-------------|------|
+| `/tas-init` | Initialize TAS for new project | All |
+| `/tas-status` | Display current project status | All |
+| `/tas-prd` | Create/update Product Requirements Document | PE |
+| `/tas-sad` | Create/update Solution Architecture Document | SE |
+| `/tas-adr` | Create Architecture Decision Record | SE |
+| `/tas-design` | Create Design Specification | SE |
+| `/tas-epic` | Create/update Epic | SE |
+| `/tas-feature` | Create/update Feature | SE |
+| `/tas-story` | Create/update Story | SE |
+| `/tas-functest` | Create Functional Testing Specification | SE |
 | `/tas-spec` | Lightweight spec (solo / prototype) | SE |
-| `/tas-plan` | Lập kế hoạch kỹ thuật implementation | SE |
+| `/tas-plan` | Create technical implementation plan | SE |
 | `/tas-dev` | Implement story (agentic) | AI |
-| `/tas-fix` | Quick fix không cần full story flow | SE |
-| `/tas-apitest` | Tạo API Testing Script tự động | SE |
-| `/tas-e2e` | Tạo E2E Test Scenarios | PE |
-| `/tas-functest-web` | Tạo Functional Test Script cho Web | SE |
-| `/tas-functest-mobile` | Tạo Functional Test Script cho Mobile | SE |
-| `/tas-e2e-web` | Tạo E2E Test Script cho Web | PE |
-| `/tas-e2e-mobile` | Tạo E2E Test Script cho Mobile | PE |
-| `/tas-bug` | Tạo Bug Report | PE |
-| `/tas-review` | Code Review với checklist | SE |
-| `/tas-brainstorm` | Brainstorm giải pháp | All |
+| `/tas-fix` | Quick fix without full story flow | SE |
+| `/tas-apitest` | Create API Testing Script automatically | SE |
+| `/tas-e2e` | Create E2E Test Scenarios | PE |
+| `/tas-functest-web` | Create Functional Test Script for Web | SE |
+| `/tas-functest-mobile` | Create Functional Test Script for Mobile | SE |
+| `/tas-e2e-web` | Create E2E Test Script for Web | PE |
+| `/tas-e2e-mobile` | Create E2E Test Script for Mobile | PE |
+| `/tas-bug` | Create Bug Report | PE |
+| `/tas-review` | Code Review with checklist | SE |
+| `/tas-brainstorm` | Brainstorm solutions | All |
 | `/tas-security` | Security Review | DSE |
 | `/ado-*` | Azure DevOps integration | All |
 
@@ -331,4 +331,4 @@ tas.yaml      Flow configuration template (edit this for your project)
 
 ## Documentation
 
-Xem `.tas/README.md` sau khi install để có tài liệu chi tiết.
+See `.tas/README.md` after install for detailed documentation.

package/{.claude → .tas/_platform/claude-code}/settings.json

@@ -19,18 +19,6 @@
     ]
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node -e \"const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const p=(d.tool_input||{}).file_path||''; const s=['.env','.prod.','.production.','appsettings.Production','secrets/','terraform/','.pem','.key','credentials'].find(x=>p.toLowerCase().includes(x.toLowerCase())); if(s) console.log('[TAS] WARNING: Sensitive file ('+s+'): '+p+' → Confirm this edit is intentional.');\"",
-            "description": "Warn before editing sensitive files"
-          }
-        ]
-      }
-    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",

package/{.claude → .tas/_platform}/hooks/code-quality.js

@@ -22,7 +22,7 @@ const { execSync } = require('child_process');
 // --- Read hook input ---
 let input;
 try {
-  const raw = fs.readFileSync('/dev/stdin', 'utf8');
+  const raw = fs.readFileSync(0, 'utf8');
   input = JSON.parse(raw);
 } catch {
   process.exit(0);

package/{.claude → .tas/_platform}/hooks/session-end.js

@@ -45,7 +45,7 @@ if (fs.existsSync(path.join(cwd, 'package.json'))) {
   } catch { /* ignore */ }
 
   if (hasTestScript) {
-    const result = run('npm test -- --passWithNoTests 2>&1', cwd);
+    const result = run('npm test', cwd);
     checks.push(result.ok
       ? '✓ Tests passed (npm test)'
       : '✗ Tests FAILED (npm test) — fix before committing'
@@ -56,11 +56,25 @@ if (fs.existsSync(path.join(cwd, 'package.json'))) {
 
 // .NET
 if (!testRan) {
-  const csprojFiles = (() => {
-    try {
-      return fs.readdirSync(cwd).filter(f => f.endsWith('.csproj') || f.endsWith('.sln'));
-    } catch { return []; }
-  })();
+  function findDotnetFiles(startDir, maxDepth = 3) {
+    const results = [];
+    function walk(dir, depth) {
+      if (depth > maxDepth) return;
+      try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+            walk(path.join(dir, entry.name), depth + 1);
+          } else if (entry.name.endsWith('.csproj') || entry.name.endsWith('.sln')) {
+            results.push(entry.name);
+          }
+        }
+      } catch { /* ignore */ }
+    }
+    walk(startDir, 0);
+    return results;
+  }
+
+  const csprojFiles = findDotnetFiles(cwd);
 
   if (csprojFiles.length > 0) {
     const result = run('dotnet test --no-build --logger "console;verbosity=minimal" 2>&1', cwd);
@@ -89,25 +103,6 @@ if (!testRan) {
   }
 }
 
-// ─── 2. Check project-status.yaml updated today ──────────────────────────────
-const statusFile = path.join(cwd, 'project-status.yaml');
-if (fs.existsSync(statusFile)) {
-  const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
-  try {
-    const content = fs.readFileSync(statusFile, 'utf8');
-    if (content.includes(today)) {
-      checks.push('✓ project-status.yaml updated today');
-    } else {
-      checks.push('⚠ project-status.yaml not updated today — run /tas-status to sync');
-    }
-  } catch {
-    checks.push('⚠ Could not read project-status.yaml');
-  }
-}
-
-// ─── 3. Remind about story status ────────────────────────────────────────────
-checks.push('→ Next: /tas-review-code before moving story to Deploy Test');
-
 // ─── Output ──────────────────────────────────────────────────────────────────
 if (checks.length > 0) {
   console.log('\n[TAS] Session end checks:');

package/.tas/commands/ado-create.md

@@ -0,0 +1,28 @@
+# /ado-create $ARGUMENTS
+
+Create new work item on Azure DevOps from local .md file.
+
+## Syntax
+/ado-create <type> <temp-id> [--parent-id <id>]
+
+- type: epic | feature | story | bug
+- temp-id: Temporary ID in local filename (will be renamed after creating on ADO)
+- --parent-id: ADO ID of parent work item (optional)
+
+## Examples
+/ado-create story 789 --parent-id 456
+/ado-create epic 001
+/ado-create bug 003 --parent-id 123
+
+## Actions
+1. Read `.tas/rules/ado-integration.md` for ADO operating rules (Always/Ask/Never, Red Flags).
+2. Read `tas.yaml`, check `ado.enabled`. If `false` or missing: report "ADO integration is disabled (`ado.enabled: false` in tas.yaml)." then stop.
+3. Run: python .tas/tools/tas-ado.py create-<type> <temp-id> [--parent-id <id>]
+4. Script will:
+   - Find file by pattern {type}-{temp-id}-*.md
+   - Extract title and description
+   - Create work item on ADO
+   - Rename file to {type}-{ado_id}-*.md
+   - Add parent relation if --parent-id provided
+   - Update frontmatter: ado_id, last_ado_sync
+5. Update root/project-status.yaml

package/.tas/commands/ado-delete.md

@@ -0,0 +1,22 @@
+# /ado-delete $ARGUMENTS
+
+Delete work item on Azure DevOps. Does NOT delete local file.
+
+## Syntax
+/ado-delete <type> <ado-id>
+
+- type: epic | feature | story | bug
+
+## Examples
+/ado-delete story 1234
+/ado-delete bug 5678
+
+## Actions
+1. Read `.tas/rules/ado-integration.md` for ADO operating rules (Always/Ask/Never, Red Flags).
+2. Read `tas.yaml`, check `ado.enabled`. If `false` or missing: report "ADO integration is disabled (`ado.enabled: false` in tas.yaml)." then stop.
+3. MUST ask user confirmation before deleting: "Are you sure you want to delete <type> #<ado-id> on ADO?"
+4. After user confirms, run: python .tas/tools/tas-ado.py delete-<type> <ado-id>
+5. Script will:
+   - Delete work item on ADO
+   - NOT delete local file (keep for reference)
+   - Update frontmatter: ado_state = Removed, last_ado_sync

package/.tas/commands/ado-get.md

@@ -0,0 +1,20 @@
+# /ado-get $ARGUMENTS
+
+Pull work item from Azure DevOps to local .md file.
+
+## Syntax
+/ado-get <ado-id>
+
+## Examples
+/ado-get 5345
+/ado-get 1234
+
+## Actions
+1. Read `tas.yaml`, check `ado.enabled`. If `false` or missing: report "ADO integration is disabled (`ado.enabled: false` in tas.yaml)." then stop.
+2. Run: python .tas/tools/tas-ado.py get <ado-id>
+3. Script will:
+   - Fetch work item from ADO
+   - Convert description HTML to Markdown
+   - Create file {type}-{ado_id}-{slug}.md with frontmatter + content
+   - Update last_ado_sync
+4. If file already exists, ask user if they want to overwrite

package/.tas/commands/ado-status.md

@@ -0,0 +1,18 @@
+# /ado-status $ARGUMENTS
+
+Update only work item status on Azure DevOps (fast, no content push).
+
+## Syntax
+/ado-status <ado-id> --status <state> [--assign <name/email>]
+
+## Examples
+/ado-status 1234 --status "In Progress"
+/ado-status 5678 --status "Resolved" --assign "user@example.com"
+
+## Actions
+1. Read `tas.yaml`, check `ado.enabled`. If `false` or missing: report "ADO integration is disabled (`ado.enabled: false` in tas.yaml)." then stop.
+2. Run: python .tas/tools/tas-ado.py update-status <ado-id> --status <state> [--assign ...]
+3. Script will:
+   - Only update state and/or assigned-to on ADO
+   - Find local file, update frontmatter: ado_state, last_ado_sync
+   - Update root/project-status.yaml

package/.tas/commands/ado-update.md

@@ -0,0 +1,27 @@
+# /ado-update $ARGUMENTS
+
+Update work item on Azure DevOps from local .md file.
+
+## Syntax
+/ado-update <type> <ado-id> [--assign <name/email>] [--status <state>]
+
+- type: epic | feature | story | bug
+- ado-id: ADO work item ID
+- --assign: assign to person (optional)
+- --status: update status (optional)
+
+## Examples
+/ado-update story 1234 --status "In Progress"
+/ado-update bug 5678 --assign "user@example.com" --status "Committed"
+/ado-update feature 456
+
+## Actions
+1. Read `.tas/rules/ado-integration.md` for ADO operating rules (Always/Ask/Never, Red Flags).
+2. Read `tas.yaml`, check `ado.enabled`. If `false` or missing: report "ADO integration is disabled (`ado.enabled: false` in tas.yaml)." then stop.
+3. Run: python .tas/tools/tas-ado.py update-<type> <ado-id> [--assign ...] [--status ...]
+4. Script will:
+   - Find local file by pattern *-<ado-id>-*.md
+   - Read title and description from file
+   - Update work item on ADO
+   - Update frontmatter: ado_state, ado_assigned_to, last_ado_sync
+5. If no --assign and --status provided, push entire file content to ADO

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

@@ -0,0 +1,33 @@
+# /tas-adr $ARGUMENTS
+
+Role: SE - Software Engineer
+Create or update Architecture Decision Record.
+
+## Actions
+1. Need context from .tas/templates/ADR.md
+2. Scan docs/adr/ to identify existing ADRs
+3. Determine mode based on $ARGUMENTS:
+
+### CREATE mode ($ARGUMENTS is new title, e.g., "Use CQRS for Order Service"):
+4. Determine next sequence number (ADR-001, ADR-002...)
+5. If docs/sad.md exists, need context from SAD to ensure ADR consistency
+6. Create file docs/adr/ADR-{NNN}-{slug}.md
+7. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add entry to `adrs`.
+
+### UPDATE mode ($ARGUMENTS is ADR ID, e.g., "ADR-001"):
+4. Need context from current ADR file
+5. Ask user what needs changing (update status, add consequences, supersede...)
+6. Update file, add changelog
+7. If supersede: update old ADR status to "Superseded by ADR-{NNN}"
+8. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `adrs.{ADR_ID}.status`.
+
+## Principles
+- ADR must have: Context, Decision, Rationale, Consequences, Alternatives Considered
+- Status: Proposed | Accepted | Deprecated | Superseded
+- Each ADR is independent, self-contained with enough context to understand
+- Link to related ADRs if any (Supersedes, Related to)
+- Mermaid diagram rules: :::mermaid wrapper, no () in node labels
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working ADR file.

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

@@ -0,0 +1,173 @@
+# /tas-apitest-plan $ARGUMENTS
+
+Role: SE - Software Engineer
+Generate API Test Specification (Markdown) from API Spec (OpenAPI 3.0, Markdown, YAML) or analyze API code.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read entire spec or analyze code before creating test spec |
+| **Always** | Organize test cases by API version — each version separate section |
+| **Always** | Append-only: don't modify sections in existing old version |
+| **Always** | Coverage matrix: each endpoint needs ≥1 happy path + ≥1 error path |
+| **Always** | Read `.tas/rules/csharp/api-testing.md` for conventions |
+| **Ask** | When spec unclear about expected response schema or business rule |
+| **Never** | Use version folder/syntax in test spec file (use section headers instead) |
+| **Never** | Skip error path — each endpoint needs cover validation errors |
+
+## Actions
+
+### Step 1 — Locate Inputs
+
+`$ARGUMENTS` is path to:
+- API Spec file (OpenAPI 3.0 JSON/YAML, Markdown)
+- Or Story ID — glob find `docs/epics/**/Story-{ID}*.md`
+- Or path to API code project to analyze
+
+If not provided → ask user:
+```
+Enter input for /tas-apitest-plan:
+1. Path to API Spec file (OpenAPI/Markdown/YAML)
+2. Story ID (to find spec link in Story)
+3. Path to API code to auto-analyze
+```
+
+### Step 2 — Detect Existing Test Spec
+
+Glob find `docs/tests/API-Test-Spec-*.md`.
+
+- **Found**: Read file, detect existing versions (find section headers `## v{N}`)
+- **Not found**: Create new with version v1
+
+### Step 3 — Parse Input
+
+**If API Spec file:**
+- Read and parse OpenAPI/Markdown/YAML
+- Collect for each endpoint:
+  - HTTP method + path, path/query params, request body schema
+  - Response schemas per status code
+  - Auth requirement, description/summary
+  - Tags to group endpoints
+
+**If Story:**
+- Read Story to find spec link in `## Technical Plan` or `## Acceptance Criteria`
+- Parse spec as above
+- Add AC mapping to test spec
+
+**If code path:**
+- Glob find controller/handler files (`.cs`, `.ts`, `.py` per stack)
+- Analyze attributes/routes to detect endpoints
+- Extract DTO classes to know request/response schema
+- Ask user confirm if detection unclear
+
+### Step 4 — Detect API Version
+
+Prioritize in order:
+1. `info.version` in OpenAPI
+2. Prefix in URL path (v1/, v2/)
+3. Ask user
+
+Version format: `v1`, `v2` (no dot).
+
+### Step 5 — Determine Output Path
+
+Output: `docs/tests/API-Test-Spec-{slug}.md`
+
+**Slug generation:**
+- From `api_name` in spec → lowercase, replace spaces with dashes
+- Or ask user for short slug (e.g., `users`, `orders`, `products`)
+
+### Step 6 — Determine Update Mode
+
+If spec file exists and version already exists:
+- **Append mode** (default): add new test cases to end of current version section
+- Ask user if want new version (v2, v3...):
+
+```
+Spec file already exists with version {current}. You want:
+1. Append test cases to version {current} (default)
+2. Create new version (v{next}) for test cases
+```
+
+### Step 7 — Generate Test Spec
+
+Read template `.tas/templates/API-Test-Spec.md` for structure.
+
+**Analyze endpoints to create coverage matrix:**
+
+For each endpoint, generate test cases for:
+1. **Happy path** (2xx) — always have
+2. **Unauthorized** (401) — if endpoint requires auth
+3. **Forbidden** (403) — if has RBAC/ownership check
+4. **Not found** (404) — if has path param
+5. **Validation error** (400/422) — if has required fields or business rules
+6. **Business rules** — from Story ACs or spec descriptions
+
+**Coverage matrix format:**
+```
+| Endpoint | Happy Path | 401 Unauthorized | 403 Forbidden | 404 Not Found | 400/422 Validation | Business Rule |
+|----------|:---------:|:----------------:|:-------------:|:-------------:|:------------------:|:-------------:|
+| GET /api/users | ✓ | ✓ | | | | |
+| POST /api/users | ✓ | ✓ | | | ✓ | |
+```
+
+**Test case detail format:**
+```
+#### TC-XXX: {Title} — {Modifier}
+- **Endpoint**: `{METHOD} {path}`
+- **Auth**: Required/Not Required
+- **Preconditions**:
+  - {List preconditions}
+- **Request Query/Path/Body**:
+  - {Request details}
+- **Expected Response**:
+  - Status: {code}
+  - Body: {schema}
+- **Assertions**:
+  - {List assertions}
+- **AC Reference**: AC-{N} (if any)
+- **Test Method Name**: `{Method}_{Resource}_Returns{Status}_When{Condition}`
+```
+
+### Step 8 — Write Test Spec File
+
+**File doesn't exist:** Create new from template.
+
+**File exists (append mode):**
+- Read current file
+- Find section `## v{N}` being worked on
+- Append new test cases to end of section before `## Version History` or `## Changelog`
+- Preserve all old content
+
+### Step 9 — Summary
+
+Display:
+1. Output file path
+2. Number of endpoints detected
+3. Number of test cases generated
+4. Coverage matrix
+5. Next steps:
+   - Review test spec file
+   - Run `/tas-apitest docs/tests/API-Test-Spec-{slug}.md` to generate code
+
+```
+## API Test Spec Generated
+
+**Output**: `docs/tests/API-Test-Spec-{slug}.md`
+**Version**: v{N}
+**Endpoints**: {N}
+**Test Cases**: {N}
+
+### Coverage Matrix
+[Print coverage matrix]
+
+### Next Steps
+1. Review test spec: `docs/tests/API-Test-Spec-{slug}.md`
+2. Generate test code: `/tas-apitest docs/tests/API-Test-Spec-{slug}.md`
+3. Run tests: `dotnet test tests/ApiTests/`
+```
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to test spec file.