@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/.tas/commands/tas-e2e.md

@@ -0,0 +1,102 @@
+# /tas-e2e $ARGUMENTS
+
+Role: QA / PE
+Generate E2E test scenario documents from an Epic or user flow description.
+
+## IMPORTANT - Layer 3: E2E Testing
+- E2E tests verify ENTIRE flow linking multiple features/stories
+- E2E scenario MUST reference FT IDs from Layer 2 (Functional Tests)
+- E2E scripts (created by /tas-e2e-mobile or /tas-e2e-web) will REUSE helpers from Layer 2
+- Output is markdown scenario file, NOT test code
+
+## Actions
+
+### Step 1: Determine Input
+$ARGUMENTS can be:
+- **Epic ID** (e.g., "Epic-002", "AL-Epic-002-authentication") → generate scenarios from all features/stories in epic
+- **Flow description** (e.g., "user registration to first scan") → generate cross-epic scenario
+
+If no $ARGUMENTS: list existing Epics and ask user to choose.
+
+### Step 2: Gather Context
+
+#### If Epic ID:
+1. Read Epic file and all Feature files within
+2. Read all Story files of those Features
+3. Find all `Func-Test-*.md` files to get FT IDs
+
+#### If Flow Description:
+1. Search across `docs/epics/` to find related Features/Stories
+2. Identify related Epics (cross-epic scenario)
+3. Collect FT IDs from Func-Test-*.md files
+
+### Step 3: Read template
+Read `.tas/templates/E2E-Scenario.md`
+Read `root/tas.yaml` to get project code
+
+### Step 4: Generate Scenario
+
+#### Naming Convention:
+- **Single-epic**: `{PROJECT}_E{EPIC}_E2E_{NNN}_{MODIFIER}`
+  - Example: `AL_E002_E2E_001_H`
+- **Cross-epic**: `{PROJECT}_XEPIC_E2E_{NNN}_{MODIFIER}`
+  - Example: `AL_XEPIC_E2E_001_H`
+
+#### Scenario Steps Table:
+Each step MUST have "Builds on FT IDs" column to reference Layer 2:
+
+```markdown
+| Step | Screen/Page | Action | Expected Result | Builds on FT IDs |
+|------|-------------|--------|-----------------|-------------------|
+| 1 | Login Screen | User logs in | Home screen shown | AL_E002_F002_S001_FT_001_H |
+| 2 | Home Screen | View allergen list | List displayed | AL_E003_F001_S001_FT_001_H |
+```
+
+If step has NO FT reference → write "-" (new logic, no func test yet)
+
+#### Generated content:
+1. Flow Overview (narrative description)
+2. Scenario Steps table
+3. Step Details (detail each step)
+4. Alternate Flows (if any)
+5. Error Flows (if any)
+6. Test Data per environment
+7. Prerequisites checklist
+8. Success Criteria
+9. FT Reuse Map (map step → FT ID → helper function)
+
+### Step 5: Output File
+- **Single-epic**: `docs/epics/{epic-dir}/E2E-Scenario-{NNN}-{slug}.md`
+- **Cross-epic**: `docs/e2e-scenarios/E2E-Scenario-{NNN}-{slug}.md`
+
+Auto-create `docs/e2e-scenarios/` directory if not exists.
+
+### Step 6: Prompting
+After generating, ask user:
+- "Any alternate flows to cover?"
+- "Any error scenarios to add?"
+- "Test data for all environments sufficient?"
+- "Need to test on both mobile and web?"
+
+## FT Reuse Map
+Each scenario file has "FT Reuse Map" section to:
+- Map scenario step → FT ID → source file → helper function
+- /tas-e2e-mobile and /tas-e2e-web read this section to import helpers from Layer 2
+
+```markdown
+## FT Reuse Map
+| Step | FT ID | Source File | Helper Function |
+|------|-------|-------------|-----------------|
+| 1 | AL_E002_F002_S001_FT_001_H | features/auth/login/helpers.ts | fillLoginForm() |
+| 2 | AL_E003_F001_S001_FT_001_H | features/home/allergens/helpers.ts | viewAllergenList() |
+```
+
+## Status Flow
+Draft → Ready → Implemented → Verified
+
+## Principles
+- Output is MARKDOWN scenario, NOT test code
+- Test code created by /tas-e2e-mobile or /tas-e2e-web
+- Each step SHOULD reference FT IDs when possible (to reuse, not rewrite)
+- Scenario must be testable: has preconditions, test data, clear success criteria
+- Cross-epic scenarios use XEPIC prefix instead of Epic number

package/.tas/commands/tas-epic.md

@@ -0,0 +1,35 @@
+# /tas-epic $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Epic document.
+
+## Prerequisite
+- docs/prd.md must exist
+
+## Actions
+1. Need context from root/tas.yaml and docs/prd.md
+2. Need context from .tas/templates/Epic.md
+3. Determine mode based on $ARGUMENTS:
+
+### CREATE mode ($ARGUMENTS is new Epic description, or no $ARGUMENTS):
+4. If no $ARGUMENTS, ask user for Epic description.
+5. Read project.code from root/tas.yaml. Scan docs/epics/ to determine sequence number.
+6. Create directory docs/epics/{code}-Epic-{NNN}-{slug}/
+7. Create file docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Epic-{NNN}-{slug}.md
+8. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add entry to `epics`.
+
+### UPDATE mode ($ARGUMENTS is Epic ID, e.g., "Epic-001"):
+4. Find directory docs/epics/{code}-Epic-001-*/
+5. Need context from current Epic file
+6. Ask user what needs changing (update scope, add feature, change status...)
+7. Update file, add changelog
+8. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `epics.{EPIC_ID}.status`.
+
+## Principles
+- Each Epic maps to one business capability in PRD
+- Epic does NOT contain technical details, only business value
+- Effort estimation at T-shirt size level: S/M/L/XL
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Epic file.

package/.tas/commands/tas-feature.md

@@ -0,0 +1,47 @@
+# /tas-feature $ARGUMENTS
+
+Role: PE - Product Engineer
+Create or update Feature document, including Integration Test and E2E/Acceptance Test design.
+
+## Prerequisite
+- At least one Epic must exist in docs/epics/
+
+## Actions
+1. Need context from root/tas.yaml
+2. Need context from .tas/templates/Feature.md
+3. Determine mode based on $ARGUMENTS:
+
+### CREATE mode ($ARGUMENTS is new Feature description, or no $ARGUMENTS):
+4. Read project.code from root/tas.yaml. List existing Epics, ask user which Epic this Feature belongs to.
+5. Scan selected Epic directory to determine Feature sequence number.
+6. Create directory docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/
+7. Create file {code}-Feature-{NNN}-{slug}.md in that directory
+8. After PE fills description and acceptance criteria, AUTOMATICALLY switch to test design:
+   a. **Integration Test Cases**: Ask PE:
+      - "Which services/modules does this Feature interact with?"
+      - "What linked flows between stories need testing?"
+      - "Any data flows needing end-to-end verification within this feature?"
+      Write to Integration Test Cases section.
+   b. **E2E / Acceptance Test Cases**: Ask PE:
+      - "What's the main user scenario to verify this feature on Staging?"
+      - "Any scenarios needing real or near-real data testing?"
+      - "Which acceptance criteria need manual PE verification?"
+      Write to E2E Test Cases section. This is the checklist PE uses in Phase 2 when running /tas-functest + /tas-e2e.
+9. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add entry to `epics.{EPIC_ID}.features`.
+
+### UPDATE mode ($ARGUMENTS is Feature ID, e.g., "Feature-003"):
+4. Find Feature file in docs/epics/ tree (using glob)
+5. Need context from current Feature file
+6. Ask user what needs changing (add story, update AC, add test cases, change status...)
+7. Update file, add changelog
+8. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `epics.{EPIC_ID}.features.{FEATURE_ID}.status`.
+
+## Principles
+- Feature is a specific function that can be demoed
+- Feature MUST have clear, testable acceptance criteria
+- Integration Test Cases MUST cover linked flows between stories
+- E2E Test Cases MUST be sufficient for PE to verify feature on Staging in Phase 2
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Feature file.

package/.tas/commands/tas-fix.md

@@ -0,0 +1,51 @@
+# /tas-fix $ARGUMENTS
+
+Role: SE - Software Engineer
+Quick fix for small bugs or obvious errors — no ticket needed, no full lifecycle.
+Use when: solo dev, quick hotfix, bug found during development.
+Differs from /tas-bug: no Bug file created, no status tracking, no deploy flow.
+
+## Stack Detection
+Read `.tas/rules/common/stack-detection.md`.
+
+## Actions
+
+### 1. Understand bug
+$ARGUMENTS is error description, error message, or file:line_number.
+- If error message/stack trace provided: parse immediately, identify error file and line
+- If only description: ask exactly 1 clarifying question (reproduce steps or expected vs actual)
+- DO NOT ask more than 1 question
+
+### 2. Diagnose (max 3 files read)
+- Read error file and directly related files
+- Identify root cause in 1-2 short sentences
+- DO NOT read entire project, DO NOT scan folder structure
+- If need to read more files beyond first 3: ask user confirmation
+
+### 3. Fix with regression test
+
+Before fixing, read relevant rules:
+- `.tas/rules/common/security.md` — check if fix creates security risks
+- `.tas/rules/common/testing.md` — regression test writing patterns
+- `.tas/rules/[lang_rules]/coding-style.md` — current stack conventions (if identifiable)
+
+Then:
+a. Write 1 minimal test case reproducing bug (if project has test framework)
+b. Confirm test FAILS
+c. Fix code at root cause
+d. Confirm test PASSES
+e. Quick run of test suite if available (to check regression)
+
+### 4. Wrap up
+- Output commit message: `fix: <short description>`
+- Remind: "If this bug may recur or affects production, consider using /tas-bug for full tracking."
+
+## Principles
+- Total files read ≤ 3 unless permitted
+- Fix at root cause, DO NOT patch symptom
+- If fix leads to architecture change → stop, suggest using /tas-bug + /tas-adr
+- If bug is in production with high severity → stop, suggest using /tas-bug with severity Critical/High
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to related Story or Bug file (if any).

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

@@ -0,0 +1,144 @@
+# /tas-functest-mobile $ARGUMENTS
+
+Role: SE / QA
+Generate all Detox automation test scripts for a mobile Feature.
+
+## IMPORTANT - Layer 2: Mobile Functional Test Scripts
+- Create Detox test scripts from Func-Test-Spec (markdown)
+- Scripts located in `apps/mobile/e2e/features/`
+- Reusable helpers exported for Layer 3 (E2E) reuse
+- Hardcoded data in tests, credentials from .env
+
+## Actions
+
+### Step 1: Identify Feature
+1. $ARGUMENTS is Feature ID or file path
+2. If not provided: scan `docs/epics/**/Feature-*.md` for features with status In Progress
+3. Read Feature file to get Epic/Feature numbers and list of Stories
+
+### Step 2: Check Prerequisites
+1. Check `apps/mobile/` exists. If not → error:
+   > "Mobile app doesn't exist in this project. Please create apps/mobile/ first."
+2. Find all `Func-Test-*.md` files in Feature directory:
+   ```
+   docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md
+   ```
+3. If no Func-Test-Spec exists → error:
+   > "No Func-Test-Spec for this Feature yet. Run /tas-functest {story-ID} first."
+4. Read `apps/mobile/e2e/test-ids.ts` to know existing testIDs
+5. Read `apps/mobile/e2e/helpers/data-loader.ts` and `test-utils.ts` to understand patterns
+
+### Step 3: Aggregate FT Test Cases
+- From all Func-Test-Spec files, aggregate list of FT test cases
+- Group by Story
+- Get test data requirements from each spec
+
+### Step 4: Generate Test Scripts
+For EACH Story with Func-Test-Spec:
+
+**File output**: `apps/mobile/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.e2e.ts`
+
+**Structure**:
+```typescript
+/**
+ * Functional Tests: {Story Name}
+ * Story: {Story_ID}
+ * Feature: {Feature_ID}  
+ * Epic: {Epic_ID}
+ * 
+ * Generated by /tas-functest-mobile
+ * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ */
+
+import { device, element, expect, by, waitFor } from 'detox';
+import { TEST_IDS } from '../../../test-ids';
+import { loadTestData, getCredentials } from '../../../helpers/data-loader';
+import { login, navigateTo } from '../../../helpers/test-utils';
+
+const testData = loadTestData();
+
+describe('{Feature Name} - {Story Name}', () => {
+  beforeAll(async () => {
+    await device.launchApp({ newInstance: true });
+  });
+
+  beforeEach(async () => {
+    await device.reloadReactNative();
+  });
+
+  // AC Reference: AC-1
+  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    it('should {description from spec}', async () => {
+      // Given: {precondition}
+      // When: {action}
+      // Then: {expected}
+    });
+  });
+});
+```
+
+### Step 5: Update test-ids.ts (if needed)
+- If test cases need testID not in test-ids.ts
+- Add new testID per current naming convention
+- Keep structure: nested object with dot notation
+
+### Step 6: Generate Feature Helpers
+Create file `apps/mobile/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
+```typescript
+/**
+ * Reusable helpers for {Feature Name}
+ * Exported for Layer 3 E2E scripts reuse
+ */
+
+export async function {featureSpecificHelper}() {
+  // Helper logic extracted from functional tests
+}
+```
+
+### Step 7: Update package.json Script
+Add or update script in `apps/mobile/package.json`:
+```json
+"functest:mobile:{feature-slug}": "detox test --configuration ios.sim.debug --testPathPattern='e2e/features/{epic-slug}/{feature-slug}'"
+```
+
+### Step 8: Generate Index
+Create `apps/mobile/e2e/features/{epic-slug}/{feature-slug}/index.ts`:
+```typescript
+export * from './helpers';
+```
+
+## File Structure Output
+```
+apps/mobile/e2e/features/
+└── {epic-slug}/
+    └── {feature-slug}/
+        ├── {story-1-slug}.func.e2e.ts
+        ├── {story-2-slug}.func.e2e.ts
+        ├── helpers.ts
+        └── index.ts
+```
+
+## Test Data Convention
+- **Hardcoded values**: Directly in test (e.g., "invalid@email", "short")
+- **Credentials**: `const creds = getCredentials();` → password from process.env
+- **Environment data**: `const testData = loadTestData();` → read from test-data.{env}.json
+- **NEVER** hardcode passwords/tokens in test files
+
+## Run Tests
+```bash
+# Run all func tests for feature
+yarn functest:mobile:{feature-slug}
+
+# Run only one story
+npx detox test --configuration ios.sim.debug --testPathPattern='e2e/features/{epic}/{feature}/{story}'
+
+# Run with Android
+npx detox test --configuration android.emu.debug --testPathPattern='e2e/features/{epic}/{feature}'
+```
+
+## Principles
+- Script MUST be runnable directly from CLI, WITHOUT Claude window
+- Each describe block uses full FT ID for grep-ability
+- Helpers MUST export for Layer 3 reuse
+- DO NOT import from Layer 3 (flows/), only export UP to Layer 3
+- If apps/mobile/ doesn't exist → graceful error, DO NOT create