Feature: per-target agent frontmatter transformation during deployment

[Mathf18]

Problem

When APM deploys agent .md files from a marketplace plugin to multiple targets (Claude Code, OpenCode, Codex, etc.), it copies the same file verbatim to each target directory (.claude/agents/, .opencode/agents/, .codex/agents/).

This causes hard crashes on platforms with different frontmatter schemas.

tools field

• Claude Code expects: comma-separated string or array → tools: Read, Grep, Glob or tools: ["Read", "Grep"]
• OpenCode expects: record/object → tools: {Read: true, Grep: true} (Zod schema: z.record(z.string(), z.boolean()))
• Result: OpenCode throws InvalidError ("expected record, received array") — hard crash, unrecoverable

color field

• Claude Code expects: named colors → color: cyan, color: yellow
• OpenCode expects: hex #RRGGBB or theme names (primary, secondary, accent, success, warning, error, info)
• Result: OpenCode throws InvalidError ("Invalid hex color format")

Impact on OpenCode

OpenCode's loadAgent() function calls Agent.safeParse() on the parsed frontmatter. On validation failure, it throws an InvalidError with no catch — a single bad agent file kills the entire application startup. There is no graceful degradation or per-file skip on validation failure.

APM already detects the problem but only during compile

apm compile warns about these files with "Failed to parse primitive ... mapping values are not allowed in this context" — but apm install (which deploys the files) does not validate or warn. The broken files are deployed silently.

Proposed solutions

Option A: Transform frontmatter per target during apm install

During apm install --target <platform>, APM transforms agent frontmatter fields to the target platform's expected format:

1. tools: Convert between array/string (Claude) ↔ record (OpenCode) formats
2. color: Convert between named colors (Claude) ↔ hex/theme names (OpenCode)
3. Unknown fields: Strip fields not supported by the target platform

This would allow plugin authors to write agent files once in any supported format, and APM would handle the translation during deployment.

Option B: Validate and warn during install (not just compile)

apm install should validate agent frontmatter against the target platform's schema and warn about incompatible fields before deploying, rather than silently deploying broken files that crash the target tool. The validation logic already exists in apm compile — it should also run during apm install.

Related

• Support tool overrides for installed agent packages #293 — Support tool overrides for installed agent packages (consumer-side)
• OpenCode agent schema: z.record(z.string(), z.boolean()) for tools, z.union([hex regex, theme enum]) for color (source)

Environment

• APM version: 0.8.10
• Plugin: data-goblin/power-bi-agentic-development v0.17.2
• Targets affected: OpenCode (confirmed hard crash), potentially Codex and Cursor

[Mathf18]

Related: #293 (Support tool overrides for installed agent packages) — that issue covers consumer-side tool overrides in apm.yml. This issue is about APM itself translating agent frontmatter fields between incompatible platform schemas during apm install --target <platform>, so plugin authors don't need to worry about per-platform format differences.

[TPHRyan]

I'm glad this issue has been made - I've just come up against the same issue.

It's somewhat surprising I haven't seen anything like this on the roadmap - for me one of the major sticking points in the current agent landscape is the subtly-different ways that different agents consume the "same" configuration files. As a result, I'd expect a tool aiming to reconcile/unify these agents to at least have plans regarding this

[Mathf18]

Related, but probably separate from the frontmatter transformation problem in this issue:

While validating the OpenCode path, I confirmed that APM does redeploy agents into ~/.config/opencode/agents/ for several marketplace plugins (pbi-desktop, reports, semantic-models, tabular-editor, skills-for-fabric). A forced reinstall restored their tools, color, and model frontmatter as expected.

However, data-goblin/power-bi-agentic-development/plugins/pbip still does not deploy its pbip-validator agent at all.

Evidence from local validation:

• apm install -g -t opencode --update --force -v reports agent integration for the plugins above, but no agent integration for plugins/pbip
• apm.lock.yaml shows plugins/pbip as package_type: hook_package
• the same lockfile shows the working agent-deploying plugins as package_type: marketplace_plugin
• the pbip-validator.md source file exists, so this looks more like package discovery/classification than missing content

So from what I can tell there are two distinct OpenCode/APM problems:

1. agent frontmatter compatibility/transformation (tools, color, etc.)
2. some plugin packages not being classified/deployed in a way that carries their agents at all

I think this second one should likely be tracked separately, but I wanted to note it here because it showed up during validation of the behavior described in this issue.

[sergio-sisternes-epam]

Thanks for the detailed write-up, @Mathf18 -- the OpenCode crash reproduction and schema analysis are really helpful. This is a real problem that needs solving.

We want to address this, but there's an architectural question we need to work through first: should frontmatter transformation happen at install time (where files are deployed) or at compile time (where apm compile already owns source-to-target-specific output)?

Each approach has trade-offs around separation of concerns and user workflow, and we want to get this right before committing to an implementation direction.

Flagging for deeper discussion with @danielmeppiel. We'll update this issue once we have alignment on the approach.

[Mathf18]

Thanks @sergio-sisternes-epam, as I remember, the crash happens directly after apm install. Thanks for the follow-up!

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/multi-target
area/content-security
type/bug
status/needs-design

Milestone

null

Suggested next action

Split the fix into two phases: Phase 1 (immediate bug fix) -- extend apm install to validate agent frontmatter against the target platform schema and warn/skip on validation failure, reusing existing compile-time logic; Phase 2 (feature) -- per-target frontmatter transformation during deployment. Confirm the phase split in a comment and open a PR for Phase 1.

Suggested issue comment

This is a real and critical bug -- OpenCode crashing on startup because APM deployed an incompatible agent file is unacceptable. Thanks for the detailed reproduction with version info and schema references.

The fix should land in two phases:

**Phase 1 (bug fix -- implement this first)**
Extend `apm install` to validate agent frontmatter against the target platform schema before deploying. The validation logic already exists in `apm compile` -- it should run during `apm install` as well. On validation failure: warn the user with a clear message identifying the incompatible field and the target, and skip deploying that agent file rather than deploying a file that crashes the target.

This closes the "silent deployment of broken files" gap immediately and unblocks OpenCode users.

**Phase 2 (feature -- separate issue)**
Per-target frontmatter transformation (Option A in the issue body): APM transforms `tools` array/string <-> record and `color` named <-> hex during deployment. This requires a per-platform schema registry and transform functions -- a design doc should settle the transform table and the handling of unknown fields.

For now, this issue tracks Phase 1. If you are interested in contributing Phase 1, the starting point is [src/apm_cli/integration/skill_integrator.py](https://github.com/microsoft/apm/tree/main/src/apm_cli/integration/skill_integrator.py) and the existing compile-time validation at [src/apm_cli/commands/compile.py](https://github.com/microsoft/apm/tree/main/src/apm_cli/commands/compile.py).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is a genuine and high-severity bug: APM deploys agent files that crash OpenCode on startup, with no graceful degradation. The dual-option framing is appropriate. From a UX perspective, Option B (validate and warn) is the right first fix -- it unblocks users immediately (skip the broken file, show a clear warning) without requiring the complexity of transform tables. Option A (transform) is the right long-term solution but is a separate feature. The issue should be resolved in phases, with Phase 1 (validate and warn) landing first.

Supply Chain Security Expert -- Risk-Surface Reviewer

Frontmatter transformation (Option A) must not silently strip or alter fields that have security implications. The transform table must be an explicit allow-list (fields with known safe transforms) rather than a strip-unknown approach. area/content-security (transformation of deployed package content) and area/multi-target (per-target deployment differences) apply. theme/portability is the primary theme -- the root cause is that APM copies files verbatim across targets with different schemas.

OSS Growth Hacker -- Contributor-Tone Reviewer

Activated -- author has 1 prior interaction on microsoft/apm. The issue body is technically detailed and well-researched (schema references, version info, related issues). The reply should validate the crash report explicitly, acknowledge the OpenCode-specific schema conflict, and give a concrete path for Phase 1 contribution. Warm and encouraging without being condescending.

Python Architect -- Architecture Reviewer

Phase 1 (validate and warn) is straightforward: reuse compile-time validation logic in the install path, wrap in a try/except, emit a warning and skip on failure. Cross-cutting impact is low -- the change lives in SkillIntegrator or the install pipeline. Phase 2 (transform) requires: a per-platform frontmatter schema registry, transform functions for tools and color fields, changes to SkillIntegrator deploy logic, and a maintenance commitment to keep the transform table current as platform schemas evolve. The two phases have very different complexity profiles. status/needs-design is correct to settle the Phase 2 transform approach -- Phase 1 does not require design.

Doc Writer -- Documentation Reviewer

Activated -- Phase 2 (transform) would require documentation of per-target frontmatter rules. Deferred until design is accepted. Phase 1 (validate and warn) should be documented in the apm install reference page (new warning output format). area/docs-site was considered but not added -- the Phase 1 change is a behavior fix, not a new feature requiring new doc pages.

APM CEO -- Triage Arbiter

Real crash bug with clear reproduction. The two-phase approach is the right call: Phase 1 (validate and warn) is a bug fix that can land quickly by reusing existing compile-time logic; Phase 2 (transform) is a feature that needs design. type/bug is correct (the root cause is silent deployment of incompatible files). status/needs-design reflects that the full resolution (Phase 2) requires a transform table design, while acknowledging Phase 1 is unblocked. Maintainers should confirm the phase split in a comment and open a Phase 1 PR. Theme: theme/portability (the bug is caused by verbatim cross-target deployment without schema awareness).

{
  "decision": "needs-design",
  "decision_detail": "Phase 1 (validate and warn during install, reuse compile-time logic) is unblocked; Phase 2 (per-target transform table) requires a design document for the transform rules and unknown-field handling.",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/content-security"],
  "type": "type/bug",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a Phase 1 PR that validates agent frontmatter against target platform schema during apm install and warns/skips on incompatible files, reusing compile-time validation logic.",
  "comment_markdown": "Real crash bug confirmed. Two-phase fix: Phase 1 (bug fix) -- validate frontmatter during install and warn/skip on failure (reuse compile-time logic, no design needed); Phase 2 (feature) -- per-target transform table (needs design). Phase 1 PR can start now at skill_integrator.py + compile.py validation logic."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.6M · ◷