compound-engineering-pi 0.2.3

package/plugins/compound-engineering/commands/test-browser.md

@@ -0,0 +1,339 @@
+---
+name: test-browser
+description: Run browser tests on pages affected by current PR or branch
+argument-hint: "[PR number, branch name, or 'current' for current branch]"
+---
+
+# Browser Test Command
+
+<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>
+
+## CRITICAL: Use agent-browser CLI Only
+
+**DO NOT use Chrome MCP tools (mcp__claude-in-chrome__*).**
+
+This command uses the `agent-browser` CLI exclusively. The agent-browser CLI is a Bash-based tool from Vercel that runs headless Chromium. It is NOT the same as Chrome browser automation via MCP.
+
+If you find yourself calling `mcp__claude-in-chrome__*` tools, STOP. Use `agent-browser` Bash commands instead.
+
+## Introduction
+
+<role>QA Engineer specializing in browser-based end-to-end testing</role>
+
+This command tests affected pages in a real browser, catching issues that unit tests miss:
+- JavaScript integration bugs
+- CSS/layout regressions
+- User workflow breakages
+- Console errors
+
+## Prerequisites
+
+<requirements>
+- Local development server running (e.g., `bin/dev`, `rails server`, `npm run dev`)
+- agent-browser CLI installed (see Setup below)
+- Git repository with changes to test
+</requirements>
+
+## Setup
+
+**Check installation:**
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+```bash
+npm install -g agent-browser
+agent-browser install  # Downloads Chromium (~160MB)
+```
+
+See the `agent-browser` skill for detailed usage.
+
+## Main Tasks
+
+### 0. Verify agent-browser Installation
+
+Before starting ANY browser testing, verify agent-browser is installed:
+
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Ready" || (echo "Installing..." && npm install -g agent-browser && agent-browser install)
+```
+
+If installation fails, inform the user and stop.
+
+### 1. Ask Browser Mode
+
+<ask_browser_mode>
+
+Before starting tests, ask user if they want to watch the browser:
+
+Use AskUserQuestion with:
+- Question: "Do you want to watch the browser tests run?"
+- Options:
+  1. **Headed (watch)** - Opens visible browser window so you can see tests run
+  2. **Headless (faster)** - Runs in background, faster but invisible
+
+Store the choice and use `--headed` flag when user selects "Headed".
+
+</ask_browser_mode>
+
+### 2. Determine Test Scope
+
+<test_target> $ARGUMENTS </test_target>
+
+<determine_scope>
+
+**If PR number provided:**
+```bash
+gh pr view [number] --json files -q '.files[].path'
+```
+
+**If 'current' or empty:**
+```bash
+git diff --name-only main...HEAD
+```
+
+**If branch name provided:**
+```bash
+git diff --name-only main...[branch]
+```
+
+</determine_scope>
+
+### 3. Map Files to Routes
+
+<file_to_route_mapping>
+
+Map changed files to testable routes:
+
+| File Pattern | Route(s) |
+|-------------|----------|
+| `app/views/users/*` | `/users`, `/users/:id`, `/users/new` |
+| `app/controllers/settings_controller.rb` | `/settings` |
+| `app/javascript/controllers/*_controller.js` | Pages using that Stimulus controller |
+| `app/components/*_component.rb` | Pages rendering that component |
+| `app/views/layouts/*` | All pages (test homepage at minimum) |
+| `app/assets/stylesheets/*` | Visual regression on key pages |
+| `app/helpers/*_helper.rb` | Pages using that helper |
+| `src/app/*` (Next.js) | Corresponding routes |
+| `src/components/*` | Pages using those components |
+
+Build a list of URLs to test based on the mapping.
+
+</file_to_route_mapping>
+
+### 4. Verify Server is Running
+
+<check_server>
+
+Before testing, verify the local server is accessible:
+
+```bash
+agent-browser open http://localhost:3000
+agent-browser snapshot -i
+```
+
+If server is not running, inform user:
+```markdown
+**Server not running**
+
+Please start your development server:
+- Rails: `bin/dev` or `rails server`
+- Node/Next.js: `npm run dev`
+
+Then run `/test-browser` again.
+```
+
+</check_server>
+
+### 5. Test Each Affected Page
+
+<test_pages>
+
+For each affected route, use agent-browser CLI commands (NOT Chrome MCP):
+
+**Step 1: Navigate and capture snapshot**
+```bash
+agent-browser open "http://localhost:3000/[route]"
+agent-browser snapshot -i
+```
+
+**Step 2: For headed mode (visual debugging)**
+```bash
+agent-browser --headed open "http://localhost:3000/[route]"
+agent-browser --headed snapshot -i
+```
+
+**Step 3: Verify key elements**
+- Use `agent-browser snapshot -i` to get interactive elements with refs
+- Page title/heading present
+- Primary content rendered
+- No error messages visible
+- Forms have expected fields
+
+**Step 4: Test critical interactions**
+```bash
+agent-browser click @e1  # Use ref from snapshot
+agent-browser snapshot -i
+```
+
+**Step 5: Take screenshots**
+```bash
+agent-browser screenshot page-name.png
+agent-browser screenshot --full page-name-full.png  # Full page
+```
+
+</test_pages>
+
+### 6. Human Verification (When Required)
+
+<human_verification>
+
+Pause for human input when testing touches:
+
+| Flow Type | What to Ask |
+|-----------|-------------|
+| OAuth | "Please sign in with [provider] and confirm it works" |
+| Email | "Check your inbox for the test email and confirm receipt" |
+| Payments | "Complete a test purchase in sandbox mode" |
+| SMS | "Verify you received the SMS code" |
+| External APIs | "Confirm the [service] integration is working" |
+
+Use AskUserQuestion:
+```markdown
+**Human Verification Needed**
+
+This test touches the [flow type]. Please:
+1. [Action to take]
+2. [What to verify]
+
+Did it work correctly?
+1. Yes - continue testing
+2. No - describe the issue
+```
+
+</human_verification>
+
+### 7. Handle Failures
+
+<failure_handling>
+
+When a test fails:
+
+1. **Document the failure:**
+   - Screenshot the error state: `agent-browser screenshot error.png`
+   - Note the exact reproduction steps
+
+2. **Ask user how to proceed:**
+   ```markdown
+   **Test Failed: [route]**
+
+   Issue: [description]
+   Console errors: [if any]
+
+   How to proceed?
+   1. Fix now - I'll help debug and fix
+   2. Create todo - Add to todos/ for later
+   3. Skip - Continue testing other pages
+   ```
+
+3. **If "Fix now":**
+   - Investigate the issue
+   - Propose a fix
+   - Apply fix
+   - Re-run the failing test
+
+4. **If "Create todo":**
+   - Create `{id}-pending-p1-browser-test-{description}.md`
+   - Continue testing
+
+5. **If "Skip":**
+   - Log as skipped
+   - Continue testing
+
+</failure_handling>
+
+### 8. Test Summary
+
+<test_summary>
+
+After all tests complete, present summary:
+
+```markdown
+## Browser Test Results
+
+**Test Scope:** PR #[number] / [branch name]
+**Server:** http://localhost:3000
+
+### Pages Tested: [count]
+
+| Route | Status | Notes |
+|-------|--------|-------|
+| `/users` | Pass | |
+| `/settings` | Pass | |
+| `/dashboard` | Fail | Console error: [msg] |
+| `/checkout` | Skip | Requires payment credentials |
+
+### Console Errors: [count]
+- [List any errors found]
+
+### Human Verifications: [count]
+- OAuth flow: Confirmed
+- Email delivery: Confirmed
+
+### Failures: [count]
+- `/dashboard` - [issue description]
+
+### Created Todos: [count]
+- `005-pending-p1-browser-test-dashboard-error.md`
+
+### Result: [PASS / FAIL / PARTIAL]
+```
+
+</test_summary>
+
+## Quick Usage Examples
+
+```bash
+# Test current branch changes
+/test-browser
+
+# Test specific PR
+/test-browser 847
+
+# Test specific branch
+/test-browser feature/new-dashboard
+```
+
+## agent-browser CLI Reference
+
+**ALWAYS use these Bash commands. NEVER use mcp__claude-in-chrome__* tools.**
+
+```bash
+# Navigation
+agent-browser open <url>           # Navigate to URL
+agent-browser back                 # Go back
+agent-browser close                # Close browser
+
+# Snapshots (get element refs)
+agent-browser snapshot -i          # Interactive elements with refs (@e1, @e2, etc.)
+agent-browser snapshot -i --json   # JSON output
+
+# Interactions (use refs from snapshot)
+agent-browser click @e1            # Click element
+agent-browser fill @e1 "text"      # Fill input
+agent-browser type @e1 "text"      # Type without clearing
+agent-browser press Enter          # Press key
+
+# Screenshots
+agent-browser screenshot out.png       # Viewport screenshot
+agent-browser screenshot --full out.png # Full page screenshot
+
+# Headed mode (visible browser)
+agent-browser --headed open <url>      # Open with visible browser
+agent-browser --headed click @e1       # Click in visible browser
+
+# Wait
+agent-browser wait @e1             # Wait for element
+agent-browser wait 2000            # Wait milliseconds
+```

package/plugins/compound-engineering/commands/test-xcode.md

@@ -0,0 +1,332 @@
+---
+name: test-xcode
+description: Build and test iOS apps on simulator using XcodeBuildMCP
+argument-hint: "[scheme name or 'current' to use default]"
+disable-model-invocation: true
+---
+
+# Xcode Test Command
+
+<command_purpose>Build, install, and test iOS apps on the simulator using XcodeBuildMCP. Captures screenshots, logs, and verifies app behavior.</command_purpose>
+
+## Introduction
+
+<role>iOS QA Engineer specializing in simulator-based testing</role>
+
+This command tests iOS/macOS apps by:
+- Building for simulator
+- Installing and launching the app
+- Taking screenshots of key screens
+- Capturing console logs for errors
+- Supporting human verification for external flows
+
+## Prerequisites
+
+<requirements>
+- Xcode installed with command-line tools
+- XcodeBuildMCP server connected
+- Valid Xcode project or workspace
+- At least one iOS Simulator available
+</requirements>
+
+## Main Tasks
+
+### 0. Verify XcodeBuildMCP is Installed
+
+<check_mcp_installed>
+
+**First, check if XcodeBuildMCP tools are available.**
+
+Try calling:
+```
+mcp__xcodebuildmcp__list_simulators({})
+```
+
+**If the tool is not found or errors:**
+
+Tell the user:
+```markdown
+**XcodeBuildMCP not installed**
+
+Please install the XcodeBuildMCP server first:
+
+\`\`\`bash
+claude mcp add XcodeBuildMCP -- npx xcodebuildmcp@latest
+\`\`\`
+
+Then restart Claude Code and run `/xcode-test` again.
+```
+
+**Do NOT proceed** until XcodeBuildMCP is confirmed working.
+
+</check_mcp_installed>
+
+### 1. Discover Project and Scheme
+
+<discover_project>
+
+**Find available projects:**
+```
+mcp__xcodebuildmcp__discover_projs({})
+```
+
+**List schemes for the project:**
+```
+mcp__xcodebuildmcp__list_schemes({ project_path: "/path/to/Project.xcodeproj" })
+```
+
+**If argument provided:**
+- Use the specified scheme name
+- Or "current" to use the default/last-used scheme
+
+</discover_project>
+
+### 2. Boot Simulator
+
+<boot_simulator>
+
+**List available simulators:**
+```
+mcp__xcodebuildmcp__list_simulators({})
+```
+
+**Boot preferred simulator (iPhone 15 Pro recommended):**
+```
+mcp__xcodebuildmcp__boot_simulator({ simulator_id: "[uuid]" })
+```
+
+**Wait for simulator to be ready:**
+Check simulator state before proceeding with installation.
+
+</boot_simulator>
+
+### 3. Build the App
+
+<build_app>
+
+**Build for iOS Simulator:**
+```
+mcp__xcodebuildmcp__build_ios_sim_app({
+  project_path: "/path/to/Project.xcodeproj",
+  scheme: "[scheme_name]"
+})
+```
+
+**Handle build failures:**
+- Capture build errors
+- Create P1 todo for each build error
+- Report to user with specific error details
+
+**On success:**
+- Note the built app path for installation
+- Proceed to installation step
+
+</build_app>
+
+### 4. Install and Launch
+
+<install_launch>
+
+**Install app on simulator:**
+```
+mcp__xcodebuildmcp__install_app_on_simulator({
+  app_path: "/path/to/built/App.app",
+  simulator_id: "[uuid]"
+})
+```
+
+**Launch the app:**
+```
+mcp__xcodebuildmcp__launch_app_on_simulator({
+  bundle_id: "[app.bundle.id]",
+  simulator_id: "[uuid]"
+})
+```
+
+**Start capturing logs:**
+```
+mcp__xcodebuildmcp__capture_sim_logs({
+  simulator_id: "[uuid]",
+  bundle_id: "[app.bundle.id]"
+})
+```
+
+</install_launch>
+
+### 5. Test Key Screens
+
+<test_screens>
+
+For each key screen in the app:
+
+**Take screenshot:**
+```
+mcp__xcodebuildmcp__take_screenshot({
+  simulator_id: "[uuid]",
+  filename: "screen-[name].png"
+})
+```
+
+**Review screenshot for:**
+- UI elements rendered correctly
+- No error messages visible
+- Expected content displayed
+- Layout looks correct
+
+**Check logs for errors:**
+```
+mcp__xcodebuildmcp__get_sim_logs({ simulator_id: "[uuid]" })
+```
+
+Look for:
+- Crashes
+- Exceptions
+- Error-level log messages
+- Failed network requests
+
+</test_screens>
+
+### 6. Human Verification (When Required)
+
+<human_verification>
+
+Pause for human input when testing touches:
+
+| Flow Type | What to Ask |
+|-----------|-------------|
+| Sign in with Apple | "Please complete Sign in with Apple on the simulator" |
+| Push notifications | "Send a test push and confirm it appears" |
+| In-app purchases | "Complete a sandbox purchase" |
+| Camera/Photos | "Grant permissions and verify camera works" |
+| Location | "Allow location access and verify map updates" |
+
+Use AskUserQuestion:
+```markdown
+**Human Verification Needed**
+
+This test requires [flow type]. Please:
+1. [Action to take on simulator]
+2. [What to verify]
+
+Did it work correctly?
+1. Yes - continue testing
+2. No - describe the issue
+```
+
+</human_verification>
+
+### 7. Handle Failures
+
+<failure_handling>
+
+When a test fails:
+
+1. **Document the failure:**
+   - Take screenshot of error state
+   - Capture console logs
+   - Note reproduction steps
+
+2. **Ask user how to proceed:**
+   ```markdown
+   **Test Failed: [screen/feature]**
+
+   Issue: [description]
+   Logs: [relevant error messages]
+
+   How to proceed?
+   1. Fix now - I'll help debug and fix
+   2. Create todo - Add to todos/ for later
+   3. Skip - Continue testing other screens
+   ```
+
+3. **If "Fix now":**
+   - Investigate the issue in code
+   - Propose a fix
+   - Rebuild and retest
+
+4. **If "Create todo":**
+   - Create `{id}-pending-p1-xcode-{description}.md`
+   - Continue testing
+
+</failure_handling>
+
+### 8. Test Summary
+
+<test_summary>
+
+After all tests complete, present summary:
+
+```markdown
+## 📱 Xcode Test Results
+
+**Project:** [project name]
+**Scheme:** [scheme name]
+**Simulator:** [simulator name]
+
+### Build: ✅ Success / ❌ Failed
+
+### Screens Tested: [count]
+
+| Screen | Status | Notes |
+|--------|--------|-------|
+| Launch | ✅ Pass | |
+| Home | ✅ Pass | |
+| Settings | ❌ Fail | Crash on tap |
+| Profile | ⏭️ Skip | Requires login |
+
+### Console Errors: [count]
+- [List any errors found]
+
+### Human Verifications: [count]
+- Sign in with Apple: ✅ Confirmed
+- Push notifications: ✅ Confirmed
+
+### Failures: [count]
+- Settings screen - crash on navigation
+
+### Created Todos: [count]
+- `006-pending-p1-xcode-settings-crash.md`
+
+### Result: [PASS / FAIL / PARTIAL]
+```
+
+</test_summary>
+
+### 9. Cleanup
+
+<cleanup>
+
+After testing:
+
+**Stop log capture:**
+```
+mcp__xcodebuildmcp__stop_log_capture({ simulator_id: "[uuid]" })
+```
+
+**Optionally shut down simulator:**
+```
+mcp__xcodebuildmcp__shutdown_simulator({ simulator_id: "[uuid]" })
+```
+
+</cleanup>
+
+## Quick Usage Examples
+
+```bash
+# Test with default scheme
+/xcode-test
+
+# Test specific scheme
+/xcode-test MyApp-Debug
+
+# Test after making changes
+/xcode-test current
+```
+
+## Integration with /workflows:review
+
+When reviewing PRs that touch iOS code, the `/workflows:review` command can spawn this as a subagent:
+
+```
+Task general-purpose("Run /xcode-test for scheme [name]. Build, install on simulator, test key screens, check for crashes.")
+```