cm-labs.md

[Timbermitch]

APM Feedback — CM Labs (Wanda)

Team name: CM Labs
Project: Wanda — AI Data Engineer for Microsoft Fabric
Repo: https://github.com/Timbermitch/wanda/blob/main/apm.yml
Submitter: Timbermitch

What we used APM for

We used APM as the manifest layer for Wanda — an agent that investigates failed Microsoft Fabric pipelines. The apm.yml describes:

• The agent persona (linked via AGENTS.md)
• The MCP server config (linked via mcp.json) which exposes 4 Fabric tools
• The Python entrypoint (src/wanda.py)
• Capabilities and read-only Fabric permissions

This let us co-locate the agent's identity, tools, runtime, and permissions in one declarative file alongside the source code.

What worked

• The apm.yml schema was easy to write by hand. Clear separation between metadata, runtime config, capabilities, and permissions.
• Linking to AGENTS.md and mcp.json from a single manifest is great — it keeps the agent's persona, tools, and runtime co-located.
• The capabilities and permissions sections felt natural for describing what Wanda does (read-only Fabric investigation) without overpromising.
• Treating the agent as a versionable package alongside the code is the right mental model.

What could be improved

• Documentation for apm.yml is still light. We had to look at examples in the APM repo to figure out the expected fields.
• It wasn't obvious whether permissions are enforced at runtime or just declarative metadata.
• The versioning convention (apiVersion: apm.github.com/v1) — we copied this from examples but couldn't find a definitive reference.
• A schema definition (JSON Schema or similar) so editors can validate apm.yml while you write it would be a big win.
• Example manifests for common agent shapes — read-only investigation agent, write-capable workflow agent, multi-MCP-server agent — would help newcomers.
• Tighter integration with the Copilot SDK so the SDK can read apm.yml directly to discover MCP servers and persona, instead of needing separate config.

Overall

Useful piece of the puzzle. The single-manifest approach is the right idea — it makes agents portable and reproducible. Mostly needs more docs and tooling around the schema to feel production-ready. We'd use it again.

[github-actions]

Triage decision

defer-later

Proposed labels

area/docs-site
area/package-authoring
type/docs
status/accepted

Milestone

null

Suggested next action

Extract each piece of feedback into a separate, scoped issue (schema reference docs, JSON Schema / editor validation, example manifests) and link them back here as the parent.

Suggested issue comment

Thanks for sharing this detailed write-up, Timbermitch! Using APM to declaratively describe Wanda's identity, MCP tools, runtime, and permissions as a versionable agent package is exactly the use case APM is built for -- hearing it worked for a production pipeline-investigation agent on Microsoft Fabric is great signal.

Your feedback points at real gaps we know exist:

1. **`apm.yml` field reference is sparse** -- we rely too heavily on examples rather than a proper schema reference. The canonical docs page is https://github.com/microsoft/apm/tree/main/docs/src/content/docs/reference but it does not yet have a field-by-field `apm.yml` guide.

2. **`permissions` are declarative metadata**, not runtime-enforced constraints. APM records them in the manifest so tooling and humans can audit what an agent declares it needs, but it does not intercept or gate on permissions at runtime. We should make this explicit in the docs.

3. **`apiVersion: apm.github.com/v1`** is the current stable value. The reference lives at https://github.com/microsoft/apm#-apmyml -- not ideal, we need a versioned spec page.

4. **JSON Schema for `apm.yml`** is a high-value tooling improvement (editor validation, `$schema` pointer in manifests). This is a concrete, scoped task that would make a great first contribution.

5. **Example manifests for common shapes** (read-only investigation agent, write-capable workflow agent, multi-MCP-server agent) would dramatically improve the on-ramp.

6. **Copilot SDK integration** (SDK reads `apm.yml` directly to discover MCP servers + persona) is a longer-horizon goal that requires SDK-side collaboration and is out of scope for this issue.

For now this thread is a useful parent. If you or anyone else wants to take on any of the above, opening a focused issue with a specific scope is the best path -- or jump straight to a PR for the JSON Schema (even a minimal draft helps anchor the discussion).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Real surface identified: apm.yml authoring experience for new users. The feedback maps directly to the first-run funnel -- a new adopter hand-writes a manifest by copying examples because no authoritative schema reference exists. The JSON Schema request is standard practice in npm/cargo ecosystems (package.json schema, Cargo.toml schema) and would immediately improve the first-run experience. The permissions clarity request addresses a developer security mental-model gap (are these enforced or advisory?). All of these are grounded in the README-anchored capability of APM as a declarative agent manifest layer.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication for the primary feedback. One observation worth noting in docs: the permissions field is declarative metadata, not a runtime enforcement gate -- this should be stated clearly in the schema reference to prevent users from assuming APM enforces read-only or write-capable boundaries at the tool level. Clarifying this in docs reduces the risk of users believing APM provides a security boundary it does not.

OSS Growth Hacker -- Contributor-Tone Reviewer

Timbermitch is a NONE-association first-time contributor who came back after using APM in production to give detailed, structured feedback -- this is the highest-value contributor signal: a power user with real deployment experience. The reply should warmly acknowledge the production usage context (Wanda, Microsoft Fabric) by name, treat each feedback point as actionable, and actively invite a contribution (JSON Schema is a perfect first PR target). Converting this user into a contributor for the schema tooling work would be a meaningful outcome.

Python Architect -- Architecture Reviewer

Not activated -- the issue is feedback and documentation requests with no proposed code changes or cross-cutting design decisions required; there is no interface, data model, or migration boundary at stake in this issue.

Doc Writer -- Documentation Reviewer

Docs work is clearly implied: (1) a field-by-field apm.yml schema reference page, (2) a permissions model clarification (declarative vs runtime), (3) an apiVersion reference, (4) example manifest pages for common agent shapes. All of these belong in docs/src/content/docs/reference/ and docs/src/content/docs/getting-started/. area/docs-site is the primary area. area/package-authoring rides as secondary because the JSON Schema tooling and example manifests fall under the package authoring surface. The suggested comment wording uses "agent manifest", "apm.yml", and "MCP tools" consistently with how the README and docs use these terms.

APM CEO -- Triage Arbiter

This feedback validates that the declarative manifest model is right and that adoption is happening in real enterprise scenarios (Microsoft Fabric pipelines). The gaps are real and block adoption: sparse docs, no editor tooling, and ambiguous permissions semantics undermine the "production-ready" story. Deferred because the feedback bundles several distinct work items that need to be split into focused issues before any one of them can land. Priority is clear but not urgent enough to pull a milestone assignment -- let maintainers split and schedule. The JSON Schema work especially should be labeled good first issue when it gets its own issue.

{
  "decision": "defer-later",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/docs-site", "area/package-authoring"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Extract each piece of feedback into a separate, scoped issue (schema reference docs, JSON Schema / editor validation, example manifests) and link them back here as the parent.",
  "comment_markdown": "Thanks for sharing this detailed write-up, Timbermitch! Using APM to declaratively describe Wanda's identity, MCP tools, runtime, and permissions as a versionable agent package is exactly the use case APM is built for -- hearing it worked for a production pipeline-investigation agent on Microsoft Fabric is great signal.\n\nYour feedback points at real gaps we know exist:\n\n1. **`apm.yml` field reference is sparse** -- we rely too heavily on examples rather than a proper schema reference.\n\n2. **`permissions` are declarative metadata**, not runtime-enforced constraints. APM records them in the manifest so tooling and humans can audit what an agent declares it needs, but it does not intercept or gate on permissions at runtime.\n\n3. **`apiVersion: apm.github.com/v1`** is the current stable value.\n\n4. **JSON Schema for `apm.yml`** is a high-value tooling improvement that would make a great first contribution.\n\n5. **Example manifests for common shapes** would dramatically improve the on-ramp.\n\n6. **Copilot SDK integration** is a longer-horizon goal out of scope for this issue.\n\nIf you want to take on any of the above, opening a focused issue with a specific scope is the best path -- or jump straight to a PR for the JSON Schema."
}

---

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.7M · ◷