feat: native OpenCode integration + Cursor/OpenCode docs polish by danielmeppiel · Pull Request #307 · microsoft/apm

danielmeppiel · 2026-03-14T23:32:20Z

Summary

Native OpenCode IDE integration — apm install deploys primitives to .opencode/ when the directory exists, plus documentation consistency fixes across all docs for Cursor and OpenCode.

OpenCode primitive mapping

APM Primitive	OpenCode Location	Format
Agents	`.opencode/agents/<name>.md`	MD + YAML frontmatter
Prompts → Commands	`.opencode/commands/<name>.md`	MD + frontmatter
Skills	`.opencode/skills/<name>/SKILL.md`	agentskills.io standard
MCP	`opencode.json` → `mcp` key	JSON (OpenCode-specific schema)
Instructions	`AGENTS.md` (via `apm compile`)	Compiled markdown

What's included

Code:

OpenCodeClientAdapter for MCP server management in opencode.json
OpenCode agent/command integration in install, uninstall, and pack flows
.opencode/skills/ cleanup in both manifest-based and legacy paths
.opencode/hooks/ defensive routing in partition filter
TargetProfile entry for OpenCode (agents, commands, skills — no hooks)
should_integrate_opencode() target detection
.is_dir() guards (not .exists()) for .opencode/ detection

Docs:

All docs pages updated consistently for OpenCode support
README.md headline: adds OpenCode
quick-start.md, first-package.md, compilation.md, ide-tool-integration.md, how-it-works.md, what-is-apm.md, why-apm.md, teams.md, making-the-case.md, cli-commands.md
Clarified that OpenCode needs apm compile for instructions (reads AGENTS.md)

Tests: 1778 unit tests passing. E2E verified: install (5 agents + 5 skills to .opencode/) and uninstall (full cleanup).

Credits

Inspired by @timvw's work in #257. Closes #305.

Add .cursor/ to directory tree example, file deployment description, editor pickup list, commit guidance, and sync tip. Remove Cursor from the compile-only note since it now has full native install support. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update 8 doc pages that still described Cursor as compile-only or omitted .cursor/ from path lists: - first-package.md: Cursor no longer needs apm compile - why-apm.md: Cursor moved from 'bridges other tools' to native - ci-cd.md: drift checks include .cursor/, compile comments updated - github-rulesets.md: Cursor removed from compile-only category - security.md: .cursor/ added to deploy path allowlists and FAQ - compilation.md: .cursor/ in folder tree, Cursor in native list - pack-distribute.md: cursor target option, .cursor/ in bundle tree - cli-commands.md: Cursor integration detection, uninstall table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@timvw

Add OpenCode as a new opt-in integration target. When .opencode/ directory exists, apm install deploys: - Agents → .opencode/agents/<name>.md - Commands → .opencode/commands/<name>.md (from .prompt.md) - Skills → .opencode/skills/<name>/SKILL.md - MCP → opencode.json (new OpenCodeClientAdapter) OpenCode reads AGENTS.md natively, so apm compile already works. Implementation: - Add opencode TargetProfile to KNOWN_TARGETS (targets.py) - Wire agent, command, skill integrators for .opencode/ (opt-in) - Create OpenCodeClientAdapter for opencode.json MCP format - Add opencode to pack/compile target options - Wire install/uninstall for all OpenCode primitives - Add 20 unit tests (1778 total passing) - Update 13 Starlight doc pages - Credit @timvw in CHANGELOG (PR #257 research) Closes #257 Co-authored-by: Tim Van Wassenhove <timvw@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add .opencode/skills/ prefix to manifest-based skill removal - Add .opencode/skills/ to legacy orphan cleanup loop - Remove '# only if .cursor/ already exists' comments from quick-start.md Co-authored-by: Tim Van Wassenhove <timvw@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Use .is_dir() instead of .exists() for target marker checks - Return False (not True) from configure_mcp_server when .opencode/ absent - Thread 'enabled' param through to _to_opencode_format - Add commands_opencode to partition_managed_files docstring - Fix OpenCode MCP format description in ide-tool-integration docs Co-authored-by: Tim Van Wassenhove <timvw@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

OpenCode reads AGENTS.md (not per-file instructions), so apm compile is required for instructions — unlike Copilot/Claude/Cursor which read .github/instructions/ and .cursor/rules/ natively. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add .opencode/hooks/ to partition_managed_files filter (defensive) - Add comment explaining OpenCode has no hooks support - Fix quick-start.md and making-the-case.md missing OpenCode in tool lists Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix 'three' → 'four' AI coding tools count in teams.md - Clarify OpenCode needs apm compile for instructions in first-package.md - Fix should_integrate_opencode docstring: include 'commands' - Add PR #306 reference to CHANGELOG entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds first-class OpenCode support across APM’s integration/pack/compile surface area so that, when .opencode/ is present, apm install can deploy OpenCode-native primitives and MCP config, and the docs consistently describe Cursor/OpenCode behavior.

Changes:

Introduces OpenCode as a known target/profile and wires agent/command/skill + MCP behaviors (.opencode/* + opencode.json).
Extends install/uninstall/pack/compile and managed-file partitioning to recognize OpenCode paths.
Updates docs (and README/CHANGELOG) to describe OpenCode support and directory-based opt-in behavior.

Reviewed changes

Copilot reviewed 33 out of 34 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/unit/integration/test_command_integrator.py	Adds unit coverage for `.prompt.md` → `.opencode/commands/*.md` and OpenCode sync cleanup.
tests/unit/integration/test_agent_integrator.py	Adds unit coverage for `.agent.md` → `.opencode/agents/*.md` and OpenCode sync cleanup.
tests/unit/core/test_target_detection.py	Adds tests for `opencode` target description, `should_integrate_opencode`, and `.opencode/` auto-detection.
src/apm_cli/integration/targets.py	Adds `opencode` `TargetProfile` (agents/commands/skills).
src/apm_cli/integration/skill_integrator.py	Extends skill copy/promotion + sync cleanup to include `.opencode/skills/`.
src/apm_cli/integration/mcp_integrator.py	Adds `opencode` runtime support + stale cleanup in `opencode.json`.
src/apm_cli/integration/command_integrator.py	Adds OpenCode-specific command integration + sync removal.
src/apm_cli/integration/base_integrator.py	Extends managed-file partitioning to bucket OpenCode agents/commands and recognize `.opencode/*` prefixes.
src/apm_cli/integration/agent_integrator.py	Adds OpenCode-specific agent integration + sync removal.
src/apm_cli/factory.py	Registers `OpenCodeClientAdapter` in `ClientFactory`.
src/apm_cli/core/target_detection.py	Adds `opencode` to target types, detection logic, integration predicate, and descriptions.
src/apm_cli/commands/uninstall.py	Adds uninstall-time sync cleanup for `.opencode/agents`, `.opencode/commands`, `.opencode/skills`.
src/apm_cli/commands/pack.py	Adds `opencode` to `apm pack --target` choices.
src/apm_cli/commands/install.py	Threads `integrate_opencode` through integration orchestration and records deployed OpenCode paths.
src/apm_cli/commands/compile.py	Adds `opencode` to compile `--target` choices and help text.
src/apm_cli/bundle/packer.py	Adds `.opencode/` filtering for `apm pack --target opencode`.
src/apm_cli/adapters/client/opencode.py	New MCP adapter translating Copilot schema → OpenCode `opencode.json` (`mcp` key).
docs/src/content/docs/reference/cli-commands.md	Documents OpenCode auto-detection + install/uninstall/pack behavior updates.
docs/src/content/docs/introduction/why-apm.md	Mentions `.opencode/` as an additional opt-in native integration directory.
docs/src/content/docs/introduction/what-is-apm.md	Adds OpenCode to supported tools table and narrative.
docs/src/content/docs/introduction/how-it-works.md	Adds OpenCode native integration description and MCP mention.
docs/src/content/docs/integrations/ide-tool-integration.md	Adds OpenCode integration section + compile note for instructions.
docs/src/content/docs/integrations/ci-cd.md	Updates drift-check paths and “commit deployed files” guidance to include `.opencode/`.
docs/src/content/docs/guides/skills.md	Adds `.opencode/skills/` as an opt-in compatibility target.
docs/src/content/docs/guides/pack-distribute.md	Updates pack target docs and example bundle tree to include `.opencode/`.
docs/src/content/docs/guides/compilation.md	Updates compilation guidance to clarify OpenCode’s instruction source (`AGENTS.md`).
docs/src/content/docs/getting-started/quick-start.md	Updates quick start examples and narrative to include OpenCode outputs.
docs/src/content/docs/getting-started/first-package.md	Updates first-package guide to mention OpenCode in the tool set and compile expectations.
docs/src/content/docs/enterprise/teams.md	Updates enterprise narrative to include OpenCode as a 4th tool.
docs/src/content/docs/enterprise/security.md	Updates security posture wording for `.opencode/` allowlisted deploy prefixes.
docs/src/content/docs/enterprise/making-the-case.md	Updates positioning text to include OpenCode.
README.md	Adds OpenCode mention in headline and compile standards list.
CHANGELOG.md	Adds Unreleased entries for native OpenCode integration and OpenCode MCP adapter.
.gitignore	Adds `scout-pipeline-result.png` ignore entry.

Comments suppressed due to low confidence (2)

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

Step 2 states that “Instructions … were deployed to … .opencode/”, but OpenCode instructions are described elsewhere as coming from AGENTS.md via apm compile (and OpenCode doesn’t use an .opencode/ instructions directory). Consider rewording this line to avoid implying that apm install deploys instructions into .opencode/.

1. The package was downloaded into `apm_modules/` (like `node_modules/`).
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.

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

This paragraph says OpenCode “pick[s] up the new context immediately … no compile step”, but the OpenCode flow in this PR relies on apm compile to generate AGENTS.md for instructions. Consider qualifying this statement (e.g., immediate for agents/commands/skills/MCP; compile needed when you want instruction updates reflected in AGENTS.md).

## That's it

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.

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

    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


src/apm_cli/commands/install.py

            detect_target,
            should_integrate_vscode,
            should_integrate_claude,
+            should_integrate_opencode,
            get_target_description,
        )



src/apm_cli/commands/compile.py

 @click.option(
    "--target",
    "-t",
-    type=click.Choice(["vscode", "agents", "claude", "all"]),
+    type=click.Choice(["vscode", "agents", "claude", "opencode", "all"]),
    default=None,
-    help="Target platform: vscode/agents (AGENTS.md), claude (CLAUDE.md), or all. Auto-detects if not specified.",
+    help="Target platform: vscode/agents (AGENTS.md), claude (CLAUDE.md), opencode (AGENTS.md), or all. Auto-detects if not specified.",


src/apm_cli/integration/skill_integrator.py

+        opencode_skills_dir = project_root / ".opencode" / "skills"
+        if opencode_skills_dir.exists():
+            result = self._clean_orphaned_skills(opencode_skills_dir, installed_skill_names)
+            stats['files_removed'] += result['files_removed']
+            stats['errors'] += result['errors']


src/apm_cli/integration/targets.py

+    # OpenCode does not support hooks — instructions are via AGENTS.md (apm compile).
+    "opencode": TargetProfile(
+        name="opencode",
+        root_dir=".opencode",
+        primitives={
+            "agents": PrimitiveMapping(
+                "agents", ".md", "opencode_agent"
+            ),
+            "commands": PrimitiveMapping(
+                "commands", ".md", "opencode_command"
+            ),
+            "skills": PrimitiveMapping(
+                "skills", "/SKILL.md", "skill_standard"
+            ),
+        },
+        auto_create=False,
+        detect_by_dir=True,
+    ),


danielmeppiel and others added 12 commits March 14, 2026 23:46

chore: remove accidentally committed PNG

2dab08d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

chore: gitignore scout-pipeline-result.png

137213c

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs: add OpenCode to AGENTS.md consumers list

53f5069

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs: add OpenCode to README headline and compile description

ca5a88b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings March 14, 2026 23:32

Copilot started reviewing on behalf of danielmeppiel March 14, 2026 23:32 View session

danielmeppiel closed this Mar 14, 2026

Copilot AI reviewed Mar 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: native OpenCode integration + Cursor/OpenCode docs polish#307

feat: native OpenCode integration + Cursor/OpenCode docs polish#307
danielmeppiel wants to merge 12 commits intomainfrom
feat/opencode-integration

danielmeppiel commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

danielmeppiel commented Mar 14, 2026

Summary

OpenCode primitive mapping

What's included

Credits

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants