opencodekit 0.18.1 → 0.18.3

package/dist/template/.opencode/skill/swarm-coordination/references/reconciler.md

@@ -0,0 +1,172 @@
+# Reconciler Agent Pattern (Self-Healing)
+
+The reconciler is the key to scaling beyond 50+ agents. Without reconciliation, broken builds cascade and the swarm collapses. The reconciler provides **continuous self-healing** by watching for failures and spawning targeted fix tasks.
+
+## When to Use Reconciler
+
+- **50+ agents** running in parallel → **REQUIRED**
+- **10-50 agents** → Recommended
+- **<10 agents** → Optional (leader can handle)
+
+## Reconciler Responsibilities
+
+1. **Watch CI/Build Status**: Monitor build gates continuously
+2. **Detect Failures**: Identify which worker caused the failure
+3. **Analyze Root Cause**: Determine if it's a merge conflict, test failure, or type error
+4. **Spawn Fix Tasks**: Create targeted fix tasks with context about what failed
+5. **Verify Fix**: Wait for fix to pass gates before continuing
+
+## Reconciler vs Leader
+
+| Aspect         | Leader                        | Reconciler                    |
+| -------------- | ----------------------------- | ----------------------------- |
+| Focus          | Orchestration, spawning       | Recovery, fixing              |
+| Runs           | At swarm start, between waves | Continuously during execution |
+| On failure     | Spawns workers                | Spawns fix tasks              |
+| Failure impact | Can't start work              | Wave can't complete           |
+
+## Implementing Reconciler
+
+The reconciler runs in a loop during swarm execution:
+
+```typescript
+// Reconciler runs in background during swarm execution
+async function runReconciler(teamName: string, buildCommand: string) {
+  while (swarmActive) {
+    // 1. Check build status
+    const status = await swarm({
+      operation: "monitor",
+      operation: "status",
+      team_name: teamName,
+    });
+    const stats = JSON.parse(status).summary;
+
+    // 2. If there are errors, investigate
+    if (stats.errors > 0) {
+      // 3. Get error details
+      const errors = await getWorkerErrors(teamName);
+
+      for (const error of errors) {
+        // 4. Analyze root cause
+        const cause = await analyzeError(error);
+
+        // 5. Spawn fix task
+        const fixBead = await br create({
+          title: `Fix: ${cause.summary}`,
+          type: "bug",
+          description: `Detected by reconciler: ${error.message}. Root cause: ${cause.rootCause}. Suggested fix: ${cause.suggestion}`,
+        });
+
+        // 6. Assign to targeted worker
+        await Task({
+          subagent_type: "general",
+          description: `Fix ${error.worker}`,
+          prompt: `Fix the error in ${error.file}.
+
+Error: ${error.message}
+Root cause: ${cause.rootCause}
+Suggested fix: ${cause.suggestion}
+
+Run: ${buildCommand}
+Verify: npm run typecheck && npm run lint`,
+        });
+      }
+    }
+
+    // Wait before next check
+    await sleep(30000); // Check every 30 seconds
+  }
+}
+```
+
+## Error Analysis Patterns
+
+The reconciler categorizes errors:
+
+| Error Type     | Detection                        | Fix Strategy                 |
+| -------------- | -------------------------------- | ---------------------------- |
+| Merge conflict | "CONFLICT" in output, git status | Re-base, resolve, force push |
+| Type error     | "typecheck failed"               | Fix types, run typecheck     |
+| Test failure   | "test failed", "expect" mismatch | Fix test or implementation   |
+| Lint error     | "lint failed", formatting issues | Run lint:fix                 |
+| Build error    | "build failed", bundler errors   | Fix imports, dependencies    |
+
+## Spawning Fix Tasks
+
+When the reconciler spawns a fix task, it includes:
+
+```typescript
+// Create fix task with full context
+await br create({
+  title: `Fix: ${error.type} in ${error.file}`,
+  type: "bug",
+  description: `## Error Detected
+- Worker: ${error.worker}
+- File: ${error.file}
+- Error: ${error.message}
+- Timestamp: ${error.timestamp}
+
+## Root Cause Analysis
+${cause.explanation}
+
+## Suggested Fix
+${cause.suggestion}
+
+## Verification
+Run: ${buildCommand}
+Must pass before wave can complete.`,
+});
+```
+
+## Reconciler in Wave Execution
+
+Add reconciler monitoring to each wave:
+
+```typescript
+// Execute wave with reconciler
+async function executeWaveWithReconciler(wave, teamName) {
+  // Start reconciler in background
+  const reconciler = runReconciler(teamName, "npm run typecheck && npm run lint");
+
+  // Execute workers in this wave
+  await Promise.all(wave.tasks.map(spawnWorker));
+
+  // Wait for all workers + reconciler to complete
+  await reconciler;
+
+  // Verify wave output before proceeding
+  await bash("npm run typecheck && npm run lint");
+}
+```
+
+## Example: Full Swarm with Reconciler
+
+```typescript
+// Full swarm execution with reconciler
+async function runSwarmWithReconciler(tasks, teamName) {
+  // 1. Analyze and create waves
+  const waves = createWaves(tasks);
+
+  // 2. Execute each wave with reconciler
+  for (const wave of waves) {
+    console.log(`Executing wave ${wave.number} with ${wave.tasks.length} tasks`);
+
+    // Start reconciler for this wave
+    const reconcilerPromise = runReconciler(teamName, "npm run typecheck && npm run lint");
+
+    // Spawn workers
+    await Promise.all(wave.tasks.map((task) => spawnWorker(task, teamName)));
+
+    // Wait for reconciler to finish fixing any errors
+    await reconcilerPromise;
+
+    // Verify wave output
+    const result = await bash("npm run typecheck && npm run lint");
+    if (!result.success) {
+      throw new Error(`Wave ${wave.number} failed gates`);
+    }
+
+    console.log(`Wave ${wave.number} complete`);
+  }
+}
+```

package/dist/template/.opencode/skill/swarm-coordination/references/tier-enforcement.md

@@ -0,0 +1,78 @@
+# Tier Enforcement (Longshot Pattern)
+
+For multi-agent execution at scale (10+ agents), enforce explicit tier hierarchy. This is the Longshot pattern that enabled 200 agents to build Minecraft.
+
+## Tier System
+
+| Tier            | Role                  | Swarm Equivalent | Responsibility                                                 |
+| --------------- | --------------------- | ---------------- | -------------------------------------------------------------- |
+| **planner**     | Lead orchestrator     | Build agent      | Analyzes scope, decomposes into sub-tasks, coordinates workers |
+| **sub-planner** | Mid-level coordinator | N/A              | Takes planner output, further decomposes, assigns to workers   |
+| **worker**      | Execution agent       | Worker agents    | Executes assigned work, reports progress                       |
+
+## When Tiers Are Required
+
+- **<10 agents**: Optional - flat decomposition works
+- **10-50 agents**: Recommended - planner + workers
+- **50+ agents**: Required - planner + sub-planners + workers
+
+## Enforcing Tier Boundaries
+
+The swarm leader enforces tier boundaries:
+
+```typescript
+// Tier enforcement in swarm execution
+async function enforceTiers(waves, tierConfig) {
+  // Wave 1: Planner tasks only
+  const planners = waves.filter((w) => w.tier === "planner");
+  await executeWave(planners);
+
+  // Wave 2: Sub-planner tasks (if any)
+  const subPlanners = waves.filter((w) => w.tier === "sub-planner");
+  await executeWave(subPlanners);
+
+  // Wave 3+: Worker tasks
+  const workers = waves.filter((w) => w.tier === "worker");
+  await executeWave(workers);
+}
+```
+
+## Handoff Contracts Between Tiers
+
+Each tier must declare handoff contracts:
+
+```typescript
+// Planner declares what it produces for sub-planners
+const plannerHandoff = {
+  produces: [
+    { artifact: "docs/auth-design.md", format: "markdown" },
+    { artifact: "tasks/auth-tasks.json", format: "json" },
+  ],
+  consumedBy: ["sub-planner-auth"],
+};
+
+// Worker declares what it consumes from sub-planners
+const workerHandoff = {
+  consumes: [{ artifact: "tasks/auth-tasks.json", format: "json" }],
+  produces: [{ artifact: "src/auth/service.ts", format: "typescript" }],
+};
+```
+
+## Anti-Pattern: Flat Decomposition at Scale
+
+Without tiers, 20 agents get 20 flat tasks → chaos:
+
+- Workers step on each other
+- No coordination between related work
+- Merge conflicts everywhere
+- No clear ownership
+
+With tiers (Longshot pattern):
+
+```
+Lead Planner → Sub-planner A → Worker 1, 2, 3
+              → Sub-planner B → Worker 4, 5, 6
+              Sub-planner C → Worker 7, 8, 9
+```
+
+This mirrors real engineering orgs: lead → tech lead → IC. The architecture is the differentiator.

package/dist/template/.opencode/skill/swarm-coordination/references/tmux-integration.md

@@ -0,0 +1,134 @@
+# Tmux Integration (Visual Swarm Monitoring)
+
+Enable real-time visualization of swarm workers in separate tmux panes.
+
+## Setup
+
+1. Start OpenCode inside tmux:
+
+```bash
+tmux new -s opencode
+opencode
+```
+
+2. The tmux tool auto-detects when running inside tmux and uses these defaults:
+   - Layout: `main-vertical` (leader left, workers right)
+   - Main pane size: 60%
+   - Auto-cleanup: enabled
+
+## Detecting Tmux
+
+```typescript
+// Check if running inside tmux
+const status = await tmux({ operation: "detect" });
+const { available, inside_session } = JSON.parse(status);
+
+if (!inside_session) {
+  console.log("Tip: Run inside tmux for visual swarm monitoring");
+  console.log("Start with: tmux new -s opencode");
+}
+```
+
+## Spawning Worker Panes
+
+When spawning workers, create visual panes:
+
+```typescript
+// Before spawning worker via Task tool
+if (inside_session) {
+  // Create pane for this worker
+  const pane = await tmux({
+    operation: "spawn",
+    worker_id: "worker-1",
+    title: "Explorer: auth.ts",
+    size: 40, // 40% width
+  });
+
+  const { pane_id } = JSON.parse(pane);
+
+  // Send command to pane (optional - for visual feedback)
+  await tmux({
+    operation: "send",
+    pane_id,
+    command: `echo "🔍 Worker-1: Exploring auth.ts..."`,
+  });
+}
+
+// Spawn the actual worker
+await Task({
+  subagent_type: "general",
+  description: "Execute worker-1",
+  prompt: `...`,
+});
+```
+
+## Layout Options
+
+| Layout            | Description                           | Best For                      |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| `main-vertical`   | Main pane left, workers stacked right | Default, good for 2-4 workers |
+| `main-horizontal` | Main pane top, workers below          | Wide monitors                 |
+| `tiled`           | Equal grid for all panes              | Many workers (5+)             |
+| `even-horizontal` | Equal width columns                   | 2-3 workers                   |
+| `even-vertical`   | Equal height rows                     | 2-3 workers                   |
+
+```typescript
+// Change layout dynamically
+await tmux({
+  operation: "layout",
+  layout: "tiled", // When many workers spawn
+});
+```
+
+## Monitoring Worker Output
+
+```typescript
+// Capture output from a worker's pane
+const output = await tmux({
+  operation: "capture",
+  pane_id: "%5",
+});
+
+// Check what the worker is doing
+console.log(JSON.parse(output).output);
+```
+
+## Cleanup
+
+```typescript
+// Kill specific pane when worker completes
+await tmux({
+  operation: "kill",
+  pane_id: "%5",
+});
+
+// Or cleanup all spawned panes at end of swarm
+await tmux({
+  operation: "cleanup",
+});
+```
+
+## User Commands
+
+| Action                  | Keys          |
+| ----------------------- | ------------- |
+| Switch to next pane     | `Ctrl+B →`    |
+| Switch to previous pane | `Ctrl+B ←`    |
+| Zoom current pane       | `Ctrl+B z`    |
+| Detach (keep running)   | `Ctrl+B d`    |
+| Reattach                | `tmux attach` |
+| List all panes          | `Ctrl+B w`    |
+
+## Watch Command
+
+Use `/swarm-watch` for real-time progress monitoring:
+
+```bash
+/swarm-watch my-swarm-team
+```
+
+This renders the beautiful TUI block and shows:
+
+- Worker progress percentages
+- Current files being worked on
+- Completion status

package/dist/template/.opencode/skill/swift-concurrency/SKILL.md

@@ -1,9 +1,21 @@
 ---
 name: swift-concurrency
 description: 'Expert guidance on Swift Concurrency best practices, patterns, and implementation. Use when developers mention: (1) Swift Concurrency, async/await, actors, or tasks, (2) "use Swift Concurrency" or "modern concurrency patterns", (3) migrating to Swift 6, (4) data races or thread safety issues, (5) refactoring closures to async/await, (6) @MainActor, Sendable, or actor isolation, (7) concurrent code architecture or performance optimization, (8) concurrency-related linter warnings (SwiftLint or similar; e.g. async_without_await, Sendable/actor isolation/MainActor lint).'
+version: 1.0.0
+tags: [apple, code-quality]
+dependencies: []
 ---
+
 # Swift Concurrency
 
+## When to Use
+
+- When working on Swift concurrency features, async/await, actors, or Swift 6 migration issues.
+
+## When NOT to Use
+
+- When concurrency is not involved or the codebase is not Swift.
+
 ## Overview
 
 This skill provides expert guidance on Swift Concurrency, covering modern async/await patterns, actors, tasks, Sendable conformance, and migration to Swift 6. Use this skill to help developers write safe, performant concurrent code and navigate the complexities of Swift's structured concurrency model.
@@ -29,8 +41,6 @@ When analyzing Swift projects for concurrency issues:
    - Use `Grep` for `SWIFT_STRICT_CONCURRENCY` or `SWIFT_DEFAULT_ACTOR_ISOLATION` in `.pbxproj` files
    - Use `Grep` for `SWIFT_UPCOMING_FEATURE_` to find enabled upcoming features
 
-
-
 ## Project Settings Intake (Evaluate Before Advising)
 
 Concurrency behavior depends on build settings. Always try to determine:
@@ -109,6 +119,7 @@ When a developer needs concurrency guidance, follow this decision tree:
 ### When to Use Each Concurrency Tool
 
 **async/await** - Making existing synchronous code asynchronous
+
 ```swift
 // Use for: Single asynchronous operations
 func fetchUser() async throws -> User {
@@ -117,6 +128,7 @@ func fetchUser() async throws -> User {
 ```
 
 **async let** - Running multiple independent async operations in parallel
+
 ```swift
 // Use for: Fixed number of parallel operations known at compile time
 async let user = fetchUser()
@@ -125,6 +137,7 @@ let profile = try await (user, posts)
 ```
 
 **Task** - Starting unstructured asynchronous work
+
 ```swift
 // Use for: Fire-and-forget operations, bridging sync to async contexts
 Task {
@@ -133,6 +146,7 @@ Task {
 ```
 
 **Task Group** - Dynamic parallel operations with structured concurrency
+
 ```swift
 // Use for: Unknown number of parallel operations at compile time
 await withTaskGroup(of: Result.self) { group in
@@ -143,6 +157,7 @@ await withTaskGroup(of: Result.self) { group in
 ```
 
 **Actor** - Protecting mutable state from data races
+
 ```swift
 // Use for: Shared mutable state accessed from multiple contexts
 actor DataCache {
@@ -152,6 +167,7 @@ actor DataCache {
 ```
 
 **@MainActor** - Ensuring UI updates on main thread
+
 ```swift
 // Use for: View models, UI-related classes
 @MainActor
@@ -163,6 +179,7 @@ class ViewModel: ObservableObject {
 ### Common Scenarios
 
 **Scenario: Network request with UI update**
+
 ```swift
 Task { @concurrent in
     let data = try await fetchData() // Background
@@ -173,6 +190,7 @@ Task { @concurrent in
 ```
 
 **Scenario: Multiple parallel network requests**
+
 ```swift
 async let users = fetchUsers()
 async let posts = fetchPosts()
@@ -181,6 +199,7 @@ let (u, p, c) = try await (users, posts, comments)
 ```
 
 **Scenario: Processing array items in parallel**
+
 ```swift
 await withTaskGroup(of: ProcessedItem.self) { group in
     for item in items {
@@ -195,6 +214,7 @@ await withTaskGroup(of: ProcessedItem.self) { group in
 ## Swift 6 Migration Quick Guide
 
 Key changes in Swift 6:
+
 - **Strict concurrency checking** enabled by default
 - **Complete data-race safety** at compile time
 - **Sendable requirements** enforced on boundaries