feat: add native OpenCode integration

.gitignore

@@ -69,3 +69,4 @@ skill-plan.md
 skill-strategy.md
 apm_modules/
 build/tmp/
+scout-pipeline-result.png

CHANGELOG.md

@@ -11,8 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Native Cursor IDE integration — `apm install` deploys primitives to `.cursor/` when the directory exists: instructions→rules (`.mdc`), agents, skills, hooks (`hooks.json`), and MCP (`mcp.json`)
+- Native OpenCode integration — `apm install` deploys primitives to `.opencode/` when the directory exists: agents, commands (from prompts), skills, and MCP (`opencode.json`) — inspired by @timvw (#257, #306)
 - `TargetProfile` data layer (`src/apm_cli/integration/targets.py`) — data-driven target definitions for scalable multi-target architecture
 - `CursorClientAdapter` for MCP server management in `.cursor/mcp.json`
+- `OpenCodeClientAdapter` for MCP server management in `opencode.json`
 
 ## [0.7.9] - 2026-03-13
 

docs/src/content/docs/enterprise/making-the-case.md

@@ -52,7 +52,7 @@ An internal advocacy toolkit for APM. Each section is self-contained and designe
 
 Plugins handle single-tool installation for a single AI platform. APM adds capabilities that plugins do not provide:
 
-- **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, and any other agent runtime simultaneously.
+- **Cross-tool composition.** One manifest manages configuration for Copilot, Claude, Cursor, OpenCode, and any other agent runtime simultaneously.
 - **Consumer-side lock files.** Plugins install the latest version. APM pins exact versions so your team stays synchronized.
 - **CI enforcement.** There is no plugin equivalent of `apm audit --ci` for drift detection in a CI pipeline.
 - **Multi-source dependency resolution.** APM resolves transitive dependencies across packages from multiple git hosts.

docs/src/content/docs/enterprise/security.md

@@ -12,7 +12,7 @@ This page documents APM's security posture for enterprise security reviews, comp
 APM is a build-time dependency manager for AI prompts and configuration. It performs four operations:
 
 1. **Resolves git repositories** — clones or sparse-checks-out packages from GitHub or Azure DevOps.
-2. **Deploys static files** — copies markdown, JSON, and YAML files into project directories (`.github/`, `.claude/`, `.cursor/`).
+2. **Deploys static files** — copies markdown, JSON, and YAML files into project directories (`.github/`, `.claude/`, `.cursor/`, `.opencode/`).
 3. **Generates compiled output** — produces `AGENTS.md`, `CLAUDE.md`, and similar files from templates and prompts.
 4. **Records a lock file** — writes `apm.lock.yaml` with exact commit SHAs for every resolved dependency.
 
@@ -66,7 +66,7 @@ APM deploys files only to controlled subdirectories within the project root. Thr
 All deploy paths are validated before any file operation. The `validate_deploy_path` check enforces three rules:
 
 1. **No `..` segments.** Any path containing `..` is rejected outright.
-2. **Allowed prefixes only.** Paths must start with an allowed prefix (`.github/`, `.claude/`, or `.cursor/`).
+2. **Allowed prefixes only.** Paths must start with an allowed prefix (`.github/`, `.claude/`, `.cursor/`, or `.opencode/`).
 3. **Resolution containment.** The fully resolved path must remain within the project root directory.
 
 A path must pass all three checks. Failure on any check prevents the file from being written.
@@ -188,7 +188,7 @@ No. APM makes no network requests beyond git clone/fetch operations to resolve d
 
 ### Can a malicious package write files outside the project?
 
-No. All deploy paths are validated against the project root using path traversal checks, prefix allowlists, and resolved path containment. Symlinks are skipped entirely. A package cannot write files outside `.github/`, `.claude/`, or `.cursor/` within the project root.
+No. All deploy paths are validated against the project root using path traversal checks, prefix allowlists, and resolved path containment. Symlinks are skipped entirely. A package cannot write files outside `.github/`, `.claude/`, `.cursor/`, or `.opencode/` within the project root.
 
 ### Can a transitive dependency inject MCP servers?
 

docs/src/content/docs/enterprise/teams.md

@@ -13,7 +13,7 @@ Every configuration change is auditable.
 
 ## The problem at scale
 
-Consider a mid-to-large engineering organization: 50 repositories, 200 developers, three AI coding tools (Copilot, Claude, Cursor).
+Consider a mid-to-large engineering organization: 50 repositories, 200 developers, four AI coding tools (Copilot, Claude, Cursor, OpenCode).
 
 Without centralized configuration management, a predictable set of problems emerges:
 
@@ -61,7 +61,7 @@ Two developers running `apm install` from the same lock file get identical confi
 
 ### Install
 
-`apm install` reads the lock file and deploys configuration into the native formats expected by each tool — `.github/` for Copilot, `.claude/` for Claude, `.cursor/` for Cursor. APM generates static files and then gets out of the way. There is no runtime, no daemon, no background process.
+`apm install` reads the lock file and deploys configuration into the native formats expected by each tool — `.github/` for Copilot, `.claude/` for Claude, `.cursor/` for Cursor, `.opencode/` for OpenCode. APM generates static files and then gets out of the way. There is no runtime, no daemon, no background process.
 
 ### Audit
 

docs/src/content/docs/getting-started/first-package.md

@@ -105,13 +105,13 @@ APM automatically:
 
 ## 7. Optional: Compile for Other Tools
 
-If you use tools beyond GitHub Copilot, Claude, and Cursor (which read deployed primitives natively), generate compiled instruction files:
+If you use tools beyond GitHub Copilot, Claude, Cursor, and OpenCode (which read deployed primitives natively), generate compiled instruction files:
 
 ```bash
 apm compile
 ```
 
-This produces `AGENTS.md` (for Codex) and `CLAUDE.md` for tools that need a single instructions file. Copilot, Claude, and Cursor users can skip this step.
+This produces `AGENTS.md` (for Codex, Gemini) and `CLAUDE.md` for tools that need a single instructions file. Copilot, Claude, and Cursor users can skip this step — OpenCode users need `apm compile` only if their packages include instructions (OpenCode reads `AGENTS.md` for those).
 
 ## Next Steps
 

docs/src/content/docs/getting-started/quick-start.md

@@ -82,17 +82,22 @@ my-project/
     commands/
       apm-sample-package/
         ...
-  .cursor/                          # only if .cursor/ already exists
+  .cursor/
     rules/
       design-standards.mdc
     agents/
       design-reviewer.md
+  .opencode/
+    agents/
+      design-reviewer.md
+    commands/
+      design-review.md
 ```
 
 Three things happened:
 
 1. The package was downloaded into `apm_modules/` (like `node_modules/`).
-2. Instructions, agents, and skills were deployed to `.github/`, `.claude/`, and `.cursor/` (when present) -- the native directories that GitHub Copilot, Claude, and Cursor read from.
+2. Instructions, agents, and skills were deployed to `.github/`, `.claude/`, `.cursor/`, and `.opencode/` (when present) -- the native directories that GitHub Copilot, Claude, Cursor, and OpenCode read from.
 3. A lockfile (`apm.lock.yaml`) was created, pinning the exact commit so every team member gets identical configuration.
 
 Your `apm.yml` now tracks the dependency:
@@ -107,7 +112,7 @@ dependencies:
 
 ## That's it
 
-Open your editor. GitHub Copilot, Claude, and Cursor pick up the new context immediately -- no extra configuration, no compile step, no restart. The agent now knows your project's design standards, can run your prompt templates, and follows the conventions defined in the package.
+Open your editor. GitHub Copilot, Claude, Cursor, and OpenCode pick up the new context immediately -- no extra configuration, no compile step, no restart. The agent now knows your project's design standards, can run your prompt templates, and follows the conventions defined in the package.
 
 This is the core idea: **packages define what your AI agent knows, and `apm install` puts that knowledge exactly where your tools expect it.**
 

docs/src/content/docs/guides/compilation.md

@@ -4,7 +4,7 @@ sidebar:
   order: 1
 ---
 
-Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. `apm compile` is for teams that use Codex, Gemini, or other tools that read single-root-file formats like `AGENTS.md` or `CLAUDE.md`. It is also useful when you want a consolidated view of all instructions in one file.
+Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. For OpenCode, `apm install` deploys agents, commands, skills, and MCP, but instructions require `apm compile` to generate the `AGENTS.md` that OpenCode reads. `apm compile` is also needed for Codex, Gemini, or other tools that read single-root-file formats.
 
 **Solving the AI agent scalability problem through constraint satisfaction optimization**
 
@@ -42,14 +42,14 @@ target: copilot  # or vscode, claude, or all
 
 | Target | Files Generated | Consumers |
 |--------|-----------------|-----------|
-| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, Codex, Gemini |
+| `copilot` | `AGENTS.md` | GitHub Copilot, Cursor, OpenCode, Codex, Gemini |
 | `claude` | `CLAUDE.md` | Claude Code, Claude Desktop |
 | `all` | Both `AGENTS.md` and `CLAUDE.md` | Universal compatibility |
 | `minimal` | `AGENTS.md` only | Works everywhere, no folder integration |
 
 > **Aliases**: `vscode` and `agents` are accepted as aliases for `copilot`.
 
-> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, and `.cursor/agents/`.
+> **Note**: `AGENTS.md` and `CLAUDE.md` contain **only instructions** (grouped by `applyTo` patterns). Prompts, agents, commands, hooks, and skills are integrated by `apm install`, not `apm compile`. See the [Integrations Guide](../../integrations/ide-tool-integration/) for details on how `apm install` populates `.github/prompts/`, `.github/agents/`, `.github/skills/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/agents/`, `.opencode/agents/`, and `.opencode/commands/`.
 
 ### How It Works
 
@@ -435,10 +435,11 @@ Different AI tools get different levels of support from `apm install` vs `apm co
 | GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** |
 | Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
 | Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
+| OpenCode | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP) | Via `AGENTS.md` | **Full** |
 | Codex CLI | -- | `AGENTS.md` | Instructions via compile |
 | Gemini | -- | `GEMINI.md` | Instructions via compile |
 
-For Copilot, Claude, and Cursor users, `apm install` handles everything natively. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
+For Copilot, Claude, and Cursor users, `apm install` handles everything natively. OpenCode users should also run `apm compile` to generate `AGENTS.md` for instructions. Compilation is the bridge that brings instruction support to tools that do not yet have first-class APM integration.
 
 ## Theoretical Foundations
 

docs/src/content/docs/guides/pack-distribute.md

@@ -62,7 +62,7 @@ apm pack --dry-run
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--format` | `apm` | Bundle format (`apm` or `plugin`) |
-| `-t, --target` | auto-detect | File filter: `copilot`, `vscode`, `claude`, `cursor`, `all`. `vscode` is an alias for `copilot` |
+| `-t, --target` | auto-detect | File filter: `copilot`, `vscode`, `claude`, `cursor`, `opencode`, `all`. `vscode` is an alias for `copilot` |
 | `--archive` | off | Produce `.tar.gz` instead of directory |
 | `-o, --output` | `./build` | Output directory |
 | `--dry-run` | off | List files without writing |
@@ -77,7 +77,8 @@ The target flag controls which deployed files are included based on path prefix:
 | `vscode` | Alias for `copilot` |
 | `claude` | Paths starting with `.claude/` |
 | `cursor` | Paths starting with `.cursor/` |
-| `all` | `.github/`, `.claude/`, and `.cursor/` |
+| `opencode` | Paths starting with `.opencode/` |
+| `all` | `.github/`, `.claude/`, `.cursor/`, and `.opencode/` |
 
 When no target is specified, APM auto-detects from the `target` field in `apm.yml`, falling back to `all`.
 
@@ -134,6 +135,11 @@ build/my-project-1.0.0/
       ...
     agents/
       ...
+  .opencode/
+    agents/
+      ...
+    commands/
+      ...
   apm.lock.yaml
 ```
 

docs/src/content/docs/guides/skills.md

@@ -54,6 +54,7 @@ APM copies skills directly to `.github/skills/` (primary), `.claude/skills/`, an
 - **Primary**: `.github/skills/{skill-name}/` — Works with Copilot, Codex, Gemini
 - **Compatibility**: `.claude/skills/{skill-name}/` — Only if `.claude/` folder already exists
 - **Compatibility**: `.cursor/skills/{skill-name}/` — Only if `.cursor/` folder already exists
+- **Compatibility**: `.opencode/skills/{skill-name}/` — Only if `.opencode/` folder already exists
 
 ### Skill Folder Naming
 
@@ -293,6 +294,7 @@ APM decides where to output skills based on project structure:
 | `.github/` exists | `.github/skills/{skill-name}/SKILL.md` |
 | `.claude/` also exists | Also copies to `.claude/skills/{skill-name}/SKILL.md` |
 | `.cursor/` also exists | Also copies to `.cursor/skills/{skill-name}/SKILL.md` |
+| `.opencode/` also exists | Also copies to `.opencode/skills/{skill-name}/SKILL.md` |
 | Neither exists | Creates `.github/skills/` |
 
 Override with:

docs/src/content/docs/integrations/ci-cd.md

@@ -67,13 +67,13 @@ This step is not needed if your team only uses GitHub Copilot and Claude, which
 
 ### Verify Deployed Primitives
 
-To ensure `.github/`, `.claude/`, and `.cursor/` integration files stay in sync with `apm.yml`, add a drift check:
+To ensure `.github/`, `.claude/`, `.cursor/`, and `.opencode/` integration files stay in sync with `apm.yml`, add a drift check:
 
 ```yaml
       - name: Check APM integration drift
         run: |
           apm install
-          if [ -n "$(git status --porcelain -- .github/ .claude/ .cursor/)" ]; then
+          if [ -n "$(git status --porcelain -- .github/ .claude/ .cursor/ .opencode/)" ]; then
             echo "APM integration files are out of date. Run 'apm install' and commit."
             exit 1
           fi
@@ -171,6 +171,6 @@ See the [Pack & Distribute guide](../../guides/pack-distribute/) for the full wo
 
 - **Pin APM version** in CI to avoid unexpected changes: `pip install apm-cli==0.7.7`
 - **Commit `apm.lock.yaml`** so CI resolves the same dependency versions as local development
-- **Commit `.github/`, `.claude/`, and `.cursor/` deployed files** so contributors and cloud-based Copilot get agent context without running `apm install`
+- **Commit `.github/`, `.claude/`, `.cursor/`, and `.opencode/` deployed files** so contributors and cloud-based Copilot get agent context without running `apm install`
 - **If using `apm compile`** (for Codex, Gemini), run it in CI and fail the build if the output differs from what's committed
 - **Use `GITHUB_APM_PAT`** for private dependencies; never use the default `GITHUB_TOKEN` for cross-repo access

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -148,7 +148,7 @@ apm install microsoft/apm-sample-package
 
 ### Optional: Compiled Context with AGENTS.md
 
-For tools that do not support granular primitive discovery (such as Codex or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read deployed primitives natively.
+For tools that do not support granular primitive discovery (such as Codex or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode also reads `AGENTS.md`, so run `apm compile` to deploy instructions there.
 
 ```bash
 # Compile all local and dependency instructions into AGENTS.md
@@ -184,6 +184,22 @@ When you run `apm install`, APM integrates package primitives into Claude's nati
 | `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
 | `.claude/settings.json` (hooks key) | Hooks from installed packages (merged into settings) |
 
+### OpenCode (`.opencode/`)
+
+APM natively integrates with OpenCode when a `.opencode/` directory exists in your project. Run `apm install` and APM automatically deploys primitives to OpenCode's native format:
+
+| APM Primitive | OpenCode Destination | Format |
+|---|---|---|
+| Agents (`.agent.md`) | `.opencode/agents/*.md` | Markdown with YAML frontmatter |
+| Prompts (`.prompt.md`) | `.opencode/commands/*.md` | Converted to command format |
+| Skills (`SKILL.md`) | `.opencode/skills/{name}/SKILL.md` | Identical (agentskills.io standard) |
+| MCP servers | `opencode.json` | `mcp` key with `command` array, `environment` |
+| Instructions | Via `AGENTS.md` | Read natively by OpenCode |
+
+**Setup**: Create a `.opencode/` directory in your project root, then run `apm install`. APM detects the directory and deploys automatically. OpenCode reads `AGENTS.md` natively for instructions.
+
+> **Note**: OpenCode does not support hooks.
+
 #### Cursor (`.cursor/`)
 
 | Location | Purpose |
@@ -286,7 +302,7 @@ apm install anthropics/claude-plugins-official/plugins/hookify
 
 ### Optional: Target-Specific Compilation
 
-Compilation is optional for Copilot, Claude, and Cursor, which read deployed primitives natively. Use it when targeting tools like Codex or Gemini, or when you want a single merged instruction file:
+Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode, run `apm compile` to generate `AGENTS.md` (OpenCode's instruction source). Also use it when targeting Codex or Gemini:
 
 ```bash
 # Generate all formats (default)

docs/src/content/docs/introduction/how-it-works.md

@@ -123,7 +123,7 @@ graph TD
 4. **AI Coding Agents** - Execute your compiled workflows (Copilot, Cursor, etc.)
 5. **Supporting Infrastructure** - MCP servers for tools, LLM models for execution
 
-GitHub Copilot and Claude read the deployed primitives natively. Cursor also receives native integration when `.cursor/` exists (rules, agents, skills, hooks, MCP). For other tools (Codex, Gemini), `apm compile` generates an `agents.md` instruction file they can consume.
+GitHub Copilot and Claude read the deployed primitives natively. Cursor and OpenCode also receive native integration when `.cursor/` or `.opencode/` exists. For other tools (Codex, Gemini), `apm compile` generates an `agents.md` instruction file they can consume.
 
 ## The Three Layers Explained
 
@@ -271,6 +271,7 @@ APM auto-detects the target based on project structure (`.github/` or `.claude/`
 For tools that read a single instructions file, `apm compile` merges your primitives into a portable document the tool can consume. This gives you instruction-level support rather than full primitive integration.
 
 - **Cursor** - native integration to `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json`
+- **OpenCode** - native integration to `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, `opencode.json` (MCP)
 - **Codex CLI** - compiled to `AGENTS.md`
 - **Gemini** - compiled to `GEMINI.md`