compound-workflow 0.1.1

package/src/.agents/commands/test-browser.md

@@ -0,0 +1,393 @@
+---
+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 browser MCP automation tools.
+
+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 reaching for browser automation tools outside of `agent-browser`, STOP. Use `agent-browser` Bash commands instead.
+
+## Guardrails
+
+- Use the agent-browser CLI only; do not use other browser automation (e.g. MCP).
+- Do not modify application code; validate only (run tests, capture snapshots, report).
+
+## 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 (use your repo's dev command)
+- agent-browser CLI installed (see Setup below)
+- Git repository with changes to test
+</requirements>
+
+Portability notes:
+
+- If `gh` is unavailable, use `current` mode and derive changed files from `git diff`.
+- If the default branch is not `main`, use `default_branch` from the Repo Config Block in `AGENTS.md` or fall back to `master`.
+- If the dev server URL is not `http://localhost:3000`, use `dev_server_url` from the Repo Config Block in `AGENTS.md`.
+
+Branching note:
+
+- Prefer testing the branch you are currently on.
+- Only switch branches (or create a worktree) when the user explicitly asks to test a different branch/PR.
+
+## 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. Resolve Defaults (ALWAYS FIRST)
+
+Determine:
+
+- Read `AGENTS.md` and look for the "Repo Config Block" YAML.
+- `server_url`: from `dev_server_url`, else default `http://localhost:3000`
+- `default_branch`: from `default_branch`, else try `main`, else `master`
+
+Announce:
+
+- Server URL you will test against
+- Branch you are currently on
+- How you will determine changed files
+
+### 1. 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.
+
+### 2. Ask Browser Mode
+
+<ask_browser_mode>
+
+Before starting tests, ask user if they want to watch the browser:
+
+Use AskQuestion 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>
+
+### 3. 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 `gh` is not available, ask the user for a branch name or use `current`.
+
+**If 'current' or empty:**
+
+Prefer the upstream tracking branch if available:
+
+```bash
+git diff --name-only @{upstream}...HEAD
+```
+
+If upstream is not configured, fall back to the configured default branch:
+
+```bash
+git diff --name-only "origin/${default_branch}"...HEAD
+```
+
+If neither is available, fall back to the last commit:
+
+```bash
+git diff --name-only HEAD~1..HEAD
+```
+
+**If branch name provided:**
+
+If you are already on that branch, treat it like `current`.
+
+If you are not on that branch, ask whether to switch branches or use a worktree via `git-worktree`.
+
+To compute changed files for that branch (once checked out):
+
+```bash
+git diff --name-only "origin/${default_branch}"...HEAD
+```
+
+</determine_scope>
+
+### 3. Map Files to Routes
+
+<file_to_route_mapping>
+
+Map changed files to testable routes.
+
+This mapping is repo-specific. Prefer project conventions first.
+
+If the repo does not have an obvious file->route mapping, ask the user for 3-10 URLs to validate.
+
+Examples of starting heuristics:
+
+- Backend API changes: validate at least one happy-path request and one error path (if a browser route exists, validate it too).
+- UI component changes: validate at least one page that renders the component.
+- Router changes: validate affected routes directly.
+- Shared layout/styling changes: validate at least the homepage + 1-3 key flows.
+
+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 `dev_server_url` is configured in `AGENTS.md`, use that instead of `http://localhost:3000`.
+
+If server is not running, inform user:
+```markdown
+**Server not running**
+
+Please start your development server:
+- Use the repo's dev command (see `AGENTS.md` if configured)
+
+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 AskQuestion:
+```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.
+
+```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/src/.agents/commands/workflow/brainstorm.md

@@ -0,0 +1,252 @@
+---
+name: brainstorm
+invocation: workflow:brainstorm
+description: Explore requirements and approaches through collaborative dialogue before planning implementation
+argument-hint: "[feature idea or problem to explore]"
+---
+
+# Brainstorm a Feature or Improvement
+
+**Note: The current year is 2026.** Use this when dating brainstorm
+documents.
+
+Brainstorming helps answer **WHAT** to build through collaborative
+dialogue. It precedes `/workflow:plan`, which answers **HOW** to build
+it.
+
+**Process knowledge:** Load the `brainstorming` skill for detailed
+discussion-first facilitation (one-question-then-prompts), approach
+exploration patterns, and YAGNI principles.
+
+## Guardrails
+
+- Do not write or modify application code.
+- Do not create commits or PRs.
+- Output is the brainstorm document only.
+
+---
+
+## Feature Description
+
+<feature_description>#$ARGUMENTS</feature_description>
+
+**If the feature description above is empty, ask the user:**\
+"What would you like to explore? Please describe the feature, problem,
+or improvement you're thinking about."
+
+Do not proceed until you have a feature description from the user.
+
+---
+
+## Execution Flow
+
+---
+
+### Phase 0: Assess Requirements Clarity
+
+Evaluate whether brainstorming is needed based on the feature
+description.
+
+**Clear requirements indicators:**
+
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**\
+Use **AskQuestion** to suggest:
+
+> "Your requirements seem detailed enough to proceed directly to
+> planning. Should I run `/workflow:plan` instead, or would you like to
+> explore the idea further?"
+
+---
+
+### Phase 1: Understand the Idea
+
+#### 1.1 Repository Research (Lightweight)
+
+Run a quick repo scan to understand existing patterns:
+
+- Task repo-research-analyst("Understand existing patterns related to:
+  <feature_description>")
+
+Focus on: - Similar features - Established patterns - AGENTS.md guidance
+
+Also consider any repo-level guidance files such as `AGENTS.md`.
+
+---
+
+#### 1.2 Structured Dialogue Exploration (Default)
+
+Engage in collaborative dialogue rather than a rapid question loop.
+
+**Critical (non-negotiable):** Default response shape is **synthesize + discussion prompts + assumptions**. Multiple-choice / AskQuestion only for handoffs (Phase 0, Phase 4) or a single blocking question when the user is stuck.
+
+**Enforcement rule:** Do **not** use AskQuestion during exploration until **after** at least one full dialogue iteration (Synthesize + discussion prompts + Capture). AskQuestion is only for handoffs or when one focused multiple-choice truly unblocks.
+
+**Default cadence (per iteration):**
+
+1. **Synthesize Current Understanding** (2--4 bullets)
+2. **Ask at most ONE high-leverage question** (only if needed)
+3. **Surface Tensions & Unknowns** using 3--5 **discussion prompts** (not interrogation)
+4. **Capture Emerging Assumptions** (bullets)
+
+**Hard rules:**
+
+- Do not ask follow-up questions in the same turn.
+- Ask **no more than one** clarifying question per iteration.
+- If blocked, ask **one** additional clarifying question max, then return to prompts.
+
+**First assistant message template (copy/paste shape):**
+
+```markdown
+**What I think you're aiming for (so far):**
+- ...
+- ...
+
+**One question to anchor us:**
+<single sentence>
+
+**Prompts to react to (pick any):**
+- Tradeoff: ...
+- Edge area: ...
+- UX vs architecture: ...
+- Scale implication: ...
+- Short-term vs long-term: ...
+
+**Working assumptions (tell me what’s wrong):**
+- ...
+- ...
+```
+
+For each iteration:
+
+1.  **Synthesize Current Understanding**
+
+    - What the feature appears to be
+    - Who it impacts
+    - What class of change this is (incremental, foundational, risky, trivial)
+    - Implied constraints
+
+2.  **Ask at most ONE high-leverage question** (only if needed to unblock discussion)
+
+3.  **Surface Tensions & Unknowns** via 3--5 prompts to react to (not interrogation), such as:
+
+    - Tradeoff
+    - Edge area
+    - Scale implication
+    - UX vs architecture tension
+    - Short-term vs long-term implication
+
+4.  **Capture Emerging Assumptions** Explicitly note:
+
+    - Working assumptions
+    - Tentative decisions
+    - Areas still unresolved
+
+5.  Continue iteratively until:
+
+    - Direction is clear
+    - Or user says "proceed"
+
+---
+
+#### Targeted Clarification Fallback
+
+If ambiguity blocks meaningful progress:
+
+- Ask **one** focused, high-leverage clarification question.
+- Only use direct questioning when it is truly blocking meaningful discussion.
+- Avoid serial low-value questioning.
+
+---
+
+### Phase 2: Explore Approaches
+
+Propose **2--3 concrete approaches** based on research and dialogue.
+
+For each approach, provide:
+
+- Brief description (2--3 sentences)
+- Pros and cons
+- When it is best suited
+
+Lead with your recommendation and explain why. Apply YAGNI --- prefer
+simpler solutions.
+
+Use **AskQuestion** to confirm preferred direction if needed.
+
+---
+
+### Phase 3: Capture the Design
+
+Write a brainstorm document to:
+
+docs/brainstorms/YYYY-MM-DD-`<topic>`-brainstorm.md
+
+**Document structure must include:**
+
+- What We're Building
+- Why This Approach
+- Key Decisions
+- Open Questions
+
+Ensure `docs/brainstorms/` exists before writing.
+
+**Critical Rule:**\
+Before proceeding to Phase 4, check if Open Questions remain.
+
+If Open Questions exist:
+
+- Classify each as **blocking** vs **non-blocking**.
+- You MUST ask the user about each **blocking** question.
+- Move resolved questions into a "Resolved Questions" section.
+- Non-blocking questions may remain for planning, but must be clearly stated.
+
+---
+
+### Phase 4: Handoff
+
+Use **AskQuestion** to present next steps:
+
+**Question:**
+"Brainstorm captured. What would you like to do next?"
+
+**Options:**
+
+1.  Review and refine
+2.  Proceed to planning
+3.  Ask more questions
+4.  Done for now
+
+If "Ask more questions" is selected: Return to Phase 1.2 and continue
+structured dialogue.
+
+If "Review and refine" is selected: Load the `document-review` skill and
+apply it.
+
+---
+
+## Output Summary
+
+When complete, display:
+
+Brainstorm complete!
+
+Document: docs/brainstorms/YYYY-MM-DD-`<topic>`-brainstorm.md
+
+Key decisions: - \[Decision 1\] - \[Decision 2\]
+
+Next: Run `/workflow:plan` when ready to implement.
+
+---
+
+## Important Guidelines
+
+- Stay focused on WHAT, not HOW
+- Dialogue first; interrogation only when necessary
+- Apply YAGNI
+- Keep outputs concise (200--300 words per section max)
+- NEVER CODE during brainstorming