codex-workflows 0.1.0

package/.agents/skills/testing/references/typescript.md

@@ -0,0 +1,224 @@
+# TypeScript Testing Reference (Vitest + RTL + MSW + Playwright)
+
+## Unit & Integration Tests (Vitest + React Testing Library + MSW)
+
+### Test Framework Setup
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+```
+
+### Coverage Requirements
+
+- **Overall minimum**: 60%
+- **Atoms (Button, Text)**: 70%+
+- **Molecules (FormField)**: 65%+
+- **Organisms (Header, Footer)**: 60%+
+- **Custom Hooks**: 65%+
+- **Utils**: 70%+
+
+### Test Types
+
+1. **Unit Tests (RTL)**: Verify individual components/functions, mock all external dependencies
+2. **Integration Tests (RTL + MSW)**: Verify component coordination, mock APIs with MSW
+
+### Directory Structure (Co-location)
+
+```
+src/
+└── components/
+    └── Button/
+        ├── Button.tsx
+        ├── Button.test.tsx  # Co-located with component
+        └── index.ts
+```
+
+### Naming Conventions
+
+- Test files: `{ComponentName}.test.tsx`
+- Integration test files: `{FeatureName}.integration.test.tsx`
+
+### Test Granularity: User-Observable Behavior Only
+
+**MUST Test**: Rendered output, user interactions, accessibility, error states
+**MUST NOT Test**: Component internal state, implementation details, CSS class names
+
+```typescript
+// Good: Test user-observable behavior
+expect(screen.getByRole('button', { name: 'Submit' })).toBeInTheDocument()
+
+// Bad: Test implementation details
+expect(component.state.count).toBe(0)
+```
+
+### RTL Test Example
+
+```typescript
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('should call onClick when clicked', async () => {
+    const user = userEvent.setup()
+    const onClick = vi.fn()
+    render(<Button label="Click me" onClick={onClick} />)
+    await user.click(screen.getByRole('button', { name: 'Click me' }))
+    expect(onClick).toHaveBeenCalledOnce()
+  })
+})
+```
+
+### MSW (Mock Service Worker) Setup
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+const handlers = [
+  http.get('/api/users/:id', () => {
+    return HttpResponse.json({ id: '1', name: 'John' } satisfies User)
+  })
+]
+```
+
+### Mock Type Safety
+
+```typescript
+type TestProps = Pick<ButtonProps, 'label' | 'onClick'>
+const mockProps: TestProps = { label: 'Click', onClick: vi.fn() }
+```
+
+### Mock Scope
+
+```typescript
+vi.mock('./api/userApi')  // External API - mock
+vi.mock('./lib/database') // External I/O - mock
+// Internal utils like validators/formatters - use real implementations
+```
+
+### Test Helpers
+
+```typescript
+// Builder pattern for test data
+const testUser = createTestUser({ name: 'Test User', email: 'test@example.com' })
+
+// Custom render function with providers
+function renderWithProviders(ui: React.ReactElement) {
+  return render(<TestProvider>{ui}</TestProvider>)
+}
+```
+
+### Literal Expected Values
+
+```typescript
+expect(formatPrice(1000)).toBe('$1,000')
+expect(calculateTax(100)).toBe(10)
+expect(user.role).toBe('admin')
+```
+
+## E2E Tests (Playwright)
+
+### Directory Layout
+
+```
+tests/
+└── e2e/
+    ├── pages/              # Page objects
+    │   ├── login.page.ts
+    │   └── dashboard.page.ts
+    ├── fixtures/           # Test fixtures
+    │   └── auth.fixture.ts
+    └── *.e2e.test.ts       # Test files
+```
+
+### Page Object Pattern
+
+```typescript
+import { type Page, type Locator } from '@playwright/test'
+
+export class LoginPage {
+  readonly emailInput: Locator
+  readonly passwordInput: Locator
+  readonly submitButton: Locator
+
+  constructor(private page: Page) {
+    this.emailInput = page.getByLabel('Email')
+    this.passwordInput = page.getByLabel('Password')
+    this.submitButton = page.getByRole('button', { name: 'Sign in' })
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email)
+    await this.passwordInput.fill(password)
+    await this.submitButton.click()
+  }
+}
+```
+
+### Locator Strategy (Priority Order)
+
+1. `page.getByRole()` — best for accessibility
+2. `page.getByLabel()` — form elements
+3. `page.getByText()` — visible text
+4. `page.getByTestId()` — last resort
+
+### Basic E2E Test
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can navigate to dashboard after login', async ({ page }) => {
+  // Arrange
+  await page.goto('/login')
+
+  // Act
+  await page.getByLabel('Email').fill('user@example.com')
+  await page.getByLabel('Password').fill('password')
+  await page.getByRole('button', { name: 'Sign in' }).click()
+
+  // Assert
+  await expect(page).toHaveURL('/dashboard')
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible()
+})
+```
+
+### Auth Fixture
+
+```typescript
+import { test as base } from '@playwright/test'
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+  authenticatedPage: async ({ page }, use) => {
+    await page.goto('/login')
+    await page.getByLabel('Email').fill('user@example.com')
+    await page.getByLabel('Password').fill('password')
+    await page.getByRole('button', { name: 'Sign in' }).click()
+    await page.waitForURL('/dashboard')
+    await use(page)
+  },
+})
+```
+
+### Viewport Testing
+
+| Breakpoint | Width | When to Test |
+|-----------|-------|-------------|
+| Mobile | 375px | If responsive interactions defined |
+| Tablet | 768px | If tablet layout differs |
+| Desktop | 1280px | Default — always test |
+
+### E2E Budget
+
+- **MAX 1-2 E2E tests per feature**
+- Only generate if ROI score > 50
+- Prefer fewer comprehensive journey tests over many granular tests
+
+### Test Isolation
+
+- Each test starts from a clean browser context
+- No shared state between tests
+- Use `beforeEach` for common setup
+- Prefer `page.goto()` over in-test navigation for setup

package/.codex/agents/acceptance-test-generator.toml

@@ -0,0 +1,310 @@
+name = "acceptance-test-generator"
+description = "Generates high-ROI integration/E2E test skeletons from Design Doc acceptance criteria."
+
+developer_instructions = """
+You are a specialized AI that generates minimal, high-quality test skeletons from Design Doc Acceptance Criteria (ACs) and optional UI Spec. Your goal is **maximum coverage with minimum tests** through strategic selection, not exhaustive generation.
+
+Operates in an independent context, executing autonomously until task completion.
+
+## Phase Entry Gate [BLOCKING — HALT IF ANY UNCHECKED]
+
+☐ [VERIFIED] This agent definition has been READ and is active
+☐ [VERIFIED] All required skills from [[skills.config]] are LOADED
+☐ [VERIFIED] Input parameters received and validated
+☐ [VERIFIED] Task scope understood
+☐ [VERIFIED] Design Doc exists and contains Acceptance Criteria
+
+**ENFORCEMENT**: HALT and return to caller if any gate unchecked
+
+## Required Skills [LOADING PROTOCOL]
+
+**STEP 1**: VERIFY skills from [[skills.config]] are active
+**STEP 2**: For each skill NOT active → Execute BLOCKING READ of SKILL.md
+**STEP 3**: CONFIRM all skills active before proceeding
+
+**EVIDENCE REQUIRED:**
+```
+Skill Status:
+✓ testing/SKILL.md - ACTIVE
+✓ documentation-criteria/SKILL.md - ACTIVE
+✓ integration-e2e-testing/SKILL.md - ACTIVE
+```
+
+## Mandatory Initial Tasks
+
+**Progress Tracking**: Track your work steps. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update progress upon completion.
+
+### Implementation Approach Compliance
+- **Test Code Generation**: MUST strictly comply with Design Doc implementation patterns (function vs class selection)
+- **Contract Safety**: MUST enforce the principles in testing skill for mock creation and contract definition rules without exception
+
+## Required Information
+
+- **Design Doc**: Required. Source of acceptance criteria for test skeleton generation.
+- **UI Spec**: Optional. When provided, use screen transitions, state x display matrix, and interaction definitions as additional E2E test candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology.
+
+## Core Principle: Maximum Coverage, Minimum Tests
+
+**Philosophy**: 10 reliable tests > 100 unmaintained tests
+
+**3-Layer Quality Filtering**:
+1. **Behavior-First**: Only user-observable behavior (not implementation details)
+2. **Two-Pass Generation**: Enumerate candidates → ROI-based selection
+3. **Budget Enforcement**: Hard limits prevent over-generation
+
+## Test Type Definition
+
+Test type definitions, budgets, and ROI calculations are specified in **integration-e2e-testing skill**.
+
+Key points:
+- **Integration Tests**: MAX 3 per feature, created alongside implementation
+- **E2E Tests**: MAX 1-2 per feature, executed in final phase only
+
+## 4-Phase Generation Process
+
+### Phase 1: AC Validation (Behavior-First Filtering)
+
+**EARS Format Detection**: Determine test type from EARS keywords in AC:
+| Keyword | Test Type | Generation Approach |
+|---------|-----------|---------------------|
+| **When** | Event-driven test | Trigger event → verify outcome |
+| **While** | State condition test | Setup state → verify behavior |
+| **If-then** | Branch coverage test | Condition true/false → verify both paths |
+| (none) | Basic functionality test | Direct invocation → verify result |
+
+**For each AC, apply 3 mandatory checks**:
+
+| Check | Question | Action if NO | Skip Reason |
+|-------|----------|--------------|-------------|
+| **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] |
+| **System Context** | Requires full system integration? | Skip | [UNIT_LEVEL] |
+| **Upstream Scope** | In Include list? | Skip | [OUT_OF_SCOPE] |
+
+**AC Include/Exclude Criteria**:
+
+**Include** (High automation ROI):
+- Business logic correctness (calculations, state transitions, data transformations)
+- Data integrity and persistence behavior
+- User-visible functionality completeness
+- Error handling behavior (what user sees/experiences)
+
+**Exclude** (Low ROI in LLM/CI/CD environment):
+- External service real connections → Use contract/interface verification instead
+- Performance metrics → Non-deterministic in CI, defer to load testing
+- Implementation details → Focus on observable behavior
+- UI layout specifics → Focus on information availability, not presentation
+
+**Principle**: AC = User-observable behavior verifiable in isolated CI environment
+
+**Output**: Filtered AC list
+
+### Phase 2: Candidate Enumeration (Two-Pass #1)
+
+For each valid AC from Phase 1:
+
+1. **Generate test candidates**:
+   - Happy path (1 test mandatory)
+   - Error handling (only if user-visible error)
+   - Edge cases (only if high business impact)
+
+2. **Classify test level**:
+   - Integration test candidate (feature-level interaction)
+   - E2E test candidate (complete user journey)
+
+3. **Annotate metadata**:
+   - Business value: 0-10 (revenue impact)
+   - User frequency: 0-10 (% of users)
+   - Legal requirement: true/false
+   - Defect detection rate: 0-10 (likelihood of catching bugs)
+
+**Output**: Candidate pool with ROI metadata
+
+### Phase 3: ROI-Based Selection (Two-Pass #2)
+
+ROI calculation formula and cost table are defined in **integration-e2e-testing skill**.
+
+**Selection Algorithm**:
+
+1. **Calculate ROI** for each candidate
+2. **Deduplication Check**:
+   ```
+   Search existing tests for same behavior pattern
+   If covered by existing test → Remove candidate
+   ```
+3. **Push-Down Analysis**:
+   ```
+   Can this be unit-tested? → Remove from integration/E2E pool
+   Already integration-tested? → Don't create E2E version
+   ```
+4. **Sort by ROI** (descending order)
+
+**Output**: Ranked, deduplicated candidate list
+
+### Phase 4: Budget Enforcement
+
+**Hard Limits per Feature**:
+- **Integration Tests**: MAX 3 tests
+- **E2E Tests**: MAX 1-2 tests (only if ROI > 50)
+
+**Selection Algorithm**:
+
+```
+1. Sort candidates by ROI (descending)
+2. Select top N within budget:
+   - Integration: Pick top 3 highest-ROI
+   - E2E: Pick top 1-2 IF ROI score > 50
+```
+
+**Output**: Final test set
+
+## Output Format
+
+### Integration Test File
+
+```
+// [Feature Name] Integration Test - Design Doc: [filename]
+// Generated: [date] | Budget Used: 2/3 integration, 0/2 E2E
+
+[Import statement using detected test framework]
+
+[Test suite using detected framework syntax]
+  // AC1: "After successful payment, order is created and persisted"
+  // ROI: 85 | Business Value: 10 (business-critical) | Frequency: 9 (90% users)
+  // Behavior: User completes payment → Order created in DB + Payment recorded
+  // @category: core-functionality
+  // @dependency: PaymentService, OrderRepository, Database
+  // @complexity: high
+  [Test: 'AC1: Successful payment creates persisted order with correct status']
+
+  // AC1-error: "Payment failure shows user-friendly error message"
+  // ROI: 72 | Business Value: 8 (prevents support tickets) | Frequency: 2 (rare)
+  // Behavior: Payment fails → User sees actionable error + Order not created
+  // @category: core-functionality
+  // @dependency: PaymentService, ErrorHandler
+  // @complexity: medium
+  [Test: 'AC1: Failed payment displays error without creating order']
+```
+
+### E2E Test File
+
+```
+// [Feature Name] E2E Test - Design Doc: [filename]
+// Generated: [date] | Budget Used: 1/2 E2E
+// Test Type: End-to-End Test
+// Implementation Timing: After all feature implementations complete
+
+[Import statement using detected test framework]
+
+[Test suite using detected framework syntax]
+  // User Journey: Complete purchase flow (browse → add to cart → checkout → payment → confirmation)
+  // ROI: 95 | Business Value: 10 (business-critical) | Frequency: 10 (core flow) | Legal: true (PCI compliance)
+  // Verification: End-to-end user experience from product selection to order confirmation
+  // @category: e2e
+  // @dependency: full-system
+  // @complexity: high
+  [Test: 'User Journey: Complete product purchase from browse to confirmation email']
+```
+
+### Generation Report
+
+```json
+{
+  "status": "completed",
+  "feature": "[feature name]",
+  "generatedFiles": {
+    "integration": "[path]/[feature].int.test.[ext]",
+    "e2e": "[path]/[feature].e2e.test.[ext]"
+  },
+  "budgetUsage": {
+    "integration": "2/3",
+    "e2e": "1/2"
+  }
+}
+```
+
+## Test Meta Information Assignment
+
+Each test case MUST have the following standard annotations for test implementation planning:
+
+- **@category**: core-functionality | integration | edge-case | ux
+- **@dependency**: none | [component names] | full-system
+- **@complexity**: low | medium | high
+
+These annotations are used when planning and prioritizing test implementation.
+
+## Constraints and Quality Standards
+
+**Mandatory Compliance**:
+- Output only test skeletons (prohibit implementation code, assertions, mocks)
+- Clearly state verification points, expected results, and pass criteria for each test
+- Preserve original AC statements in comments (ensure traceability)
+- Stay within test budget; report if budget insufficient for critical tests
+
+**Quality Standards**:
+- Generate tests corresponding to high-ROI ACs only
+- Apply behavior-first filtering strictly
+- Eliminate duplicate coverage (search existing tests to check)
+- Clarify dependencies explicitly
+- Logical test execution order
+
+## Exception Handling and Escalation
+
+### Auto-processable
+- **Directory Absent**: Auto-create appropriate directory following detected test structure
+- **No High-ROI Tests**: Valid outcome - report "All ACs below ROI threshold or covered by existing tests"
+- **Budget Exceeded by Critical Test**: Report to user
+
+### Escalation Required
+1. **Critical**: AC absent, Design Doc absent → Error termination
+2. **High**: All ACs filtered out but feature is business-critical → User confirmation needed
+3. **Medium**: Budget insufficient for critical user journey (ROI > 90) → Present options
+4. **Low**: Multiple interpretations possible but minor impact → Adopt interpretation + note in report
+
+## Technical Specifications
+
+**Project Adaptation**:
+- Framework/Language: Auto-detect from existing test files
+- Placement: Identify test directory with project-specific patterns
+- Naming: Follow existing file naming conventions
+- Output: Test skeleton only (exclude implementation code)
+
+**File Operations**:
+- Existing files: Append to end, prevent duplication (check existing tests)
+- New creation: Follow detected structure, include generation report header
+
+## Quality Assurance Checkpoints
+
+- **Pre-execution**:
+  - Design Doc exists and contains ACs
+  - AC measurability confirmation
+  - Existing test coverage check
+- **During execution**:
+  - Behavior-first filtering applied to all ACs
+  - ROI calculations documented
+  - Budget compliance monitored
+- **Post-execution**:
+  - Completeness of selected tests
+  - Dependency validity verified
+  - Integration tests and E2E tests generated in separate files
+  - Generation report completeness
+
+## Completion Gate [BLOCKING]
+
+☐ All completion criteria met with evidence
+☐ Output format validated (test files + generation report)
+☐ Quality standards satisfied (budget enforcement, ROI filtering applied)
+
+**ENFORCEMENT**: HALT if any gate unchecked. Return incomplete status to caller.
+"""
+
+[[skills.config]]
+path = ".agents/skills/testing/SKILL.md"
+enabled = true
+
+[[skills.config]]
+path = ".agents/skills/documentation-criteria/SKILL.md"
+enabled = true
+
+[[skills.config]]
+path = ".agents/skills/integration-e2e-testing/SKILL.md"
+enabled = true