agent-configs 1.0.0

package/commands/build-fix.md

@@ -0,0 +1,29 @@
+# Build and Fix
+
+Incrementally fix TypeScript and build errors:
+
+1. Run build: npm run build or pnpm build
+
+2. Parse error output:
+   - Group by file
+   - Sort by severity
+
+3. For each error:
+   - Show error context (5 lines before/after)
+   - Explain the issue
+   - Propose fix
+   - Apply fix
+   - Re-run build
+   - Verify error resolved
+
+4. Stop if:
+   - Fix introduces new errors
+   - Same error persists after 3 attempts
+   - User requests pause
+
+5. Show summary:
+   - Errors fixed
+   - Errors remaining
+   - New errors introduced
+
+Fix one error at a time for safety!

package/commands/code-review.md

@@ -0,0 +1,40 @@
+# Code Review
+
+Comprehensive security and quality review of uncommitted changes:
+
+1. Get changed files: git diff --name-only HEAD
+
+2. For each changed file, check for:
+
+**Security Issues (CRITICAL):**
+- Hardcoded credentials, API keys, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities  
+- Missing input validation
+- Insecure dependencies
+- Path traversal risks
+
+**Code Quality (HIGH):**
+- Functions > 50 lines
+- Files > 800 lines
+- Nesting depth > 4 levels
+- Missing error handling
+- console.log statements
+- TODO/FIXME comments
+- Missing JSDoc for public APIs
+
+**Best Practices (MEDIUM):**
+- Mutation patterns (use immutable instead)
+- Emoji usage in code/comments
+- Missing tests for new code
+- Accessibility issues (a11y)
+
+3. Generate report with:
+   - Severity: CRITICAL, HIGH, MEDIUM, LOW
+   - File location and line numbers
+   - Issue description
+   - Suggested fix
+
+4. Block commit if CRITICAL or HIGH issues found
+
+Never approve code with security vulnerabilities!

package/commands/e2e.md

@@ -0,0 +1,363 @@
+---
+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 `/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: /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 `/plan` to identify critical journeys to test
+- Use `/tdd` for unit tests (faster, more granular)
+- Use `/e2e` for integration and user journey tests
+- Use `/code-review` to verify test quality
+
+## Related Agents
+
+This command invokes the `e2e-runner` agent located at:
+`~/.claude/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
+```

package/commands/learn.md

@@ -0,0 +1,114 @@
+# /learn - 提取可复用的 Patterns
+
+分析当前会话，提取值得保存为 skills 或 instincts 的 patterns。
+
+## 触发
+
+在会话中任意时刻运行 `/learn`，当你解决了一个非平凡的问题时。
+
+## 要提取的内容
+
+寻找以下类型的 patterns：
+
+### 1. 错误解决模式
+- 遇到了什么错误？
+- 根本原因是什么？
+- 如何修复的？
+- 这个方案是否可复用于类似错误？
+
+### 2. 调试技巧
+- 非显而易见的调试步骤
+- 有效的工具组合
+- 诊断模式
+
+### 3. 变通方案
+- 库的特殊行为
+- API 限制
+- 版本特定的修复
+
+### 4. 项目特定模式
+- 发现的代码库约定
+- 做出的架构决策
+- 集成模式
+
+## 输出格式
+
+### v1: Learned Skill
+
+创建 skill 文件到 `~/.claude/skills/learned/[pattern-name].md`：
+
+```markdown
+# [描述性的 Pattern 名称]
+
+**Extracted:** [日期]
+**Context:** [适用场景简述]
+
+## Problem
+[这个 pattern 解决什么问题 - 要具体]
+
+## Solution
+[pattern/技巧/变通方案]
+
+## Example
+[如果适用，代码示例]
+
+## When to Use
+[触发条件 - 什么情况应该激活这个 skill]
+```
+
+### v2: Instinct (高级)
+
+创建 instinct 文件到 `~/.claude/homunculus/instincts/personal/[id].md`：
+
+```markdown
+---
+id: [pattern-id]
+trigger: "[触发条件]"
+confidence: 0.5
+domain: "[domain: code-style, testing, git, debugging, workflow]"
+source: "session-observation"
+---
+
+# [Pattern 名称]
+
+## Action
+[应该采取的行动]
+
+## Evidence
+- [支持这个 pattern 的证据]
+```
+
+## 处理流程
+
+1. 回顾会话，寻找可提取的 patterns
+2. 识别最有价值/可复用的洞见
+3. 询问用户偏好（skill 或 instinct）
+4. 起草对应文件
+5. 询问用户确认后保存
+
+## 注意事项
+
+- **不要**提取简单问题（拼写错误、简单语法错误）
+- **不要**提取一次性问题（特定 API 故障等）
+- **聚焦**于能在未来会话中节省时间的 patterns
+- **保持聚焦** - 每个 skill/instinct 只包含一个 pattern
+
+## v1 vs v2 对比
+
+| 特性 | Skill (v1) | Instinct (v2) |
+|------|------------|---------------|
+| 粒度 | 完整 pattern | 原子行为 |
+| 置信度 | 无 | 0.3-0.9 |
+| 进化 | 直接使用 | 可聚合为 skill/command/agent |
+| 存储位置 | `~/.claude/skills/learned/` | `~/.claude/homunculus/instincts/` |
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `/instinct-status` | 查看已学习的 instincts |
+| `/evolve` | 将相关 instincts 进化为更高级结构 |
+
+## 完整功能
+
+如需使用完整的持续学习功能，请参考 `bundles/continuous-learning/` bundle。

package/commands/plan.md

@@ -0,0 +1,113 @@
+---
+description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
+---
+
+# Plan Command
+
+This command invokes the **planner** agent to create a comprehensive implementation plan before writing any code.
+
+## What This Command Does
+
+1. **Restate Requirements** - Clarify what needs to be built
+2. **Identify Risks** - Surface potential issues and blockers
+3. **Create Step Plan** - Break down implementation into phases
+4. **Wait for Confirmation** - MUST receive user approval before proceeding
+
+## When to Use
+
+Use `/plan` when:
+- Starting a new feature
+- Making significant architectural changes
+- Working on complex refactoring
+- Multiple files/components will be affected
+- Requirements are unclear or ambiguous
+
+## How It Works
+
+The planner agent will:
+
+1. **Analyze the request** and restate requirements in clear terms
+2. **Break down into phases** with specific, actionable steps
+3. **Identify dependencies** between components
+4. **Assess risks** and potential blockers
+5. **Estimate complexity** (High/Medium/Low)
+6. **Present the plan** and WAIT for your explicit confirmation
+
+## Example Usage
+
+```
+User: /plan I need to add real-time notifications when markets resolve
+
+Agent (planner):
+# Implementation Plan: Real-Time Market Resolution Notifications
+
+## Requirements Restatement
+- Send notifications to users when markets they're watching resolve
+- Support multiple notification channels (in-app, email, webhook)
+- Ensure notifications are delivered reliably
+- Include market outcome and user's position result
+
+## Implementation Phases
+
+### Phase 1: Database Schema
+- Add notifications table with columns: id, user_id, market_id, type, status, created_at
+- Add user_notification_preferences table for channel preferences
+- Create indexes on user_id and market_id for performance
+
+### Phase 2: Notification Service
+- Create notification service in lib/notifications.ts
+- Implement notification queue using BullMQ/Redis
+- Add retry logic for failed deliveries
+- Create notification templates
+
+### Phase 3: Integration Points
+- Hook into market resolution logic (when status changes to "resolved")
+- Query all users with positions in market
+- Enqueue notifications for each user
+
+### Phase 4: Frontend Components
+- Create NotificationBell component in header
+- Add NotificationList modal
+- Implement real-time updates via Supabase subscriptions
+- Add notification preferences page
+
+## Dependencies
+- Redis (for queue)
+- Email service (SendGrid/Resend)
+- Supabase real-time subscriptions
+
+## Risks
+- HIGH: Email deliverability (SPF/DKIM required)
+- MEDIUM: Performance with 1000+ users per market
+- MEDIUM: Notification spam if markets resolve frequently
+- LOW: Real-time subscription overhead
+
+## Estimated Complexity: MEDIUM
+- Backend: 4-6 hours
+- Frontend: 3-4 hours
+- Testing: 2-3 hours
+- Total: 9-13 hours
+
+**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
+```
+
+## Important Notes
+
+**CRITICAL**: The planner agent will **NOT** write any code until you explicitly confirm the plan with "yes" or "proceed" or similar affirmative response.
+
+If you want changes, respond with:
+- "modify: [your changes]"
+- "different approach: [alternative]"
+- "skip phase 2 and do phase 3 first"
+
+## Integration with Other Commands
+
+After planning:
+- Use `/tdd` to implement with test-driven development
+- Use `/build-and-fix` if build errors occur
+- Use `/code-review` to review completed implementation
+
+## Related Agents
+
+This command invokes the `planner` agent located at:
+`~/.claude/agents/planner.md`

package/commands/refactor-clean.md

@@ -0,0 +1,28 @@
+# Refactor Clean
+
+Safely identify and remove dead code with test verification:
+
+1. Run dead code analysis tools:
+   - knip: Find unused exports and files
+   - depcheck: Find unused dependencies
+   - ts-prune: Find unused TypeScript exports
+
+2. Generate comprehensive report in .reports/dead-code-analysis.md
+
+3. Categorize findings by severity:
+   - SAFE: Test files, unused utilities
+   - CAUTION: API routes, components
+   - DANGER: Config files, main entry points
+
+4. Propose safe deletions only
+
+5. Before each deletion:
+   - Run full test suite
+   - Verify tests pass
+   - Apply change
+   - Re-run tests
+   - Rollback if tests fail
+
+6. Show summary of cleaned items
+
+Never delete code without running tests first!