@torus-engineering/tas-kit 1.7.0 → 1.9.0

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

@@ -1,115 +1,128 @@
-# /tas-dev $ARGUMENTS
-
-Vai trò: SE - Software Engineer
-Implement một User Story theo Technical Plan đã được duyệt.
-
-## Always / Ask / Never
-
-| | Hành động |
-|---|---|
-| **Always** | Kiểm tra `plan_status` trước khi implement |
-| **Always** | Follow tasks trong `## Technical Plan` của Story |
-| **Always** | Launch review agent độc lập sau khi implement — không review trong cùng session |
-| **Ask** | Khi phát hiện plan cần thay đổi đáng kể trong lúc code |
-| **Ask** | Khi cần đọc thêm file ngoài scope của plan |
-| **Never** | Implement ngoài scope Story |
-| **Never** | Skip bước review sau khi implement |
-
-## QUAN TRỌNG - Quy tắc đọc file
-- CHỈ đọc Story file — Technical Plan đã có đủ context kỹ thuật.
-- Không tự đọc PRD, SAD, ADR, Design-Spec trừ khi user xác nhận.
-- Không list thư mục, không quét project structure.
-- Không đọc `.tas/checklists/story-done.md` ở bước đầu (chỉ đọc ở bước cuối).
-
-## Stack Detection
-Đọc `.claude/rules/common/stack-detection.md`.
-
-## Hành động
-
-### Bước 1 — Xác định Story
-
-`$ARGUMENTS` là Story ID hoặc file path.
-Nếu không có: đọc `project-status.yaml`, tìm stories có `status: Committed` hoặc `status: In Progress`. Nếu nhiều hơn một, liệt kê để user chọn.
-Đọc Story file.
-
-### Bước 1.5 — Gate: Kiểm tra plan_status
-
-Đọc `plan_status` từ frontmatter của Story.
-
-**Nếu `plan_status: pending`:**
-Đọc `require_plan` từ root/`tas.yaml`:
-- `require_plan: true` (hoặc field không tồn tại) → **DỪNG LẠI**:
-  > "Story này chưa có Technical Plan. Chạy `/tas-plan {Story-ID}` trước khi implement."
-- `require_plan: false` → tiếp tục, hiển thị warning và chờ xác nhận:
-  > "⚠️ Quick mode: Story chưa có Technical Plan. Tiếp tục implement không?"
-
-**Nếu `plan_status: completed`:** tiếp tục bình thường.
-
-### Bước 2 — Đọc Technical Plan
-
-Từ Story file, đọc section `## Technical Plan`:
-- Approach đã chọn
-- Files to Change / Files to Create
-- Database Changes, Config Changes
-- Tasks list (checklist thực hiện theo thứ tự)
-
-Nếu không có Technical Plan (quick mode) → phân tích AC và implement trực tiếp theo AC.
-
-### Bước 3 — Implement
-
-#### Nếu `use_tdd = true` trong `tas.yaml`:
-a. **Red phase** — Viết test cases TRƯỚC theo AC trong Story. Chạy tests, xác nhận FAIL.
-b. **Green phase** — Viết code tối thiểu để pass tests.
-c. **Refactor** — Clean up, đảm bảo tests vẫn pass.
-
-#### Nếu `use_tdd = false`:
-a. Implement code theo AC + Tasks trong Technical Plan
-b. Viết unit tests cover các cases trong `## Unit Test Cases`
-c. Chạy tests, fix nếu fail
-→ Nếu tests vẫn fail sau 1 lần tự fix: launch `build-resolver` agent với error output để diagnose.
-
-Trong quá trình implement, tick từng task hoàn thành trong Story file: `- [x] Task 1: ...`
-
-Nếu phát hiện plan cần thay đổi đáng kể → thông báo user trước khi thay đổi hướng.
-
-### Bước 4 — Post-Implementation Review (Isolated Agent)
-
-Thực hiện theo `.claude/rules/common/post-review-agent.md`.
-Truyền vào: Story file path, danh sách changed files, stack (từ CLAUDE.md), lang_agent.
-
-### Bước 5 — Definition of Done
-
-Đọc `.tas/checklists/story-done.md`, verify từng mục, tick vào Story:
-- `- [x] Technical plan completed` — nếu plan_status: completed (hoặc quick mode xác nhận)
-- `- [x] Code implemented` — nếu implement xong
-- `- [x] Unit tests pass` — nếu tests đã pass
-- `- [x] No regression` — nếu toàn bộ test suite pass
-- `- [x] Documentation updated (if needed)` — nếu đã cập nhật
-- `- [x] Code review passed` — nếu review gate pass (không có Critical/High)
-- `- [ ] Acceptance criteria verified` — KHÔNG tick, để PE verify
-
-**Optional — nếu Story thay đổi API public, database schema, hoặc setup:**
-Launch `doc-updater` agent: cập nhật docs liên quan (README, SAD section, API docs).
-> Scope: [danh sách changed files]. Story: [Story ID + title].
-> Chỉ cập nhật phần docs đã lỗi thời — không viết lại từ đầu.
-
-### Bước 6 — Wrap up
-
-Cập nhật Story status → `In Progress` (nếu chưa).
-Tạo commit message theo conventions trong `CLAUDE.md`.
-Hỏi: "Tests OK và review passed rồi — bạn đã test thủ công chưa? Muốn chuyển sang Deploy Test không?"
-
-Nếu Yes:
-- Cập nhật Story status → `Deploy Test`
-- Thêm Changelog entry
-- Cập nhật `project-status.yaml`
-- Gợi ý: `/ado-update story {ado-id} --status "Deploy Test"` nếu dùng ADO
-
-## Nguyên tắc
-- KHÔNG implement ngoài scope của Story
-- Mỗi public method PHẢI có XML doc comment (C#) hoặc JSDoc (TypeScript) hoặc docstring (Python)
-- Review phải chạy qua Agent độc lập — không inline trong session hiện tại
-- **Khi nào cần tạo ADR** (nếu Technical Plan chưa đề cập):
-  - Thay đổi kiến trúc ảnh hưởng nhiều components
-  - Thêm mới design pattern hoặc framework
-  - Quyết định trade-off kỹ thuật quan trọng
+# /tas-dev $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Implement một User Story theo Technical Plan đã được duyệt.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Kiểm tra `plan_status` trước khi implement |
+| **Always** | Follow tasks trong `## Technical Plan` của Story |
+| **Always** | Launch review agent độc lập sau khi implement — không review trong cùng session |
+| **Ask** | Khi phát hiện plan cần thay đổi đáng kể trong lúc code |
+| **Ask** | Khi cần đọc thêm file ngoài scope của plan |
+| **Never** | Implement ngoài scope Story |
+| **Never** | Skip bước review sau khi implement |
+
+## QUAN TRỌNG - Quy tắc đọc file
+- CHỈ đọc Story file — Technical Plan đã có đủ context kỹ thuật.
+- Không tự đọc PRD, SAD, ADR, Design-Spec trừ khi user xác nhận.
+- Không list thư mục, không quét project structure.
+- Không đọc `.tas/checklists/story-done.md` ở bước đầu (chỉ đọc ở bước cuối).
+
+## Stack Detection
+Đọc `.claude/rules/common/stack-detection.md`.
+
+## Hành động
+
+### Bước 1 — Xác định Story
+
+`$ARGUMENTS` là Story ID hoặc file path.
+Nếu không có: đọc `project-status.yaml`, tìm stories có `status: Committed` hoặc `status: In Progress`. Nếu nhiều hơn một, liệt kê để user chọn.
+Đọc Story file.
+
+### Bước 1.5 — Gate: Kiểm tra plan_status
+
+Đọc `plan_status` từ frontmatter của Story.
+
+**Nếu `plan_status: pending`:**
+Đọc `require_plan` từ root/`tas.yaml`:
+- `require_plan: true` (hoặc field không tồn tại) → **DỪNG LẠI**:
+  > "Story này chưa có Technical Plan. Chạy `/tas-plan {Story-ID}` trước khi implement."
+- `require_plan: false` → tiếp tục, hiển thị warning và chờ xác nhận:
+  > "⚠️ Quick mode: Story chưa có Technical Plan. Tiếp tục implement không?"
+
+**Nếu `plan_status: completed`:** tiếp tục bình thường.
+
+### Bước 2 — Đọc Technical Plan
+
+Từ Story file, đọc section `## Technical Plan`:
+- Approach đã chọn
+- Files to Change / Files to Create
+- Database Changes, Config Changes
+- Tasks list (checklist thực hiện theo thứ tự)
+
+Nếu không có Technical Plan (quick mode) → phân tích AC và implement trực tiếp theo AC.
+
+### Bước 3 — Implement
+
+**Nếu stack là Node.js/Express/Next.js** → invoke skill `js-backend-patterns` để tham khảo
+repository pattern, service layer, N+1 prevention, caching, error handling trước khi code.
+
+#### Nếu `use_tdd = true` trong `tas.yaml`:
+a. **Red phase** — Viết test cases TRƯỚC theo AC trong Story. Chạy tests, xác nhận FAIL.
+
+   Platform-specific (từ stack detection):
+   - **Mobile (React Native)**: Jest + React Testing Library — Components (`render`, `fireEvent`, `screen`), Hooks (`renderHook`), Services/API (Jest mocks + MSW), Utils, Zustand stores. File: `src/**/*.test.ts(x)`
+   - **Web (React + Node)**: Vitest/Jest + React Testing Library — Components, Hooks, Services (MSW/Nock), Backend services (Jest). File: `src/**/*.test.ts(x)`
+   - **Backend (.NET)**: xUnit — Unit (services, repositories), Integration (TestServer), API (WebApplicationFactory). File: `tests/Unit/`, `tests/Integration/`, `tests/Api/`
+
+b. **Green phase** — Viết code tối thiểu để pass tests.
+c. **Refactor** — Clean up, đảm bảo tests vẫn pass.
+
+#### Nếu `use_tdd = false`:
+a. Implement code theo AC + Tasks trong Technical Plan
+b. Viết unit tests cover các cases trong `## Unit Test Cases`
+c. Chạy tests, fix nếu fail
+→ Nếu tests vẫn fail sau 1 lần tự fix: launch `build-resolver` agent với error output để diagnose.
+
+Trong quá trình implement, tick từng task hoàn thành trong Story file: `- [x] Task 1: ...`
+
+Nếu phát hiện plan cần thay đổi đáng kể → thông báo user trước khi thay đổi hướng.
+
+### Bước 4 — Post-Implementation Review (Isolated Agent)
+
+Thực hiện theo `.claude/rules/common/post-review-agent.md`.
+Truyền vào: Story file path, danh sách changed files, stack (từ CLAUDE.md), lang_agent.
+
+### Bước 5 — Definition of Done
+
+Đọc `.tas/checklists/story-done.md`, verify từng mục, tick vào Story:
+- `- [x] Technical plan completed` — nếu plan_status: completed (hoặc quick mode xác nhận)
+- `- [x] Code implemented` — nếu implement xong
+- `- [x] Unit tests pass` — nếu tests đã pass
+- `- [x] No regression` — nếu toàn bộ test suite pass
+- `- [x] Documentation updated (if needed)` — nếu đã cập nhật
+- `- [x] Code review passed` — nếu review gate pass (không có Critical/High)
+- `- [ ] Acceptance criteria verified` — KHÔNG tick, để PE verify
+
+**Optional — nếu Story thay đổi API public, database schema, hoặc setup:**
+Launch `doc-updater` agent: cập nhật docs liên quan (README, SAD section, API docs).
+> Scope: [danh sách changed files]. Story: [Story ID + title].
+> Chỉ cập nhật phần docs đã lỗi thời — không viết lại từ đầu.
+
+### Bước 6 — Wrap up
+
+Cập nhật Story status → `In Progress` (nếu chưa).
+Tạo commit message theo conventions trong `CLAUDE.md`.
+Hỏi: "Tests OK và review passed rồi — bạn đã test thủ công chưa? Muốn chuyển sang Deploy Test không?"
+
+Nếu Yes:
+- Cập nhật Story status → `Deploy Test`
+- Thêm Changelog entry
+- Cập nhật `project-status.yaml`
+- Gợi ý: `/ado-update story {ado-id} --status "Deploy Test"` nếu dùng ADO
+
+## Nguyên tắc
+- KHÔNG implement ngoài scope của Story
+- Mỗi public method PHẢI có XML doc comment (C#) hoặc JSDoc (TypeScript) hoặc docstring (Python)
+- Review phải chạy qua Agent độc lập — không inline trong session hiện tại
+- **Khi nào cần tạo ADR** (nếu Technical Plan chưa đề cập):
+  - Thay đổi kiến trúc ảnh hưởng nhiều components
+  - Thêm mới design pattern hoặc framework
+  - Quyết định trade-off kỹ thuật quan trọng
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào file Story đang làm việc.

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

@@ -0,0 +1,155 @@
+# /tas-e2e-mobile $ARGUMENTS
+
+Vai tro: SE / QA
+Generate Detox E2E test scripts tu mot E2E Scenario markdown file.
+
+## QUAN TRONG - Layer 3: Mobile E2E Scripts
+- Tao Detox test scripts tu E2E-Scenario (markdown)
+- Scripts nam trong `apps/mobile/e2e/flows/`
+- REUSE helpers tu Layer 2 functional tests (features/)
+- Chain functional test steps thanh end-to-end flows
+
+## Hanh dong
+
+### Buoc 1: Xac dinh Scenario
+1. $ARGUMENTS la path den E2E-Scenario-*.md file
+2. Neu khong co: scan `docs/epics/**/E2E-Scenario-*.md` va `docs/e2e-scenarios/E2E-Scenario-*.md`
+3. List scenarios va hoi user chon
+
+### Buoc 2: Kiem tra Prerequisites
+1. Kiem tra `apps/mobile/` ton tai. Neu khong → bao loi graceful
+2. Doc scenario file de lay:
+   - Scenario steps va flow
+   - FT ID references (cot "Builds on FT IDs")
+   - FT Reuse Map (section cuoi)
+   - Test data per environment
+   - Scenario type (single-epic / cross-epic)
+
+### Buoc 3: Tim Functional Test Helpers
+Tu FT Reuse Map trong scenario:
+1. Tim tung source file trong `apps/mobile/e2e/features/`
+2. Verify helper functions ton tai
+3. Neu helper khong ton tai → tao stub va ghi note "TODO: implement helper"
+4. Import map: FT ID → file path → function name
+
+### Buoc 4: Generate E2E Script
+
+**File output**: `apps/mobile/e2e/flows/{scenario-slug}.e2e.ts`
+
+**Structure**:
+```typescript
+/**
+ * E2E Flow: {Scenario Name}
+ * Scenario: {Scenario_ID}
+ * Epic(s): {Epic_ID(s)}
+ * Type: {single-epic | cross-epic}
+ * 
+ * Generated by /tas-e2e-mobile
+ * Spec: {path to E2E-Scenario-*.md}
+ */
+
+import { device, element, expect, by, waitFor } from 'detox';
+import { TEST_IDS } from '../test-ids';
+import { loadTestData, getCredentials } from '../helpers/data-loader';
+import { login, logout, navigateToTab } from '../helpers/test-utils';
+
+// Layer 2 helpers (reuse from functional tests)
+import { fillLoginForm, verifyLoginSuccess } from '../features/{epic}/{feature}/helpers';
+import { viewAllergenList } from '../features/{epic2}/{feature2}/helpers';
+
+const testData = loadTestData();
+
+describe('E2E Flow: {Scenario Name}', () => {
+  beforeAll(async () => {
+    await device.launchApp({ newInstance: true });
+  });
+
+  // Main Flow
+  describe('{PROJECT}_E{EPIC}_E2E_001_H: {Flow Title}', () => {
+    it('Step 1: {Action}', async () => {
+      // Reuses: AL_E002_F002_S001_FT_001_H
+      const creds = getCredentials();
+      await fillLoginForm(creds.email, creds.password);
+      await verifyLoginSuccess();
+    });
+
+    it('Step 2: {Action}', async () => {
+      // Reuses: AL_E003_F001_S001_FT_001_H
+      await viewAllergenList();
+    });
+
+    it('Step 3: {New logic - no FT reference}', async () => {
+      // New step: no functional test helper exists
+      await element(by.id(TEST_IDS.SCAN.SCREEN.CAMERA)).tap();
+      // ...
+    });
+  });
+
+  // Alternate Flow (if defined in scenario)
+  describe('{PROJECT}_E{EPIC}_E2E_002_N: {Alternate Flow}', () => {
+    it('should handle {error condition}', async () => {
+      // ...
+    });
+  });
+});
+```
+
+### Buoc 5: Update package.json Script
+Them hoac update script trong `apps/mobile/package.json`:
+```json
+"e2e:flow:{scenario-slug}": "detox test --configuration ios.sim.debug --testPathPattern='e2e/flows/{scenario-slug}'"
+```
+
+### Buoc 6: Generate Execution Report (Optional)
+Sau khi chay tests, generate report tu `.tas/templates/E2E-Execution-Report.md`:
+- Summary metrics (passed/failed/skipped)
+- Results by test ID
+- Failed test details
+- Performance metrics
+- AC coverage analysis
+
+## File Structure Output
+```
+apps/mobile/e2e/flows/
+├── {scenario-1-slug}.e2e.ts
+├── {scenario-2-slug}.e2e.ts
+└── ...
+```
+
+## Reuse Strategy
+```
+Layer 2 (features/)          Layer 3 (flows/)
+┌───────────────────┐       ┌──────────────────────┐
+│ helpers.ts        │──────>│ {scenario}.e2e.ts     │
+│  - fillLoginForm()│       │  import { fillLogin } │
+│  - verifyLogin()  │       │  import { viewList }  │
+└───────────────────┘       │                      │
+┌───────────────────┐       │  Step 1: fillLogin() │
+│ helpers.ts        │──────>│  Step 2: viewList()  │
+│  - viewList()     │       │  Step 3: new logic   │
+└───────────────────┘       └──────────────────────┘
+```
+
+## Chay Tests
+```bash
+# Chay E2E flow cu the
+yarn e2e:flow:{scenario-slug}
+
+# Chay tat ca E2E flows
+npx detox test --configuration ios.sim.debug --testPathPattern='e2e/flows/'
+
+# Chay voi Android
+npx detox test --configuration android.emu.debug --testPathPattern='e2e/flows/{scenario}'
+
+# Chay va generate report
+npx detox test --configuration ios.sim.debug --testPathPattern='e2e/flows/{scenario}' --reporters=jest-junit
+```
+
+## Nguyen tac
+- PHAI reuse helpers tu Layer 2 khi co the, KHONG viet lai logic da co
+- Moi step trong E2E flow nen tuong ung voi 1 functional test helper
+- Steps khong co FT reference → viet logic moi trong flow file
+- Scripts PHAI chay duoc tu CLI, KHONG can cua so Claude
+- Neu apps/mobile/ khong ton tai → bao loi graceful
+- describe block dung full E2E ID de grep duoc
+- import paths: relative tu flows/ len features/

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

@@ -0,0 +1,163 @@
+# /tas-e2e-web $ARGUMENTS
+
+Vai tro: SE / QA
+Generate Playwright E2E test scripts tu mot E2E Scenario markdown file.
+
+## QUAN TRONG - Layer 3: Web E2E Scripts
+- Tao Playwright test scripts tu E2E-Scenario (markdown)
+- Scripts nam trong `apps/web/e2e/flows/`
+- REUSE helpers tu Layer 2 functional tests (features/)
+- Cross-browser testing (Chromium, Firefox, WebKit)
+- Chain functional test steps thanh end-to-end flows
+
+## Hanh dong
+
+### Buoc 1: Xac dinh Scenario
+1. $ARGUMENTS la path den E2E-Scenario-*.md file
+2. Neu khong co: scan `docs/epics/**/E2E-Scenario-*.md` va `docs/e2e-scenarios/E2E-Scenario-*.md`
+3. List scenarios va hoi user chon
+
+### Buoc 2: Kiem tra Prerequisites
+1. Kiem tra `apps/web/` ton tai. Neu khong → bao:
+   > "Web app chua ton tai trong project nay. Neu project chi co mobile, dung /tas-e2e-mobile."
+   > DUNG LAI, KHONG tao file.
+2. Doc scenario file de lay:
+   - Scenario steps va flow
+   - FT ID references
+   - FT Reuse Map
+   - Test data per environment
+3. Doc `apps/web/playwright.config.ts` (neu co)
+
+### Buoc 3: Tim Functional Test Helpers
+Tu FT Reuse Map trong scenario:
+1. Tim source files trong `apps/web/e2e/features/`
+2. Verify helper functions va page objects ton tai
+3. Neu helper khong ton tai → tao stub va ghi "TODO: implement helper"
+4. Import map: FT ID → file path → function name
+
+### Buoc 4: Generate E2E Script
+
+**File output**: `apps/web/e2e/flows/{scenario-slug}.spec.ts`
+
+**Structure**:
+```typescript
+/**
+ * E2E Flow: {Scenario Name}
+ * Scenario: {Scenario_ID}
+ * Epic(s): {Epic_ID(s)}
+ * Type: {single-epic | cross-epic}
+ * 
+ * Generated by /tas-e2e-web
+ * Spec: {path to E2E-Scenario-*.md}
+ */
+
+import { test, expect, Page } from '@playwright/test';
+import { loadTestData, getCredentials } from '../helpers/data-loader';
+
+// Layer 2 helpers (reuse from functional tests)
+import { fillLoginForm, verifyLoginSuccess } from '../features/{epic}/{feature}/helpers';
+import { viewAllergenList } from '../features/{epic2}/{feature2}/helpers';
+
+const testData = loadTestData();
+
+test.describe('E2E Flow: {Scenario Name}', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(testData.baseUrl);
+  });
+
+  // Main Flow
+  test.describe('{PROJECT}_E{EPIC}_E2E_001_H: {Flow Title}', () => {
+    test('Complete flow', async ({ page }) => {
+      // Step 1: Login (reuses AL_E002_F002_S001_FT_001_H)
+      const creds = getCredentials();
+      await fillLoginForm(page, creds.email, creds.password);
+      await verifyLoginSuccess(page);
+
+      // Step 2: View allergen list (reuses AL_E003_F001_S001_FT_001_H)
+      await viewAllergenList(page);
+
+      // Step 3: New logic (no FT reference)
+      await page.getByTestId('scan-button').click();
+      await expect(page.getByTestId('scan-result')).toBeVisible();
+    });
+  });
+
+  // Cross-browser validation
+  test.describe('{PROJECT}_E{EPIC}_E2E_001_H - Cross-browser', () => {
+    test('should complete flow on all browsers', async ({ page, browserName }) => {
+      test.info().annotations.push({ type: 'browser', description: browserName });
+      // Same flow, validated across browsers via Playwright projects config
+    });
+  });
+
+  // Alternate/Error flows
+  test.describe('{PROJECT}_E{EPIC}_E2E_002_N: {Error Flow}', () => {
+    test('should handle {error condition}', async ({ page }) => {
+      // ...
+    });
+  });
+});
+```
+
+### Buoc 5: Update package.json Script
+Them hoac update script trong `apps/web/package.json`:
+```json
+"e2e:flow:{scenario-slug}": "npx playwright test e2e/flows/{scenario-slug}"
+```
+
+### Buoc 6: Generate Execution Report (Optional)
+Tu `.tas/templates/E2E-Execution-Report.md`:
+- Bao gom browser-specific results
+- Viewport testing results
+- Performance metrics (LCP, INP, CLS)
+
+## File Structure Output
+```
+apps/web/e2e/flows/
+├── {scenario-1-slug}.spec.ts
+├── {scenario-2-slug}.spec.ts
+└── ...
+```
+
+## Reuse Strategy
+```
+Layer 2 (features/)          Layer 3 (flows/)
+┌───────────────────┐       ┌──────────────────────────┐
+│ helpers.ts        │──────>│ {scenario}.spec.ts        │
+│  - fillLogin(page)│       │  import { fillLogin }     │
+│  - verify(page)   │       │  import { viewList }      │
+└───────────────────┘       │                          │
+┌───────────────────┐       │  Step 1: fillLogin(page) │
+│ helpers.ts        │──────>│  Step 2: viewList(page)  │
+│  - viewList(page) │       │  Step 3: new logic       │
+└───────────────────┘       └──────────────────────────┘
+```
+
+Note: Web helpers nhan `page: Page` parameter (khac voi mobile dung global Detox API).
+
+## Chay Tests
+```bash
+# Chay E2E flow cu the
+yarn e2e:flow:{scenario-slug}
+
+# Chay tat ca E2E flows
+npx playwright test e2e/flows/
+
+# Chay chi tren Firefox
+npx playwright test --project=firefox e2e/flows/{scenario}
+
+# Chay voi debug UI
+npx playwright test --ui e2e/flows/{scenario}
+
+# Chay va generate HTML report
+npx playwright test e2e/flows/{scenario} --reporter=html
+```
+
+## Nguyen tac
+- PHAI reuse helpers tu Layer 2 khi co the
+- Web helpers PHAI nhan `page: Page` parameter (dependency injection)
+- Scripts PHAI chay duoc tu CLI
+- Neu apps/web/ khong ton tai → bao loi graceful, KHONG tao
+- Cross-browser: Chromium, Firefox, WebKit (tu playwright.config.ts)
+- describe block dung full E2E ID
+- import paths: relative tu flows/ len features/

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

@@ -0,0 +1,102 @@
+# /tas-e2e $ARGUMENTS
+
+Vai tro: QA / PE
+Generate E2E test scenario documents tu mot Epic hoac user flow description.
+
+## QUAN TRONG - Layer 3: E2E Testing
+- E2E tests kiem tra TOAN BO flow lien ket giua nhieu features/stories
+- E2E scenario PHAI reference FT IDs tu Layer 2 (Functional Tests)
+- E2E scripts (tao boi /tas-e2e-mobile hoac /tas-e2e-web) se REUSE helpers tu Layer 2
+- Output la markdown scenario file, KHONG phai test code
+
+## Hanh dong
+
+### Buoc 1: Xac dinh Input
+$ARGUMENTS co the la:
+- **Epic ID** (vd: "Epic-002", "AL-Epic-002-authentication") → generate scenarios tu tat ca features/stories trong epic
+- **Flow description** (vd: "user registration to first scan") → generate cross-epic scenario
+
+Neu khong co $ARGUMENTS: list cac Epics hien co va hoi user chon.
+
+### Buoc 2: Thu thap Context
+
+#### Neu la Epic ID:
+1. Doc Epic file va tat ca Feature files ben trong
+2. Doc tat ca Story files cua cac Features
+3. Tim tat ca `Func-Test-*.md` files de lay FT IDs
+
+#### Neu la Flow Description:
+1. Search across `docs/epics/` de tim Features/Stories lien quan
+2. Xac dinh cac Epics lien quan (cross-epic scenario)
+3. Thu thap FT IDs tu Func-Test-*.md files
+
+### Buoc 3: Doc template
+Doc `.tas/templates/E2E-Scenario.md`
+Doc `root/tas.yaml` de lay project code
+
+### Buoc 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:
+Moi step PHAI co cot "Builds on FT IDs" de 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 |
+```
+
+Neu step KHONG co FT reference → ghi "-" (new logic, chua co func test)
+
+#### Noi dung generate:
+1. Flow Overview (narrative description)
+2. Scenario Steps table
+3. Step Details (chi tiet tung buoc)
+4. Alternate Flows (neu co)
+5. Error Flows (neu co)
+6. Test Data per environment
+7. Prerequisites checklist
+8. Success Criteria
+9. FT Reuse Map (map step → FT ID → helper function)
+
+### Buoc 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 neu chua ton tai.
+
+### Buoc 6: Prompting
+Sau khi generate, hoi user:
+- "Co flow phu nao can cover khong?"
+- "Co error scenario nao can them khong?"
+- "Test data cho cac environment da day du chua?"
+- "Co can test tren ca mobile va web khong?"
+
+## FT Reuse Map
+Moi scenario file co section "FT Reuse Map" de:
+- Map scenario step → FT ID → source file → helper function
+- /tas-e2e-mobile va /tas-e2e-web doc section nay de import helpers tu 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
+
+## Nguyen tac
+- Output la MARKDOWN scenario, KHONG phai test code
+- Test code duoc tao boi /tas-e2e-mobile hoac /tas-e2e-web
+- Moi step NEN reference FT IDs khi co the (de reuse, khong viet lai)
+- Scenario phai testable: co preconditions, test data, success criteria ro rang
+- Cross-epic scenarios dung prefix XEPIC thay vi Epic number