@torus-engineering/tas-kit 1.10.0 → 1.12.0

package/{.claude → .tas}/commands/tas-functest-web.md

@@ -1,192 +1,192 @@
-# /tas-functest-web $ARGUMENTS
-
-Vai tro: SE / QA
-Generate tat ca Playwright automation test scripts cho mot web Feature.
-
-## QUAN TRONG - Layer 2: Web Functional Test Scripts
-- Tao Playwright test scripts tu Func-Test-Spec (markdown)
-- Scripts nam trong `apps/web/e2e/features/`
-- Reusable helpers duoc export de Layer 3 (E2E) tai su dung
-- Data hardcoded trong test, credentials tu .env
-- Cross-viewport testing (mobile, tablet, desktop)
-
-## 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/web/` ton tai. Neu khong → bao:
-   > "Web app chua ton tai trong project nay. Neu project chi co mobile, dung /tas-functest-mobile."
-   > DUNG LAI, KHONG tao file.
-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/web/playwright.config.ts` (neu co) de hieu config hien tai
-5. Doc `apps/web/e2e/helpers/` (neu co) 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/web/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.spec.ts`
-
-**Structure**:
-```typescript
-/**
- * Functional Tests: {Story Name}
- * Story: {Story_ID}
- * Feature: {Feature_ID}
- * Epic: {Epic_ID}
- * 
- * Generated by /tas-functest-web
- * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
- */
-
-import { test, expect } from '@playwright/test';
-import { loadTestData, getCredentials } from '../../../helpers/data-loader';
-
-const testData = loadTestData();
-
-test.describe('{Feature Name} - {Story Name}', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/target-page');
-  });
-
-  // AC Reference: AC-1
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
-    test('should {description from spec}', async ({ page }) => {
-      // Given: {precondition}
-      // When: {action}
-      await page.getByTestId('element-id').click();
-      // Then: {expected}
-      await expect(page.getByTestId('result')).toBeVisible();
-    });
-  });
-
-  // Viewport testing for responsive features
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H - Viewports', () => {
-    const viewports = [
-      { width: 375, height: 812, name: 'mobile' },
-      { width: 768, height: 1024, name: 'tablet' },
-      { width: 1280, height: 720, name: 'desktop' },
-    ];
-
-    for (const vp of viewports) {
-      test(`should work on ${vp.name} (${vp.width}x${vp.height})`, async ({ page }) => {
-        await page.setViewportSize({ width: vp.width, height: vp.height });
-        // Test responsive behavior
-      });
-    }
-  });
-});
-```
-
-### Buoc 5: Generate Feature Helpers
-Tao file `apps/web/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
-```typescript
-import { Page, expect } from '@playwright/test';
-
-/**
- * Reusable helpers cho {Feature Name}
- * Duoc tai su dung boi Layer 3 E2E scripts
- */
-
-export async function {featureSpecificHelper}(page: Page) {
-  // Helper logic extracted from functional tests
-}
-```
-
-### Buoc 6: Generate/Update Data Loader (neu chua co)
-Neu `apps/web/e2e/helpers/data-loader.ts` chua ton tai, tao:
-```typescript
-type TestEnv = 'dev' | 'staging' | 'prod';
-
-export function loadTestData(env?: TestEnv) {
-  const targetEnv = env || (process.env.TEST_ENV as TestEnv) || 'dev';
-  return require(`../data/test-data.${targetEnv}.json`);
-}
-
-export function getCredentials(userType = 'default') {
-  const data = loadTestData();
-  const user = data.users[userType] || data.users.default;
-  return {
-    email: user.email,
-    password: process.env.TEST_USER_PASSWORD || '',
-  };
-}
-```
-
-### Buoc 7: Update package.json Script
-Them hoac update script trong `apps/web/package.json`:
-```json
-"functest:web:{feature-slug}": "npx playwright test e2e/features/{epic-slug}/{feature-slug}"
-```
-
-### Buoc 8: Generate Index
-Tao `apps/web/e2e/features/{epic-slug}/{feature-slug}/index.ts`:
-```typescript
-export * from './helpers';
-```
-
-## File Structure Output
-```
-apps/web/e2e/features/
-└── {epic-slug}/
-    └── {feature-slug}/
-        ├── {story-1-slug}.func.spec.ts
-        ├── {story-2-slug}.func.spec.ts
-        ├── helpers.ts
-        └── index.ts
-```
-
-## Selector Strategy (Playwright)
-- **Uu tien**: `data-testid` → `page.getByTestId('login-submit')`
-- **Text content**: `page.getByText('Welcome')`
-- **Role**: `page.getByRole('button', { name: 'Submit' })`
-- **Label**: `page.getByLabel('Email')`
-- KHONG dung CSS selectors truyen thong (`.class`, `#id`) tru khi bat buoc
-
-## Cross-Browser Testing
-- Chromium (bat buoc)
-- Firefox (bat buoc)
-- WebKit (bat buoc)
-- Config trong `playwright.config.ts` projects section
-
-## Test Data Convention
-- **Hardcoded values**: Truc tiep trong test
-- **Credentials**: `getCredentials()` → password tu process.env
-- **Environment data**: `loadTestData()` → tu test-data.{env}.json
-- **KHONG BAO GIO** hardcode passwords/tokens
-
-## Chay Tests
-```bash
-# Chay tat ca func tests cho feature
-yarn functest:web:{feature-slug}
-
-# Chay chi mot story
-npx playwright test e2e/features/{epic}/{feature}/{story}
-
-# Chay voi browser cu the
-npx playwright test --project=firefox e2e/features/{epic}/{feature}
-
-# Chay voi debug UI
-npx playwright test --ui e2e/features/{epic}/{feature}
-```
-
-## Nguyen tac
-- Script PHAI chay duoc ngay tu CLI
-- Moi describe block dung full FT ID
-- Helpers PHAI export de Layer 3 reuse
-- KHONG import tu Layer 3 (flows/)
-- Neu apps/web/ khong ton tai → bao loi graceful, KHONG tao
-- Test phai work tren tat ca viewports (mobile, tablet, desktop)
+# /tas-functest-web $ARGUMENTS
+
+Role: SE / QA
+Generate all Playwright automation test scripts for a web Feature.
+
+## IMPORTANT - Layer 2: Web Functional Test Scripts
+- Create Playwright test scripts from Func-Test-Spec (markdown)
+- Scripts located in `apps/web/e2e/features/`
+- Reusable helpers exported for Layer 3 (E2E) reuse
+- Hardcoded data in tests, credentials from .env
+- Cross-viewport testing (mobile, tablet, desktop)
+
+## 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/web/` exists. If not → report:
+   > "Web app doesn't exist in this project. If project only has mobile, use /tas-functest-mobile."
+   > STOP, DO NOT create file.
+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 → report:
+   > "No Func-Test-Spec for this Feature yet. Run /tas-functest {story-ID} first."
+4. Read `apps/web/playwright.config.ts` (if exists) to understand current config
+5. Read `apps/web/e2e/helpers/` (if exists) 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/web/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.spec.ts`
+
+**Structure**:
+```typescript
+/**
+ * Functional Tests: {Story Name}
+ * Story: {Story_ID}
+ * Feature: {Feature_ID}
+ * Epic: {Epic_ID}
+ * 
+ * Generated by /tas-functest-web
+ * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ */
+
+import { test, expect } from '@playwright/test';
+import { loadTestData, getCredentials } from '../../../helpers/data-loader';
+
+const testData = loadTestData();
+
+test.describe('{Feature Name} - {Story Name}', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/target-page');
+  });
+
+  // AC Reference: AC-1
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    test('should {description from spec}', async ({ page }) => {
+      // Given: {precondition}
+      // When: {action}
+      await page.getByTestId('element-id').click();
+      // Then: {expected}
+      await expect(page.getByTestId('result')).toBeVisible();
+    });
+  });
+
+  // Viewport testing for responsive features
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H - Viewports', () => {
+    const viewports = [
+      { width: 375, height: 812, name: 'mobile' },
+      { width: 768, height: 1024, name: 'tablet' },
+      { width: 1280, height: 720, name: 'desktop' },
+    ];
+
+    for (const vp of viewports) {
+      test(`should work on ${vp.name} (${vp.width}x${vp.height})`, async ({ page }) => {
+        await page.setViewportSize({ width: vp.width, height: vp.height });
+        // Test responsive behavior
+      });
+    }
+  });
+});
+```
+
+### Step 5: Generate Feature Helpers
+Create file `apps/web/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
+```typescript
+import { Page, expect } from '@playwright/test';
+
+/**
+ * Reusable helpers for {Feature Name}
+ * Exported for Layer 3 E2E scripts reuse
+ */
+
+export async function {featureSpecificHelper}(page: Page) {
+  // Helper logic extracted from functional tests
+}
+```
+
+### Step 6: Generate/Update Data Loader (if not exists)
+If `apps/web/e2e/helpers/data-loader.ts` doesn't exist, create:
+```typescript
+type TestEnv = 'dev' | 'staging' | 'prod';
+
+export function loadTestData(env?: TestEnv) {
+  const targetEnv = env || (process.env.TEST_ENV as TestEnv) || 'dev';
+  return require(`../data/test-data.${targetEnv}.json`);
+}
+
+export function getCredentials(userType = 'default') {
+  const data = loadTestData();
+  const user = data.users[userType] || data.users.default;
+  return {
+    email: user.email,
+    password: process.env.TEST_USER_PASSWORD || '',
+  };
+}
+```
+
+### Step 7: Update package.json Script
+Add or update script in `apps/web/package.json`:
+```json
+"functest:web:{feature-slug}": "npx playwright test e2e/features/{epic-slug}/{feature-slug}"
+```
+
+### Step 8: Generate Index
+Create `apps/web/e2e/features/{epic-slug}/{feature-slug}/index.ts`:
+```typescript
+export * from './helpers';
+```
+
+## File Structure Output
+```
+apps/web/e2e/features/
+└── {epic-slug}/
+    └── {feature-slug}/
+        ├── {story-1-slug}.func.spec.ts
+        ├── {story-2-slug}.func.spec.ts
+        ├── helpers.ts
+        └── index.ts
+```
+
+## Selector Strategy (Playwright)
+- **Priority**: `data-testid` → `page.getByTestId('login-submit')`
+- **Text content**: `page.getByText('Welcome')`
+- **Role**: `page.getByRole('button', { name: 'Submit' })`
+- **Label**: `page.getByLabel('Email')`
+- DO NOT use traditional CSS selectors (`.class`, `#id`) unless required
+
+## Cross-Browser Testing
+- Chromium (required)
+- Firefox (required)
+- WebKit (required)
+- Config in `playwright.config.ts` projects section
+
+## Test Data Convention
+- **Hardcoded values**: Directly in test
+- **Credentials**: `getCredentials()` → password from process.env
+- **Environment data**: `loadTestData()` → from test-data.{env}.json
+- **NEVER** hardcode passwords/tokens
+
+## Run Tests
+```bash
+# Run all func tests for feature
+yarn functest:web:{feature-slug}
+
+# Run only one story
+npx playwright test e2e/features/{epic}/{feature}/{story}
+
+# Run with specific browser
+npx playwright test --project=firefox e2e/features/{epic}/{feature}
+
+# Run with debug UI
+npx playwright test --ui e2e/features/{epic}/{feature}
+```
+
+## Principles
+- Script MUST be runnable directly from CLI
+- Each describe block uses full FT ID
+- Helpers MUST export for Layer 3 reuse
+- DO NOT import from Layer 3 (flows/)
+- If apps/web/ doesn't exist → graceful error, DO NOT create
+- Tests must work on all viewports (mobile, tablet, desktop)

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

@@ -0,0 +1,76 @@
+# /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`

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

@@ -0,0 +1,17 @@
+# /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/
+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

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

@@ -0,0 +1,198 @@
+# /tas-plan $ARGUMENTS
+
+Role: SE - Software Engineer
+Bridge between business (Story) and technical (code).
+Analyze Story, create technical plan, break tasks — before implementing.
+
+**Required output:** Technical Plan written to Story file + `plan_status: completed`.
+
+## Always / Ask / Never
+
+| | Action |
+|---|---|
+| **Always** | Read Story file before doing anything |
+| **Always** | Wait for user to approve plan before writing to Story |
+| **Always** | Write Technical Plan to Story file after approval |
+| **Ask** | When need to reference SAD/ADR — confirm with user before reading |
+| **Ask** | When Story scope > 8 hours — suggest splitting Story |
+| **Never** | Start implementing in this command |
+| **Never** | Read SAD/ADR without asking user first |
+| **Never** | Write plan to Story without approval |
+
+## Actions
+
+### Step 1 — Identify Story
+
+`$ARGUMENTS` can be: Story ID (`Story-005`), file path, or Story description.
+
+- If Story ID: find file via glob `docs/epics/**/*-Story-{ID}-*.md`
+- If file path: read directly
+- If description: ask user for specific Story ID/file
+- Read Story file
+
+**Check re-plan:** If `plan_status: completed` → ask user:
+> "This Story already has a Technical Plan. Do you want to re-plan?"
+If user confirms → continue. If not → stop.
+
+### Step 2 — Parallel Context Gathering
+
+Launch 2 agents SIMULTANEOUSLY:
+
+**Agent 1 — `code-explorer`** (always run):
+> Survey codebase related to Story: "{Story title + AC summary}".
+> Find: entry points, files likely to change, existing patterns, dependencies.
+> Read max 10 most relevant files.
+> Return: concise map — what exists, what needs to change, potential conflicts.
+
+**Agent 2 — `architect`** (only run if Story shows architectural changes:
+new service/module, data flow changes, external system integration,
+database schema changes, new design pattern):
+> Evaluate architectural implications of Story: "{Story title}".
+> Read `docs/sad.md` (if exists) and files in `docs/adr/`.
+> Read `.tas/rules/common/patterns.md`.
+> Return: which ADRs relate, patterns to follow, architectural risks, constraints.
+
+Wait for ALL agents to finish, synthesize findings.
+
+### Step 3 — Ask about SAD/ADR (if still unclear)
+
+After seeing agent findings, if need to reference specific SAD or ADR:
+> "I need to read [SAD / ADR-XXX] to clarify [reason]. OK?"
+
+Only read after user confirms.
+
+### Step 4 — API Design (if Story involves backend API)
+
+**If Story shows API design** (new endpoint, API contract change, exposing service):
+Read `.tas/rules/common/api-design.md` for REST API conventions, then design API Spec before planning:
+- URL structure, HTTP methods, status codes
+- Request/response payload shape
+- Pagination, filtering if needed
+- Error response format
+
+Attach API Spec to **Technical Plan → API Contract** section in Story.
+If Story not API-related → skip this step.
+
+### Step 5 — Technical Analysis
+
+Based on Story + agent findings, list clearly:
+
+**Files to change:**
+| File | What change | Why |
+
+**Files to create** (if any):
+| File | Purpose |
+
+**Database changes** (if any): migration, schema changes, seed data
+
+**Config/Infrastructure changes** (if any): env vars, feature flags, new dependencies
+
+**Need to update SAD?** Yes/No + brief reason
+
+**Need new ADR?** Yes/No + brief reason
+
+### Step 6 — Propose approach
+
+If multiple feasible approaches, list 2-3 options:
+```
+Option A: [short description]
+  + [pro]
+  - [con]
+
+Option B: [short description]
+  + [pro]
+  - [con]
+```
+Recommend best option and reason. If only 1 approach → present directly.
+
+### Step 7 — Break Tasks
+
+Break down into implementation-order tasks. Each task ~1-2 hours:
+```
+- [ ] Task 1: [specific action — which file, what change]
+- [ ] Task 2: [specific action]
+- [ ] Task 3: Write unit tests for [AC-1, AC-2...]
+- [ ] Task 4: [if needed] Create ADR / update SAD
+```
+
+If total estimate > 8 hours → suggest splitting Story before continuing.
+
+### Step 8 — Wait for approval
+
+**STOP.** Display entire plan and ask:
+> "Does the Technical Plan above look OK? Any adjustments?"
+
+- If user approves → Step 9
+- If user has feedback → update plan, ask again
+- DO NOT write anything to Story before approval
+
+### Step 9 — Write Technical Plan to Story
+
+After approval, update Story file:
+
+**1. Add section `## Technical Plan`** to Story (replace comment placeholder):
+
+```markdown
+## Technical Plan
+> **Plan by:** {SE name} | **Date:** {current date}
+
+### Approach
+{Brief description of chosen approach and reason}
+
+### Files to Change
+| File | Change | Reason |
+|------|--------|--------|
+
+### Files to Create
+| File | Purpose |
+|------|---------|
+
+### Database Changes
+{If none: "None"}
+
+### Config Changes
+{If none: "None"}
+
+### Architecture Notes
+- SAD update needed: Yes/No
+- New ADR needed: Yes/No — {title if Yes}
+
+### Tasks
+- [ ] Task 1: ...
+- [ ] Task 2: ...
+- [ ] Task 3: Write unit tests
+```
+
+**2. Update frontmatter:**
+- `plan_status: completed`
+- `plan_date: {current datetime}`
+
+**3. Update `project-status.yaml`:**
+- `last_updated: {current date}`
+- `epics.{EPIC_ID}.features.{FEATURE_ID}.stories.{STORY_ID}.plan_status: completed`
+
+**4. If ADR needed:** run `/tas-adr "{Decision title}"` immediately after writing plan.
+
+### Step 10 — Notify next step
+> "Technical Plan written to Story. SE can start implementing with `/tas-dev {Story-ID}`."
+
+---
+
+## Quick Mode (require_plan: false in tas.yaml)
+
+For: solo dev, prototype, spike, urgent hotfix.
+
+- `/tas-dev` will NOT require running `/tas-plan` first
+- `/tas-plan` can still be run voluntarily when Story is complex
+- Trade-off: higher speed, lower traceability
+
+## Principles
+- Technical Plan lives in Story file — no separate plan file
+- Each task ~1-2 hours; whole Story ~4-8 hours
+- If estimate > 8 hours → split Story
+- If task affects architecture → suggest ADR
+- Keep plan concise, actionable — don't write essays
+
+## Final Step — Token Log
+
+Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to working Story file.