@torus-engineering/tas-kit 1.13.0 → 2.1.0

package/.tas/commands/tas-functest.md

@@ -1,76 +1,225 @@
-# /tas-functest $ARGUMENTS
-
-Role: SE / QA
-Generate Functional Test Specification from a User Story, linking test cases to Acceptance Criteria (AC).
-
-## IMPORTANT - Layer 2: Functional Testing
-- Functional tests (FT) sit between Unit tests (Layer 1) and E2E tests (Layer 3)
-- FT tests individual function/story in isolation, DOESN'T test linked flows between multiple features
-- Each FT case MUST reference AC-ID for traceability
-
-## Actions
-
-### Step 1: Identify Story
-1. $ARGUMENTS is Story ID or file path
-2. If no $ARGUMENTS: scan `docs/epics/**/Story-*.md` for stories with status In Progress or Committed
-3. Read Story file to get:
-   - All Acceptance Criteria (AC-1, AC-2, ...)
-   - Epic/Feature/Story numbers (from frontmatter or file path)
-   - Platform context (mobile/web/backend)
-4. Read `root/tas.yaml` to get project code (e.g., "AL")
-
-### Step 2: Auto-detect Platform
-From Story context, determine platform:
-- **Mobile**: Keywords "screen", "navigation", "React Native", "Detox"; paths `apps/mobile/src/features/*`
-- **Web**: Keywords "browser", "page", "Playwright", "React"; paths `apps/web/*`
-- **Backend**: Keywords "API endpoint", "service", "controller"; paths `src/Torus.*`, `tests/`
-- If cannot determine: ask user
-
-### Step 3: Generate FT Test Cases
-Read template from `.tas/templates/Func-Test-Spec.md`
-
-Naming format:
-```
-{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_{NNN}_{MODIFIER}
-```
-
-For each AC, generate:
-- **REQUIRED**: 1 Happy path test (H)
-- **SHOULD HAVE**: 1 Negative test (N) if error scenarios exist
-- **OPTIONAL**: 1 Edge case test (E) if boundary conditions exist
-
-Each test case MUST have AC-ID column in mapping table.
-
-### Step 4: Generate Test Data Requirements
-- Identify data needed for each test case
-- Hardcoded data: write directly in scenario
-- Credentials: only reference `process.env.TEST_USER_PASSWORD`, DO NOT hardcode
-- Environment-specific data: reference `test-data.{env}.json`
-
-### Step 5: Output File
-Save file at:
-```
-docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
-```
-
-### Step 6: Prompting
-After generating, ask user:
-- "Any edge cases to add?"
-- "Any negative test scenarios missed?"
-- "Any test cases to mark as P0 Critical?"
-- "What additional test data and fixtures needed?"
-
-## Traceability Feature
-- Each FT case links AC-ID in mapping column
-- When AC changes: grep AC-ID in Func-Test-*.md to know which FTs need update
-- In test script, each describe block has comment `// AC Reference: AC-{N}`
-
-## Status Flow
-Draft → Ready → Implemented → Verified
-
-## Principles
-- DO NOT create test code, only create specification (markdown)
-- Test code created by `/tas-functest-mobile` or `/tas-functest-web`
-- Func-Test-Spec is input for Layer 2 script generation
-- Each AC must have at least 1 FT case
-- FT uses type code `FT`, NOT `E2E` or `UT`
+# /tas-functest $FEATURE_FILE $CHECKLIST_FILE
+
+You are a Senior QA Engineer creating a comprehensive Functional Test Specification based on a Feature document and Test Checklist.
+
+## Purpose
+
+Generate a detailed Functional Test Specification document that maps Acceptance Criteria to executable test cases, with proper traceability, test data management, and automation readiness flags.
+
+## When to Use
+
+- Run after Test Checklist is approved
+- Run before writing automation scripts
+- Run when Feature requirements change (update test spec)
+
+## Prerequisites
+
+1. Feature document exists (pattern: `*-Feature-*.md`)
+2. Test Checklist exists (pattern: `*-TestChecklist.md`) - optional but recommended
+3. Template exists at `.tas/templates/Func-Test-Spec.md`
+4. `tas.yaml` exists at project root
+
+## Step-by-Step Actions
+
+### Step 1: Locate and Read Input Documents
+
+1. **Feature Document:**
+   - If `$FEATURE_FILE` provided, use that
+   - Otherwise, search for `*-Feature-*.md` in current directory
+   - Extract: Feature Code, Feature Name, Epic ID, Story ID, Acceptance Criteria
+
+2. **Test Checklist:**
+   - If `$CHECKLIST_FILE` provided, use that
+   - Otherwise, search for `*-TestChecklist.md` in current directory
+   - Extract all test points from checklist matrix by category
+   - Map checklist points to test cases
+
+3. **Read Template:**
+   - Read `.tas/templates/Func-Test-Spec.md`
+
+### Step 2: Parse and Structure Requirements
+
+From Feature document, extract:
+
+**A. Acceptance Criteria (AC):**
+- Each AC with Given/When/Then format
+- Assign AC ID: `{FeatureCode}-AC{N}`
+- Assign Priority: P0 (Must), P1 (Should), P2 (Nice)
+
+**B. Story Context:**
+- Story Summary: As a [user], I want [action] so that [benefit]
+- Scope: What's being tested
+- Out of Scope: What's NOT tested
+- Dependencies: APIs, mocks, upstream features
+- Test Strategy: Manual → Automation
+
+### Step 3: Map Checklist to Test Cases
+
+For each test point in checklist, create corresponding test case:
+
+**From Checklist Category → Test Type Mapping:**
+- GUI & UX → UI/UX test cases
+- Validation → Happy Path + Negative test cases
+- Business Logic → Happy Path + Edge Case test cases
+- Exception Handling → Negative test cases
+- Security → Security test cases
+- Performance → Performance test cases
+- Integration → Happy Path + Edge Case test cases
+
+**For each test point, determine:**
+- **Autoable:**
+  - `Yes` - if validation, logic, API call (automatable)
+  - `None` - if visual, exploratory, subjective (human-only)
+- **Priority:**
+  - P0 - Core business logic, security, critical validations
+  - P1 - Important business rules, error handling
+  - P2 - UI/UX, minor validations
+- **Test Data:**
+  - If Autoable=Yes: `data_test_S{STORY_ID}.json#case_{NNN}`
+  - If Autoable=None: Describe inline data
+
+### Step 4: Generate Test Case Sections
+
+Create test cases organized by type:
+
+#### 4.1 Happy Path Test Cases
+- At least 1 per AC (P0 requirement)
+- Focus on successful user flows
+- Main business scenarios
+
+#### 4.2 Negative / Error Test Cases
+- Invalid inputs, error scenarios
+- Missing required fields
+- Boundary violations
+
+#### 4.3 Edge Case / Boundary Test Cases
+- Max/min values
+- Empty/null conditions
+- Concurrent operations
+
+#### 4.4 Permission / Role-Based Test Cases
+- Different user roles
+- Access control
+- Authorization checks
+
+#### 4.5 UI / UX & Responsive Test Cases
+- Visual verification
+- Responsive layout
+- Accessibility checks
+
+**TC ID Format:** `{Epic_ID}-{Feature_ID}-{Story_ID}-{AC_ID}-{sequence}`
+
+**For each TC, provide:**
+- Pre-Condition (system state before test)
+- Logical Steps (Given/When/Then format)
+- Test Data (JSON reference or inline)
+- Expected Result (specific, verifiable)
+- Autoable flag
+- Traceability to AC
+
+### Step 5: Fill Frontmatter and Metadata
+
+```yaml
+created_date: {YYYY-MM-DD}
+updated_date: {YYYY-MM-DD}
+executor: {Current user or placeholder}
+reviewer: {Placeholder}
+status: Draft
+story_id: {Extracted from Feature}
+feature_id: {Extracted from Feature}
+epic_id: {Extracted from Feature}
+platform: {web | mobile | backend}
+tags: [functional, {feature_name}]
+locator_ref: /docs/NAMING_CONVENTION.md
+ver: 1.0
+```
+
+### Step 6: Generate Coverage Matrix
+
+**Requirement Coverage Matrix:**
+- Map each AC to covering TC IDs
+- Calculate coverage % (ACs with at least 1 TC)
+- Target: 100% AC coverage
+
+**Test Run Summary:**
+- Total TCs by priority
+- Pass/Fail/Blocked counts (initially all "— Not Run")
+
+### Step 7: Generate Risk & Assumption Log
+
+Identify 3-5 key risks:
+- API stability
+- Test data availability
+- Environment configuration
+- Feature flags
+- Third-party dependencies
+
+### Step 8: Write Output File
+
+Create file: `{FeatureCode}-FuncTest-Spec.md`
+
+Fill template with:
+- Frontmatter
+- Story Context
+- Environment Matrix (keep default, customize if needed)
+- AC Summary
+- Test Cases (all sections)
+- Coverage Matrix
+- Risk Log
+- Change Log
+
+### Step 9: Output Summary
+
+Report to user:
+```
+✓ Functional Test Spec created: {filename}
+
+Summary:
+├─ Total ACs: {count}
+├─ Total Test Cases: {count}
+│  ├─ Happy Path: {count}
+│  ├─ Negative: {count}
+│  ├─ Edge Case: {count}
+│  ├─ Permission: {count}
+│  └─ UI/UX: {count}
+├─ Automatable: {count} ({percent}%)
+└─ Manual Only: {count} ({percent}%)
+
+Priority Breakdown:
+├─ P0 (Critical): {count}
+├─ P1 (High): {count}
+└─ P2 (Medium): {count}
+
+AC Coverage: {percent}%
+Target: 100%
+
+Next Steps:
+1. Review test cases with team
+2. Create test data JSON files
+3. Implement automation for Autoable=Yes cases
+4. Update Execution Locators using QC Agent UI Mapping
+```
+
+## Important Notes
+
+1. **One AC → Multiple TCs:** Each AC should have happy path + negative cases
+2. **Traceability:** Every TC must link to an AC ID
+3. **Automation Ready:** Mark Autoable=Yes for all non-visual tests
+4. **Test Data External:** Don't inline test data for automatable tests
+5. **Human-Only Tests:** Visual/UX checks should have Autoable=None
+6. **Specific Expected Results:** Must be verifiable, not subjective
+
+## Error Handling
+
+- No Feature found: "No Feature document found. Run in feature directory or specify: /tas-functest <feature-file>"
+- No Checklist found: "Warning: No Test Checklist found. Will generate based on Feature document only."
+- Template missing: "Error: Func-Test-Spec.md template not found in .tas/templates/"
+- No ACs in Feature: "Error: Feature document has no Acceptance Criteria. Cannot generate test spec."
+
+## Best Practices
+
+1. **Follow 5W1H:** Each test case should answer What, When, Why, How
+2. **Independent Tests:** Each TC should be executable independently
+3. **Cleanup:** Include cleanup steps if TC modifies system state
+4. **Data Isolation:** Each TC should use unique test data
+5. **Reproducible:** Steps should be detailed enough for any QC to execute

package/.tas/commands/tas-init.md

@@ -1,17 +1,22 @@
-# /tas-init
-
-Initialize TAS kit for the current project.
-
-## Actions
-1. Need context from root/tas.yaml. If not exists, copy from .tas/tas-example.yaml to root and ask user to fill required information.
-2. Create directory structure: .tas/templates/, docs/, docs/adr/, docs/epics/, docs/bugs/, docs/ref/
-3. Create root/project-status.yaml file with initial state (artifacts, epics, adrs all empty).
-4. Copy default templates to .tas/templates/ if not exist.
-5. If project type is brownfield and codebase_scan_on_init = true:
-   - Scan existing codebase
-   - Create docs/codebase-overview.md summarizing current architecture
-6. Display status: project type, team roles, enabled workflow phases.
-
-## Notes
-- DO NOT recreate files if already exist
-- Ask for confirmation before executing
+---
+model: sonnet
+---
+
+# /tas-init
+
+Initialize TAS kit for the current project.
+
+## Actions
+1. Need context from root/`tas.yaml`. If absent, copy from `.tas/tas-example.yaml` to root, ask user to fill required info.
+2. Create directory structure: `.tas/templates/`, `docs/`, `docs/adr/`, `docs/features/`, `docs/bugs/`, `docs/ref/`
+3. Create root/`project-status.yaml` from `.tas/project-status-example.yaml` (flat `features` map; no `epics`/`stories` nesting).
+4. Copy default templates to `.tas/templates/` if missing.
+5. If project type is `brownfield` and `codebase_scan_on_init = true`:
+   - Scan existing codebase
+   - Create `docs/codebase-overview.md` summarizing current architecture
+6. Display status: project type, team roles, enabled workflow phases.
+
+## Notes
+- DO NOT recreate files if they already exist
+- Ask for confirmation before executing
+- Migrating from a previous kit version that had `docs/epics/`? See migration note in repo CHANGELOG — flatten manually (move `docs/epics/*/Feature-*/Feature-*.md` → `docs/features/{CODE}-Feature-{NNN}-{slug}/`).

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

@@ -0,0 +1,300 @@
+---
+model: opus
+---
+
+# /tas-master-plan $ARGUMENTS
+
+Role: Tech Lead — Master Plan Architect
+Generate full project execution plan from PRD FRs: propose scaffold Features, order all Features into dependency tracks, write machine-readable plan. Orchestration Agent reads this plan to auto-execute via `/tas-dev`.
+
+**Scope:** Planning only — reads PRD FRs, proposes scaffolds, writes plan file.
+**Out of scope:** Writing business Feature content (that's `/tas-feature`), coding, testing.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read PRD FR list as source of truth — not `docs/features/` |
+| **Always** | Propose one scaffold Feature per stack before business Features |
+| **Always** | Order tracks by SAD dependency: `service` → `integration` → `web` → `app` |
+| **Always** | Write YAML plan block in `docs/master-plan.md` for Orchestration Agent |
+| **Always** | Sync plan to root/`project-status.yaml` under `master_plan` key |
+| **Always** | On resume: read root/`project-status.yaml` to skip `done` Features — never re-run completed work |
+| **Never** | Plan Features not in PRD without PE approval |
+| **Never** | Skip scaffold phase |
+| **Never** | Assign Feature IDs without scanning `docs/features/` for existing max NNN |
+
+## Prerequisites
+- `tas.yaml` at project root
+- `docs/prd.md` with FR list
+- SAD file (path from `tas.yaml` or `docs/sad.md`) — for stack/dependency info
+
+## Steps
+
+### CREATE mode (no existing master plan)
+
+**Step 1 — Read context**
+- Read `project.code` from `tas.yaml`
+- Read `docs/prd.md` — extract full FR list: ID, title, brief description
+- Read SAD — extract stacks present + dependency order between stacks
+- Read root/`project-status.yaml` — check for existing `master_plan` key
+
+If `master_plan` key exists with `status: in_progress` → announce resume mode and go to **RESUME mode** below.
+
+**Step 2 — Scaffold proposal**
+
+For each stack found in SAD (`service` → `integration` → `web` → `app`, only stacks present), propose one scaffold Feature.
+
+Show in-conversation:
+```
+Scaffold Features (Phase 1 — blocking — must complete before business Features in each track):
+
+[ ] scaffold-service    Service foundation: DI, DB setup, error handling, logging, auth middleware base
+[ ] scaffold-web        Web foundation: routing, DI, error handling, API client base, logging
+[ ] scaffold-app        App foundation: navigation, DI, error handling, theme, logging
+
+Approve all scaffolds? (yes / customize / skip)
+```
+- Approved → Step 3
+- Customize → adjust list, then Step 3
+- Skip → warn: "⚠️ Scaffold features skipped. Foundation setup must be handled manually before coding." → Step 4
+
+**Step 3 — Create scaffold Feature docs (inline)**
+
+For each approved scaffold:
+- Scan `docs/features/` for max existing NNN → assign next sequential IDs (scaffold Features first)
+- Create `docs/features/{CODE}-Feature-{NNN}-scaffold-{stack}/`
+- Create Feature file using `.tas/templates/Feature.md`
+- Fill content using **Scaffold Content Guide** (section below)
+- Add each scaffold Feature to `project-status.yaml` per `.tas/rules/common/project-status.md`
+
+**Step 4 — Map FRs to Feature IDs and stacks**
+
+For each FR in PRD:
+- Infer which stacks it touches (cross-reference SAD layer responsibilities)
+- Assign tentative Feature ID (continuing from scaffold max NNN + 1)
+- Note inter-FR dependencies (e.g., auth FR must precede profile FR)
+- Primary stack = the stack owning the core logic of this FR
+
+Result: ordered list of `{Feature-ID, FR-title, primary-stack, touches-stacks[], depends-on[]}`
+
+**Step 5 — Build execution tracks**
+
+Group Features by primary stack → one track per stack. Within each track, assign stages (each stage = one execution wave — all Features in a stage can start simultaneously):
+
+- **Stage 1 — blocking**: scaffold Feature only. No other Feature in track starts until scaffold is `done`.
+- **Stage N — sequential**: single Feature with dependency on previous stage outcome. One Feature per stage.
+- **Stage N — parallel**: multiple Features with no dependencies on each other, but all depend on previous stage. Orchestration Agent batches by `max_parallel`.
+
+Rule: if Feature A and Feature B both depend only on Stage N-1, they belong in the same stage. If Feature B depends on Feature A, they belong in separate sequential stages.
+
+Cross-track dependencies (e.g., web Feature depends on service auth Feature): mark as `depends_on: [Feature-NNN]` — Orchestration Agent enforces before spawning.
+
+**Step 6 — Write `docs/master-plan.md`**
+
+```markdown
+# Master Plan — {CODE}
+
+_Generated: {date} | Status: ready_
+
+## Overview
+{N} FRs → {N} Features across {N} tracks: service, web, app
+
+## Tracks
+
+### Track: service
+**Stage 1 [blocking]:** Feature-001 scaffold-service
+**Stage 2 [sequential]:** Feature-003 auth
+**Stage 3 [sequential]:** Feature-005 user-management
+**Stage 4 [parallel]:** Feature-007 notifications | Feature-008 audit-log
+
+### Track: web
+...
+
+## Execution Plan
+
+```yaml
+tracks:
+  service:
+    stages:
+      - stage: 1
+        type: blocking
+        features:
+          - id: Feature-001
+            slug: scaffold-service
+            depends_on: []
+            status: pending
+      - stage: 2
+        type: sequential
+        features:
+          - id: Feature-003
+            slug: auth
+            depends_on: [Feature-001]
+            status: pending
+      - stage: 3
+        type: sequential
+        features:
+          - id: Feature-005
+            slug: user-management
+            depends_on: [Feature-003]
+            status: pending
+      - stage: 4
+        type: parallel
+        features:
+          - id: Feature-007
+            slug: notifications
+            depends_on: [Feature-003]
+            status: pending
+          - id: Feature-008
+            slug: audit-log
+            depends_on: [Feature-003]
+            status: pending
+  web:
+    stages:
+      - stage: 1
+        type: blocking
+        features:
+          - id: Feature-002
+            slug: scaffold-web
+            depends_on: []
+            status: pending
+      - stage: 2
+        type: parallel
+        features:
+          - id: Feature-004
+            slug: login-ui
+            depends_on: [Feature-002, Feature-003]
+            status: pending
+```
+
+**Step 7 — Update `project-status.yaml`**
+
+Add `master_plan` key:
+```yaml
+master_plan:
+  file: docs/master-plan.md
+  status: ready              # ready | in_progress | completed
+  last_updated: YYYY-MM-DD
+  tracks:
+    service:
+      current_stage: 1
+      stages:
+        1:
+          type: blocking
+          status: pending    # pending | in_progress | done
+          features:
+            Feature-001: pending   # pending | in_progress | done | blocked | error
+        2:
+          type: sequential
+          status: pending
+          features:
+            Feature-003: pending
+        3:
+          type: sequential
+          status: pending
+          features:
+            Feature-005: pending
+        4:
+          type: parallel
+          status: pending
+          features:
+            Feature-007: pending
+            Feature-008: pending
+    web:
+      current_stage: 1
+      stages:
+        1:
+          type: blocking
+          status: pending
+          features:
+            Feature-002: pending
+```
+
+**Step 8 — Notify**
+> "Master plan ready at `docs/master-plan.md`.
+> - Execute automatically: run Orchestration Agent (`/orchestrate` or start agent `orchestrator`)
+> - Execute manually: follow track order in master plan, run `/tas-plan {Feature-ID}` then `/tas-dev {Feature-ID}` per Feature"
+
+---
+
+### RESUME mode (existing master plan with `status: in_progress`)
+
+1. Read `docs/master-plan.md` YAML block — load tracks and stages
+2. Read `project-status.yaml` `master_plan.tracks` — load current Feature statuses
+3. Show resume summary:
+   ```
+   Resuming master plan.
+   ✅ Done: Feature-001, Feature-003
+   ⏳ In progress: Feature-005
+   ⏸ Pending: Feature-007, Feature-008, Feature-002, Feature-004
+   ```
+4. Update `project-status.yaml`: `master_plan.status: in_progress`
+5. Notify:
+   > "Resume from current state — run Orchestration Agent to continue auto-execution, or proceed manually."
+
+---
+
+### AMEND mode (invoked after ad-hoc Feature creation)
+
+Triggered when called with `AMEND` argument, or invoked inline by `/tas-feature`.
+
+**Step 1 — Read current plan state**
+- Read `docs/master-plan.md` YAML block — load existing tracks, stages, Feature IDs, stacks, and depends_on
+- Read `project-status.yaml` — get `master_plan.status` and all Feature statuses in `master_plan.tracks`
+- Read SAD — confirm stack dependency order
+
+**Step 2 — Collect unplanned Features**
+- Scan `docs/features/` directory names → extract Feature IDs from folder names
+- Compare against Feature IDs already in `master-plan.md` YAML block
+- Collect IDs not yet in plan → these are new unplanned Features
+- Read **only those new Feature files** — extract primary stack and AC for dependency inference
+- Do NOT re-read all Feature files — `master-plan.md` already has full context for planned Features
+
+**Step 3 — Determine case and re-plan**
+
+**Case A — Plan not started** (`master_plan.status: pending` or `ready`):
+- Collect ALL Features: existing pending + new unplanned
+- Re-sort by SAD dependency + inter-feature dependencies (same ordering logic as CREATE Step 5)
+- Rewrite full `docs/master-plan.md` YAML block
+- Rebuild `project-status.yaml` `master_plan.tracks` from re-sorted plan
+
+**Case B — Plan in progress** (`master_plan.status: in_progress`):
+- Lock `done` and `in_progress` Features in place — do not move them
+- Collect all `pending` Features + new unplanned Features
+- Re-sort pending group by SAD dependency + inter-feature dependencies
+- Determine insertion point per stack track based on primary stack of each new Feature
+- Append new stage(s) or merge into existing pending stages where dependency allows
+- Update `docs/master-plan.md` — replace pending stages sections only
+- Update `project-status.yaml` `master_plan.tracks` for affected tracks only
+
+**Step 4 — Report result**
+```
+Master plan updated (AMEND):
++ Added: Feature-{NNN} → Track: {stack}, Stage: {N} (depends_on: Feature-{X})
+Pending re-sorted: {N} features across {N} tracks
+```
+Return to caller — do not end turn.
+
+---
+
+## Scaffold Content Guide
+
+When filling scaffold Feature docs in Step 3:
+
+**Description**: "[Stack] layer foundation — base project structure and cross-cutting concerns"
+**User Story**: "As a developer, I want a stable [stack] foundation, so that all business features share consistent structure and patterns"
+**Actor**: Development team
+**Foundation Concerns** (replaces Business Flow) — ask PE via `AskUserQuestion` multiSelect:
+> "Which foundation concerns for [stack]?"
+Options: `DI container setup` / `Error handling pattern` / `Logging framework` / `Auth middleware base` / `Base configs (env, secrets)` / `Folder/module structure` / `Database connection` / `API client base`
+
+**Foundation Rules** (replaces Business Rules): patterns all business Features in [stack] must follow — naming, error shape, log format, auth contract
+**UI/UX Rules**: skip for `service`/`integration`; ask for `web`/`app`
+**NFR**: performance baselines, security baseline applicable across all Features in stack
+**AC** (Given/When/Then): one AC per selected Foundation Concern. Examples:
+- "Given app starts, When any unhandled exception occurs, Then error handler returns `{error, message, traceId}` shape"
+- "Given any request, When response is 401, Then auth middleware redirects to login"
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/master-plan.md`.