opkg 0.6.1 → 0.7.0

package/specs/agents-opencode.md

@@ -0,0 +1,622 @@
+---
+title: Agents
+description: Configure and use specialized agents.
+---
+
+Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
+
+:::tip
+Use the plan agent to analyze code and review suggestions without making any code changes.
+:::
+
+You can switch between agents during a session or invoke them with the `@` mention.
+
+---
+
+## Types
+
+There are two types of agents in OpenCode; primary agents and subagents.
+
+---
+
+### Primary agents
+
+Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key, or your configured `switch_agent` keybind. These agents handle your main conversation and can access all configured tools.
+
+:::tip
+You can use the **Tab** key to switch between primary agents during a session.
+:::
+
+OpenCode comes with two built-in primary agents, **Build** and **Plan**. We'll
+look at these below.
+
+---
+
+### Subagents
+
+Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages.
+
+OpenCode comes with two built-in subagents, **General** and **Explore**. We'll look at this below.
+
+---
+
+## Built-in
+
+OpenCode comes with two built-in primary agents and two built-in subagents.
+
+---
+
+### Build
+
+_Mode_: `primary`
+
+Build is the **default** primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands.
+
+---
+
+### Plan
+
+_Mode_: `primary`
+
+A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes.
+By default, all of the following are set to `ask`:
+
+- `file edits`: All writes, patches, and edits
+- `bash`: All bash commands
+
+This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
+
+---
+
+### General
+
+_Mode_: `subagent`
+
+A general-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
+
+---
+
+### Explore
+
+_Mode_: `subagent`
+
+A fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.
+
+---
+
+## Usage
+
+1. For primary agents, use the **Tab** key to cycle through them during a session. You can also use your configured `switch_agent` keybind.
+
+2. Subagents can be invoked:
+   - **Automatically** by primary agents for specialized tasks based on their descriptions.
+   - Manually by **@ mentioning** a subagent in your message. For example.
+
+     ```txt frame="none"
+     @general help me search for this function
+     ```
+
+3. **Navigation between sessions**: When subagents create their own child sessions, you can navigate between the parent session and all child sessions using:
+   - **\<Leader>+Right** (or your configured `session_child_cycle` keybind) to cycle forward through parent → child1 → child2 → ... → parent
+   - **\<Leader>+Left** (or your configured `session_child_cycle_reverse` keybind) to cycle backward through parent ← child1 ← child2 ← ... ← parent
+
+   This allows you to seamlessly switch between the main conversation and specialized subagent work.
+
+---
+
+## Configure
+
+You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
+
+---
+
+### JSON
+
+Configure agents in your `opencode.json` config file:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "{file:./prompts/build.txt}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      }
+    },
+    "plan": {
+      "mode": "primary",
+      "model": "anthropic/claude-haiku-4-20250514",
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false
+      }
+    },
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+---
+
+### Markdown
+
+You can also define agents using markdown files. Place them in:
+
+- Global: `~/.config/opencode/agent/`
+- Per-project: `.opencode/agent/`
+
+```markdown title="~/.config/opencode/agent/review.md"
+---
+description: Reviews code for quality and best practices
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.
+```
+
+The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent.
+
+---
+
+## Options
+
+Let's look at these configuration options in detail.
+
+---
+
+### Description
+
+Use the `description` option to provide a brief description of what the agent does and when to use it.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "description": "Reviews code for best practices and potential issues"
+    }
+  }
+}
+```
+
+This is a **required** config option.
+
+---
+
+### Temperature
+
+Control the randomness and creativity of the LLM's responses with the `temperature` config.
+
+Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "plan": {
+      "temperature": 0.1
+    },
+    "creative": {
+      "temperature": 0.8
+    }
+  }
+}
+```
+
+Temperature values typically range from 0.0 to 1.0:
+
+- **0.0-0.2**: Very focused and deterministic responses, ideal for code analysis and planning
+- **0.3-0.5**: Balanced responses with some creativity, good for general development tasks
+- **0.6-1.0**: More creative and varied responses, useful for brainstorming and exploration
+
+```json title="opencode.json"
+{
+  "agent": {
+    "analyze": {
+      "temperature": 0.1,
+      "prompt": "{file:./prompts/analysis.txt}"
+    },
+    "build": {
+      "temperature": 0.3
+    },
+    "brainstorm": {
+      "temperature": 0.7,
+      "prompt": "{file:./prompts/creative.txt}"
+    }
+  }
+}
+```
+
+If no temperature is specified, OpenCode uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models.
+
+---
+
+### Max steps
+
+Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only. This allows users who wish to control costs to set a limit on agentic actions.
+
+If this is not set, the agent will continue to iterate until the model chooses to stop or the user interrupts the session.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "quick-thinker": {
+      "description": "Fast reasoning with limited iterations",
+      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
+      "maxSteps": 5
+    }
+  }
+}
+```
+
+When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks.
+
+---
+
+### Disable
+
+Set to `true` to disable the agent.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "disable": true
+    }
+  }
+}
+```
+
+---
+
+### Prompt
+
+Specify a custom system prompt file for this agent with the `prompt` config. The prompt file should contain instructions specific to the agent's purpose.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "prompt": "{file:./prompts/code-review.txt}"
+    }
+  }
+}
+```
+
+This path is relative to where the config file is located. So this works for both the global OpenCode config and the project specific config.
+
+---
+
+### Model
+
+Use the `model` config to override the model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+
+:::tip
+If you don’t specify a model, primary agents use the [model globally configured](/docs/config#models) while subagents will use the model of the primary agent that invoked the subagent.
+:::
+
+```json title="opencode.json"
+{
+  "agent": {
+    "plan": {
+      "model": "anthropic/claude-haiku-4-20250514"
+    }
+  }
+}
+```
+
+The model ID in your OpenCode config uses the format `provider/model-id`. For example, if you're using [OpenCode Zen](/docs/zen), you would use `opencode/gpt-5.1-codex` for GPT 5.1 Codex.
+
+---
+
+### Tools
+
+Control which tools are available in this agent with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
+
+```json title="opencode.json" {3-6,9-12}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "tools": {
+    "write": true,
+    "bash": true
+  },
+  "agent": {
+    "plan": {
+      "tools": {
+        "write": false,
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+:::note
+The agent-specific config overrides the global config.
+:::
+
+You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "readonly": {
+      "tools": {
+        "mymcp_*": false,
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+[Learn more about tools](/docs/tools).
+
+---
+
+### Permissions
+
+You can configure permissions to manage what actions an agent can take. Currently, the permissions for the `edit`, `bash`, and `webfetch` tools can be configured to:
+
+- `"ask"` — Prompt for approval before running the tool
+- `"allow"` — Allow all operations without approval
+- `"deny"` — Disable the tool
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  }
+}
+```
+
+You can override these permissions per agent.
+
+```json title="opencode.json" {3-5,8-10}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny"
+  },
+  "agent": {
+    "build": {
+      "permission": {
+        "edit": "ask"
+      }
+    }
+  }
+}
+```
+
+You can also set permissions in Markdown agents.
+
+```markdown title="~/.config/opencode/agent/review.md"
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": ask
+    "git diff": allow
+    "git log*": allow
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+
+You can set permissions for specific bash commands.
+
+```json title="opencode.json" {7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git push": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+This can take a glob pattern.
+
+```json title="opencode.json" {7}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git *": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+And you can also use the `*` wildcard to manage permissions for all commands.
+Since the last matching rule takes precedence, put the `*` wildcard first and specific rules after.
+
+```json title="opencode.json" {8}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "*": "ask",
+          "git status": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+[Learn more about permissions](/docs/permissions).
+
+---
+
+### Mode
+
+Control the agent's mode with the `mode` config. The `mode` option is used to determine how the agent can be used.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "review": {
+      "mode": "subagent"
+    }
+  }
+}
+```
+
+The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is specified, it defaults to `all`.
+
+---
+
+### Additional
+
+Any other options you specify in your agent configuration will be **passed through directly** to the provider as model options. This allows you to use provider-specific features and parameters.
+
+For example, with OpenAI's reasoning models, you can control the reasoning effort:
+
+```json title="opencode.json" {6,7}
+{
+  "agent": {
+    "deep-thinker": {
+      "description": "Agent that uses high reasoning effort for complex problems",
+      "model": "openai/gpt-5",
+      "reasoningEffort": "high",
+      "textVerbosity": "low"
+    }
+  }
+}
+```
+
+These additional options are model and provider-specific. Check your provider's documentation for available parameters.
+
+:::tip
+Run `opencode models` to see a list of the available models.
+:::
+
+---
+
+## Create agents
+
+You can create new agents using the following command:
+
+```bash
+opencode agent create
+```
+
+This interactive command will:
+
+1. Ask where to save the agent; global or project-specific.
+2. Description of what the agent should do.
+3. Generate an appropriate system prompt and identifier.
+4. Let you select which tools the agent can access.
+5. Finally, create a markdown file with the agent configuration.
+
+---
+
+## Use cases
+
+Here are some common use cases for different agents.
+
+- **Build agent**: Full development work with all tools enabled
+- **Plan agent**: Analysis and planning without making changes
+- **Review agent**: Code review with read-only access plus documentation tools
+- **Debug agent**: Focused on investigation with bash and read tools enabled
+- **Docs agent**: Documentation writing with file operations but no system commands
+
+---
+
+## Examples
+
+Here are some examples agents you might find useful.
+
+:::tip
+Do you have an agent you'd like to share? [Submit a PR](https://github.com/anomalyco/opencode).
+:::
+
+---
+
+### Documentation agent
+
+```markdown title="~/.config/opencode/agent/docs-writer.md"
+---
+description: Writes and maintains project documentation
+mode: subagent
+tools:
+  bash: false
+---
+
+You are a technical writer. Create clear, comprehensive documentation.
+
+Focus on:
+
+- Clear explanations
+- Proper structure
+- Code examples
+- User-friendly language
+```
+
+---
+
+### Security auditor
+
+```markdown title="~/.config/opencode/agent/security-auditor.md"
+---
+description: Performs security audits and identifies vulnerabilities
+mode: subagent
+tools:
+  write: false
+  edit: false
+---
+
+You are a security expert. Focus on identifying potential security issues.
+
+Look for:
+
+- Input validation vulnerabilities
+- Authentication and authorization flaws
+- Data exposure risks
+- Dependency vulnerabilities
+- Configuration security issues
+```

package/specs/apply/README.md

@@ -0,0 +1,21 @@
+### Apply Specs
+
+This directory defines the behavior of **apply** (a.k.a. platform apply/sync): projecting a package's canonical content into **platform-specific workspace layouts**, and updating `openpackage.index.yml` to reflect what is actually installed.
+
+Apply can be triggered in two ways:
+
+- `opkg apply` – explicit apply/sync.
+
+> `opkg pack` writes registry snapshots; `opkg save` syncs workspace edits back to a mutable source. Neither mutates platform workspaces unless you run `opkg apply` (or `opkg add --apply` when adding new files).
+
+---
+
+#### Documents
+
+| File | Topic |
+|------|-------|
+| `apply-command.md` | CLI contract: args, flags, and examples |
+| `apply-behavior.md` | What apply does (create/update/delete), timing, and root-package considerations |
+| `conflicts.md` | Conflict handling (interactive vs non-interactive) and strategies |
+| `index-effects.md` | How apply affects `openpackage.index.yml`, including before/after examples |
+

package/specs/apply/apply-behavior.md

@@ -0,0 +1,58 @@
+### Apply – Behavior
+
+#### 1. Definition
+
+**Apply** (also referred to as platform apply/sync) projects a package’s canonical content into **platform-specific workspace locations** based on detected platforms and platform mapping rules.
+
+Apply may be invoked:
+
+- explicitly via `opkg apply`, or
+- as a post-step of `opkg add --apply` (when adding new files before syncing platforms).
+
+---
+
+#### 2. Purpose
+
+- Keep platform-specific working directories (e.g. `.cursor/`, `.opencode/`, etc.) consistent with the package’s canonical content.
+- Ensure `openpackage.index.yml` reflects the **paths that actually exist** after apply.
+
+---
+
+#### 3. Operations
+
+Apply distinguishes between:
+
+- **Create / Update**: write new or changed files to platform-specific targets.
+- **Delete**: remove stale files that were previously installed by the package but no longer exist in the package snapshot.
+
+Apply runs against the set of platforms detected for the effective cwd.
+
+---
+
+#### 4. Timing
+
+Apply only runs after:
+
+- Package detection and name resolution are complete.
+- File mapping/selection has succeeded.
+- When invoked as `opkg add --apply`, the add step has completed successfully.
+
+---
+
+#### 5. Root Package Considerations
+
+- Root packages may skip root-level “self mappings” (where a registry key would map to the exact same on-disk path) to avoid redundant index entries and no-op writes.
+- Root file syncing (e.g., platform-specific root files) may be skipped for root packages when appropriate to avoid syncing “back into itself”.
+
+Nested packages:
+
+- Always participate fully in apply/sync when apply is requested; their changes are projected out to platform workspaces.
+
+---
+
+#### 6. Error Reporting
+
+Failures in apply are surfaced to the user as part of the command result, along with a summary of created/updated/removed paths.
+
+See `conflicts.md` for how apply handles conflicts and interactive prompts.
+