@torus-engineering/tas-kit 1.9.0 → 1.11.1

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

@@ -1,163 +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/
+# /tas-e2e-web $ARGUMENTS
+
+Role: SE / QA
+Generate Playwright E2E test scripts from an E2E Scenario markdown file.
+
+## IMPORTANT - Layer 3: Web E2E Scripts
+- Create Playwright test scripts from E2E-Scenario (markdown)
+- Scripts located in `apps/web/e2e/flows/`
+- REUSE helpers from Layer 2 functional tests (features/)
+- Cross-browser testing (Chromium, Firefox, WebKit)
+- Chain functional test steps into end-to-end flows
+
+## Actions
+
+### Step 1: Identify Scenario
+1. $ARGUMENTS is path to E2E-Scenario-*.md file
+2. If not provided: scan `docs/epics/**/E2E-Scenario-*.md` and `docs/e2e-scenarios/E2E-Scenario-*.md`
+3. List scenarios and ask user to choose
+
+### Step 2: Check Prerequisites
+1. Check `apps/web/` exists. If not → report:
+   > "Web app doesn't exist in this project. If project only has mobile, use /tas-e2e-mobile."
+   > STOP, DO NOT create file.
+2. Read scenario file to get:
+   - Scenario steps and flow
+   - FT ID references
+   - FT Reuse Map
+   - Test data per environment
+3. Read `apps/web/playwright.config.ts` (if exists)
+
+### Step 3: Find Functional Test Helpers
+From FT Reuse Map in scenario:
+1. Find source files in `apps/web/e2e/features/`
+2. Verify helper functions and page objects exist
+3. If helper doesn't exist → create stub and note "TODO: implement helper"
+4. Import map: FT ID → file path → function name
+
+### Step 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 }) => {
+      // ...
+    });
+  });
+});
+```
+
+### Step 5: Update package.json Script
+Add or update script in `apps/web/package.json`:
+```json
+"e2e:flow:{scenario-slug}": "npx playwright test e2e/flows/{scenario-slug}"
+```
+
+### Step 6: Generate Execution Report (Optional)
+From `.tas/templates/E2E-Execution-Report.md`:
+- Include 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 receive `page: Page` parameter (unlike mobile using global Detox API).
+
+## Run Tests
+```bash
+# Run specific E2E flow
+yarn e2e:flow:{scenario-slug}
+
+# Run all E2E flows
+npx playwright test e2e/flows/
+
+# Run only on Firefox
+npx playwright test --project=firefox e2e/flows/{scenario}
+
+# Run with debug UI
+npx playwright test --ui e2e/flows/{scenario}
+
+# Run and generate HTML report
+npx playwright test e2e/flows/{scenario} --reporter=html
+```
+
+## Principles
+- MUST reuse helpers from Layer 2 when possible
+- Web helpers MUST receive `page: Page` parameter (dependency injection)
+- Scripts MUST be runnable from CLI
+- If apps/web/ doesn't exist → graceful error, DO NOT create
+- Cross-browser: Chromium, Firefox, WebKit (from playwright.config.ts)
+- describe block uses full E2E ID
+- import paths: relative from flows/ up to features/

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

@@ -1,102 +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
+# /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/.claude/commands/tas-epic.md

@@ -1,35 +1,35 @@
-# /tas-epic $ARGUMENTS
-
-Vai trò: PE - Product Engineer
-Tạo mới hoặc cập nhật Epic document.
-
-## Prerequisite
-- docs/prd.md phải tồn tại
-
-## Hành động
-1. Cần context từ root/tas.yaml và docs/prd.md
-2. Cần context từ .tas/templates/Epic.md
-3. Xác định chế độ dựa vào $ARGUMENTS:
-
-### Chế độ CREATE ($ARGUMENTS là mô tả Epic mới, hoặc không có $ARGUMENTS):
-4. Nếu không có $ARGUMENTS, hỏi user mô tả Epic.
-5. Đọc project.code từ root/tas.yaml. Quét docs/epics/ để xác định số thứ tự.
-6. Tạo thư mục docs/epics/{code}-Epic-{NNN}-{slug}/
-7. Tạo file docs/epics/{code}-Epic-{NNN}-{slug}/{code}-Epic-{NNN}-{slug}.md
-8. Cập nhật `project-status.yaml` theo `.claude/rules/common/project-status.md` — thêm entry vào `epics`.
-
-### Chế độ UPDATE ($ARGUMENTS là Epic ID, ví dụ: "Epic-001"):
-4. Tìm thư mục docs/epics/{code}-Epic-001-*/
-5. Cần context từ file Epic hiện tại
-6. Hỏi user cần thay đổi gì (cập nhật scope, thêm feature, đổ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}.status`.
-
-## Nguyên tắc
-- Mỗi Epic map với một business capability trong PRD
-- Epic KHÔNG chứa chi tiết kỹ thuật, chỉ chứa business value
-- Ước lượng effort ở mức T-shirt size: S/M/L/XL
-
-## Bước cuối — Token Log
-
-Invoke skill `token-logger`: ghi AI Usage Log vào file Epic đang làm việc.
+# /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 `.claude/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 `.claude/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
+
+Invoke skill `token-logger`: write AI Usage Log to working Epic file.