opencodekit 0.16.0 → 0.16.1

package/dist/template/.opencode/memory/_templates/prompt-engineering.md

@@ -1,333 +0,0 @@
----
-purpose: System prompt best practices and templates for agent development
-updated: 2026-01-22
-sources:
-  - Anthropic Claude Code Best Practices
-  - OpenAI Prompt Engineering Guide
-  - Mistral Prompting Capabilities
-  - Google Gemini 3 Prompt Practices
-  - Lilian Weng Prompt Engineering
-  - Mitchell Hashimoto Prompt Engineering vs Blind Prompting
----
-
-# Prompt Engineering Best Practices
-
-## Core Principles
-
-1. **Precise Instructions** - Be concise and direct. State goals clearly without fluff.
-2. **Consistency** - Maintain uniform structure (standardized tags, formatting).
-3. **Specificity** - Avoid subjective words ("too long", "interesting", "better").
-4. **Assertive Language** - Use "You MUST" instead of "You should try to".
-5. **Show, Don't Just Tell** - Include examples (few-shot learning).
-
-## Structure Template
-
-Use this order for system prompts:
-
-```markdown
-# Identity
-
-[WHO the assistant is - role, personality, expertise]
-
-# Instructions
-
-[WHAT to do - specific rules, behaviors, workflows]
-
-# Constraints
-
-[BOUNDARIES - what NOT to do, limitations, guardrails]
-
-# Output Format
-
-[HOW to respond - structure, verbosity, tone]
-
-# Examples
-
-[DEMONSTRATIONS - input/output pairs for few-shot learning]
-
-# Context
-
-[DATA - documents, code, background info - place at END for long context]
-```
-
-## Formatting Guidelines
-
-### Choose ONE format consistently:
-
-**Markdown (recommended for readability):**
-
-```markdown
-# Section
-
-## Subsection
-
-- Bullet point
-- Another point
-
-**Bold for emphasis**
-```
-
-**XML tags (recommended for data boundaries):**
-
-```xml
-<role>You are a code reviewer.</role>
-<constraints>
-- Only review TypeScript
-- Focus on security
-</constraints>
-<context>{{user_code}}</context>
-```
-
-### Never mix formats in the same prompt.
-
-## Message Roles (Priority Order)
-
-| Role        | Priority | Purpose                         |
-| ----------- | -------- | ------------------------------- |
-| `system`    | Highest  | Developer rules, business logic |
-| `user`      | Medium   | End-user input, queries         |
-| `assistant` | Lowest   | Model-generated responses       |
-
-Think of system as **function definition**, user as **arguments**.
-
-## Writing Effective Instructions
-
-### DO:
-
-- Be specific: "Output exactly 3 bullet points" not "keep it brief"
-- Define audience: "Explain to a 6-year-old" or "Write for senior engineers"
-- Provide parameters: "Maximum 100 words" not "short response"
-- Use decision trees for complex logic
-- Tell it what TO do (not what NOT to do)
-
-### DON'T:
-
-- Use subjective words: "too long", "interesting", "better"
-- Create contradictions in long prompts
-- Ask LLMs to count (provide counts as input)
-- Generate more tokens than necessary
-
-## Few-Shot Learning
-
-### Example Selection:
-
-- Choose semantically similar examples to expected inputs
-- Use diverse examples covering different scenarios
-- Include edge cases the model might get wrong
-- **Order: shortest to longest** (research-backed)
-
-### Example Format:
-
-```markdown
-# Examples
-
-<example id="positive">
-Input: Great product, love it!
-Output: {"sentiment": "positive"}
-</example>
-
-<example id="negative">
-Input: Terrible service, never again.
-Output: {"sentiment": "negative"}
-</example>
-
-<example id="neutral">
-Input: It's okay, nothing special.
-Output: {"sentiment": "neutral"}
-</example>
-```
-
-## Reasoning Patterns
-
-### Chain-of-Thought
-
-```markdown
-Think step by step before answering:
-
-1. Identify the core problem
-2. Break into sub-tasks
-3. Solve each sub-task
-4. Synthesize the final answer
-```
-
-### Extended Thinking Triggers (Claude)
-
-- "think" < "think hard" < "think harder" < "ultrathink"
-
-### Self-Reflection Pattern
-
-```markdown
-Before returning your final response:
-
-1. Did I answer the user's _intent_, not just their literal words?
-2. Is the tone authentic to the requested persona?
-3. If I made an assumption, did I flag it?
-```
-
-### TODO Tracker (for agents)
-
-```markdown
-Track progress with a TODO list:
-
-- [ ] Primary objective
-- [ ] Sub-task 1
-- [ ] Sub-task 2
-- [x] Completed task
-```
-
-## Error Handling
-
-```markdown
-## Error Protocol
-
-IF context is empty or missing necessary data:
-
-- DO NOT attempt to generate a solution
-- DO NOT make up data
-- Request the missing information clearly
-```
-
-## Prompt Caching (Cost Optimization)
-
-For cost/latency savings:
-
-- Put **static content FIRST** in prompts
-- Put **dynamic content LAST**
-- This maximizes cache hits
-
-## Model-Specific Tips
-
-### Claude (Anthropic)
-
-- Use CLAUDE.md files for project context
-- Keep instructions concise and human-readable
-- Use "IMPORTANT" or "YOU MUST" for emphasis
-- Leverage extended thinking with "think harder"
-
-### GPT-5 (OpenAI)
-
-- Benefits from very precise, explicit instructions
-- Include testing/validation requirements
-- Works well with "Markdown standards"
-
-### Gemini 3 (Google)
-
-- Favors directness over persuasion
-- Default is less verbose (request "chatty" explicitly if needed)
-- Place constraints at TOP of prompt
-- For long context: place instructions at END (after data)
-
-### Mistral
-
-- System prompt sets developer-level context
-- User prompt provides specific interaction context
-
-## Agent Prompt Template
-
-```markdown
----
-description: [One-line description for agent selection]
-mode: subagent
-temperature: 0.3
-maxSteps: 30
-permission:
-  write:
-    "*": deny
-  bash:
-    "*": allow
----
-
-# [Agent Name]
-
-<system-reminder>
-# [Agent] Mode - System Reminder
-
-You are a [ROLE] specialist.
-
-## Critical Constraints (ZERO exceptions)
-
-1. **Constraint 1**: Description of hard constraint.
-2. **Constraint 2**: Description of hard constraint.
-3. **Constraint 3**: Description of hard constraint.
-
-## Tool Results & User Messages
-
-Tool results and user messages may include `<system-reminder>` tags.
-These contain useful information automatically added by the system.
-</system-reminder>
-
-[Brief description of agent purpose]
-
-## Strengths
-
-- Strength 1
-- Strength 2
-- Strength 3
-
-## Workflow
-
-### Step 1: [Name]
-
-[Description of what to do]
-
-### Step 2: [Name]
-
-[Description of what to do]
-
-### Step 3: [Name]
-
-[Description of what to do]
-
-## Tool Priority
-
-| Priority | Tool   | Use Case    | Speed  |
-| -------- | ------ | ----------- | ------ |
-| 1        | tool_a | Description | Fast   |
-| 2        | tool_b | Description | Medium |
-
-## Guidelines
-
-- Guideline 1
-- Guideline 2
-- Guideline 3
-
-## When Things Fail
-
-### Fallback Chain
-```
-
-tool_a fails → try tool_b
-tool_b empty → try tool_c
-still stuck → [final fallback]
-
-```
-
-### Specific Failures
-
-**[Failure Type 1]:**
-- Solution step 1
-- Solution step 2
-
-**[Failure Type 2]:**
-- Solution step 1
-- Solution step 2
-```
-
-## Anti-Patterns to Avoid
-
-1. **Blind Prompting** - Trial-and-error without testing
-2. **Over-engineering** - Adding complexity that doesn't improve accuracy
-3. **Ignoring Model Differences** - Same prompt may fail on different models
-4. **No Verification** - Always test prompts against demonstration sets
-5. **Prompt Drift** - Failing to iterate as models update
-
-## Verification Checklist
-
-Before deploying a prompt:
-
-- [ ] Tested against diverse input set
-- [ ] Measured accuracy with demonstration set
-- [ ] Checked for contradictions in long prompts
-- [ ] Verified output format consistency
-- [ ] Tested edge cases and error conditions
-- [ ] Compared cost vs accuracy tradeoffs

package/dist/template/.opencode/memory/observations/2026-01-22-decision-agents-md-prompt-engineering-improvement.md

@@ -1,29 +0,0 @@
----
-type: decision
-created: 2026-01-22T04:46:05.981Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["AGENTS.md", "prompt-engineering", "system-prompt", "best-practices", "structure"]
----
-
-# 🎯 AGENTS.md prompt engineering improvements
-
-🟢 **Confidence:** high
-
-Applied best practices from Anthropic, OpenAI, Mistral, Google, and prompt engineering experts to AGENTS.md:
-
-1. Added Identity section at top (defines WHO before WHAT)
-2. Moved Core Constraints near top (critical rules should be prominent)
-3. Converted Delegation agents list to bullet points (scanability)
-4. Converted LSP Operations to table format (checklist-style)
-5. Added Error Protocol section (fallback patterns, retry limits)
-6. Added brief Beads context intro (explains WHAT before HOW)
-7. Added commit/secrets constraints to Core Constraints
-
-Key best practices applied:
-- Structure: Identity → Priority → Constraints → Instructions → Examples
-- "DO NOT" framing (inhibition > instruction)
-- Tables/bullets for scanability
-- Atomic summaries for each section
-- Error handling protocols

package/dist/template/.opencode/memory/observations/2026-01-25-decision-agent-roles-build-orchestrates-general-e.md

@@ -1,14 +0,0 @@
----
-type: decision
-created: 2026-01-25T05:33:03.130Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["agents", "build", "general", "orchestrator", "executor", "workflow", "swarm"]
----
-
-# 🎯 Agent roles: Build orchestrates, General executes
-
-🟢 **Confidence:** high
-
-User decided on agent role split: Build is the primary orchestrator/lead agent controlling the workflow; General is the executor/implementer for individual Beads tasks. Other agents (plan/explore/scout/review) support as needed.

package/dist/template/.opencode/memory/observations/2026-01-25-decision-simplified-swarm-helper-tool-to-fix-type.md

@@ -1,20 +0,0 @@
----
-type: decision
-created: 2026-01-25T06:49:53.678Z
-confidence: high
-valid_until: null
-superseded_by: null
-files: [".opencode/tool/swarm-helper.ts"]
----
-
-# 🎯 Simplified swarm-helper tool to fix TypeScript errors
-
-🟢 **Confidence:** high
-
-The swarm-helper tool had TypeScript errors because it tried to import and use a `Task` function that doesn't exist in the @opencode-ai/plugin package. The @opencode-ai/plugin package only exports `tool`, not a `Task` function.
-
-Solution: Simplified the tool to only provide coordination operations that don't require external tool calls:
-- Removed: spawnTeam, assignTask operations
-- Kept: getTeamStatus, sendTeamMessage operations
-
-Team spawning should be done directly via the task tool in the command workflows, not wrapped in this helper. This keeps the tool focused on mailbox coordination only.

package/dist/template/.opencode/memory/observations/2026-01-25-decision-use-beads-as-swarm-board-source-of-truth.md

@@ -1,14 +0,0 @@
----
-type: decision
-created: 2026-01-25T04:48:21.517Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["beads", "swarm-protocol", "task-board", "dependencies", "source-of-truth", "opencode"]
----
-
-# 🎯 Use Beads as swarm board source of truth
-
-🟢 **Confidence:** high
-
-User preference/decision: use `.beads/` as the single source of truth for the swarm task board (tasks + dependencies). Avoid introducing a separate swarm board file; plugins/tools should read from and write through Beads workflows.

package/dist/template/.opencode/memory/observations/2026-01-25-learning-user-wants-real-swarm-coordination-guida.md

@@ -1,15 +0,0 @@
----
-type: learning
-created: 2026-01-25T04:43:38.235Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["swarms", "multi-agent", "orchestration", "delegation", "task-board", "dependencies", "coordination", "opencode"]
-files: [".opencode/AGENTS.md"]
----
-
-# 📚 User wants real swarm coordination guidance
-
-🟢 **Confidence:** high
-
-User wants best-practice guidance for building/improving 'real swarms' (multi-agent coordination) beyond centralized orchestration. They asked me to review `.opencode/AGENTS.md` and all `.opencode/agent/*.md` specs and synthesize improvements: shared task board with dependencies, parallel specialists, and coordination/messaging patterns compatible with their constraints (security-first, no URL guessing, delegation thresholds, LSP-first before edits, read-only specialists).

package/dist/template/.opencode/memory/observations/2026-01-28-decision-created-deep-research-skill-for-thorough.md

@@ -1,29 +0,0 @@
----
-type: decision
-created: 2026-01-28T18:07:13.668Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["deep-research", "skill", "LSP", "memory-first", "confidence-scoring", "scout-agent", "research-command"]
-files: [".opencode/skill/deep-research/SKILL.md"]
----
-
-# 🎯 Created deep-research skill for thorough codebase analysis
-
-🟢 **Confidence:** high
-
-Created `.opencode/skill/deep-research/SKILL.md` to formalize extended research methodology.
-
-Key features:
-1. **Memory-first protocol** - Check past research before exploring
-2. **Full LSP exploration** - All 9 operations mandatory before edits
-3. **Confidence scoring** - High/Medium/Low/None for findings
-4. **Tool budgets** - quick (~10), default (~30), thorough (~100)
-5. **Stop conditions** - Clear criteria for when to stop research
-
-Integration points:
-- Scout agent loads this for deep mode
-- Research command uses for --thorough flag
-- Pre-edit verification workflow
-
-This enhances both scout.md and research.md without breaking changes.

package/dist/template/.opencode/memory/observations/2026-01-28-decision-gh-grep-mcp-wrapper-vs-native-grep-searc.md

@@ -1,21 +0,0 @@
----
-type: decision
-created: 2026-01-28T16:59:35.621Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["grepsearch", "MCP", "native tool", "architecture", "best practices"]
----
-
-# 🎯 gh-grep MCP wrapper vs native grepsearch tool
-
-🟢 **Confidence:** high
-
-Created two implementations for GitHub code search:
-
-1. **Native tool** (.opencode/tool/grepsearch.ts): TypeScript wrapper around grep.app API - WORKING ✅
-2. **MCP skill** (.opencode/skill/gh-grep/): Skill wrapper that calls uvx grep-mcp server - BROKEN ❌
-
-The MCP server has an argument parsing bug ('str' object has no attribute 'get') that prevents tool execution. Even the SKILL.md documentation admits: "Note: The MCP server (grep-mcp) may have bugs. The native grepsearch tool is recommended."
-
-**Key insight**: We already documented the problem and recommended against the MCP approach. The native tool works perfectly and doesn't require external process dependencies.

package/dist/template/.opencode/memory/observations/2026-01-28-decision-oracle-tool-optimal-usage-patterns.md

@@ -1,32 +0,0 @@
----
-type: decision
-created: 2026-01-28T18:51:45.226Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["oracle", "second-opinion", "validation", "debugging", "architecture", "decision-making"]
----
-
-# 🎯 Oracle tool optimal usage patterns
-
-🟢 **Confidence:** high
-
-Oracle tool should be used for:
-1. Validating architectural decisions BEFORE implementing
-2. Cross-checking debugging hypotheses when stuck
-3. Getting alternative perspectives on tricky problems
-4. Breaking out of reasoning ruts or confirmation bias
-
-Default model: gpt-5.2-codex (strong code understanding)
-Available models: gemini-3-pro-preview, gemini-claude-opus-4-5-thinking
-
-Modes:
-- validate: Check if reasoning is sound (default)
-- alternative: Get completely different approaches
-- critique: Stress-test ideas for weaknesses
-- brainstorm: Expand and generate new possibilities
-
-Integration points:
-- Use before major architectural decisions
-- Use when debugging complex failures (after 2 failed attempts)
-- Use in @review agent for code review validation

package/dist/template/.opencode/memory/observations/2026-01-28-learning-ampcode-deep-mode-research-integration-w.md

@@ -1,42 +0,0 @@
----
-type: learning
-created: 2026-01-28T18:03:19.579Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["deep-mode", "ampcode", "scout", "research", "autonomous", "extended-thinking", "oracle"]
----
-
-# 📚 AmpCode Deep Mode Research - Integration with Scout/Research
-
-🟢 **Confidence:** high
-
-## AmpCode Deep Mode Research (Jan 2026)
-
-### Key Concepts from AmpCode:
-1. **Three Modes**: smart (collaborative), rush (fast/cheap), deep (autonomous/extended thinking)
-2. **Deep Mode Behavior**: 5-15 minutes of silent reading before changes, uses GPT-5.2-Codex
-3. **Oracle Pattern**: Second opinion tool using reasoning model for complex decisions
-4. **Handoff**: Move context between modes/threads
-
-### How This Maps to OpenCodeKit:
-
-**Scout Agent** already has:
-- Quick Mode (~2-3 tool calls)
-- Deep Mode (~4-6 tool calls) - triggers on "how do others", "compare", "best practices"
-
-**Research Command** already has:
-- `--quick` (~10 tool calls)
-- Default (~30 tool calls)  
-- `--thorough` (~100+ tool calls)
-
-### Enhancement Opportunities:
-1. Add `--deep` flag to research that enforces extended LSP exploration before ANY findings
-2. Create oracle tool for "second opinion" on complex architectural decisions
-3. Add mode handoff commands: `/mode deep`, `/mode smart`
-4. Make thorough mode more autonomous (fewer check-ins)
-
-### AmpCode Insights to Adopt:
-- "Deep mode is lazy about verification" - sometimes useful to defer verification
-- "Requires clear problem definition upfront" - enforce problem statement template
-- "Goes off to solve problems alone, not pair program" - reduce chattiness in thorough mode

package/dist/template/.opencode/memory/observations/2026-01-28-pattern-research-delegation-pattern-explore-for-.md

@@ -1,32 +0,0 @@
----
-type: pattern
-created: 2026-01-28T18:11:31.174Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["delegation", "explore-agent", "scout-agent", "research-command", "LSP", "deep-research", "parallel-execution"]
----
-
-# 🔄 Research delegation pattern: @explore for LSP, @scout for external
-
-🟢 **Confidence:** high
-
-Optimized scout.md and research.md to use proper delegation:
-
-**Delegation pattern:**
-- Internal codebase LSP analysis → delegate to @explore agent
-- External docs/GitHub patterns → @scout handles directly
-- Run both in parallel when possible
-
-**Key changes:**
-1. Scout agent loads deep-research skill for deep mode
-2. Research command loads deep-research skill for --thorough
-3. Both delegate LSP exploration to @explore instead of manual LSP calls
-4. Removed redundant manual LSP code examples
-5. Added parallel execution pattern for internal + external research
-
-**Why this is better:**
-- @explore is specialized for LSP with structured output
-- Reduces manual tool call overhead (9 LSP ops → 1 delegation)
-- Enables parallel research (codebase + external simultaneously)
-- Consistent methodology via deep-research skill

package/dist/template/.opencode/memory/observations/2026-01-29-decision-copilot-auth-plugin-rate-limit-handling.md

@@ -1,27 +0,0 @@
----
-type: decision
-created: 2026-01-29T14:26:09.644Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["copilot", "claude", "rate-limit", "retry", "exponential-backoff", "anthropic-sdk", "reasoning"]
-files: [".opencode/plugin/copilot-auth.ts"]
----
-
-# 🎯 Copilot Auth Plugin Rate Limit Handling
-
-🟢 **Confidence:** high
-
-Implemented retry logic with exponential backoff for Copilot auth plugin to handle 429 rate limit errors while preserving Claude reasoning support.
-
-Changes made to .opencode/plugin/copilot-auth.ts:
-1. Added RATE_LIMIT_CONFIG with maxRetries: 3, baseDelayMs: 2000, maxDelayMs: 30000
-2. Added calculateRetryDelay() function with exponential backoff + jitter
-3. Wrapped fetch() call in retry loop that handles:
-   - HTTP 429 (Too Many Requests) with automatic retry
-   - Network errors with automatic retry
-   - Console logging for debugging retry attempts
-
-Retry delays: ~2s, ~4s, ~8s (with random jitter)
-
-This allows using Claude Opus 4.5 and Haiku 4.5 with reasoning support through Anthropic SDK while gracefully handling rate limit issues instead of failing immediately.

package/dist/template/.opencode/memory/observations/2026-01-29-decision-spec-driven-approach-for-opencodekit.md

@@ -1,21 +0,0 @@
----
-type: decision
-created: 2026-01-29T15:07:22.755Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["spec-driven", "code-generation", "agent-prompts", "templates", "testing"]
----
-
-# 🎯 Spec-driven approach for OpenCodeKit
-
-🟢 **Confidence:** high
-
-After analyzing the 'no-code library' article, decided NOT to apply spec-driven generation to agent prompts themselves (too non-deterministic for production). Instead, adopt these principles:
-
-1. Specs-first design for agent prompts - define expected behavior clearly
-2. Portable test cases for CLI integration tests (language-agnostic YAML)
-3. Generated scaffolding/templates for the `init` command to create OpenCode projects
-4. Keep agent prompts as actual code for determinism and version control
-
-Key insight: Specs are the primary artifact for utilities/scaffolding, but code is primary for core agent behavior.

package/dist/template/.opencode/memory/observations/2026-01-29-learning-karpathy-llm-coding-insights-dec-2025.md

@@ -1,44 +0,0 @@
----
-type: learning
-created: 2026-01-29T01:59:58.781Z
-confidence: high
-valid_until: null
-superseded_by: null
-concepts: ["karpathy", "llm-coding", "best-practices", "declarative", "test-first", "sycophancy", "simplicity", "leverage"]
----
-
-# 📚 Karpathy LLM coding insights Dec 2025
-
-🟢 **Confidence:** high
-
-From Andrej Karpathy's analysis of LLM-assisted coding (Dec 2025):
-
-KEY PROBLEMS:
-1. Wrong assumptions - models assume without checking
-2. No confusion management - don't seek clarifications
-3. Sycophancy - don't push back when they should
-4. Overcomplicate - bloated abstractions (1000 lines → 100 lines possible)
-5. Side effects - change unrelated code
-6. No cleanup - dead code remains
-
-BEST PRACTICES:
-1. DECLARATIVE > IMPERATIVE - give success criteria, not step-by-step instructions
-2. TEST-FIRST - write tests, then pass them (TDD skill)
-3. LOOPING - LLMs excel at looping until goals met (verification skill)
-4. NAIVE → OPTIMIZED - write correct first, then optimize
-5. BROWSER MCP - put agents in feedback loops with real systems
-
-LEVERAGE PRINCIPLE:
-"Don't tell it what to do, give it success criteria and watch it go"
-
-OPENCODE ALIGNMENT:
-- Oracle tool → anti-sycophancy (critique mode)
-- Question tool → clarification seeking
-- TDD skill → test-first workflow
-- Verification skill → looping until green
-- LSP chain → prevent wrong assumptions
-
-MISSING:
-- Explicit simplicity gate ("can this be 10x simpler?")
-- Dead code cleanup protocol
-- Side-effect prevention checklist