aw-ecc 1.4.21

package/commands/e2e.md

@@ -0,0 +1,373 @@
+---
+description: Generate and run end-to-end tests with Playwright. Creates test journeys, runs tests, captures screenshots/videos/traces, and uploads artifacts.
+---
+
+# E2E Command
+
+This command invokes the **e2e-runner** agent to generate, maintain, and execute end-to-end tests using Playwright.
+
+## What This Command Does
+
+1. **Generate Test Journeys** - Create Playwright tests for user flows
+2. **Run E2E Tests** - Execute tests across browsers
+3. **Capture Artifacts** - Screenshots, videos, traces on failures
+4. **Upload Results** - HTML reports and JUnit XML
+5. **Identify Flaky Tests** - Quarantine unstable tests
+
+## When to Use
+
+Use `/aw:e2e` when:
+- Testing critical user journeys (login, trading, payments)
+- Verifying multi-step flows work end-to-end
+- Testing UI interactions and navigation
+- Validating integration between frontend and backend
+- Preparing for production deployment
+
+## How It Works
+
+The e2e-runner agent will:
+
+1. **Analyze user flow** and identify test scenarios
+2. **Generate Playwright test** using Page Object Model pattern
+3. **Run tests** across multiple browsers (Chrome, Firefox, Safari)
+4. **Capture failures** with screenshots, videos, and traces
+5. **Generate report** with results and artifacts
+6. **Identify flaky tests** and recommend fixes
+
+## Example Usage
+
+```
+User: /aw:e2e Test the market search and view flow
+
+Agent (e2e-runner):
+# E2E Test Generation: Market Search and View Flow
+
+## Test Scenario Identified
+
+**User Journey:** Market Search → View Results → Click Market → View Details
+
+**Test Coverage:**
+1. Navigate to markets page
+2. Perform semantic search
+3. Verify search results
+4. Click on first result
+5. Verify market details page loads
+6. Verify chart renders
+
+## Generated Test Code
+
+```typescript
+// tests/e2e/markets/search-and-view.spec.ts
+import { test, expect } from '@playwright/test'
+import { MarketsPage } from '../../pages/MarketsPage'
+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
+
+test.describe('Market Search and View Flow', () => {
+  test('user can search markets and view details', async ({ page }) => {
+    // 1. Navigate to markets page
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Verify page loaded
+    await expect(page).toHaveTitle(/Markets/)
+    await expect(page.locator('h1')).toContainText('Markets')
+
+    // 2. Perform semantic search
+    await marketsPage.searchMarkets('election')
+
+    // Wait for API response
+    await page.waitForResponse(resp =>
+      resp.url().includes('/api/markets/search') && resp.status() === 200
+    )
+
+    // 3. Verify search results
+    const marketCards = marketsPage.marketCards
+    await expect(marketCards.first()).toBeVisible()
+    const resultCount = await marketCards.count()
+    expect(resultCount).toBeGreaterThan(0)
+
+    // Take screenshot of search results
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+
+    // 4. Click on first result
+    const firstMarketTitle = await marketCards.first().textContent()
+    await marketCards.first().click()
+
+    // 5. Verify market details page loads
+    await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
+
+    const detailsPage = new MarketDetailsPage(page)
+    await expect(detailsPage.marketName).toBeVisible()
+    await expect(detailsPage.marketDescription).toBeVisible()
+
+    // 6. Verify chart renders
+    await expect(detailsPage.priceChart).toBeVisible()
+
+    // Verify market name matches
+    const detailsTitle = await detailsPage.marketName.textContent()
+    expect(detailsTitle?.toLowerCase()).toContain(
+      firstMarketTitle?.toLowerCase().substring(0, 20) || ''
+    )
+
+    // Take screenshot of market details
+    await page.screenshot({ path: 'artifacts/market-details.png' })
+  })
+
+  test('search with no results shows empty state', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Search for non-existent market
+    await marketsPage.searchMarkets('xyznonexistentmarket123456')
+
+    // Verify empty state
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    await expect(page.locator('[data-testid="no-results"]')).toContainText(
+      /no.*results|no.*markets/i
+    )
+
+    const marketCount = await marketsPage.marketCards.count()
+    expect(marketCount).toBe(0)
+  })
+
+  test('can clear search and see all markets again', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Initial market count
+    const initialCount = await marketsPage.marketCards.count()
+
+    // Perform search
+    await marketsPage.searchMarkets('trump')
+    await page.waitForLoadState('networkidle')
+
+    // Verify filtered results
+    const filteredCount = await marketsPage.marketCards.count()
+    expect(filteredCount).toBeLessThan(initialCount)
+
+    // Clear search
+    await marketsPage.searchInput.clear()
+    await page.waitForLoadState('networkidle')
+
+    // Verify all markets shown again
+    const finalCount = await marketsPage.marketCards.count()
+    expect(finalCount).toBe(initialCount)
+  })
+})
+```
+
+## Running Tests
+
+```bash
+# Run the generated test
+npx playwright test tests/e2e/markets/search-and-view.spec.ts
+
+Running 3 tests using 3 workers
+
+  ✓  [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
+  ✓  [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
+  ✓  [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
+
+  3 passed (9.1s)
+
+Artifacts generated:
+- artifacts/search-results.png
+- artifacts/market-details.png
+- playwright-report/index.html
+```
+
+## Test Report
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    E2E Test Results                          ║
+╠══════════════════════════════════════════════════════════════╣
+║ Status:     ✅ ALL TESTS PASSED                              ║
+║ Total:      3 tests                                          ║
+║ Passed:     3 (100%)                                         ║
+║ Failed:     0                                                ║
+║ Flaky:      0                                                ║
+║ Duration:   9.1s                                             ║
+╚══════════════════════════════════════════════════════════════╝
+
+Artifacts:
+📸 Screenshots: 2 files
+📹 Videos: 0 files (only on failure)
+🔍 Traces: 0 files (only on failure)
+📊 HTML Report: playwright-report/index.html
+
+View report: npx playwright show-report
+```
+
+✅ E2E test suite ready for CI/CD integration!
+```
+
+## Test Artifacts
+
+When tests run, the following artifacts are captured:
+
+**On All Tests:**
+- HTML Report with timeline and results
+- JUnit XML for CI integration
+
+**On Failure Only:**
+- Screenshot of the failing state
+- Video recording of the test
+- Trace file for debugging (step-by-step replay)
+- Network logs
+- Console logs
+
+## Viewing Artifacts
+
+```bash
+# View HTML report in browser
+npx playwright show-report
+
+# View specific trace file
+npx playwright show-trace artifacts/trace-abc123.zip
+
+# Screenshots are saved in artifacts/ directory
+open artifacts/search-results.png
+```
+
+## Flaky Test Detection
+
+If a test fails intermittently:
+
+```
+⚠️  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
+
+Test passed 7/10 runs (70% pass rate)
+
+Common failure:
+"Timeout waiting for element '[data-testid="confirm-btn"]'"
+
+Recommended fixes:
+1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
+2. Increase timeout: { timeout: 10000 }
+3. Check for race conditions in component
+4. Verify element is not hidden by animation
+
+Quarantine recommendation: Mark as test.fixme() until fixed
+```
+
+## Browser Configuration
+
+Tests run on multiple browsers by default:
+- ✅ Chromium (Desktop Chrome)
+- ✅ Firefox (Desktop)
+- ✅ WebKit (Desktop Safari)
+- ✅ Mobile Chrome (optional)
+
+Configure in `playwright.config.ts` to adjust browsers.
+
+## CI/CD Integration
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/e2e.yml
+- name: Install Playwright
+  run: npx playwright install --with-deps
+
+- name: Run E2E tests
+  run: npx playwright test
+
+- name: Upload artifacts
+  if: always()
+  uses: actions/upload-artifact@v3
+  with:
+    name: playwright-report
+    path: playwright-report/
+```
+
+## PMX-Specific Critical Flows
+
+For PMX, prioritize these E2E tests:
+
+**🔴 CRITICAL (Must Always Pass):**
+1. User can connect wallet
+2. User can browse markets
+3. User can search markets (semantic search)
+4. User can view market details
+5. User can place trade (with test funds)
+6. Market resolves correctly
+7. User can withdraw funds
+
+**🟡 IMPORTANT:**
+1. Market creation flow
+2. User profile updates
+3. Real-time price updates
+4. Chart rendering
+5. Filter and sort markets
+6. Mobile responsive layout
+
+## Best Practices
+
+**DO:**
+- ✅ Use Page Object Model for maintainability
+- ✅ Use data-testid attributes for selectors
+- ✅ Wait for API responses, not arbitrary timeouts
+- ✅ Test critical user journeys end-to-end
+- ✅ Run tests before merging to main
+- ✅ Review artifacts when tests fail
+
+**DON'T:**
+- ❌ Use brittle selectors (CSS classes can change)
+- ❌ Test implementation details
+- ❌ Run tests against production
+- ❌ Ignore flaky tests
+- ❌ Skip artifact review on failures
+- ❌ Test every edge case with E2E (use unit tests)
+
+## Important Notes
+
+**CRITICAL for PMX:**
+- E2E tests involving real money MUST run on testnet/staging only
+- Never run trading tests against production
+- Set `test.skip(process.env.NODE_ENV === 'production')` for financial tests
+- Use test wallets with small test funds only
+
+## Integration with Other Commands
+
+- Use `/aw:plan` to identify critical journeys to test
+- Use `/aw:tdd` for unit tests (faster, more granular)
+- Use `/aw:e2e` for integration and user journey tests
+- Use `/aw:code-review` to verify test quality
+
+## Related Agents
+
+This command invokes the `e2e-runner` agent provided by ECC.
+
+For manual installs, the source file lives at:
+`agents/e2e-runner.md`
+
+## Quick Commands
+
+```bash
+# Run all E2E tests
+npx playwright test
+
+# Run specific test file
+npx playwright test tests/e2e/markets/search.spec.ts
+
+# Run in headed mode (see browser)
+npx playwright test --headed
+
+# Debug test
+npx playwright test --debug
+
+# Generate test code
+npx playwright codegen http://localhost:3000
+
+# View report
+npx playwright show-report
+```
+
+---
+
+## GHL Platform Integration
+
+Also activate the matching `platform-sdet-*` agent.
+Also activate the matching platform domain family resolved by `using-aw-skills`.
+For ALL activated agents: read frontmatter → load each skill from `skills:` array.

package/commands/eval.md

@@ -0,0 +1,120 @@
+# Eval Command
+
+Manage eval-driven development workflow.
+
+## Usage
+
+`/eval [define|check|report|list] [feature-name]`
+
+## Define Evals
+
+`/eval define feature-name`
+
+Create a new eval definition:
+
+1. Create `.claude/evals/feature-name.md` with template:
+
+```markdown
+## EVAL: feature-name
+Created: $(date)
+
+### Capability Evals
+- [ ] [Description of capability 1]
+- [ ] [Description of capability 2]
+
+### Regression Evals
+- [ ] [Existing behavior 1 still works]
+- [ ] [Existing behavior 2 still works]
+
+### Success Criteria
+- pass@3 > 90% for capability evals
+- pass^3 = 100% for regression evals
+```
+
+2. Prompt user to fill in specific criteria
+
+## Check Evals
+
+`/eval check feature-name`
+
+Run evals for a feature:
+
+1. Read eval definition from `.claude/evals/feature-name.md`
+2. For each capability eval:
+   - Attempt to verify criterion
+   - Record PASS/FAIL
+   - Log attempt in `.claude/evals/feature-name.log`
+3. For each regression eval:
+   - Run relevant tests
+   - Compare against baseline
+   - Record PASS/FAIL
+4. Report current status:
+
+```
+EVAL CHECK: feature-name
+========================
+Capability: X/Y passing
+Regression: X/Y passing
+Status: IN PROGRESS / READY
+```
+
+## Report Evals
+
+`/eval report feature-name`
+
+Generate comprehensive eval report:
+
+```
+EVAL REPORT: feature-name
+=========================
+Generated: $(date)
+
+CAPABILITY EVALS
+----------------
+[eval-1]: PASS (pass@1)
+[eval-2]: PASS (pass@2) - required retry
+[eval-3]: FAIL - see notes
+
+REGRESSION EVALS
+----------------
+[test-1]: PASS
+[test-2]: PASS
+[test-3]: PASS
+
+METRICS
+-------
+Capability pass@1: 67%
+Capability pass@3: 100%
+Regression pass^3: 100%
+
+NOTES
+-----
+[Any issues, edge cases, or observations]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## List Evals
+
+`/eval list`
+
+Show all eval definitions:
+
+```
+EVAL DEFINITIONS
+================
+feature-auth      [3/5 passing] IN PROGRESS
+feature-search    [5/5 passing] READY
+feature-export    [0/4 passing] NOT STARTED
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `define <name>` - Create new eval definition
+- `check <name>` - Run and check evals
+- `report <name>` - Generate full report
+- `list` - Show all evals
+- `clean` - Remove old eval logs (keeps last 10 runs)

package/commands/evolve.md

@@ -0,0 +1,178 @@
+---
+name: evolve
+description: Analyze instincts and suggest or generate evolved structures
+command: true
+---
+
+# Evolve Command
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve [--generate]
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [--generate]
+```
+
+Analyzes instincts and clusters related ones into higher-level structures:
+- **Commands**: When instincts describe user-invoked actions
+- **Skills**: When instincts describe auto-triggered behaviors
+- **Agents**: When instincts describe complex, multi-step processes
+
+## Usage
+
+```
+/evolve                    # Analyze all instincts and suggest evolutions
+/evolve --generate         # Also generate files under evolved/{skills,commands,agents}
+```
+
+## Evolution Rules
+
+### → Command (User-Invoked)
+When instincts describe actions a user would explicitly request:
+- Multiple instincts about "when user asks to..."
+- Instincts with triggers like "when creating a new X"
+- Instincts that follow a repeatable sequence
+
+Example:
+- `new-table-step1`: "when adding a database table, create migration"
+- `new-table-step2`: "when adding a database table, update schema"
+- `new-table-step3`: "when adding a database table, regenerate types"
+
+→ Creates: **new-table** command
+
+### → Skill (Auto-Triggered)
+When instincts describe behaviors that should happen automatically:
+- Pattern-matching triggers
+- Error handling responses
+- Code style enforcement
+
+Example:
+- `prefer-functional`: "when writing functions, prefer functional style"
+- `use-immutable`: "when modifying state, use immutable patterns"
+- `avoid-classes`: "when designing modules, avoid class-based design"
+
+→ Creates: `functional-patterns` skill
+
+### → Agent (Needs Depth/Isolation)
+When instincts describe complex, multi-step processes that benefit from isolation:
+- Debugging workflows
+- Refactoring sequences
+- Research tasks
+
+Example:
+- `debug-step1`: "when debugging, first check logs"
+- `debug-step2`: "when debugging, isolate the failing component"
+- `debug-step3`: "when debugging, create minimal reproduction"
+- `debug-step4`: "when debugging, verify fix with test"
+
+→ Creates: **debugger** agent
+
+## What to Do
+
+1. Detect current project context
+2. Read project + global instincts (project takes precedence on ID conflicts)
+3. Group instincts by trigger/domain patterns
+4. Identify:
+   - Skill candidates (trigger clusters with 2+ instincts)
+   - Command candidates (high-confidence workflow instincts)
+   - Agent candidates (larger, high-confidence clusters)
+5. Show promotion candidates (project -> global) when applicable
+6. If `--generate` is passed, write files to:
+   - Project scope: `~/.claude/homunculus/projects/<project-id>/evolved/`
+   - Global fallback: `~/.claude/homunculus/evolved/`
+
+## Output Format
+
+```
+============================================================
+  EVOLVE ANALYSIS - 12 instincts
+  Project: my-app (a1b2c3d4e5f6)
+  Project-scoped: 8 | Global: 4
+============================================================
+
+High confidence instincts (>=80%): 5
+
+## SKILL CANDIDATES
+1. Cluster: "adding tests"
+   Instincts: 3
+   Avg confidence: 82%
+   Domains: testing
+   Scopes: project
+
+## COMMAND CANDIDATES (2)
+  /adding-tests
+    From: test-first-workflow [project]
+    Confidence: 84%
+
+## AGENT CANDIDATES (1)
+  adding-tests-agent
+    Covers 3 instincts
+    Avg confidence: 82%
+```
+
+## Flags
+
+- `--generate`: Generate evolved files in addition to analysis output
+
+## Generated File Format
+
+### Command
+```markdown
+---
+name: new-table
+description: Create a new database table with migration, schema update, and type generation
+command: /new-table
+evolved_from:
+  - new-table-migration
+  - update-schema
+  - regenerate-types
+---
+
+# New Table Command
+
+[Generated content based on clustered instincts]
+
+## Steps
+1. ...
+2. ...
+```
+
+### Skill
+```markdown
+---
+name: functional-patterns
+description: Enforce functional programming patterns
+evolved_from:
+  - prefer-functional
+  - use-immutable
+  - avoid-classes
+---
+
+# Functional Patterns Skill
+
+[Generated content based on clustered instincts]
+```
+
+### Agent
+```markdown
+---
+name: debugger
+description: Systematic debugging agent
+model: sonnet
+evolved_from:
+  - debug-check-logs
+  - debug-isolate
+  - debug-reproduce
+---
+
+# Debugger Agent
+
+[Generated content based on clustered instincts]
+```

package/commands/execute.md

@@ -0,0 +1,51 @@
+---
+name: aw:execute
+description: Compatibility entrypoint for the old implementation stage. Route to aw:build and keep the same artifact discipline.
+argument-hint: "<approved plan, spec, task, or implementation request>"
+status: active
+stage: compatibility
+internal_skill: aw-build
+---
+
+# Execute
+
+Use `/aw:execute` only as a compatibility entrypoint.
+The canonical implementation stage is `/aw:build`.
+
+## Role
+
+Preserve legacy muscle memory while routing to the modern build contract.
+Do not introduce a second implementation workflow.
+This entrypoint inherits the same rule that build should finish the approved build scope or block explicitly before handing off.
+
+## Routing Rule
+
+- approved implementation work -> follow `/aw:build`
+- bugfixes with unclear root cause -> prefer `/aw:investigate` first, then return to `/aw:build`
+- old `/aw:tdd` expectations -> stay inside `/aw:build` and its RED-GREEN discipline
+
+## Outputs
+
+- implementation changes
+- `.aw_docs/features/<feature_slug>/execution.md`
+- updated `.aw_docs/features/<feature_slug>/state.json`
+
+## Must Not Do
+
+- must not drift into a separate execute-only workflow
+- must not bypass the newer build, test, review, deploy, and ship stage definitions
+
+## Recommended Next Commands
+
+- `/aw:test`
+- `/aw:review`
+
+## Final Output Shape
+
+Always end with:
+
+- `Compatibility Route`
+- `Canonical Stage`
+- `Changes`
+- `Validation`
+- `Next`