[FEATURE] Authoring-repo mode: publish local .apm/ content via apm pack without self-deploying it during apm install

[wwalendz-relativity]

Is your feature request related to a problem? Please describe.

In a package's authoring repository — i.e., the repo whose .apm/ tree IS the package source — apm install always deploys that local content into the same project's runtime target directories (.agents/skills/, .claude/skills/, etc.). There is no way to keep the publish-side behavior (apm pack bundles .apm/ content for external consumers) while suppressing the install-side self-deployment.

For an authoring repo this produces three concrete pain points:

1. Working-tree noise. Every apm install writes N copies of each local primitive into .agents/<type>/<name>/ and per-client mirrors (.claude/skills/<name>/, etc.). Authors of a 20+ skill package see 40+ deployed paths show up next to the source they just edited. The lockfile's local_deployed_files: block grows proportionally.

2. Source vs. deployed-copy drift during iteration. While editing .apm/skills/foo/SKILL.md, the file Claude Code (or Cursor, Copilot, etc.) actually loads from .claude/skills/foo/SKILL.md is a snapshot from the last apm install. The author either has to re-run apm install after every edit, or symlink manually, or accept that their own client is running stale skills. None of these are good answers for a tight authoring loop.

3. No clean way to say "ship this, don't run it here." Sometimes the author specifically does not want their in-progress skills loaded into their own client — early prototypes, breaking changes mid-refactor, skills with side effects (network calls, file writes) that shouldn't fire in the authoring session. Today the only escape hatch is includes: [], which also prevents apm pack from including the content, defeating the purpose.

Per the docs (https://microsoft.github.io/apm/reference/cli/install/): "After dependencies are integrated, primitives in the project's own .apm/ directory are deployed to the same targets." This behavior is documented as unconditional.

Describe the solution you'd like

Add a knob that splits "publish in apm pack" from "deploy on local apm install." Three shapes worth considering:

1. Manifest field (preferred for declarative repos):

   # apm.yml
   self_install: false      # default true; when false, apm install skips local .apm/ deployment
   includes: auto           # publish path unaffected — apm pack still bundles .apm/

   The field is checked only by apm install (and apm compile) when walking root .apm/. apm pack ignores it. External consumers installing this package as a dependency are unaffected because their copy lives under apm_modules/<this-package>/.apm/, not at their project root.

2. CLI flag for ad-hoc use:

   apm install --no-self-install
   

   Useful in CI (apm install --no-self-install to validate external deps resolve without polluting the workspace) and as an opt-out when the manifest field defaults to true.

3. Per-includes-entry granularity if the team wants finer control:

   includes:
     - path: skills/
       deploy_local: false   # ship in apm pack; do not deploy on install
     - templates/            # publish + deploy as today

For audit honesty, when self-install is skipped, apm.lock.yaml's local_deployed_files: should be empty (not stale entries from a prior install) and apm audit --ci should still hash-verify the source .apm/ paths the way it would the deployed ones — closing the same gap that #887 closed for the deploy-on path.

Describe alternatives you've considered

• includes: [] — kills publishing too, so apm pack produces an empty bundle. Not viable.
• Move skills outside .apm/ (e.g., src/skills/) — apm pack's file scanner walks .apm/, so out-of-tree content isn't picked up. Could declare each as a path: devDep, but that flips the problem: dev-installed but not shipped.
• Post-install cleanup script — works (Remove-Item .agents/skills/foo-*, .claude/skills/foo-* after apm install) but every consumer of the authoring repo has to remember it, and apm audit --ci will then complain about missing deployed files relative to local_deployed_files: in the lockfile.
• .gitignore the deployed paths (adjacent to [FEATURE] Extend .gitignore coverage from apm_modules/ to deployed files #1342) — files still get written on every install and still get loaded by the local AI client; this only hides them from git, which addresses pain point (1) partially and doesn't help (2) or (3).
• Narrow targets: in apm.yml — also affects what external consumers receive; the targets list is part of the package contract, not a local-only switch.
• Symlinks from .claude/skills/foo → .apm/skills/foo — would solve the drift problem (pain point 2), but APM owns those paths and overwrites symlinks on next install; also not portable to Windows authors without dev-mode.

Additional context

Concrete repro of pain point (1), redacted:

# apm.yml in an authoring repo with 21 local skills
name: example-skills-pack
version: 1.0.0
targets: [agent-skills, claude]
dependencies:
  apm: []
includes: auto
devDependencies:
  apm:
    - some-external/skill-bundle#main

# apm.lock.yaml after `apm install --dev`
dependencies:
- repo_url: some-external/skill-bundle
  ...
  deployed_files:
  - .agents/skills/skill-creator
  - .claude/skills/skill-creator
local_deployed_files:    # <-- 42 entries the author neither needs nor wants
- .agents/skills/foo-skill-1
- .agents/skills/foo-skill-2
  ...
- .claude/skills/foo-skill-1
- .claude/skills/foo-skill-2
  ...

Related prior art in this repo:

• feat: close audit-blindness gap for local .apm/ content via virtual self-entry + includes: manifest field #887 (closed) introduced the includes: field to give explicit consent to local-.apm/ publishing; this proposal builds on it by separating consent-to-publish from consent-to-self-deploy.
• [FEATURE] Extend .gitignore coverage from apm_modules/ to deployed files #1342 (open) is adjacent — gitignoring the deployed files. That's the right fix for consumers; this issue is the upstream fix for authors who don't want the files written in the first place.
• [FEATURE] add --deploy-only one-shot artifact deployment #1347 (declined) added --deploy-only for the opposite direction (deploy without project state). The decline rationale doesn't apply here because this proposal preserves all APM project state; it only suppresses the redundant copy of content the project already authors.

Naming bikeshed welcome — self_install, self_deploy, local_deploy, author_mode are all in the ballpark.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/package-authoring
area/cli
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a design doc specifying the self_install manifest field semantics, its interaction with apm install -g, and the per-primitive-type opt-out model, then link it here.

Suggested issue comment

Thanks for the detailed proposal, `@wwalendz-relativity`. The authoring-repo pain point is real -- having your own in-progress skills deployed into your own client on every `apm install` is exactly the wrong experience for a tight edit loop.

The panel routes this to needs-design. The solution direction (a `self_install: false` manifest field or `--no-self-install` flag) is sound, but three interface decisions need to be settled before code lands:

1. **Manifest field vs. CLI flag vs. both.** Shape 1 (manifest) and Shape 2 (CLI flag) solve overlapping use cases. Which is the primary interface? If both, what is the precedence?
2. **Interaction with `apm install -g`.** Does `self_install: false` suppress global install too, or only local project install? The global case may have different semantics.
3. **Per-primitive opt-out (Shape 3).** The per-includes-entry approach is more granular but also more complex. Is this in scope for v1 or deferred?

A focused design doc (or a detailed comment here) covering these three points will unblock implementation. The feature itself is clearly aligned with APM's package-authoring story.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The authoring-repo pain point is well-articulated: three concrete problems (working-tree noise, source vs. deployed-copy drift, no way to say "ship this, don't run it here") that all stem from the same root cause -- install always deploys local content. The self_install: false manifest field matches the mental model of npm's private: true and cargo's publish-exclusion patterns. This is a real gap in the package-authoring story.

Supply Chain Security Expert -- Risk-Surface Reviewer

No direct security surface. The feature affects only the local install behavior of the package author's own content. No lockfile integrity, marketplace trust, MCP config, signing, or auth changes are implied. theme/portability is appropriate.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author has NONE association -- first-time contributor with a long-form, well-researched proposal including concrete code references and a clear problem statement. The reply validates the pain point and gives specific next steps (design doc covering three open questions) so the contributor can continue to contribute.

Python Architect -- Architecture Reviewer

New apm.yml manifest field requires schema design. The install phase needs to check the flag. The interaction with apm install -g, apm pack, and the lockfile's local_deployed_files: block needs to be specified. The per-primitive opt-out (Shape 3) adds further complexity. These cross-cutting interface decisions warrant a design phase before implementation.

Doc Writer -- Documentation Reviewer

Docs work will be needed: new apm.yml field reference, updated install command docs, and an authoring guide section on the authoring-repo pattern. This is deferred until the design is settled.

APM CEO -- Triage Arbiter

Needs-design. The authoring-repo use case is important for the package-authoring story and the solution direction is sound. However, the interface decisions (manifest vs. flag, global install interaction, per-primitive opt-out) are non-trivial enough that settling them in a design doc first will prevent revision churn. No milestone until design is settled.

{
  "decision": "needs-design",
  "decision_detail": "self_install field semantics, interaction with apm install -g, and per-primitive opt-out scope must be specified before implementation.",
  "theme": "theme/portability",
  "areas": ["area/package-authoring", "area/cli"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design doc specifying the self_install manifest field semantics, its interaction with apm install -g, and the per-primitive-type opt-out model.",
  "comment_markdown": "Thanks for the detailed proposal, `@wwalendz-relativity`. The panel routes this to needs-design; three interface decisions need a design doc before code can land."
}

---

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 · sonnet46 7.9M · ◷