@torus-engineering/tas-kit 1.9.0 → 1.11.1

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

@@ -1,47 +1,47 @@
-# /tas-feature $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo mới hoặc cập nhật Feature document, bao gồm thiết kế Integration Test và E2E/Acceptance Test.
-
-## Prerequisite
-- Ít nhất một Epic phải tồn tại trong docs/epics/
-
-## Hành động
-1. Cần context từ root/tas.yaml
-2. Cần context từ .tas/templates/Feature.md
-3. Xác định chế độ dựa vào $ARGUMENTS:
-
-### Chế độ CREATE ($ARGUMENTS là mô tả Feature mới, hoặc không có $ARGUMENTS):
-4. Đọc project.code từ root/tas.yaml. Liệt kê các Epic hiện có, hỏi user Feature này thuộc Epic nào.
-5. Quét thư mục Epic đã chọn để xác định số thứ tự Feature.
-6. Tạo thư mục docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Feature-{NNN}-{slug}/
-7. Tạo file {code}-Feature-{NNN}-{slug}.md trong thư mục đó
-8. Sau khi PE điền mô tả và acceptance criteria, TỰ ĐỘNG chuyển sang thiết kế test:
-   a. **Integration Test Cases**: Hỏi PE:
-      - "Feature này tương tác với service/module nào khác?"
-      - "Các flow liên kết giữa stories cần test những gì?"
-      - "Có data flow nào cần verify end-to-end trong feature này?"
-      Ghi vào section Integration Test Cases.
-   b. **E2E / Acceptance Test Cases**: Hỏi PE:
-      - "User scenario chính để verify feature này trên Staging là gì?"
-      - "Có scenario nào cần test với data thật hoặc gần thật?"
-      - "Acceptance criteria nào cần PE verify thủ công?"
-      Ghi vào section E2E Test Cases. Đây là checklist PE dùng ở Phase 2 khi chạy /tas-verify.
-9. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm entry vào `epics.{EPIC_ID}.features`.
-
-### Chế độ UPDATE ($ARGUMENTS là Feature ID, ví dụ: "Feature-003"):
-4. Tìm file Feature trong cây docs/epics/ (dùng glob)
-5. Cần context từ file Feature hiện tại
-6. Hỏi user cần thay đổi gì (thêm story, cập nhật AC, thêm test cases, đổi status...)
-7. Cập nhật file, thêm changelog
-8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — cập nhật `epics.{EPIC_ID}.features.{FEATURE_ID}.status`.
-
-## Nguyên tắc
-- Feature là một chức năng cụ thể, có thể demo được
-- Feature PHẢI có acceptance criteria rõ ràng, testable
-- Integration Test Cases PHẢI cover các flow liên kết giữa stories
-- E2E Test Cases PHẢI đủ để PE verify feature trên Staging ở Phase 2
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Feature đang làm việc.
+# /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-verify.
+9. Update `project-status.yaml` per `.claude/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 `.claude/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
+
+Invoke skill `token-logger`: write AI Usage Log to working Feature file.

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

@@ -1,51 +1,51 @@
-# /tas-fix $ARGUMENTS
-
-Vai trò: SE - Software Engineer
-Quick fix cho bug nhỏ hoặc lỗi rõ ràng — không cần tạo ticket, không cần full lifecycle.
-Dùng khi: solo dev, hotfix nhanh, bug tìm thấy trong lúc dev.
-Khác với /tas-bug: không tạo Bug file, không track status, không deploy flow.
-
-## Stack Detection
-Đọc `.claude/rules/common/stack-detection.md`.
-
-## Hành động
-
-### 1. Hiểu bug
-$ARGUMENTS là mô tả lỗi, error message, hoặc file:line_number.
-- Nếu có error message/stack trace: parse ngay, xác định file và dòng lỗi
-- Nếu chỉ có mô tả: hỏi 1 câu duy nhất để làm rõ (reproduce steps hoặc expected vs actual)
-- KHÔNG hỏi nhiều hơn 1 câu
-
-### 2. Diagnose (tối đa 3 file đọc)
-- Đọc file lỗi và các file liên quan trực tiếp
-- Xác định root cause trong 1-2 câu ngắn
-- KHÔNG đọc toàn bộ project, KHÔNG quét cấu trúc folder
-- Nếu cần đọc thêm file ngoài 3 file đầu tiên: hỏi user xác nhận
-
-### 3. Fix với regression test
-
-Trước khi fix, đọc các rules liên quan:
-- `.claude/rules/common/security.md` — kiểm tra fix có tạo ra security risk không
-- `.claude/rules/common/testing.md` — pattern viết regression test
-- `.claude/rules/[lang_rules]/coding-style.md` — conventions của stack hiện tại (nếu xác định được)
-
-Sau đó:
-a. Viết 1 test case tối thiểu reproduce bug (nếu project có test framework)
-b. Xác nhận test FAIL
-c. Fix code đúng root cause
-d. Xác nhận test PASS
-e. Chạy nhanh test suite nếu có (để check regression)
-
-### 4. Wrap up
-- Output commit message: `fix: <mô tả ngắn gọn>`
-- Nhắc: "Nếu bug này có khả năng tái phát hoặc ảnh hưởng production, cân nhắc dùng /tas-bug để track đầy đủ."
-
-## Nguyên tắc
-- Tổng số file đọc ≤ 3 trừ khi được cho phép
-- Fix đúng root cause, KHÔNG patch symptom
-- Nếu fix kéo theo thay đổi architecture → dừng, gợi ý dùng /tas-bug + /tas-adr
-- Nếu bug thuộc production và severity cao → dừng, gợi ý dùng /tas-bug với severity Critical/High
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Story hoặc Bug liên quan (nếu có).
+# /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 `.claude/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:
+- `.claude/rules/common/security.md` — check if fix creates security risks
+- `.claude/rules/common/testing.md` — regression test writing patterns
+- `.claude/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
+
+Invoke skill `token-logger`: write AI Usage Log to related Story or Bug file (if any).

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

@@ -1,144 +1,144 @@
-# /tas-functest-mobile $ARGUMENTS
-
-Vai tro: SE / QA
-Generate tat ca Detox automation test scripts cho mot mobile Feature.
-
-## QUAN TRONG - Layer 2: Mobile Functional Test Scripts
-- Tao Detox test scripts tu Func-Test-Spec (markdown)
-- Scripts nam trong `apps/mobile/e2e/features/`
-- Reusable helpers duoc export de Layer 3 (E2E) tai su dung
-- Data hardcoded trong test, credentials tu .env
-
-## Hanh dong
-
-### Buoc 1: Xac dinh Feature
-1. $ARGUMENTS la Feature ID hoac file path
-2. Neu khong co: scan `docs/epics/**/Feature-*.md` tim features co status In Progress
-3. Doc Feature file de lay Epic/Feature numbers va danh sach Stories
-
-### Buoc 2: Kiem tra Prerequisites
-1. Kiem tra `apps/mobile/` ton tai. Neu khong → bao loi:
-   > "Mobile app chua ton tai trong project nay. Vui long tao apps/mobile/ truoc."
-2. Tim tat ca `Func-Test-*.md` files trong Feature directory:
-   ```
-   docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md
-   ```
-3. Neu khong co Func-Test-Spec nao → bao loi:
-   > "Chua co Func-Test-Spec nao cho Feature nay. Chay /tas-functest {story-ID} truoc."
-4. Doc `apps/mobile/e2e/test-ids.ts` de biet testID hien co
-5. Doc `apps/mobile/e2e/helpers/data-loader.ts` va `test-utils.ts` de hieu patterns
-
-### Buoc 3: Aggregate FT Test Cases
-- Tu tat ca Func-Test-Spec files, tong hop danh sach FT test cases
-- Nhom theo Story
-- Lay test data requirements tu moi spec
-
-### Buoc 4: Generate Test Scripts
-Voi MOI Story co 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}
-    });
-  });
-});
-```
-
-### Buoc 5: Update test-ids.ts (neu can)
-- Neu test cases can testID chua co trong test-ids.ts
-- Them testID moi theo naming convention hien tai
-- Giu nguyen structure: nested object voi dot notation
-
-### Buoc 6: Generate Feature Helpers
-Tao file `apps/mobile/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
-```typescript
-/**
- * Reusable helpers cho {Feature Name}
- * Duoc tai su dung boi Layer 3 E2E scripts
- */
-
-export async function {featureSpecificHelper}() {
-  // Helper logic extracted from functional tests
-}
-```
-
-### Buoc 7: Update package.json Script
-Them hoac update script trong `apps/mobile/package.json`:
-```json
-"functest:mobile:{feature-slug}": "detox test --configuration ios.sim.debug --testPathPattern='e2e/features/{epic-slug}/{feature-slug}'"
-```
-
-### Buoc 8: Generate Index
-Tao `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**: Truc tiep trong test (vd: "invalid@email", "short")
-- **Credentials**: `const creds = getCredentials();` → password tu process.env
-- **Environment data**: `const testData = loadTestData();` → doc tu test-data.{env}.json
-- **KHONG BAO GIO** hardcode passwords/tokens trong test files
-
-## Chay Tests
-```bash
-# Chay tat ca func tests cho feature
-yarn functest:mobile:{feature-slug}
-
-# Chay chi mot story
-npx detox test --configuration ios.sim.debug --testPathPattern='e2e/features/{epic}/{feature}/{story}'
-
-# Chay voi Android
-npx detox test --configuration android.emu.debug --testPathPattern='e2e/features/{epic}/{feature}'
-```
-
-## Nguyen tac
-- Script PHAI chay duoc ngay tu CLI, KHONG can cua so Claude
-- Moi describe block dung full FT ID de grep duoc
-- Helpers PHAI export de Layer 3 reuse
-- KHONG import tu Layer 3 (flows/), chi export LEN Layer 3
-- Neu apps/mobile/ khong ton tai → bao loi graceful, KHONG tao
+# /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