opencodekit 0.23.3 → 0.23.4

package/dist/template/.opencode/skill/agent-teams/SKILL.md

@@ -1,268 +0,0 @@
----
-name: agent-teams
-description: >
-  Use when working with Claude Code-style agent teams for parallel research, review, competing hypotheses,
-  or any task that benefits from multiple agents working simultaneously under a lead coordinator.
-  Covers team configuration, task distribution, coordination patterns, and best practices.
-version: "1.0.0"
-license: MIT
-tags: [agent-coordination, workflow]
-dependencies: []
----
-
-# Agent Teams - Multi-Agent Team Coordination
-
-> **Replaces** single-agent sequential work when tasks benefit from parallel research, review, or competing hypotheses
-
-## When to Use
-
-- Parallel research, review, or competing approaches that need coordination
-- Tasks benefit from shared findings and a lead coordinating teammates
-
-## When NOT to Use
-
-- Single-agent tasks or tightly coupled edits where coordination overhead is wasteful
-- Simple parallel work that can use fire-and-forget subagents instead
-
-## Overview
-
-**Agent Teams = Lead + Teammates + Shared Task List + Messaging**
-
-- **Lead agent**: Coordinates the team - distributes tasks, monitors progress, synthesizes results
-- **Teammates**: Execute tasks independently but can message each other and the lead
-- **Task list**: Shared work queue that the lead manages
-- **Messaging**: Bidirectional communication between lead and teammates
-
-## When to Use Agent Teams vs Subagents
-
-| Criteria              | Agent Teams                            | Subagents (Task tool)               |
-| --------------------- | -------------------------------------- | ----------------------------------- |
-| **Coordination**      | Lead coordinates, teammates message    | Fire-and-forget, results return     |
-| **Communication**     | Bidirectional messaging                | One-way (result only)               |
-| **Task reassignment** | Dynamic - lead can reassign            | Fixed - each subagent does its task |
-| **Context sharing**   | Shared through lead                    | Independent contexts                |
-| **Best for**          | Research, review, competing approaches | Independent implementation tasks    |
-| **Overhead**          | Higher - coordination cost             | Lower - no coordination             |
-
-### Decision Matrix
-
-```
-Need coordination between workers?  → Agent Teams
-Workers are fully independent?      → Subagents (Task tool)
-Need competing hypotheses?          → Agent Teams
-Need shared findings?               → Agent Teams
-Simple parallel execution?          → Subagents (Task tool)
-```
-
-### Parallel Skill Selection
-
-| Scenario                                    | Use This Skill              |
-| ------------------------------------------- | --------------------------- |
-| 3+ independent bug investigations           | dispatching-parallel-agents |
-| Coordinated team (research + review + impl) | agent-teams                 |
-| Large plan with dependency graph            | swarm-coordination          |
-| 2 independent tasks                         | Just use 2 Task() calls     |
-
-## When to Use
-
-- **Parallel research**: Multiple agents researching different aspects of a problem
-- **Code review**: Multiple reviewers examining different files/concerns
-- **Competing hypotheses**: Agents try different approaches, best one wins
-- **Large refactors**: Agents handle different subsystems with coordination
-- **Architecture exploration**: Agents explore different design options simultaneously
-
-## When NOT to Use
-
-- Single-agent tasks (overhead not worth it)
-- Tightly coupled work where agents would constantly block each other
-- Tasks under 3 independent units of work
-- Simple file edits with no research needed
-
-## Team Configuration Patterns
-
-### Pattern 1: Research Team
-
-```
-Lead: build agent
-├── Teammate 1 (explore): Search codebase for existing patterns
-├── Teammate 2 (scout): Research external docs and best practices
-└── Teammate 3 (review): Analyze current implementation for issues
-```
-
-**Use when**: Entering unfamiliar territory, evaluating new libraries, understanding complex systems.
-
-### Pattern 2: Review Team
-
-```
-Lead: build agent
-├── Teammate 1 (review): Security audit
-├── Teammate 2 (review): Performance review
-└── Teammate 3 (review): Architecture review
-```
-
-**Use when**: Pre-merge review of significant features, security-sensitive changes.
-
-### Pattern 3: Competing Approaches
-
-```
-Lead: build agent
-├── Teammate 1 (general): Implement approach A
-├── Teammate 2 (general): Implement approach B
-└── Teammate 3 (general): Implement approach C
-```
-
-**Use when**: Multiple valid solutions exist and you need to compare empirically.
-
-### Pattern 4: Subsystem Team
-
-```
-Lead: build agent
-├── Teammate 1 (general): Handle frontend changes
-├── Teammate 2 (general): Handle backend changes
-└── Teammate 3 (general): Handle database migrations
-```
-
-**Use when**: Large features spanning multiple subsystems with clear boundaries.
-
-## Best Practices
-
-### Task Distribution
-
-1. **5-6 tasks per teammate maximum** - More than this degrades quality
-2. **Clear boundaries** - Each teammate should own distinct files/modules
-3. **Avoid file conflicts** - Never assign the same file to multiple teammates
-4. **Include verification** - Each task should include its own verification step
-
-### Coordination
-
-1. **Lead synthesizes** - Don't let teammates make final decisions; lead integrates
-2. **Regular check-ins** - Lead should review intermediate results, not just final
-3. **Fail fast** - If a teammate hits a blocker, escalate to lead immediately
-4. **Shared conventions** - Establish naming, formatting, and style before dispatching
-
-### Communication
-
-1. **Task descriptions should be self-contained** - Teammate shouldn't need to ask clarifying questions
-2. **Include context** - What files to read, what patterns to follow, what constraints exist
-3. **Specify output format** - What should the teammate report back?
-4. **Include acceptance criteria** - How does the lead know the task is done?
-
-## Implementation with OpenCode
-
-### Using the Task Tool (Current)
-
-```typescript
-// Spawn research team
-const codebaseAnalysis = Task({
-  subagent_type: "explore",
-  description: "Analyze auth patterns",
-  prompt: `Research authentication patterns in this codebase:
-    1. Find all auth-related files
-    2. Map the auth flow
-    3. Identify potential security issues
-    Report back: file list, flow diagram, issues found`,
-});
-
-const externalResearch = Task({
-  subagent_type: "scout",
-  description: "Research JWT best practices",
-  prompt: `Research current JWT best practices:
-    1. Token rotation patterns
-    2. Refresh token security
-    3. Common vulnerabilities
-    Report back: recommended patterns with code examples`,
-});
-
-const codeReview = Task({
-  subagent_type: "review",
-  description: "Review auth security",
-  prompt: `Security review of auth implementation:
-    1. Check token storage
-    2. Verify CSRF protection
-    3. Audit session management
-    Report back: vulnerabilities found with severity ratings`,
-});
-
-// Lead synthesizes all results into unified recommendation
-```
-
-### Using Swarm Coordination (Advanced)
-
-For more structured parallel work, combine with the `swarm-coordination` skill:
-
-```typescript
-// Load swarm for structured coordination
-skill({ name: "swarm-coordination" });
-
-// Analyze and plan
-swarm({ op: "plan", task: "Implement auth overhaul across 3 subsystems" });
-
-// Create delegation packets
-swarm({
-  op: "delegate",
-  bead_id: "auth-frontend",
-  title: "Frontend auth components",
-  outcome: "All auth forms and guards updated",
-  must_do: "Follow existing component patterns, run component tests",
-  must_not: "Don't modify API contracts, don't add new dependencies",
-});
-```
-
-## Anti-Patterns
-
-### ❌ Too Many Teammates
-
-```
-Lead
-├── T1: Button component     ← Too granular
-├── T2: Input component      ← Too granular
-├── T3: Form component       ← Too granular
-├── T4: Modal component      ← Too granular
-├── T5: Toast component      ← Too granular
-├── T6: Dialog component     ← Too granular
-├── T7: Dropdown component   ← Too granular
-└── T8: Tabs component       ← Too granular
-```
-
-**Fix**: Group related work. 2-3 teammates handling related components each.
-
-### ❌ Overlapping File Ownership
-
-```
-T1: Refactor auth service     ← Both touch auth.ts!
-T2: Add new auth endpoint     ← Both touch auth.ts!
-```
-
-**Fix**: One teammate owns auth.ts changes. The other waits or works on different files.
-
-### ❌ Missing Context
-
-```
-Task({ prompt: "Fix the auth bug" })  ← Which bug? What file? What behavior?
-```
-
-**Fix**: Include file paths, error messages, expected vs actual behavior, and reproduction steps.
-
-### ❌ No Verification
-
-```
-Task({ prompt: "Implement feature X" })  ← No way to verify success
-```
-
-**Fix**: Include acceptance criteria: "Run `npm test auth`, ensure all pass. Run `npm run typecheck`."
-
-## Checklist
-
-Before dispatching a team:
-
-- [ ] Identified 3+ independent tasks (otherwise use single agent)
-- [ ] Each task has clear file ownership (no overlaps)
-- [ ] Each task has self-contained context (files, patterns, constraints)
-- [ ] Each task has acceptance criteria (verification commands)
-- [ ] Lead has a synthesis plan (how to integrate results)
-- [ ] Tasks are sized appropriately (5-6 per teammate max)
-
-## See Also
-
-- `dispatching-parallel-agents` — for independent debugging-focused parallel investigations
-- `swarm-coordination` — for dependency-aware large-plan execution

package/dist/template/.opencode/skill/code-navigation/SKILL.md

@@ -1,142 +0,0 @@
----
-name: code-navigation
-description: Use when navigating unfamiliar code, tracing cross-file dependencies, or before editing — efficient code reading patterns that minimize tool calls and token waste
-version: 1.0.0
-tags: [workflow, code-quality, context]
-dependencies: []
-agent_types: [planner, worker, reviewer]
-tools: []
----
-
-# Code Navigation Skill
-
-## When to Use
-
-- Exploring an unfamiliar codebase or module
-- Tracing a function call across multiple files
-- Understanding blast radius before a breaking change
-- Planning edits that touch multiple files
-
-## When NOT to Use
-
-- Simple single-file edits where you already know the location
-- Reading config or documentation files
-
-## Core Principle
-
-> Collapse multiple tool calls into fewer, smarter ones. Every unnecessary read or search wastes tokens and turns.
-
-## Choose The Right Navigation Tool
-
-- Use `srcwalk_read`, `srcwalk_deps`, `grep`, `csearch` for file reading, blast-radius checks, pattern search, and multi-keyword chunk search
-- Use `srcwalk_callers`, `srcwalk_callees`, `srcwalk_flow`, `srcwalk_impact`, `srcwalk_map` for call graphs, orientation slices, impact triage, and repo maps — these are first-class Pi tools, no separate skill load needed
-- All tools are backed by the installed `srcwalk` binary via the `srcwalk.ts` extension
-
-## Navigation Patterns
-
-### Pattern 1: Search First, Read Second
-
-**Wrong** (3-6 tool calls):
-```
-glob("*.ts") → read(file1) → "too big" → grep("functionName") → read(file2) → read(file3, section)
-```
-
-**Right** (1-2 tool calls):
-```
-grep("functionName", path: "src/") → read(exact_file, offset: line-10, limit: 30)
-```
-
-Start with `grep` or `csearch` to locate, then read only what you need.
-
-### Pattern 2: Multi-Symbol Search
-
-When tracing a call chain (A calls B calls C), search for all symbols together:
-```
-grep({ pattern: "functionA|functionB|functionC", path: "src/" })
-```
-
-Or use `srcwalk_callers` for structural caller detection, or `srcwalk_flow` for a combined callers+callees+resolves slice.
-
-### Pattern 3: Don't Re-Read What You've Already Seen
-
-**Anti-pattern**: Search returns full function body, then agent reads the same file again.
-
-If search results already show the code you need, work from that output. Only re-read when:
-- You need surrounding context (lines above/below the match)
-- You need the exact content for editing (verify before edit)
-- The search result was truncated
-
-### Pattern 4: Blast Radius Check (Before Breaking Changes)
-
-**WHEN**: Before renaming, removing, or changing the signature of an export.
-**SKIP**: When adding new code, fixing internal bugs, or reading.
-
-Steps:
-1. `srcwalk_deps(path: "src/file.ts")` — find importers and downstream users
-2. `srcwalk_callers({ symbol: "symbolName", scope: "src" })` — find call sites with optional depth/filter
-3. Review each caller to assess impact
-4. Plan edits from leaf callers inward (furthest dependencies first)
-
-### Pattern 5: Context Locality
-
-When editing a file, search results from the same directory/package are more likely relevant. Use `path` to scope grep results:
-- `grep({ pattern: "...", path: "src/same-module/" })`
-
-### Pattern 6: Outline Before Deep Read
-
-For large files (>200 lines), get the structure first:
-```
-srcwalk_read(path: "src/large-file.ts")
-```
-
-This gives you structure and line ranges. Then read only the section you need.
-
-### Pattern 7: Follow the Call Chain (Not the File Tree)
-
-**Wrong**: Read files top-to-bottom hoping to understand the flow.
-**Right**: Start from the entry point, follow function calls:
-
-```
-1. `grep({ pattern: "entryPoint" })` → find where it is defined
-2. `srcwalk_callees({ symbol: "entryPoint", scope: "src" })` or `srcwalk_flow` for call graph orientation
-3. `srcwalk_read(section: "line-range")` → drill into the interesting callee
-```
-
-## With Srcwalk Backend
-
-All navigation tools are native srcwalk_* tools. Available tools:
-
-| Task | Tool | Notes |
-|---|---|---|
-| Pattern search | `grep` | Exact/regex symbol search, multi-pattern, scoped |
-| Multi-keyword chunk search | `csearch` | Find code by multiple keywords, returns ranked function/class chunks |
-| Find files by glob | `glob` | Built-in glob file discovery |
-| Large file read | `srcwalk_read` | Auto-outlines, shows structure |
-| Direct callers | `srcwalk_callers` | Structural call-site evidence |
-| Transitive callers | `srcwalk_callers(depth: N)` | Multi-hop BFS up to 5 |
-| Forward call graph | `srcwalk_callees(detailed: true)` | Ordered sites with arg slots |
-| Function orientation | `srcwalk_flow` | Callers + callees + resolves |
-| Import + dependents | `srcwalk_deps` | File-scoped import evidence + heuristic |
-| Heuristic triage | `srcwalk_impact` | Follow up with callers for proof |
-| Repo shape | `srcwalk_map` | Token budgets + directory skeleton |
-
-**IMPORTANT**: Use `grep` for exact-pattern searches, `csearch` for multi-keyword chunk discovery, and `srcwalk_*` tools for structural navigation (call graphs, deps, file reads).
-
-## Cost Awareness
-
-Every tool call has a token cost. Efficient navigation means:
-- Fewer tool calls per task
-- Less context consumed by redundant reads
-- More budget available for actual implementation
-
-**Target**: Find and understand any symbol in ≤3 tool calls, not 6+.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---|---|
-| Read entire large file | Use outline first, then section read |
-| Search → read same code again | Work from search results directly |
-| Trace calls one-by-one | `srcwalk_callers` / `srcwalk_callees` or multi-pattern `grep` |
-| Explore randomly | Start from entry point, follow calls |
-| Forget to check blast radius | Always check before signature changes |

package/dist/template/.opencode/skill/condition-based-waiting/SKILL.md

@@ -1,135 +0,0 @@
----
-name: condition-based-waiting
-description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
-version: 1.0.0
-tags: [testing, debugging]
-dependencies: []
----
-
-# Condition-Based Waiting
-
-> **Replaces** arbitrary `sleep()` / `setTimeout()` calls and hardcoded delays that cause flaky tests and slow CI
-
-## When to Use
-
-- Tests are flaky due to arbitrary delays or timing guesses
-- You need to wait for async state changes (events, file writes, state transitions)
-
-## When NOT to Use
-
-- You are explicitly testing timing behavior (debounce, throttle, intervals)
-- A fixed, documented timeout is part of the requirement
-
-## Common Rationalizations
-
-| Rationalization                               | Rebuttal                                                                       |
-| --------------------------------------------- | ------------------------------------------------------------------------------ |
-| "50ms is plenty of time"                      | It's plenty on YOUR machine. CI runners under load disagree                    |
-| "The sleep worked in local testing"           | Local = fast SSD, idle CPU. CI = shared resources, variable latency            |
-| "Adding a waitFor is more complex than sleep" | A 5-line waitFor is simpler than debugging a flaky test 10 times               |
-| "This operation is always fast"               | "Always" until garbage collection, disk I/O, or network latency says otherwise |
-| "I'll increase the timeout if it flakes"      | Increasing timeouts slows the entire suite and masks the real problem          |
-| "It only fails sometimes"                     | "Sometimes" = race condition. Condition-based waiting eliminates it entirely   |
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
-
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise((r) => setTimeout(r, 50));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined);
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario          | Pattern                                              |
-| ----------------- | ---------------------------------------------------- |
-| Wait for event    | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state    | `waitFor(() => machine.state === 'ready')`           |
-| Wait for count    | `waitFor(() => items.length >= 5)`                   |
-| Wait for file     | `waitFor(() => fs.existsSync(path))`                 |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)`         |
-
-## Implementation
-
-Generic polling function:
-
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000,
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result;
-
-    if (Date.now() - startTime > timeoutMs) {
-      throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
-    }
-
-    await new Promise((r) => setTimeout(r, 10)); // Poll every 10ms
-  }
-}
-```
-
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
-
-## Common Mistakes
-
-**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
-**✅ Fix:** Poll every 10ms
-
-**❌ No timeout:** Loop forever if condition never met
-**✅ Fix:** Always include timeout with clear error
-
-**❌ Stale data:** Cache state before loop
-**✅ Fix:** Call getter inside loop for fresh data
-
-## When Arbitrary Timeout IS Correct
-
-```typescript
-// Tool ticks every 100ms - need 2 ticks to verify partial output
-await waitForEvent(manager, "TOOL_STARTED"); // First: wait for condition
-await new Promise((r) => setTimeout(r, 200)); // Then: wait for timed behavior
-// 200ms = 2 ticks at 100ms intervals - documented and justified
-```
-
-**Requirements:**
-
-1. First wait for triggering condition
-2. Based on known timing (not guessing)
-3. Comment explaining WHY
-
-## Verification
-
-- **After applying:** run the previously flaky test 5+ times — should pass consistently
-- **Check:** no hardcoded sleep/delay values remain in the test file
-- **Measure:** test execution time should decrease (no wasted wait time)
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-
-- Fixed 15 flaky tests across 3 files
-- Pass rate: 60% → 100%
-- Execution time: 40% faster
-- No more race conditions
-
-## See Also
-
-- `systematic-debugging`
-- `test-driven-development`