opencodekit 0.18.0 → 0.18.2

package/dist/template/.opencode/skill/beads/references/GIT_SYNC.md

@@ -0,0 +1,25 @@
+# Git Sync
+
+## Manual Sync (Non-Invasive)
+
+**Important:** `br` never executes git commands. You must manually commit changes.
+
+```bash
+# Export changes to JSONL
+br sync --flush-only
+
+# Then manually commit
+git add .beads/
+git commit -m "sync beads"
+git push
+```
+
+**Use when**: End of session, before handoff, after major progress.
+
+## Cleanup Old Issues
+
+```bash
+br cleanup --days 7
+```
+
+Removes closed issues older than N days. Run weekly.

package/dist/template/.opencode/skill/beads/references/HIERARCHY.md

@@ -0,0 +1,71 @@
+# Hierarchical Structure: Epic → Task → Subtask
+
+Beads supports up to 3 levels of hierarchy using hierarchical IDs:
+
+```
+br-a3f8        (Epic - parent feature)
+├── br-a3f8.1  (Task - first child)
+├── br-a3f8.2  (Task - second child)
+│   ├── br-a3f8.2.1  (Subtask - child of .2)
+│   └── br-a3f8.2.2  (Subtask - child of .2)
+└── br-a3f8.3  (Task - third child)
+```
+
+## When to Decompose
+
+| Scenario                     | Structure                            |
+| ---------------------------- | ------------------------------------ |
+| Bug fix, config change       | Single bead                          |
+| Small feature (1-2 files)    | Single bead                          |
+| Feature crossing FE/BE       | Epic + tasks by domain               |
+| New system/service           | Epic + tasks by component            |
+| Multi-day work               | Epic + tasks for parallelization     |
+| Work needing multiple agents | Epic + tasks (agents claim children) |
+
+## Creating Hierarchical Beads
+
+```bash
+# Step 1: Create Epic (parent)
+br create --title "User Authentication System" --type epic --priority 1 \
+  --description "Complete auth with OAuth, sessions, and protected routes"
+# Returns: br-a3f8
+
+# Step 2: Create child tasks with parent
+br create --title "Database schema for auth" --type task --priority 2 \
+  --parent br-a3f8 --description "Create user and session tables"
+# Returns: br-a3f8.1  ← Hierarchical ID!
+
+# Step 3: Create dependent tasks
+br create --title "OAuth integration" --type task --priority 2 \
+  --parent br-a3f8 --blocked-by br-a3f8.1
+# Returns: br-a3f8.2
+```
+
+## Parallel Execution with Dependencies
+
+```
+br-a3f8.1 [Database] ──┬──> br-a3f8.2 [Backend] ──┐
+     (READY)           │                          │
+                       │                          ▼
+                       └──> br-a3f8.3 [Frontend]  br-a3f8.5 [Testing]
+                       │         │                     ▲
+                       └──> br-a3f8.4 [Docs] ──────────┘
+
+Parallel tracks:
+• Agent 1 (backend): .1 → .2
+• Agent 2 (frontend): wait for .1, then .3
+• Agent 3 (qa): wait for .2 and .3, then .5
+```
+
+**Key insight**: After br-a3f8.1 completes, .2, .3, and .4 all become READY simultaneously. Multiple agents can claim them in parallel.
+
+## Querying Hierarchy
+
+```bash
+# See all open issues
+br list --status open
+
+# See ready work (unblocked tasks)
+br ready
+# Returns tasks where all dependencies are closed
+```

package/dist/template/.opencode/skill/beads/references/MULTI_AGENT.md

@@ -0,0 +1,40 @@
+# Multi-Agent Coordination (Swarm Mode)
+
+For parallel execution with multiple subagents, use the **beads-bridge** skill:
+
+```typescript
+skill({ name: "beads-bridge" });
+```
+
+**beads-bridge** provides (via unified `swarm` tool):
+
+- `swarm({ operation: "sync" })` - Sync Beads tasks to OpenCode todos for subagent visibility
+- `swarm({ operation: "monitor" })` - Real-time progress tracking and visualization
+- `swarm({ operation: "plan" })` - Task classification and dependency analysis
+- `swarm({ operation: "delegate" })` - Create delegation packets for workers
+
+**When to use beads vs beads-bridge:**
+
+| Scenario                       | Use                              |
+| ------------------------------ | -------------------------------- |
+| Single agent, linear work      | `beads` skill only               |
+| Multiple agents in parallel    | `beads-bridge` + `beads`         |
+| Need subagents to see tasks    | `beads-bridge` (swarm sync push) |
+| Track worker progress visually | `beads-bridge` (swarm monitor)   |
+
+**Example swarm workflow:**
+
+```typescript
+// 1. Push beads to OpenCode todos (subagents can see via todoread)
+swarm({ operation: "sync", action: "push" });
+
+// 2. Spawn workers in parallel using Task tool
+Task({ subagent_type: "general", description: "Worker 1", prompt: "..." });
+Task({ subagent_type: "general", description: "Worker 2", prompt: "..." });
+
+// 3. Monitor progress
+swarm({ operation: "monitor", action: "render_block", team_name: "my-swarm" });
+
+// 4. Pull completed work back to beads
+swarm({ operation: "sync", action: "pull" });
+```

package/dist/template/.opencode/skill/beads/references/SESSION_PROTOCOL.md

@@ -0,0 +1,61 @@
+# Session Start Protocol
+
+**Every session, follow these steps:**
+
+## Session Start Checklist
+
+- [ ] Run `br ready` to find unblocked work
+- [ ] If none, run `br list --status open` to see all open tasks
+- [ ] Claim the task: `br update <id> --status in_progress`
+- [ ] Load context: `br show <id>`
+
+## Step 1: Find Ready Work
+
+```bash
+br ready
+```
+
+Returns highest priority task with no blockers.
+
+If no tasks returned, check all open work:
+
+```bash
+br list --status open
+```
+
+## Step 2: Claim Task
+
+```bash
+br update <id> --status in_progress
+```
+
+## Step 3: Get Full Context
+
+```bash
+br show <id>
+```
+
+Shows full description, dependencies, notes, history.
+
+## Step 4: Do the Work
+
+Implement the task, adding notes as you learn.
+
+## Step 5: Complete and Sync
+
+```bash
+br close <id> --reason "Implemented auth with JWT tokens"
+br sync --flush-only
+git add .beads/
+git commit -m "sync beads"
+# RESTART SESSION - fresh context
+```
+
+Always restart session after closing a task. One task per session.
+
+## Session End Checklist
+
+- [ ] Close the bead with a clear reason: `br close <id> --reason "..."`
+- [ ] Sync Beads to JSONL: `br sync --flush-only`
+- [ ] Commit `.beads/` changes manually
+- [ ] Restart session (fresh context)

package/dist/template/.opencode/skill/beads/references/TASK_CREATION.md

@@ -0,0 +1,38 @@
+# Task Creation
+
+## When to Create Tasks
+
+Create tasks when:
+
+- User mentions tracking work across sessions
+- User says "we should fix/build/add X"
+- Work has dependencies or blockers
+- Discovered work while implementing (>2 min effort)
+
+## Basic Task Creation
+
+```bash
+br create --title "Fix authentication bug" --priority 0 --type bug
+# Priority: 0=critical, 1=high, 2=normal, 3=low, 4=backlog
+# Types: task, bug, feature, epic, chore
+```
+
+## With Description
+
+```bash
+br create --title "Implement OAuth" --type feature --priority 1 \
+  --description "Add OAuth2 support for Google, GitHub. Use passport.js."
+```
+
+## Epic with Children
+
+```bash
+# Create parent epic
+br create --title "Epic: OAuth Implementation" --priority 0 --type epic
+# Returns: oauth-abc
+
+# Create child tasks with parent
+br create --title "Research OAuth providers" --priority 1 --parent oauth-abc
+br create --title "Implement auth endpoints" --priority 1 --parent oauth-abc
+br create --title "Add frontend login UI" --priority 2 --parent oauth-abc
+```

package/dist/template/.opencode/skill/beads/references/TROUBLESHOOTING.md

@@ -0,0 +1,13 @@
+# Error Handling
+
+## Common Issues
+
+**No ready tasks**
+
+- Run `br list --status open` to see all tasks
+- Some may be blocked - check dependencies with `br show <id>`
+
+**Sync failures**
+
+- Run `br doctor` to repair database
+- Check git remote access

package/dist/template/.opencode/skill/beads-bridge/SKILL.md

@@ -6,13 +6,21 @@ description: >
   dependency management, hierarchical decomposition, and session protocols.
 version: "2.0.0"
 license: MIT
+tags: [agent-coordination, workflow]
+dependencies: [beads]
 ---
 
 # Beads Bridge - Cross-Session Task Coordination
 
-Bridge between Beads git-backed task tracking, OpenCode's native todo system, and swarm coordination.
+## When to Use
 
-**Note:** `br` (beads_rust) is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.
+- Work spans multiple sessions and needs persistent task tracking
+- Multiple agents must coordinate via Beads, swarm, and OpenCode todos
+
+## When NOT to Use
+
+- Single-session, single-agent work with no dependencies
+- Simple tasks that don’t require Beads or swarm coordination
 
 ## Overview
 
@@ -36,14 +44,6 @@ Bridge between Beads git-backed task tracking, OpenCode's native todo system, an
 - `plan`: Task classification + dependency graphs (before spawning workers)
 - `delegate`: Create delegation packets (assigning work to workers)
 
-## When to Use This Skill
-
-- Work spans multiple sessions (need persistence)
-- Tasks have complex dependencies
-- Multiple agents need to coordinate on shared work
-- Need to recover swarm state after session restart
-- Subagents need to see Beads tasks via todoread
-
 ## Core Workflows
 
 ### 1. Session Start: Load Beads into Todos

package/dist/template/.opencode/skill/brainstorming/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: brainstorming
 description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: []
 ---
 
 # Brainstorming Ideas Into Designs
 
+## When to Use
+
+- You have a rough idea that needs clarification into a design or spec
+- You need to explore multiple approaches and validate trade-offs before coding
+
+## When NOT to Use
+
+- Requirements are already clear and execution is mechanical
+- You are already in implementation with a validated plan or PRD
+
 ## Overview
 
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

package/dist/template/.opencode/skill/chrome-devtools/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: chrome-devtools
 description: Chrome DevTools for debugging, performance analysis, and browser automation. Use when debugging web apps, analyzing performance, inspecting network requests, or automating browser interactions.
+version: 1.0.0
+tags: [automation, debugging]
+dependencies: []
 ---
 
 # Chrome DevTools (MCP)
 
-Control and inspect a live Chrome browser via Chrome DevTools Protocol.
+## When to Use
+
+- When you need to debug or inspect a live Chrome page via DevTools Protocol tools.
+
+## When NOT to Use
+
+- When cross-browser automation is required (use Playwright-based skills instead).
+
 
 ## Available Tools
 

package/dist/template/.opencode/skill/cloudflare/SKILL.md

@@ -7,11 +7,21 @@ references:
   - d1
   - durable-objects
   - workers-ai
+version: 1.0.0
+tags: [integration, devops]
+dependencies: []
 ---
 
 # Cloudflare Platform Skill
 
-Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+## When to Use
+
+- When you need guidance or references for building on Cloudflare products.
+
+## When NOT to Use
+
+- When the task doesn't involve Cloudflare services or infrastructure.
+
 
 ## How to Use This Skill
 
@@ -133,101 +143,111 @@ Need IaC?
 ## Product Index
 
 ### Compute & Runtime
-| Product | Entry File |
-|---------|------------|
-| Workers | `./references/workers/README.md` |
-| Pages | `./references/pages/README.md` |
-| Pages Functions | `./references/pages-functions/README.md` |
-| Durable Objects | `./references/durable-objects/README.md` |
-| Workflows | `./references/workflows/README.md` |
-| Containers | `./references/containers/README.md` |
+
+| Product               | Entry File                                     |
+| --------------------- | ---------------------------------------------- |
+| Workers               | `./references/workers/README.md`               |
+| Pages                 | `./references/pages/README.md`                 |
+| Pages Functions       | `./references/pages-functions/README.md`       |
+| Durable Objects       | `./references/durable-objects/README.md`       |
+| Workflows             | `./references/workflows/README.md`             |
+| Containers            | `./references/containers/README.md`            |
 | Workers for Platforms | `./references/workers-for-platforms/README.md` |
-| Cron Triggers | `./references/cron-triggers/README.md` |
-| Tail Workers | `./references/tail-workers/README.md` |
-| Snippets | `./references/snippets/README.md` |
-| Smart Placement | `./references/smart-placement/README.md` |
+| Cron Triggers         | `./references/cron-triggers/README.md`         |
+| Tail Workers          | `./references/tail-workers/README.md`          |
+| Snippets              | `./references/snippets/README.md`              |
+| Smart Placement       | `./references/smart-placement/README.md`       |
 
 ### Storage & Data
-| Product | Entry File |
-|---------|------------|
-| KV | `./references/kv/README.md` |
-| D1 | `./references/d1/README.md` |
-| R2 | `./references/r2/README.md` |
-| Queues | `./references/queues/README.md` |
-| Hyperdrive | `./references/hyperdrive/README.md` |
-| DO Storage | `./references/do-storage/README.md` |
-| Secrets Store | `./references/secrets-store/README.md` |
-| Pipelines | `./references/pipelines/README.md` |
+
+| Product         | Entry File                               |
+| --------------- | ---------------------------------------- |
+| KV              | `./references/kv/README.md`              |
+| D1              | `./references/d1/README.md`              |
+| R2              | `./references/r2/README.md`              |
+| Queues          | `./references/queues/README.md`          |
+| Hyperdrive      | `./references/hyperdrive/README.md`      |
+| DO Storage      | `./references/do-storage/README.md`      |
+| Secrets Store   | `./references/secrets-store/README.md`   |
+| Pipelines       | `./references/pipelines/README.md`       |
 | R2 Data Catalog | `./references/r2-data-catalog/README.md` |
-| R2 SQL | `./references/r2-sql/README.md` |
+| R2 SQL          | `./references/r2-sql/README.md`          |
 
 ### AI & Machine Learning
-| Product | Entry File |
-|---------|------------|
+
+| Product    | Entry File                          |
+| ---------- | ----------------------------------- |
 | Workers AI | `./references/workers-ai/README.md` |
-| Vectorize | `./references/vectorize/README.md` |
+| Vectorize  | `./references/vectorize/README.md`  |
 | Agents SDK | `./references/agents-sdk/README.md` |
 | AI Gateway | `./references/ai-gateway/README.md` |
-| AI Search | `./references/ai-search/README.md` |
+| AI Search  | `./references/ai-search/README.md`  |
 
 ### Networking & Connectivity
-| Product | Entry File |
-|---------|------------|
-| Tunnel | `./references/tunnel/README.md` |
-| Spectrum | `./references/spectrum/README.md` |
-| TURN | `./references/turn/README.md` |
+
+| Product              | Entry File                                    |
+| -------------------- | --------------------------------------------- |
+| Tunnel               | `./references/tunnel/README.md`               |
+| Spectrum             | `./references/spectrum/README.md`             |
+| TURN                 | `./references/turn/README.md`                 |
 | Network Interconnect | `./references/network-interconnect/README.md` |
-| Argo Smart Routing | `./references/argo-smart-routing/README.md` |
-| Workers VPC | `./references/workers-vpc/README.md` |
+| Argo Smart Routing   | `./references/argo-smart-routing/README.md`   |
+| Workers VPC          | `./references/workers-vpc/README.md`          |
 
 ### Security
-| Product | Entry File |
-|---------|------------|
-| WAF | `./references/waf/README.md` |
-| DDoS Protection | `./references/ddos/README.md` |
-| Bot Management | `./references/bot-management/README.md` |
-| API Shield | `./references/api-shield/README.md` |
-| Turnstile | `./references/turnstile/README.md` |
+
+| Product         | Entry File                              |
+| --------------- | --------------------------------------- |
+| WAF             | `./references/waf/README.md`            |
+| DDoS Protection | `./references/ddos/README.md`           |
+| Bot Management  | `./references/bot-management/README.md` |
+| API Shield      | `./references/api-shield/README.md`     |
+| Turnstile       | `./references/turnstile/README.md`      |
 
 ### Media & Content
-| Product | Entry File |
-|---------|------------|
-| Images | `./references/images/README.md` |
-| Stream | `./references/stream/README.md` |
+
+| Product           | Entry File                                 |
+| ----------------- | ------------------------------------------ |
+| Images            | `./references/images/README.md`            |
+| Stream            | `./references/stream/README.md`            |
 | Browser Rendering | `./references/browser-rendering/README.md` |
-| Zaraz | `./references/zaraz/README.md` |
+| Zaraz             | `./references/zaraz/README.md`             |
 
 ### Real-Time Communication
-| Product | Entry File |
-|---------|------------|
-| RealtimeKit | `./references/realtimekit/README.md` |
+
+| Product      | Entry File                            |
+| ------------ | ------------------------------------- |
+| RealtimeKit  | `./references/realtimekit/README.md`  |
 | Realtime SFU | `./references/realtime-sfu/README.md` |
 
 ### Developer Tools
-| Product | Entry File |
-|---------|------------|
-| Wrangler | `./references/wrangler/README.md` |
-| Miniflare | `./references/miniflare/README.md` |
-| C3 | `./references/c3/README.md` |
-| Observability | `./references/observability/README.md` |
-| Analytics Engine | `./references/analytics-engine/README.md` |
-| Web Analytics | `./references/web-analytics/README.md` |
-| Sandbox | `./references/sandbox/README.md` |
-| Workerd | `./references/workerd/README.md` |
+
+| Product            | Entry File                                  |
+| ------------------ | ------------------------------------------- |
+| Wrangler           | `./references/wrangler/README.md`           |
+| Miniflare          | `./references/miniflare/README.md`          |
+| C3                 | `./references/c3/README.md`                 |
+| Observability      | `./references/observability/README.md`      |
+| Analytics Engine   | `./references/analytics-engine/README.md`   |
+| Web Analytics      | `./references/web-analytics/README.md`      |
+| Sandbox            | `./references/sandbox/README.md`            |
+| Workerd            | `./references/workerd/README.md`            |
 | Workers Playground | `./references/workers-playground/README.md` |
 
 ### Infrastructure as Code
-| Product | Entry File |
-|---------|------------|
-| Pulumi | `./references/pulumi/README.md` |
+
+| Product   | Entry File                         |
+| --------- | ---------------------------------- |
+| Pulumi    | `./references/pulumi/README.md`    |
 | Terraform | `./references/terraform/README.md` |
-| API | `./references/api/README.md` |
+| API       | `./references/api/README.md`       |
 
 ### Other Services
-| Product | Entry File |
-|---------|------------|
+
+| Product       | Entry File                             |
+| ------------- | -------------------------------------- |
 | Email Routing | `./references/email-routing/README.md` |
 | Email Workers | `./references/email-workers/README.md` |
 | Static Assets | `./references/static-assets/README.md` |
-| Bindings | `./references/bindings/README.md` |
+| Bindings      | `./references/bindings/README.md`      |
 | Cache Reserve | `./references/cache-reserve/README.md` |

package/dist/template/.opencode/skill/compaction/SKILL.md

@@ -4,13 +4,21 @@ description: >
   Use when context is growing large during long-running tasks and needs server-side or client-side
   summarization to continue effectively. Covers compaction triggers, custom summarization patterns,
   session handoff, and context preservation strategies.
-version: "1.0.0"
-license: MIT
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
 ---
 
 # Context Compaction - Managing Long-Running Sessions
 
-Handle context growth in long-running sessions through proactive compaction, strategic summarization, and session handoff patterns.
+## When to Use
+
+- Context is growing large and needs distillation/compaction to continue.
+
+## When NOT to Use
+
+- Short sessions with low context usage where no compaction is needed.
+
 
 ## Overview
 

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

@@ -1,42 +1,28 @@
 ---
 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
 
-## 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.
-
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
+- Tests are flaky due to arbitrary delays or timing guesses
+- You need to wait for async state changes (events, file writes, state transitions)
 
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
-```
+## When NOT to Use
 
-**Use when:**
+- You are explicitly testing timing behavior (debounce, throttle, intervals)
+- A fixed, documented timeout is part of the requirement
 
-- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
-- Tests are flaky (pass sometimes, fail under load)
-- Tests timeout when run in parallel
-- Waiting for async operations to complete
+## Overview
 
-**Don't use when:**
+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.
 
-- Testing actual timing behavior (debounce, throttle intervals)
-- Always document WHY if using arbitrary timeout
+**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
 
 ## Core Pattern
 

package/dist/template/.opencode/skill/context-engineering/SKILL.md

@@ -1,13 +1,24 @@
 ---
 name: context-engineering
 description: Use when designing AGENTS.md hierarchies, understanding autonomous duration, or writing intent layers - covers principles for extending agent work capacity
+version: 1.0.0
+tags: [context, documentation]
+dependencies: []
 ---
 
 # Context Engineering
 
-Principles for maximizing agent effectiveness through context design.
+## When to Use
+
+- Designing or refactoring AGENTS.md hierarchies and intent layers
+- You need to extend autonomous work duration via better context structure
+
+## When NOT to Use
+
+- You only need pruning/distillation mechanics (use context-management)
+- Simple tasks where context design is not relevant
+
 
-**For practical context tools (prune/distill/compress), use `context-management` skill.**
 
 ## Core Principle