opencodekit 0.15.20 → 0.16.0

package/dist/template/.opencode/memory/_templates/tasks.md

@@ -0,0 +1,198 @@
+# Implementation Tasks
+
+**Bead:** [bead-id]
+**Spec:** [link to spec]
+**Date:** [YYYY-MM-DD]
+
+---
+
+## Task Metadata
+
+Each task can have these optional fields in YAML frontmatter:
+
+```yaml
+---
+id: "1.1" # Task identifier
+depends_on: [] # Task IDs that must complete first
+parallel: true # Can run concurrently with other parallel tasks
+conflicts_with: [] # Task IDs that modify same files (cannot parallelize)
+files: [] # Files this task will modify
+estimated_minutes: 30 # Time estimate for planning
+---
+```
+
+---
+
+## 1. Setup
+
+### 1.1 [Prerequisite task]
+
+```yaml
+depends_on: []
+parallel: false
+files: ["package.json", "tsconfig.json"]
+```
+
+- [ ] [Task description]
+
+### 1.2 [Environment or config task]
+
+```yaml
+depends_on: ["1.1"]
+parallel: false
+files: [".env.example"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 2. Core Implementation
+
+### 2.1 [Primary implementation task]
+
+```yaml
+depends_on: ["1.1", "1.2"]
+parallel: true
+conflicts_with: []
+files: ["src/feature/index.ts"]
+```
+
+- [ ] [Task description]
+
+### 2.2 [Secondary implementation task]
+
+```yaml
+depends_on: ["1.1", "1.2"]
+parallel: true
+conflicts_with: []
+files: ["src/feature/utils.ts"]
+```
+
+- [ ] [Task description]
+
+### 2.3 [Integration task]
+
+```yaml
+depends_on: ["2.1", "2.2"]
+parallel: false
+conflicts_with: []
+files: ["src/feature/index.ts", "src/feature/utils.ts"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 3. Testing
+
+### 3.1 [Unit test task]
+
+```yaml
+depends_on: ["2.1"]
+parallel: true
+files: ["tests/feature.test.ts"]
+```
+
+- [ ] [Task description]
+
+### 3.2 [Integration test task]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["tests/integration/feature.test.ts"]
+```
+
+- [ ] [Task description]
+
+### 3.3 [Edge case verification]
+
+```yaml
+depends_on: ["3.1", "3.2"]
+parallel: false
+files: []
+```
+
+- [ ] [Task description]
+
+---
+
+## 4. Documentation
+
+### 4.1 [Code comments / JSDoc]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["src/feature/*.ts"]
+```
+
+- [ ] [Task description]
+
+### 4.2 [README updates]
+
+```yaml
+depends_on: ["2.3"]
+parallel: true
+files: ["README.md"]
+```
+
+- [ ] [Task description]
+
+---
+
+## 5. Verification
+
+### 5.1 All tests pass
+
+```yaml
+depends_on: ["3.1", "3.2", "3.3"]
+parallel: false
+```
+
+- [ ] `[test command]`
+
+### 5.2 Lint clean
+
+```yaml
+depends_on: ["2.3", "4.1"]
+parallel: true
+```
+
+- [ ] `[lint command]`
+
+### 5.3 Build succeeds
+
+```yaml
+depends_on: ["5.1", "5.2"]
+parallel: false
+```
+
+- [ ] `[build command]`
+
+---
+
+## Dependency Graph
+
+Visualize task flow (auto-generated from above):
+
+```
+1.1 ──┬──> 2.1 ──┬──> 2.3 ──┬──> 3.2 ──┬──> 5.1 ──> 5.3
+     │         │         │         │
+1.2 ──┘   2.2 ──┘    3.1 ──┘    5.2 ──┘
+                      │
+                 4.1 ──┘
+                 4.2
+```
+
+**Legend:**
+
+- `──>` = depends_on (sequential)
+- Tasks at same level with `parallel: true` = can run concurrently
+
+---
+
+## Notes
+
+<!-- Implementation notes, gotchas, or decisions made during task creation -->

package/dist/template/.opencode/memory/observations/2026-01-31-decision-created-dedicated-worker-agent-for-swarm.md

@@ -0,0 +1,20 @@
+---
+type: decision
+created: 2026-01-31T13:42:23.877Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["worker", "swarm", "tmux", "agent", "spawn_session", "primary", "subagent"]
+---
+
+# 🎯 Created dedicated worker agent for swarm
+
+🟢 **Confidence:** high
+
+Created a new `worker` agent (primary mode) specifically for tmux-spawned swarm tasks. This keeps `general` as a subagent (for Task tool delegation) while providing a standalone agent that can be spawned via `opencode run --agent worker`.
+
+Key differences:
+- worker: mode=primary, can run standalone, focused on delegated task execution
+- general: mode=subagent, only via Task tool, fast small tasks
+
+The tmux tool now defaults to `agent: "worker"` for spawn_session operations.

package/dist/template/.opencode/memory/observations/2026-01-31-decision-rollback-to-v1-1-47-for-copilot-claude-r.md

@@ -0,0 +1,21 @@
+---
+type: decision
+created: 2026-01-31T17:20:18.779Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["copilot", "claude", "reasoning", "thinking_budget", "rollback", "v1.1.47", "signature validation"]
+---
+
+# 🎯 Rollback to v1.1.47 for Copilot Claude reasoning
+
+🟢 **Confidence:** high
+
+User decided to rollback to OpenCode v1.1.47 approach instead of waiting for PR #8958 to merge. The v1.1.48+ native SDK has "Invalid signature in thinking block" errors with Claude models via GitHub Copilot.
+
+Rollback includes:
+1. Restore copilot-auth.ts with thinking_budget injection (from commit 6f003b5)
+2. Restore custom SDK at .opencode/plugin/sdk/copilot/ with reasoning_text/reasoning_opaque handling
+3. Restore opencode.json github-copilot provider config with reasoning: true for Claude models
+
+This custom SDK bypasses native signature validation but provides working extended thinking.

package/dist/template/.opencode/memory/observations/2026-01-31-decision-simplified-swarm-to-task-tool-pattern.md

@@ -0,0 +1,44 @@
+---
+type: decision
+created: 2026-01-31T18:41:11.898Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["swarm", "task-tool", "parallel-execution", "mailbox", "simplification"]
+files: [".opencode/tool/swarm-monitor.ts", ".opencode/tool/swarm-delegate.ts", ".opencode/plugin/swarm-enforcer.ts", ".opencode/agent/build.md"]
+---
+
+# 🎯 Simplified swarm to Task tool pattern
+
+🟢 **Confidence:** high
+
+## Decision
+Removed mailbox complexity from swarm system. The Task tool handles agent lifecycle and result collection natively.
+
+## Changes Made
+1. **swarm-monitor.ts**: Removed mail_send, mail_read, persist_todos, restore_todos, get_todos. Now only has progress_update, progress_render, render_block, status, clear.
+2. **swarm-delegate.ts**: Updated example to remove swarm-monitor references
+3. **swarm-enforcer.ts**: Renamed from "SWARM PROTOCOL" to "BEADS PROTOCOL", simplified messaging
+4. **build.md agent**: Dramatically simplified - removed complex PARL workflow, tmux panes, mailbox monitoring. Now focuses on Task tool pattern.
+5. **Removed files**: tmux.ts, worker.md (no longer needed)
+
+## Why
+- Task tool already handles results returning to parent
+- OpenCode manages agent lifecycle automatically
+- Mailbox was adding complexity without value
+- Session navigation (ctrl+alt+left/right) provides visibility
+
+## New Pattern
+```typescript
+// Simple parallel execution
+Task({ subagent_type: "explore", prompt: "Find X..." });
+Task({ subagent_type: "general", prompt: "Implement Y..." });
+// Results return directly - no mailbox needed
+```
+
+## Files Affected
+- .opencode/tool/swarm-monitor.ts
+- .opencode/tool/swarm-delegate.ts
+- .opencode/plugin/swarm-enforcer.ts
+- .opencode/agent/build.md
+- dist/template/* (all synced)

package/dist/template/.opencode/memory/observations/2026-01-31-decision-swarm-architecture-task-tool-over-tmux.md

@@ -0,0 +1,33 @@
+---
+type: decision
+created: 2026-01-31T18:34:23.413Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["swarm", "task-tool", "child-session", "parallel", "architecture", "simplify"]
+---
+
+# 🎯 Swarm architecture: Task tool over tmux
+
+🟢 **Confidence:** high
+
+Decided to use Task tool (child sessions) instead of tmux-spawned orphan sessions for swarm coordination.
+
+Reasons:
+1. Task tool manages lifecycle automatically - no orphaned processes
+2. Results return directly to parent - no mailbox communication needed
+3. Built-in session navigation (ctrl+alt+right/left) for visibility
+4. Simpler architecture - no process management complexity
+
+Removed:
+- worker agent (.opencode/agent/worker.md)
+- tmux tool (.opencode/tool/tmux.ts)
+- swarm-monitor mailbox complexity
+
+Pattern for parallel work:
+```typescript
+// Launch parallel subagents - results return to parent
+Task({ subagent_type: "general", prompt: "Task 1..." });
+Task({ subagent_type: "explore", prompt: "Task 2..." });
+// Navigate to child sessions: ctrl+alt+right/left
+```

package/dist/template/.opencode/memory/observations/2026-01-31-decision-worker-skills-defined-for-swarm-delegati.md

@@ -0,0 +1,30 @@
+---
+type: decision
+created: 2026-01-31T19:09:09.501Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["swarm", "delegation", "worker skills", "verification", "TDD", "tool priority"]
+---
+
+# 🎯 Worker skills defined for swarm delegation
+
+🟢 **Confidence:** high
+
+Updated swarm-delegate and swarm-plan tools to recommend essential skills for worker agents:
+
+Required/Recommended skills for workers:
+1. verification-before-completion - REQUIRED: Workers must verify before claiming done
+2. test-driven-development - RECOMMENDED: Write tests first, watch fail, implement, verify pass  
+3. tool-priority - RECOMMENDED: Use LSP before edits, grep for patterns, read before edit
+
+Changes made:
+- swarm-delegate.ts: Added "Recommended skills for workers" section to tool description
+- swarm-plan.ts: Added "Worker skills" section with skill() calls to load
+
+These skills ensure workers:
+- Follow proper verification protocol (no false "done" claims)
+- Use TDD for quality implementation
+- Use correct tool priority (LSP before edits)
+
+Both tools synced to dist/template/.

package/dist/template/.opencode/memory/observations/2026-01-31-learning-gpt-reasoning-config-for-github-copilot.md

@@ -0,0 +1,51 @@
+---
+type: learning
+created: 2026-01-31T18:13:49.325Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["opencode", "gpt", "reasoning", "github-copilot", "model-config", "variants", "reasoningEffort"]
+---
+
+# 📚 GPT reasoning config for GitHub Copilot
+
+🟢 **Confidence:** high
+
+## GPT Models Reasoning Configuration on GitHub Copilot Provider
+
+For OpenAI GPT models (gpt-5.2, gpt-5.2-codex) via github-copilot provider, reasoning is configured using these options:
+
+### Key Options
+- `reasoningEffort`: "low" | "medium" | "high" - Controls reasoning depth
+- `reasoningSummary`: "auto" | "always" | "never" - Show reasoning summary
+- `textVerbosity`: "low" | "medium" | "high" - Controls output verbosity
+- `include`: ["reasoning.encrypted_content"] - Include encrypted reasoning
+
+### Configuration Structure
+```json
+"github-copilot": {
+  "models": {
+    "gpt-5.2": {
+      "reasoning": true,
+      "options": {
+        "reasoningEffort": "medium",
+        "reasoningSummary": "auto"
+      },
+      "variants": {
+        "high": { "reasoningEffort": "high", "include": ["reasoning.encrypted_content"] },
+        "low": { "reasoningEffort": "low" },
+        "medium": { "reasoningEffort": "medium" }
+      }
+    }
+  }
+}
+```
+
+### Usage
+1. Select model: `/models` → choose `github-copilot/gpt-5.2`
+2. Cycle variants: Use keybind to switch between low/medium/high
+3. Or add `--variant high` when starting
+
+### Difference from Claude models
+- Claude uses `thinking_budget` (token count)
+- GPT uses `reasoningEffort` (low/medium/high qualitative levels)

package/dist/template/.opencode/memory/observations/2026-01-31-learning-opencode-custom-tools-api.md

@@ -0,0 +1,48 @@
+---
+type: learning
+created: 2026-01-31T13:08:45.478Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["opencode", "custom-tools", "plugin", "bun-shell", "tool-schema"]
+---
+
+# 📚 OpenCode Custom Tools API
+
+🟢 **Confidence:** high
+
+## Proper Custom Tool Format
+
+OpenCode custom tools must use the `@opencode-ai/plugin` package:
+
+```typescript
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description: "Tool description",
+  args: {
+    param: tool.schema.string().describe("Parameter description"),
+  },
+  async execute(args, context) {
+    // context provides: agent, sessionID, messageID, directory, worktree
+    return "result";
+  },
+});
+```
+
+### Key Points:
+1. **Import**: `import { tool } from "@opencode-ai/plugin"`
+2. **Schema**: Use `tool.schema` (which is Zod) for argument types
+3. **Shell commands**: Use `Bun.$` for shell commands, NOT Node.js child_process
+4. **Context**: Second argument provides session info (directory, worktree, etc.)
+5. **Multiple exports**: Each named export becomes `<filename>_<exportname>` tool
+
+### Shell Command Example:
+```typescript
+// Use Bun shell (NOT child_process)
+const result = await Bun.$`tmux -V`.quiet();
+return result.stdout.toString().trim();
+```
+
+### Docs Reference:
+https://opencode.ai/docs/custom-tools/

package/dist/template/.opencode/memory/observations/2026-01-31-learning-opencode-v1-1-48-skills-as-slash-command.md

@@ -0,0 +1,21 @@
+---
+type: learning
+created: 2026-01-31T18:45:52.872Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["opencode", "skills", "slash-commands", "v1.1.48", "TUI", "implement"]
+---
+
+# 📚 OpenCode v1.1.48: Skills as slash commands
+
+🟢 **Confidence:** high
+
+OpenCode v1.1.48 introduced the ability to invoke skills as slash commands in the TUI.
+
+This means:
+1. Skills in `.opencode/skill/` can be invoked directly via `/skill-name`
+2. Commands in `.opencode/command/` that load skills via `skill({ name: "..." })` need to stay consistent with actual skill capabilities
+3. When simplifying tools/skills, must also update any commands that reference them
+
+Example: `/implement` loads swarm-coordination skill and uses swarm-monitor operations - if those operations change, implement.md must be updated too.

package/dist/template/.opencode/memory/observations/2026-01-31-learning-swarm-system-simplified-removed-mailbox-.md

@@ -0,0 +1,30 @@
+---
+type: learning
+created: 2026-01-31T19:06:48.076Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["swarm", "beads", "parallel execution", "task tool", "mailbox removal"]
+files: [".opencode/tool/swarm-monitor.ts", ".opencode/command/implement.md", ".opencode/command/handoff.md", ".opencode/command/resume.md", ".opencode/command/new-feature.md", ".opencode/command/research.md", ".opencode/skill/beads/SKILL.md", ".opencode/skill/beads-bridge/SKILL.md", ".opencode/skill/swarm-coordination/SKILL.md"]
+---
+
+# 📚 Swarm system simplified - removed mailbox operations
+
+🟢 **Confidence:** high
+
+The swarm system has been simplified to use Task tool for parallel execution instead of internal mailbox operations. Removed obsolete operations: restore_todos, persist_todos, mail_send, mail_read, get_todos. 
+
+Current valid swarm-monitor operations: progress_update, render_block, status, clear
+
+Updated files:
+- .opencode/tool/swarm-monitor.ts (removed obsolete operations)
+- .opencode/command/implement.md (updated examples)
+- .opencode/command/handoff.md (removed persist_todos)
+- .opencode/command/resume.md (removed restore_todos)
+- .opencode/command/new-feature.md (removed mail_send)
+- .opencode/command/research.md (simplified examples)
+- .opencode/skill/beads/SKILL.md (added beads-bridge section)
+- .opencode/skill/beads-bridge/SKILL.md (removed obsolete operations)
+- .opencode/skill/swarm-coordination/SKILL.md (removed obsolete operations)
+
+Key insight: Task tool results replace mailbox messages. Workers return completion status directly via Task results, not via mail_send/mail_read.

package/dist/template/.opencode/memory/observations/2026-01-31-learning-v1-1-48-native-copilot-reasoning-via-pr-.md

@@ -0,0 +1,45 @@
+---
+type: learning
+created: 2026-01-31T17:23:15.170Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["v1.1.48", "copilot", "reasoning", "native", "PR 8900", "thinking_budget", "reasoning_opaque", "reasoning_text"]
+---
+
+# 📚 v1.1.48 Native Copilot Reasoning via PR 8900
+
+🟢 **Confidence:** high
+
+## v1.1.48 Native Copilot Reasoning Support (PR #8900)
+
+OpenCode v1.1.48 includes native Copilot-specific provider that properly handles reasoning tokens! This was merged Jan 31, 2026.
+
+### What PR #8900 Does:
+1. Creates dedicated Copilot provider under `src/provider/sdk/copilot/`
+2. Handles `reasoning_text` and `reasoning_opaque` fields natively
+3. Properly stores and passes `reasoning_opaque` back to Copilot API for multi-turn context
+4. Uses `providerOptions.copilot` key (not `openaiCompatible`)
+5. Adds `copilot_cache_control` to all messages
+
+### Key Implementation Details:
+- Provider options key changed from `openaiCompatible` to `copilot`
+- Assistant messages include `reasoning_text` and `reasoning_opaque`
+- The opaque signature MUST be passed back for multi-turn reasoning to work properly
+- Gemini models work with reasoning; Claude thinking is NOT yet supported server-side by GitHub
+
+### For Plugin Configuration (v1.1.48+):
+- NO custom SDK needed anymore
+- Use native `github-copilot` provider
+- Enable reasoning with `reasoning: true` in model config
+- May need to pass `thinking_budget` via providerOptions.copilot
+
+### GitHub Copilot Model Capabilities (from API):
+- Claude models support `max_thinking_budget: 32000` and `min_thinking_budget: 1024`
+- GPT models use `/responses` API endpoint
+- Claude uses chat completions API
+
+### Important Note:
+- Gemini models DO return `reasoning_text` via Copilot
+- Claude extended thinking is blocked SERVER-SIDE by GitHub (not a client issue)
+- The custom SDK we built is now obsolete for v1.1.48+

package/dist/template/.opencode/memory/observations/2026-01-31-warning-cannot-add-custom-config-to-opencode-jso.md

@@ -0,0 +1,18 @@
+---
+type: warning
+created: 2026-01-31T13:04:00.635Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["opencode.json", "config", "schema", "tmux", "custom-config", "validation"]
+---
+
+# ⚠️ Cannot add custom config to opencode.json
+
+🟢 **Confidence:** high
+
+opencode.json has a strict JSON schema (https://opencode.ai/config.json). You CANNOT add arbitrary config sections like "tmux". The schema only allows specific keys like: agent, autoupdate, compaction, experimental, formatter, instructions, keybinds, mcp, model, permission, plugin, provider, share, small_model, tools, tui, watcher.
+
+Custom tool configuration must be handled within the tool itself (via environment variables, separate config file, or hardcoded defaults) - NOT in opencode.json.
+
+The user already commented out the invalid tmux section at lines 785-790.

package/dist/template/.opencode/memory/observations/2026-01-31-warning-opencode-v1-1-48-claude-thinking-block-s.md

@@ -0,0 +1,51 @@
+---
+type: warning
+created: 2026-01-31T17:14:16.151Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["opencode", "copilot", "claude", "thinking-block", "signature", "reasoning", "v1.1.48", "bug", "sdk", "backup"]
+---
+
+# ⚠️ OpenCode v1.1.48+ Claude Thinking Block Signature Bug
+
+🟢 **Confidence:** high
+
+## Problem
+When upgrading OpenCode from v1.1.48 to dev branch, Claude models via GitHub Copilot fail with:
+`messages.1.content.0: Invalid 'signature' in 'thinking' block`
+
+## Root Cause
+- OpenCode v1.1.48+ native `@ai-sdk/github-copilot` SDK validates thinking block signatures
+- Switching models mid-session causes signature validation failures
+- Thinking blocks from one model (GLM 4.7, MiniMax, etc.) have incompatible signatures with Claude
+- GitHub issue #6418, fix in draft PR #8958
+
+## Working Configuration (Pre-upgrade)
+Location: `backup/sdk/` contains custom copilot SDK that bypassed signature validation
+- `backup/sdk/copilot/` - Custom @ai-sdk/github-copilot implementation
+- `~/.config/opencode/plugin/copilot-auth.ts` - Auth plugin with disabled custom reasoning (664 lines)
+- `~/.config/opencode/opencode.json` - Model configurations
+
+## Key Files in Backup SDK
+```
+backup/sdk/copilot/
+├── chat/
+│   ├── convert-to-openai-compatible-chat-messages.ts
+│   ├── get-response-metadata.ts
+│   ├── map-openai-compatible-finish-reason.ts
+│   ├── openai-compatible-api-types.ts
+│   ├── openai-compatible-chat-language-model.ts
+│   ├── openai-compatible-chat-options.ts
+│   ├── openai-compatible-metadata-extractor.ts
+│   └── openai-compatible-prepare-tools.ts
+├── copilot-provider.ts
+├── index.ts
+└── openai-compatible-error.ts
+```
+
+## Workarounds
+1. Don't switch to Claude mid-session from models with thinking blocks
+2. Start fresh sessions when using Claude with extended thinking
+3. Wait for PR #8958 to be merged
+4. Restore custom SDK from backup (breaks native reasoning handling)

package/dist/template/.opencode/memory/observations/2026-02-01-decision-add-skills-vs-commands-to-global-agents-.md

@@ -0,0 +1,15 @@
+---
+type: decision
+created: 2026-02-01T11:37:16.161Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["AGENTS.md", "skills vs commands", "global rules"]
+files: [".opencode/AGENTS.md"]
+---
+
+# 🎯 Add Skills vs Commands to global AGENTS rules
+
+🟢 **Confidence:** high
+
+User requested adding the 'Skills vs Commands' guidance to the global rules file .opencode/AGENTS.md.

package/dist/template/.opencode/memory/observations/2026-02-01-decision-build-agent-auto-loads-skills-contextual.md

@@ -0,0 +1,31 @@
+---
+type: decision
+created: 2026-02-01T16:02:30.722Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["skills", "auto-loading", "build-agent", "context", "prd", "swarm", "debugging", "testing", "frontend"]
+---
+
+# 🎯 Build agent auto-loads skills contextually
+
+🟢 **Confidence:** high
+
+Build agent loads skills based on context, NOT all at once:
+
+**Always load:**
+- beads (task tracking)
+- verification-before-completion (never skip)
+
+**Conditional loading:**
+- prd-task: when prd.md exists
+- prd: when feature needs PRD creation
+- swarm-coordination: when 3+ parallel tasks
+- systematic-debugging: for bug fixes
+- test-driven-development: for test work
+- frontend-design: for UI/component work
+- using-git-worktrees: for epics or --worktree flag
+- requesting-code-review: before claiming done
+- finishing-a-development-branch: when completing feature
+
+This prevents skill overload and keeps context focused.