Docs: clarify install-time discovery rules for marketplace-published plugins (`.apm/<type>/` vs root convention dirs)

[danielmeppiel]

TL;DR

Authoring a multi-plugin marketplace publisher repo today requires reading APM's integrator source code to figure out the right source layout. The pack-distribute and marketplace-authoring guides imply a layout that silently breaks at install time for half the primitive types.

Concrete ask (docs-only): add a per-primitive scan-path table sourced from the integrators, recommend .apm/<type>/ as the symmetric canonical layout for marketplace publishers, and add a worked example of a multi-plugin publisher repo (top-level marketplace: + per-plugin apm.yml + per-plugin apm pack).

Problem

The "convention dirs" layout shown for apm pack in the pack-distribute guide (i.e. agents/, skills/, commands/, instructions/, hooks/ at plugin root) is asymmetric between the pack-export code path and the install-integrate code path.

• apm pack (liberal): accepts both .apm/<type>/ AND root <type>/ for all primitive types.
• apm install (per-integrator, stricter): only agents and skills accept root <type>/. Instructions, commands, hooks, and mcps are scanned ONLY under .apm/<type>/.

As a marketplace publisher, this means if I author a plugin with instructions/foo.instructions.md at plugin root (per the docs), apm pack happily includes my file in the bundle — but downstream apm install silently drops it. No warning, no error, no doc that flags this.

This bit me hard while building DevExpGbb/zava-agent-config (a multi-plugin marketplace publisher used for an enterprise demo). Debugging took ~half a day; the only way to discover the gap was reading instruction_integrator.py.

What I expected from the docs

That the "convention dirs" pattern shown as the canonical apm pack output (per Bundle structure → Single plugin per repo and the remap table) would also be the layout that consumers see and that integrators scan at install time. The remap table even shows .apm/instructions/*.instructions.md → instructions/*.instructions.md as the deployed shape — implying parity. Nothing on pack-distribute, marketplace-authoring, or marketplaces mentions that authoring directly into root instructions/ (without .apm/) will be silently dropped at install time.

What actually happens

Two scan modes diverge:

Pack-export (liberal — accepts both layouts):

• _collect_apm_components() scans .apm/{agents,skills,prompts,instructions,commands} — src/apm_cli/bundle/plugin_exporter.py:~83
• _collect_root_plugin_components() scans root {agents,skills,commands,instructions} — src/apm_cli/bundle/plugin_exporter.py:~111

Install-integrate (per-integrator, stricter):

Integrator	Source	Scans .apm/<type>/	Scans root <type>/
AgentIntegrator.find_agent_files	integration/agent_integrator.py:40-64	✅ .apm/agents/, .apm/chatmodes/	✅ <root>/*.agent.md, <root>/*.chatmode.md
SkillIntegrator._integrate_skill_bundle	integration/skill_integrator.py:1029+	✅ .apm/skills/	✅ <root>/skills/<name>/ (only when package_type ∈ {MARKETPLACE_PLUGIN, SKILL_BUNDLE})
InstructionIntegrator.find_instruction_files	integration/instruction_integrator.py:35-44	✅	❌ hard-coded subdirs=[".apm/instructions"]
CommandIntegrator.find_prompt_files	integration/command_integrator.py:185	✅ .apm/prompts/	❌
HookIntegrator	integration/hook_integrator.py:282	✅ .apm/hooks/	❌

Net: agents and skills tolerate root convention-dirs at install time; instructions, commands, hooks, mcps do not.

Concrete failure I hit

In zava-agent-config v2.0.0, plugins followed the convention-dirs pattern shown in the pack docs:

• plugins/<kit>/agents/security.agent.md → ✅ deploys (root *.agent.md glob)
• plugins/<kit>/skills/<name>/SKILL.md → ✅ deploys (MARKETPLACE_PLUGIN branch in SkillIntegrator)
• plugins/<kit>/instructions/<x>.instructions.md → ❌ silently does not deploy — only .apm/instructions/ is scanned

apm pack showed the file in the bundle, so authoring-side feedback was green. The gap surfaced only when a downstream consumer ran apm install and noticed agent prompts weren't picking up the rules. No warning, no doc page, no per-primitive layout reference.

How I resolved it (validates the recommended layout)

zava-agent-config v4.0.0 standardizes on plugins/<kit>/.apm/<type>/ for every primitive type. Verified end-to-end:

1. Install side (apm install): all 7 primitives across 4 plugins deploy correctly — 2 agents, 2 skills, 3 instructions. Storefront PR (merged) shows green CI on apm audit --ci.

2. Pack side (apm pack per-kit): with a per-plugin apm.yml (containing minimal dependencies: apm: [] to satisfy the "neither dependencies nor marketplace" check), apm pack --offline correctly:

   • synthesizes plugin.json from apm.yml metadata into build/<name>-<version>/plugin.json
   • remaps .apm/agents/*.agent.md → agents/*.agent.md
   • remaps .apm/skills/<name>/ → skills/<name>/
   • emits a clean Anthropic-shape plugin bundle ready to publish

So the symmetric .apm/<type>/ source layout is the canonical layout that satisfies both code paths simultaneously. The docs just don't say so.

What would help

A docs section (probably an addition to pack-distribute or a new "Plugin layout reference" page) that:

1. Documents the asymmetry explicitly — pack-export is liberal, install-integrate is stricter and per-primitive.
2. Provides a per-primitive scan-path table like the one above, sourced from the integrators rather than the pack exporter, so authors know what consumers will actually see at install time.
3. Recommends .apm/<type>/ as the symmetric canonical layout for ALL primitives in a multi-plugin marketplace publisher repo — i.e. tell authors "use .apm/<type>/ and both code paths agree; use root convention dirs and only agents+skills will work."
4. Shows a worked example of a marketplace publisher repo with multiple plugins, each as a self-contained APM package: per-plugin apm.yml + .apm/<type>/ source tree + per-plugin apm pack to emit plugin.json, plus a top-level apm pack to emit marketplace.json. The current marketplace-authoring guide covers the marketplace block beautifully but stops short of showing the in-plugin source layout, and the pack-distribute "Multi-plugin repo" section is similarly silent on per-plugin source layout. zava-agent-config at v4.0.0 is a working reference if useful as a starting point.

Scope

This is a docs-only ask — please do not treat it as a request to change integrator behavior. Whether the install-time scanners should also accept root convention dirs (matching the pack exporter) is a separate behavior question I'm happy to file as a follow-up if useful. For now I just want the docs to reflect what the code actually does, so the next author building a marketplace publisher repo doesn't lose half a day to silent-drop debugging.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/package-authoring
area/docs-site
type/docs
status/accepted
priority/high

Milestone

0.13.0

Suggested next action

Draft a "Plugin layout reference" section (or page) for the pack-distribute guide that includes the per-primitive scan-path table from the issue body, the canonical .apm/<primitive>/ recommendation, and a minimal worked example of a multi-plugin publisher repo.

Suggested issue comment

Thank you for this detailed, code-grounded report, Daniel. This is exactly the
kind of authoring-experience gap that hurts marketplace adoption -- you pack
successfully, the bundle looks right, and install silently drops half your
primitives with no warning. That is a real documentation failure on our part.

We are accepting this as a high-priority docs addition to the 0.13.0 milestone.
The four asks in your report map cleanly to work we can do:

1. Document the pack/install asymmetry explicitly in the pack-distribute guide.
2. Add a per-primitive scan-path table (sourced from the integrators, not the
   exporter) so authors know what install-time consumers actually see.
3. Establish `.apm/<primitive>/` as the canonical, symmetric layout recommendation
   for ALL primitives in a marketplace publisher repo.
4. Add a worked multi-plugin publisher example showing per-plugin `apm.yml` +
   `.apm/<primitive>/` source tree + per-plugin `apm pack` + top-level
   `apm pack` to emit `marketplace.json`.

Items 1-3 are straightforward additions to the existing
[pack-distribute]((microsoft.github.io/redacted) and
[marketplace-authoring]((microsoft.github.io/redacted)
guides. Item 4 is the highest-effort piece and may ship as a follow-up in the
same milestone.

The behavior question (should install-time scanners also accept root convention
dirs?) is worth a separate issue -- please do file it when ready. For now, the
docs will clearly state the current scanner behavior and the symmetric layout
that avoids the trap.

If you want to contribute the doc fix yourself, the Starlight content lives in
`docs/src/content/docs/guides/`. The integrator source paths you already
referenced make the scan-path table essentially ready to drop in. Happy to
review a PR.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The issue maps to a concrete user task: authoring a multi-plugin marketplace publisher repo and expecting that what apm pack includes is what apm install deploys. The silent-drop of instructions/, commands/, and hooks/ placed at plugin root (while agents and skills work) violates the principle of least surprise and directly breaks the pack-to-install mental model that APM commits to. The evidence is code-level (integrator line references, comparison table) and the ask is strictly documentation -- no behavior change requested. This is a high-quality, actionable user-need report that maps cleanly to the pack-distribute and marketplace-authoring guides.

Supply Chain Security Expert -- Risk-Surface Reviewer

No P/G/S risk surface is introduced or modified by the requested docs change. The pack/install asymmetry is a reliability and usability gap, not a supply-chain attack surface. Instructions, commands, and hooks that silently fail to deploy are frustrating but do not create a security boundary breach. No theme/security or theme/governance label is warranted. The issue is squarely in area/package-authoring and area/docs-site.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with established interaction history on microsoft/apm; no first-time contributor tone adjustment is needed.

Python Architect -- Architecture Reviewer

Not activated -- issue explicitly scopes itself to docs only and requests no code or design change; no cross-cutting interface or data model decision is implied by the documentation ask.

Doc Writer -- Documentation Reviewer

This is an unambiguous docs issue. The four asks map precisely to docs/src/content/docs/guides/pack-distribute/ (items 1-3) and docs/src/content/docs/guides/marketplace-authoring/ (item 4). The area/docs-site label is required as a primary area. All vocabulary in the suggested comment -- "pack", "install", "convention dirs", "bundle structure", "integrator" -- is consistent with the existing guide vocabulary. The per-primitive scan-path table in the issue body can be adapted almost verbatim. The worked multi-plugin example (item 4) is the heaviest lift and may warrant a separate tracking note or follow-up PR.

APM CEO -- Triage Arbiter

Accept unconditionally. A COLLABORATOR building customer demos on APM hit a silent-failure scenario caused by an undocumented asymmetry between the pack exporter and the install integrators. The ask is bounded, well-evidenced, and directly improves marketplace publisher onboarding -- a strategic growth surface. Primary theme is theme/portability (pack/install parity is a portability contract). Priority is priority/high because the silent-drop wastes real authoring time and damages trust in the pack-to-install pipeline. Milestone 0.13.0 is appropriate as the only open milestone; this is a well-scoped docs addition that fits a minor release cycle.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/package-authoring", "area/docs-site"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.13.0",
  "next_action": "Draft a 'Plugin layout reference' section for the pack-distribute guide that includes the per-primitive scan-path table, the canonical .apm/<primitive>/ recommendation, and a minimal worked multi-plugin publisher example.",
  "comment_markdown": "Thank you for this detailed, code-grounded report, Daniel. This is exactly the kind of authoring-experience gap that hurts marketplace adoption -- you pack successfully, the bundle looks right, and install silently drops half your primitives with no warning. That is a real documentation failure on our part.\n\nWe are accepting this as a high-priority docs addition to the 0.13.0 milestone. The four asks in your report map cleanly to work we can do:\n\n1. Document the pack/install asymmetry explicitly in the pack-distribute guide.\n2. Add a per-primitive scan-path table (sourced from the integrators, not the exporter) so authors know what install-time consumers actually see.\n3. Establish `.apm/<primitive>/` as the canonical, symmetric layout recommendation for ALL primitives in a marketplace publisher repo.\n4. Add a worked multi-plugin publisher example showing per-plugin `apm.yml` + `.apm/<primitive>/` source tree + per-plugin `apm pack` + top-level `apm pack` to emit `marketplace.json`.\n\nItems 1-3 are straightforward additions to the existing pack-distribute and marketplace-authoring guides. Item 4 is the highest-effort piece and may ship as a follow-up in the same milestone.\n\nThe behavior question (should install-time scanners also accept root convention dirs?) is worth a separate issue -- please do file it when ready. For now, the docs will clearly state the current scanner behavior and the symmetric layout that avoids the trap.\n\nIf you want to contribute the doc fix yourself, the Starlight content lives in `docs/src/content/docs/guides/`. The integrator source paths you already referenced make the scan-path table essentially ready to drop in. Happy to review a PR."
}

---

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.

Note

🔒 Integrity filter blocked 46 items

The following items were blocked because they don't meet the GitHub integrity level.

• [FEATURE] Extended MCP Server Configuration in apm.yml #20 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Allow install to download and unpack a GitHub release automatically #514 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Skills from .well-known URIs #554 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Feature: per-target agent frontmatter transformation during deployment #581 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• bug: apm run start picks wrong runtime — system PATH stub takes priority over APM-managed binary, codex v0.116+ incompatible with GitHub Models #605 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Add ability to specify a different configuration file name or path #612 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• bug: apm install plugin@marketplace validation bypasses registry proxy #615 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Renovate supporting apm.yml #639 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Align CONTRIBUTING, Python formatting (Black/isort), and CI #645 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Copilot CLI user-scope instructions: can apm install -g write copilot-instructions.md #650 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• Marketplace add source parity with the Anthropic spec #676 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] PEP 8 Support #690 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] URL-based marketplace work Extension #692 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Kiro Support #702 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• [FEATURE] Installation via NPM registry #732 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 30 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 843.2K · ◷