@kodrunhq/opencode-autopilot 1.4.0 → 1.6.0

package/assets/skills/e2e-testing/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: e2e-testing
+description: End-to-end testing patterns for critical user flows -- test the system as a user would use it
+stacks: []
+requires: []
+---
+
+# E2E Testing
+
+End-to-end testing patterns for critical user flows. E2E tests verify the system works correctly from the user's perspective, exercising the full stack from UI (or API surface) through business logic to data storage and back. This skill covers when to write E2E tests, how to design them, and how to keep them reliable.
+
+## When to Use
+
+- Critical user flows that must never break (login, signup, checkout, data creation)
+- Integration points between multiple services or layers
+- Flows where unit tests cannot catch the issue (routing, middleware chains, full request lifecycle)
+- Before major releases as a confidence gate
+- After infrastructure changes (database migrations, service upgrades, environment changes)
+- When a bug was reported that unit and integration tests did not catch
+
+## When NOT to Use
+
+- Pure logic that can be tested with unit tests (calculations, transformations, validators)
+- Single API endpoint behavior (use integration tests)
+- UI component rendering in isolation (use component tests)
+- Performance benchmarking (use dedicated performance tests)
+
+E2E tests are the most expensive tests to write and maintain. Use them surgically for flows where no other test type provides sufficient confidence.
+
+## E2E Test Design Principles
+
+### Test User Journeys, Not Components
+
+An E2E test should mirror a real user workflow from start to finish:
+
+```
+// Good: Complete user journey
+test("new user can sign up, verify email, and access dashboard", () => {
+  navigateTo("/signup")
+  fillForm({ email: "alice@example.com", password: "SecurePass123!" })
+  clickButton("Create Account")
+  verifyEmailLink()
+  expectRedirectTo("/dashboard")
+  expectVisible("Welcome, Alice")
+})
+
+// Bad: Testing a single component in E2E
+test("signup button renders correctly", () => {
+  navigateTo("/signup")
+  expectVisible("Create Account")  // This is a component test
+})
+```
+
+### Use Realistic Data
+
+- Use data that resembles production data in structure and edge cases
+- Include special characters, long strings, and boundary values
+- Avoid "test123" or "foo@bar.com" -- use realistic names and formats
+- If the system has user roles, test each role's journey separately
+
+### Keep Tests Independent
+
+- Each test should work regardless of execution order
+- Never depend on state created by a previous test
+- Set up all required state within the test itself (or in a beforeEach hook)
+- Clean up created state after the test (or use isolated test environments)
+
+### Use the Page Object Pattern
+
+Encapsulate UI interactions behind a clean interface:
+
+```
+// Page object
+const loginPage = {
+  navigate: () => goto("/login"),
+  fillEmail: (email) => fill("[data-testid=email]", email),
+  fillPassword: (password) => fill("[data-testid=password]", password),
+  submit: () => click("[data-testid=login-button]"),
+  getErrorMessage: () => getText("[data-testid=error-message]"),
+}
+
+// Test uses page object
+test("login with valid credentials", () => {
+  loginPage.navigate()
+  loginPage.fillEmail("alice@example.com")
+  loginPage.fillPassword("SecurePass123!")
+  loginPage.submit()
+  expectRedirectTo("/dashboard")
+})
+```
+
+Benefits: tests are readable, selector changes only need one update, complex interactions are reusable.
+
+## Test Structure
+
+Every E2E test follows the same four-phase structure:
+
+### Arrange
+
+Set up the preconditions for the test:
+
+- Create test data (users, records, configurations)
+- Navigate to the starting page or API endpoint
+- Ensure the system is in a clean, known state
+- Set up any mocks for external services (payment gateways, email providers)
+
+### Act
+
+Perform the user actions being tested:
+
+- Click buttons, fill forms, navigate between pages
+- Submit API requests with realistic payloads
+- Wait for async operations to complete (use explicit waits, not sleep)
+
+### Assert
+
+Verify the expected outcome:
+
+- Check page content, URLs, and UI state
+- Verify API responses (status codes, body content)
+- Check that side effects occurred (database records created, emails sent)
+- Verify error states when testing failure scenarios
+
+### Cleanup
+
+Remove test artifacts:
+
+- Delete created test data
+- Reset any modified configurations
+- Close opened connections or sessions
+- Leave the system in the same state it was in before the test
+
+## Common E2E Patterns
+
+### Pattern: Happy Path First
+
+Always implement the successful flow before testing error cases.
+
+1. Write the happy path test (user completes the flow successfully)
+2. Verify the happy path is stable and passes consistently
+3. Then add error case tests (invalid input, network failures, auth failures)
+4. Then add edge case tests (concurrent requests, timeout scenarios)
+
+Rationale: the happy path test validates that the entire stack works. If the happy path fails, error case tests are meaningless.
+
+### Pattern: Smoke Tests
+
+A minimal set of E2E tests that verify the application starts and basic flows work:
+
+- Application loads without errors
+- Login works with valid credentials
+- The primary feature is accessible and functional
+- Critical API endpoints respond with expected status codes
+
+Run smoke tests on every commit. They should complete in under 2 minutes. If a smoke test fails, the build is broken.
+
+### Pattern: Critical Path Tests
+
+Tests for the most important user flows -- the ones that directly impact revenue or user trust:
+
+- User registration and onboarding
+- Core feature workflow (the thing users pay for)
+- Payment and billing (if applicable)
+- Data export and deletion (compliance-critical)
+
+Run critical path tests before every release and on the release candidate branch. They may take 5-15 minutes.
+
+### Pattern: Contract Tests for Service Boundaries
+
+When your E2E tests span multiple services, use contract tests to verify the API contract between them:
+
+- Producer tests: verify the API produces responses matching the contract
+- Consumer tests: verify the client correctly handles the contract responses
+- Contract changes require both sides to update
+
+This reduces the need for full cross-service E2E tests, which are expensive and flaky.
+
+## Anti-Pattern Catalog
+
+### Anti-Pattern: Testing Everything E2E
+
+**What it looks like:** Writing E2E tests for every feature, including pure logic and simple CRUD operations.
+
+**Why it is harmful:** E2E tests are slow (seconds to minutes per test), expensive to maintain, and brittle. A large E2E suite becomes a bottleneck that slows down development.
+
+**Instead:** Use the testing pyramid -- unit tests for logic, integration tests for APIs and data access, E2E only for critical user flows. A healthy ratio is roughly 70% unit, 20% integration, 10% E2E.
+
+### Anti-Pattern: Flaky Tests
+
+**What it looks like:** Tests that pass or fail randomly without any code change. Developers re-run the suite hoping for green.
+
+**Why it is harmful:** Flaky tests destroy trust in the test suite. Teams start ignoring failures, and real bugs slip through.
+
+**Instead:**
+- Use explicit waits instead of arbitrary sleep/delays
+- Ensure clean state before each test (no leftover data from previous runs)
+- Avoid timing-dependent assertions (use polling with timeout instead)
+- Run flaky tests in isolation to identify the root cause
+- Quarantine flaky tests until fixed -- do not leave them in the main suite
+
+### Anti-Pattern: No Cleanup
+
+**What it looks like:** Tests create data (users, records, files) but never clean up, causing subsequent tests to fail due to duplicate data or unexpected state.
+
+**Why it is harmful:** Tests become order-dependent and fail in CI but pass locally (or vice versa).
+
+**Instead:** Clean up in afterEach hooks. Use database transactions that roll back. Use unique identifiers (timestamps, UUIDs) for test data. Run each test in an isolated environment if possible.
+
+### Anti-Pattern: Hardcoded Selectors
+
+**What it looks like:** Tests use CSS selectors like `.btn-primary`, `#submit`, or DOM structure paths like `div > form > button:nth-child(3)`.
+
+**Why it is harmful:** Any UI restructuring or CSS class change breaks the tests, even if the functionality is unchanged.
+
+**Instead:** Use dedicated test attributes (`data-testid="login-button"`) that are decoupled from styling and structure. These survive redesigns.
+
+### Anti-Pattern: No Test Data Strategy
+
+**What it looks like:** Tests use the same hardcoded user ("admin@test.com") and assume it exists in the database.
+
+**Why it is harmful:** Tests fail in fresh environments, cannot run in parallel (shared state conflicts), and mask data-dependent bugs.
+
+**Instead:** Each test creates its own data, uses it, and cleans it up. Use factories or fixtures that generate unique, realistic test data.
+
+## Integration with Our Tools
+
+### Automated Review of E2E Tests
+
+Use `oc_review` to check E2E test quality. The review engine evaluates:
+- Test isolation (no shared state between tests)
+- Proper cleanup (data created is data deleted)
+- Realistic assertions (not just "page loaded")
+- Flakiness risks (timing dependencies, non-deterministic data)
+
+### TDD for E2E Tests
+
+Reference the tdd-workflow skill for the RED-GREEN-REFACTOR approach when writing E2E tests:
+1. **RED:** Write the E2E test for the user journey. It fails because the feature does not exist.
+2. **GREEN:** Implement the feature (building up from unit and integration tests). The E2E test passes.
+3. **REFACTOR:** Clean up the implementation. The E2E test still passes, confirming behavior is preserved.
+
+## Failure Modes
+
+### Test Is Flaky
+
+**Symptom:** Test passes locally, fails in CI (or passes 9 out of 10 times).
+
+**Diagnosis:** Check for timing dependencies (race conditions between UI updates and assertions), environment differences (ports, timeouts, screen resolution), and shared state (parallel test runs interfering).
+
+**Fix:** Add explicit waits for async operations. Use unique test data per run. Ensure the CI environment matches local as closely as possible.
+
+### Test Passes Locally but Fails in CI
+
+**Symptom:** Consistent pass on developer machines, consistent fail in CI.
+
+**Diagnosis:** Environment differences -- different browser versions, screen sizes, network latency, database contents, or missing environment variables.
+
+**Fix:** Run tests in containers that match the CI environment. Use headless browsers with fixed viewport sizes. Check that all environment variables are set in CI config.
+
+### Test Suite Is Too Slow
+
+**Symptom:** E2E suite takes more than 15 minutes, blocking the deployment pipeline.
+
+**Diagnosis:** Too many E2E tests, or tests are doing work that could be done at a lower level.
+
+**Fix:** Move non-critical tests to integration level. Run smoke tests on every commit, critical path tests on release branches only. Parallelize test execution across multiple workers. Use shared authentication setup across tests instead of logging in for each one.

package/assets/skills/git-worktrees/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: git-worktrees
+description: Git worktrees for isolated parallel development — work on multiple branches simultaneously without stashing
+stacks: []
+requires: []
+---
+
+# Git Worktrees
+
+Git worktrees let you check out multiple branches simultaneously in separate directories, all sharing the same repository. Instead of stashing, switching branches, and losing context, you create isolated workspaces where each branch has its own working directory.
+
+## When to Use
+
+- **Working on multiple features simultaneously** — keep each feature in its own directory with its own running dev server, tests, and editor window
+- **Need to switch context without stashing** — stashing is lossy (you forget what you stashed and why). Worktrees preserve full context
+- **Running long-running tests on one branch while developing on another** — tests run in worktree A while you code in worktree B
+- **Reviewing a PR while keeping your current work intact** — check out the PR branch in a new worktree, review and test it, then return to your main worktree
+- **Comparing implementations side-by-side** — two worktrees with different approaches, run benchmarks in both
+- **Hotfix on production while mid-feature** — create a worktree from the release branch, apply the fix, merge it, then return to your feature
+
+## Git Worktrees Workflow
+
+### Step 1: Create a Worktree
+
+```bash
+# Create a worktree for an existing branch
+git worktree add ../project-feature-name feature-branch
+
+# Create a worktree with a new branch
+git worktree add -b new-feature ../project-new-feature main
+
+# Create a worktree from a specific commit or tag
+git worktree add ../project-hotfix v2.1.0
+```
+
+**What happens:** Git creates a new directory (the worktree) that shares the same `.git` repository as your main checkout. Both directories can have different branches checked out, different staged changes, and different working directory state — but they share the same commit history, remotes, and configuration.
+
+**Key detail:** The `.git` directory in a worktree is a file (not a directory) that points back to the main repository's `.git/worktrees/` folder. This is how Git knows they are linked.
+
+### Step 2: Naming Convention
+
+Use a consistent naming pattern so worktrees are easy to find and identify:
+
+```
+../project-branchname        # Sibling directory pattern
+../myapp-fix-auth            # Project name + branch purpose
+../myapp-feature-search      # Project name + feature name
+../myapp-pr-review-142       # Project name + PR number
+```
+
+**Rules:**
+- Keep worktrees as siblings of the main repository (one directory up)
+- Prefix with the project name to avoid confusion when working on multiple projects
+- Include the purpose in the name (not just the branch name)
+- Do not create worktrees inside the main repository directory
+
+### Step 3: Working in Worktrees
+
+Each worktree is independent:
+
+```bash
+# Switch to the worktree
+cd ../project-feature-name
+
+# Work normally — all git commands work as expected
+git status
+git add .
+git commit -m "feat: implement search"
+git push origin feature-branch
+
+# Run project-specific tools
+bun install          # Each worktree needs its own node_modules
+bun test             # Tests run against this worktree's code
+bun run dev          # Dev server runs independently
+```
+
+**What is shared:** Commit history, branches, remotes, tags, git config, hooks.
+
+**What is NOT shared:** Working directory, staged changes (index), node_modules, build artifacts, .env files, editor state.
+
+### Step 4: Synchronize Between Worktrees
+
+Changes committed in one worktree are immediately visible to the other (they share the same repository):
+
+```bash
+# In worktree A: commit changes
+git commit -m "feat: add user model"
+
+# In worktree B: the commit exists (same repo)
+git log --oneline    # Shows the commit from worktree A
+
+# To get worktree A's changes into worktree B's branch
+git merge feature-a  # Or git rebase, git cherry-pick
+```
+
+**Important:** Do not check out the same branch in two worktrees. Git prevents this because it would cause index corruption. If you need to see the same code, use `git show` or `git diff` instead.
+
+### Step 5: Cleanup
+
+```bash
+# List all worktrees
+git worktree list
+
+# Remove a worktree (deletes the directory)
+git worktree remove ../project-feature-name
+
+# Clean up stale worktree references (if directory was manually deleted)
+git worktree prune
+
+# Force-remove a worktree with uncommitted changes
+git worktree remove --force ../project-feature-name
+```
+
+**When to clean up:**
+- After merging the branch (the worktree served its purpose)
+- After closing the PR you were reviewing
+- After the experiment failed and you want to discard it
+- Regularly — run `git worktree list` weekly to find stale worktrees
+
+## Common Patterns
+
+### Pattern: Parallel Feature Development
+
+**Scenario:** You are implementing feature A when a high-priority bug report comes in. You need to fix the bug immediately without losing your feature A context.
+
+```bash
+# You are in the main worktree, mid-feature-A
+# Create a worktree for the hotfix
+git worktree add -b hotfix/auth-bypass ../myapp-hotfix main
+
+# Switch to the hotfix worktree
+cd ../myapp-hotfix
+bun install
+
+# Fix the bug, test it, commit, push, create PR
+# ...
+
+# Return to your feature work — everything is exactly where you left it
+cd ../myapp
+# Continue feature A with full context preserved
+```
+
+**Benefit:** Zero context loss. No stashing, no branch switching, no re-running setup commands. Your feature A terminal, editor, and mental state are all preserved.
+
+### Pattern: Safe Experimentation
+
+**Scenario:** You want to try a risky refactor but are not sure it will work. You do not want to pollute your branch with experimental commits.
+
+```bash
+# Create an experimental worktree
+git worktree add -b experiment/new-architecture ../myapp-experiment main
+
+cd ../myapp-experiment
+bun install
+
+# Experiment freely — nothing affects your main worktree
+# If it works: merge the branch into main
+# If it fails: just remove the worktree
+git worktree remove ../myapp-experiment
+git branch -D experiment/new-architecture
+```
+
+**Benefit:** Zero risk. The experiment is completely isolated. If it fails, cleanup is a single command. No need to `git reset --hard`, no dangling commits, no stash entries to forget about.
+
+### Pattern: PR Review with Full Testing
+
+**Scenario:** You need to review a PR and want to run the tests locally, but you do not want to stop your current work.
+
+```bash
+# Fetch the PR branch
+git fetch origin pull/142/head:pr-142
+
+# Create a worktree for the review
+git worktree add ../myapp-pr-142 pr-142
+
+cd ../myapp-pr-142
+bun install
+bun test
+bun run dev   # Test the feature manually
+
+# Review complete — clean up
+cd ../myapp
+git worktree remove ../myapp-pr-142
+git branch -D pr-142
+```
+
+**Benefit:** Full local testing of the PR without disrupting your work. You can run the PR's dev server alongside your own.
+
+### Pattern: Comparison Testing
+
+**Scenario:** You want to measure the performance impact of a change by comparing before and after.
+
+```bash
+# Worktree A: the branch with your optimization
+git worktree add ../myapp-optimized optimization-branch
+
+# Worktree B: the baseline (main branch, already your main worktree)
+
+# Run benchmarks in both
+cd ../myapp && bun run benchmark > /tmp/baseline.txt
+cd ../myapp-optimized && bun run benchmark > /tmp/optimized.txt
+
+# Compare results
+diff /tmp/baseline.txt /tmp/optimized.txt
+```
+
+**Benefit:** True side-by-side comparison. No "run benchmarks, switch branches, run again, hope nothing changed" workflow.
+
+## Anti-Pattern Catalog
+
+### Anti-Pattern: Too Many Worktrees
+
+**What goes wrong:** You create a worktree for every branch and end up with 10+ worktrees. You lose track of which ones are active, which are stale, and which have uncommitted work.
+
+**Instead:** Limit yourself to 2-3 active worktrees at most. One for your main work, one for a hotfix or PR review, and optionally one for experimentation. Clean up worktrees as soon as their purpose is served.
+
+**Check:** Run `git worktree list` regularly. If you see more than 3 entries, clean up.
+
+### Anti-Pattern: Forgetting to Clean Up
+
+**What goes wrong:** Stale worktrees waste disk space (each has its own node_modules, build artifacts, etc.) and create confusion when you stumble upon them weeks later.
+
+**Instead:** Clean up immediately after the worktree's purpose is served. Set a reminder if needed. Run `git worktree list` as part of your weekly routine.
+
+**Check:** `du -sh ../myapp-*` to see how much space worktrees are consuming.
+
+### Anti-Pattern: Shared Dependencies
+
+**What goes wrong:** You assume worktrees share node_modules (they do not). You run the project in a new worktree without installing dependencies and get cryptic errors.
+
+**Instead:** Run `bun install` (or the project's dependency install command) in every new worktree. Each worktree has its own dependency tree. This is by design — different branches may have different dependencies.
+
+### Anti-Pattern: Checking Out the Same Branch
+
+**What goes wrong:** You try to check out the same branch in two worktrees. Git prevents this with an error. You bypass it with `--force` and corrupt the index.
+
+**Instead:** Never check out the same branch in two worktrees. If you need to see the same code in two places, use `git show branch:file` or create a copy. If you need to move a branch to a different worktree, first remove the old worktree.
+
+### Anti-Pattern: Worktrees Inside the Main Repo
+
+**What goes wrong:** You create worktrees inside the main repository directory (`./worktrees/feature-name`). This confuses tools, IDEs, and sometimes Git itself.
+
+**Instead:** Always create worktrees as siblings of the main repository (`../project-feature-name`). This keeps each worktree's directory tree clean and avoids nesting issues.
+
+## Failure Modes
+
+### "fatal: branch is already checked out"
+
+**Cause:** You are trying to check out a branch that is already checked out in another worktree. Git prevents this to avoid index corruption.
+
+**Fix:** Either: (a) use a different branch, (b) remove the other worktree first with `git worktree remove`, or (c) create a new branch from the desired commit with `git worktree add -b new-name ../path commit`.
+
+### "fatal: path already exists"
+
+**Cause:** The target directory for the worktree already exists (from a previous worktree that was not properly cleaned up, or a coincidental name collision).
+
+**Fix:** Either: (a) choose a different path, (b) remove the existing directory if it is safe to do so, or (c) run `git worktree prune` if the directory is a stale worktree reference.
+
+### Merge Conflicts When Syncing
+
+**Cause:** Both worktrees modified the same files on different branches. When you try to merge or rebase, conflicts arise.
+
+**Fix:** Handle like normal Git conflicts. The worktree does not change the conflict resolution process. Resolve in whichever worktree is doing the merge.
+
+### Node Modules Out of Sync
+
+**Cause:** You pulled new changes in a worktree but did not re-install dependencies. The lockfile changed but node_modules is stale.
+
+**Fix:** Run `bun install` after pulling changes. If issues persist, delete node_modules and reinstall: `rm -rf node_modules && bun install`.
+
+### IDE Not Recognizing Worktree
+
+**Cause:** Some IDEs get confused when multiple directories share the same `.git` repository.
+
+**Fix:** Open the worktree directory directly (not the parent). Most modern editors (VS Code, Cursor, Zed) handle worktrees correctly when you open the worktree root as the project.
+
+## Quick Reference
+
+```bash
+# Create worktree (existing branch)
+git worktree add ../project-branch branch-name
+
+# Create worktree (new branch from base)
+git worktree add -b new-branch ../project-branch base-branch
+
+# List all worktrees
+git worktree list
+
+# Remove worktree
+git worktree remove ../project-branch
+
+# Clean stale references
+git worktree prune
+```
+
+**Remember:** Install dependencies in every new worktree. Clean up when done. Limit to 2-3 active worktrees.