opencode agents

home/common/programs/opencode/commands/issue.md

@@ -0,0 +1,38 @@
+---
+description: Analyze and fix a GitHub issue end-to-end (plan, branch, implement, test, PR)
+model: claude-sonnet-4-0
+---
+
+Please analyze and fix the GitHub issue: $ARGUMENTS.
+
+Follow these steps:
+
+# PLAN
+1. Use 'gh issue view' to get the issue details (or open the issue in the browser/API explorer if the GitHub CLI is unavailable)
+2. Understand the problem described in the issue
+3. Ask clarifying questions if necessary
+4. Understand the prior art for this issue
+- Search the scratchpads for previous thoughts related to the issue
+- Search PRs to see if you can find history on this issue
+- Search the codebase for relevant files
+5. Think harder about how to break the issue down into a series of small, manageable tasks.
+6. Document your plan in a new scratchpad
+  - include the issue name in the filename
+  - include a link to the issue in the scratchpad.
+
+# CREATE
+- Create a new branch for the issue
+- Solve the issue in small, manageable steps, according to your plan.
+- Commit your changes after each step.
+
+# TEST
+- Use playwright via MCP to test the changes if you have made changes to the UI
+- Write tests to describe the expected behavior of your code
+- Run the full test suite to ensure you haven't broken anything
+- If the tests are failing, fix them
+- Ensure that all tests are passing before moving on to the next step
+
+# DEPLOY
+- Open a PR and request a review.
+
+Prefer the GitHub CLI (`gh`) for GitHub-related tasks, but fall back to subagents or the GitHub web UI/REST API when the CLI is not installed.

home/common/programs/opencode/commands/merge.md

@@ -0,0 +1,23 @@
+---
+description: Merge a worktree branch back into the base branch
+---
+Merge a branch from the worktree.
+If you're currently working on a worktree, assume that's the one I'm referring to.
+
+Start by committing any staged and unstaged changes. I may have made changes to the worktree manually.
+Then merge back the new main branch, since I may have made changes to it.
+
+# Language specific:
+
+## Rust
+
+Ensure cargo check is happy.
+Ensure clippy is happy. clean up any new warnings.
+
+## Typescript
+
+Ensure tsc is happy.
+
+# Finally
+
+Squash the commits into a single one, merge into the base branch, and delete the worktree.

home/common/programs/opencode/commands/remove-deadcode.md

@@ -0,0 +1,323 @@
+---
+description: Remove unused code with LSP-verified safety, atomic commits
+---
+
+<command-instruction>
+You are a dead code removal specialist. Execute the FULL dead code removal workflow.
+
+Your core weapon: **LSP FindReferences**. If a symbol has ZERO external references, it's dead. Remove it.
+
+## CRITICAL RULES
+
+1. **LSP is law.** Never guess. Always verify with `LspFindReferences` before removing ANYTHING.
+2. **One removal = one commit.** Every dead code removal gets its own atomic commit.
+3. **Test after every removal.** Run tests after each. If it fails, REVERT and skip.
+4. **Leaf-first order.** Remove deepest unused symbols first, then work up the dependency chain. Removing a leaf may expose new dead code upstream.
+5. **Never remove entry points.** `src/index.ts`, `src/cli/index.ts`, test files, config files, and files in `packages/` are off-limits unless explicitly targeted.
+
+---
+
+## STEP 0: REGISTER TODO LIST (MANDATORY FIRST ACTION)
+
+```
+TodoWrite([
+  {"id": "scan", "content": "PHASE 1: Scan codebase for dead code candidates using LSP + explore agents", "status": "pending", "priority": "high"},
+  {"id": "verify", "content": "PHASE 2: Verify each candidate with LspFindReferences - zero false positives", "status": "pending", "priority": "high"},
+  {"id": "plan", "content": "PHASE 3: Plan removal order (leaf-first dependency order)", "status": "pending", "priority": "high"},
+  {"id": "remove", "content": "PHASE 4: Remove dead code one-by-one (remove -> test -> commit loop)", "status": "pending", "priority": "high"},
+  {"id": "final", "content": "PHASE 5: Final verification - full test suite + build + typecheck", "status": "pending", "priority": "high"}
+])
+```
+
+---
+
+## PHASE 1: SCAN FOR DEAD CODE CANDIDATES
+
+**Mark scan as in_progress.**
+
+### 1.1: Launch Parallel Explore Agents (ALL BACKGROUND)
+
+Fire ALL simultaneously:
+
+```
+// Agent 1: Find all exported symbols
+delegate_task(subagent_type="explore", run_in_background=true,
+  prompt="Find ALL exported functions, classes, types, interfaces, and constants across src/.
+  List each with: file path, line number, symbol name, export type (named/default).
+  EXCLUDE: src/index.ts root exports, test files.
+  Return as structured list.")
+
+// Agent 2: Find potentially unused files
+delegate_task(subagent_type="explore", run_in_background=true,
+  prompt="Find files in src/ that are NOT imported by any other file.
+  Check import/require statements across the entire codebase.
+  EXCLUDE: index.ts files, test files, entry points, config files, .md files.
+  Return list of potentially orphaned files.")
+
+// Agent 3: Find unused imports within files
+delegate_task(subagent_type="explore", run_in_background=true,
+  prompt="Find unused imports across src/**/*.ts files.
+  Look for import statements where the imported symbol is never referenced in the file body.
+  Return: file path, line number, imported symbol name.")
+
+// Agent 4: Find functions/variables only used in their own declaration
+delegate_task(subagent_type="explore", run_in_background=true,
+  prompt="Find private/non-exported functions, variables, and types in src/**/*.ts that appear
+  to have zero usage beyond their declaration. Return: file path, line number, symbol name.")
+```
+
+### 1.2: Direct AST-Grep Scans (WHILE AGENTS RUN)
+
+```typescript
+// Find unused imports pattern
+ast_grep_search(pattern="import { $NAME } from '$PATH'", lang="typescript", paths=["src/"])
+
+// Find empty export objects
+ast_grep_search(pattern="export {}", lang="typescript", paths=["src/"])
+```
+
+### 1.3: Collect All Results
+
+Collect background agent results. Compile into a master candidate list:
+
+```
+## DEAD CODE CANDIDATES
+
+| # | File | Line | Symbol | Type | Confidence |
+|---|------|------|--------|------|------------|
+| 1 | src/foo.ts | 42 | unusedFunc | function | HIGH |
+| 2 | src/bar.ts | 10 | OldType | type | MEDIUM |
+```
+
+**Mark scan as completed.**
+
+---
+
+## PHASE 2: VERIFY WITH LSP (ZERO FALSE POSITIVES)
+
+**Mark verify as in_progress.**
+
+For EVERY candidate from Phase 1, run this verification:
+
+### 2.1: The LSP Verification Protocol
+
+For each candidate symbol:
+
+```typescript
+// Step 1: Find the symbol's exact position
+LspDocumentSymbols(filePath)  // Get line/character of the symbol
+
+// Step 2: Find ALL references across the ENTIRE workspace
+LspFindReferences(filePath, line, character, includeDeclaration=false)
+// includeDeclaration=false -> only counts USAGES, not the definition itself
+
+// Step 3: Evaluate
+// 0 references -> CONFIRMED DEAD CODE
+// 1+ references -> NOT dead, remove from candidate list
+```
+
+### 2.2: False Positive Guards
+
+**NEVER mark as dead code if:**
+- Symbol is in `src/index.ts` (package entry point)
+- Symbol is in any `index.ts` that re-exports (barrel file check: look if it's re-exported)
+- Symbol is referenced in test files (tests are valid consumers)
+- Symbol has `@public` or `@api` JSDoc tags
+- Symbol is in a file listed in `package.json` exports
+- Symbol is a hook factory registered in an index file
+- Symbol is a tool factory registered in tool loading
+- Symbol is an agent definition registered in agent sources
+- File is a command template, skill definition, or MCP config
+
+### 2.3: Build Confirmed Dead Code List
+
+After verification, produce:
+
+```
+## CONFIRMED DEAD CODE (LSP-verified, 0 external references)
+
+| # | File | Line | Symbol | Type | Safe to Remove |
+|---|------|------|--------|------|----------------|
+| 1 | src/foo.ts | 42 | unusedFunc | function | YES |
+```
+
+**If ZERO confirmed dead code found: Report "No dead code found" and STOP.**
+
+**Mark verify as completed.**
+
+---
+
+## PHASE 3: PLAN REMOVAL ORDER
+
+**Mark plan as in_progress.**
+
+### 3.1: Dependency Analysis
+
+For each confirmed dead symbol:
+1. Check if removing it would expose other dead code
+2. Check if other dead symbols depend on this one
+3. Build removal dependency graph
+
+### 3.2: Order by Leaf-First
+
+```
+Removal Order:
+1. [Leaf symbols - no other dead code depends on them]
+2. [Intermediate symbols - depended on only by already-removed dead code]
+3. [Dead files - entire files with no live exports]
+```
+
+### 3.3: Register Granular Todos
+
+Create one todo per removal.
+
+**Mark plan as completed.**
+
+---
+
+## PHASE 4: ITERATIVE REMOVAL LOOP
+
+**Mark remove as in_progress.**
+
+For EACH dead code item, execute this exact loop:
+
+### 4.1: Pre-Removal Check
+
+```typescript
+// Re-verify it's still dead (previous removals may have changed things)
+LspFindReferences(filePath, line, character, includeDeclaration=false)
+// If references > 0 now -> SKIP (previous removal exposed a new consumer)
+```
+
+### 4.2: Remove the Dead Code
+
+Use appropriate tool:
+
+**For unused imports:**
+```typescript
+Edit(filePath, oldString="import { deadSymbol } from '...';\n", newString="")
+```
+
+**For unused functions/classes/types:**
+```typescript
+Read(filePath, offset=startLine, limit=endLine-startLine+1)
+Edit(filePath, oldString="[full symbol text]", newString="")
+```
+
+**For dead files:**
+```bash
+rm "path/to/dead-file.ts"
+```
+
+**After removal, also clean up:**
+- Remove any imports that were ONLY used by the removed code
+- Remove any now-empty import statements
+- Fix any trailing whitespace / double blank lines left behind
+
+### 4.3: Post-Removal Verification
+
+```typescript
+// 1. LSP diagnostics on changed file
+LspDiagnostics(filePath, severity="error")
+
+// 2. Run tests
+bash("npm test")  // or bun test, cargo test, etc.
+
+// 3. Typecheck
+bash("npm run typecheck")  // or equivalent
+```
+
+### 4.4: Handle Failures
+
+If ANY verification fails:
+1. **REVERT** the change immediately (`git checkout -- [file]`)
+2. Mark this removal todo as `cancelled` with note: "Removal caused [error]. Skipped."
+3. Proceed to next item
+
+### 4.5: Commit
+
+```bash
+git add [changed-files]
+git commit -m "refactor: remove unused [symbolType] [symbolName] from [filePath]"
+```
+
+Mark this removal todo as `completed`.
+
+### 4.6: Re-scan After Removal
+
+After removing a symbol, check if its removal exposed NEW dead code:
+- Were there imports that only existed to serve the removed symbol?
+- Are there other symbols in the same file now unreferenced?
+
+If new dead code is found, add it to the removal queue.
+
+**Repeat 4.1-4.6 for every item. Mark remove as completed when done.**
+
+---
+
+## PHASE 5: FINAL VERIFICATION
+
+**Mark final as in_progress.**
+
+### 5.1: Full Test Suite
+```bash
+npm test
+```
+
+### 5.2: Full Typecheck
+```bash
+npm run typecheck
+```
+
+### 5.3: Full Build
+```bash
+npm run build
+```
+
+### 5.4: Summary Report
+
+```markdown
+## Dead Code Removal Complete
+
+### Removed
+| # | Symbol | File | Type | Commit |
+|---|--------|------|------|--------|
+| 1 | unusedFunc | src/foo.ts | function | abc1234 |
+
+### Skipped (caused failures)
+| # | Symbol | File | Reason |
+|---|--------|------|--------|
+| 1 | riskyFunc | src/bar.ts | Test failure: [details] |
+
+### Verification
+- Tests: PASSED (X/Y passing)
+- Typecheck: CLEAN
+- Build: SUCCESS
+- Total dead code removed: N symbols across M files
+- Total commits: K atomic commits
+```
+
+**Mark final as completed.**
+
+---
+
+## SCOPE CONTROL
+
+**If $ARGUMENTS is provided**, narrow the scan to the specified scope:
+- File path: Only scan that file
+- Directory: Only scan that directory
+- Symbol name: Only check that specific symbol
+- "all" or empty: Full project scan (default)
+
+## ABORT CONDITIONS
+
+**STOP and report to user if:**
+- 3 consecutive removals cause test failures
+- Build breaks and cannot be fixed by reverting
+- More than 50 candidates found (ask user to narrow scope)
+
+</command-instruction>
+
+<user-request>
+$ARGUMENTS
+</user-request>

home/common/programs/opencode/commands/smart-debug.md

@@ -0,0 +1,69 @@
+---
+description: Debug complex issues with root cause analysis and multiple fix approaches
+model: claude-sonnet-4-0
+---
+
+Debug complex issues using specialized debugging agents:
+
+## Debugging Approach
+
+### 1. Primary Debug Analysis
+Use Task tool with subagent_type="debugger" to:
+- Analyze error messages and stack traces
+- Identify code paths leading to the issue
+- Reproduce the problem systematically
+- Isolate the root cause
+- Suggest multiple fix approaches
+
+Prompt: "Debug issue: $ARGUMENTS. Provide detailed analysis including:
+1. Error reproduction steps
+2. Root cause identification
+3. Code flow analysis leading to the error
+4. Multiple solution approaches with trade-offs
+5. Recommended fix with implementation details"
+
+### 2. Performance Debugging (if performance-related)
+If the issue involves performance problems, also use Task tool with subagent_type="performance-engineer" to:
+- Profile code execution
+- Identify bottlenecks
+- Analyze resource usage
+- Suggest optimization strategies
+
+Prompt: "Profile and debug performance issue: $ARGUMENTS. Include:
+1. Performance metrics and profiling data
+2. Bottleneck identification
+3. Resource usage analysis
+4. Optimization recommendations
+5. Before/after performance projections"
+
+## Debug Output Structure
+
+### Root Cause Analysis
+- Precise identification of the bug source
+- Explanation of why the issue occurs
+- Impact analysis on other components
+
+### Reproduction Guide
+- Step-by-step reproduction instructions
+- Required environment setup
+- Test data or conditions needed
+
+### Solution Options
+1. **Quick Fix** - Minimal change to resolve issue
+   - Implementation details
+   - Risk assessment
+
+2. **Proper Fix** - Best long-term solution
+   - Refactoring requirements
+   - Testing needs
+
+3. **Preventive Measures** - Avoid similar issues
+   - Code patterns to adopt
+   - Tests to add
+
+### Implementation Guide
+- Specific code changes needed
+- Order of operations for the fix
+- Validation steps
+
+Issue to debug: $ARGUMENTS

home/common/programs/opencode/commands/tdd-cycle.md

@@ -0,0 +1,155 @@
+---
+description: Execute a full TDD red-green-refactor cycle
+model: claude-opus-4-1
+---
+
+Execute a comprehensive Test-Driven Development (TDD) workflow with strict red-green-refactor discipline:
+
+## Configuration
+
+### Coverage Thresholds
+- Minimum line coverage: 80%
+- Minimum branch coverage: 75%
+- Critical path coverage: 100%
+
+### Refactoring Triggers
+- Cyclomatic complexity > 10
+- Method length > 20 lines
+- Class length > 200 lines
+- Duplicate code blocks > 3 lines
+
+## Phase 1: Test Specification and Design
+
+### 1. Requirements Analysis
+- Use Task tool with subagent_type="architect-review"
+- Prompt: "Analyze requirements for: $ARGUMENTS. Define acceptance criteria, identify edge cases, and create test scenarios. Output a comprehensive test specification."
+- Output: Test specification, acceptance criteria, edge case matrix
+- Validation: Ensure all requirements have corresponding test scenarios
+
+### 2. Test Architecture Design
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Design test architecture for: $ARGUMENTS based on test specification. Define test structure, fixtures, mocks, and test data strategy. Ensure testability and maintainability."
+- Output: Test architecture, fixture design, mock strategy
+- Validation: Architecture supports isolated, fast, reliable tests
+
+## Phase 2: RED - Write Failing Tests
+
+### 3. Write Unit Tests (Failing)
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Write FAILING unit tests for: $ARGUMENTS. Tests must fail initially. Include edge cases, error scenarios, and happy paths. DO NOT implement production code."
+- Output: Failing unit tests, test documentation
+- **CRITICAL**: Verify all tests fail with expected error messages
+
+### 4. Verify Test Failure
+- Use Task tool with subagent_type="code-reviewer"
+- Prompt: "Verify that all tests for: $ARGUMENTS are failing correctly. Ensure failures are for the right reasons (missing implementation, not test errors). Confirm no false positives."
+- Output: Test failure verification report
+- **GATE**: Do not proceed until all tests fail appropriately
+
+## Phase 3: GREEN - Make Tests Pass
+
+### 5. Minimal Implementation
+- Use Task tool with subagent_type="backend-architect"
+- Prompt: "Implement MINIMAL code to make tests pass for: $ARGUMENTS. Focus only on making tests green. Do not add extra features or optimizations. Keep it simple."
+- Output: Minimal working implementation
+- Constraint: No code beyond what's needed to pass tests
+
+### 6. Verify Test Success
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Run all tests for: $ARGUMENTS and verify they pass. Check test coverage metrics. Ensure no tests were accidentally broken."
+- Output: Test execution report, coverage metrics
+- **GATE**: All tests must pass before proceeding
+
+## Phase 4: REFACTOR - Improve Code Quality
+
+### 7. Code Refactoring
+- Use Task tool with subagent_type="code-reviewer"
+- Prompt: "Refactor implementation for: $ARGUMENTS while keeping tests green. Apply SOLID principles, remove duplication, improve naming, and optimize performance. Run tests after each refactoring."
+- Output: Refactored code, refactoring report
+- Constraint: Tests must remain green throughout
+
+### 8. Test Refactoring
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Refactor tests for: $ARGUMENTS. Remove test duplication, improve test names, extract common fixtures, and enhance test readability. Ensure tests still provide same coverage."
+- Output: Refactored tests, improved test structure
+- Validation: Coverage metrics unchanged or improved
+
+## Phase 5: Integration and System Tests
+
+### 9. Write Integration Tests (Failing First)
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Write FAILING integration tests for: $ARGUMENTS. Test component interactions, API contracts, and data flow. Tests must fail initially."
+- Output: Failing integration tests
+- Validation: Tests fail due to missing integration logic
+
+### 10. Implement Integration
+- Use Task tool with subagent_type="backend-architect"
+- Prompt: "Implement integration code for: $ARGUMENTS to make integration tests pass. Focus on component interaction and data flow."
+- Output: Integration implementation
+- Validation: All integration tests pass
+
+## Phase 6: Continuous Improvement Cycle
+
+### 11. Performance and Edge Case Tests
+- Use Task tool with subagent_type="test-automator"
+- Prompt: "Add performance tests and additional edge case tests for: $ARGUMENTS. Include stress tests, boundary tests, and error recovery tests."
+- Output: Extended test suite
+- Metric: Increased test coverage and scenario coverage
+
+### 12. Final Code Review
+- Use Task tool with subagent_type="architect-review"
+- Prompt: "Perform comprehensive review of: $ARGUMENTS. Verify TDD process was followed, check code quality, test quality, and coverage. Suggest improvements."
+- Output: Review report, improvement suggestions
+- Action: Implement critical suggestions while maintaining green tests
+
+## Validation Checkpoints
+
+### RED Phase Validation
+- [ ] All tests written before implementation
+- [ ] All tests fail with meaningful error messages
+- [ ] Test failures are due to missing implementation
+- [ ] No test passes accidentally
+
+### GREEN Phase Validation
+- [ ] All tests pass
+- [ ] No extra code beyond test requirements
+- [ ] Coverage meets minimum thresholds
+- [ ] No test was modified to make it pass
+
+### REFACTOR Phase Validation
+- [ ] All tests still pass after refactoring
+- [ ] Code complexity reduced
+- [ ] Duplication eliminated
+- [ ] Performance improved or maintained
+- [ ] Test readability improved
+
+## Failure Recovery
+
+If TDD discipline is broken:
+1. **STOP** immediately
+2. Identify which phase was violated
+3. Rollback to last valid state
+4. Resume from correct phase
+5. Document lesson learned
+
+## Anti-Patterns to Avoid
+
+- Writing implementation before tests
+- Writing tests that already pass
+- Skipping the refactor phase
+- Writing multiple features without tests
+- Modifying tests to make them pass
+- Ignoring failing tests
+- Writing tests after implementation
+
+## Success Criteria
+
+- 100% of code written test-first
+- All tests pass continuously
+- Coverage exceeds thresholds
+- Code complexity within limits
+- Zero defects in covered code
+- Clear test documentation
+- Fast test execution (< 5 seconds for unit tests)
+
+TDD implementation for: $ARGUMENTS

home/common/programs/opencode/commands/update.md

@@ -0,0 +1,9 @@
+---
+description: Rebase/merge upstream changes into the current branch
+---
+This command should only work while in a secondary branch (not main or master).
+
+Commit any unstaged changes
+Fetch updates from the origin repo
+If there are new commits on the parent branch (typically origin/main), then merge them back into the current branch
+Solve any conflicts, and analyze the incoming changes to see if additional changes are required to the branch's code (e.g.: if something was renamed in the meantime in main, our new code may need to be adjusted)

home/common/programs/opencode/commands/work.md

@@ -0,0 +1,8 @@
+---
+description: Start a new feature in a git worktree
+---
+In a worktrees directory inside the git project's root, create a new worktree for the requested feature.
+create the directory if it doesn't exist.
+keep the branch name concise, and don't include "opencode" in its name.
+do all the work for the feature in the new worktree.
+run "kitty @ set-tab-title" to set the tab title of this kitty session to "<project>/<feature>"