[FEATURE] Copilot CLI user-scope instructions: can apm install -g write copilot-instructions.md

[Kacie2025]

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

We're trying to use apm install -g to bootstrap Copilot CLI for our team. Looking at the source, targets.py marks Claude as fully supported at user scope, but Copilot CLI has instructions listed in unsupported_user_primitives. Copilot CLI doesn't read *.instructions.md files from a subdirectory at user level. It only reads one specific file: ~/.copilot/copilot-instructions.md. APM doesn't write to that file, so there's no way to get instructions deployed globally for Copilot through APM today.

Describe the solution you'd like

Support deploying instruction primitives to ~/.copilot/copilot-instructions.md at user scope. Maybe by concatenating instruction primitives into that single file, or adding a special case mapping for Copilot.

Describe alternatives you've considered

• Placing content in ~/.copilot/agents/*.agent.md. Copilot picks up the agent, but doesn't load its content into every conversation. Agents are on demand, not
  always on like instructions.
• Writing copilot-instructions.md via a script. Works but means maintaining config outside of APM.
• Using project level apm install for .github/instructions/. Works but requires being inside a repo.

[danielmeppiel]

Why not working on a team level package with the instructions that need to be deployed globally?

If it's better to segregate concerns at your scale, a better way is to make sure you leverage apm-policy.yml to mandate instructions packages per project. You can place that in the GitHub org if you use GitHub.

Concatenation in a monolithic global instructions file is an antipattern and won't work well with LLMs.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/multi-target
area/cli
area/docs-site
type/feature
status/accepted

Milestone

0.9.4

Suggested next action

Remove copilot-instructions.md from unsupported_user_primitives in targets.py, implement user-scope path resolution for Copilot CLI instructions (mirroring the Claude user-scope pattern), and add tests and docs.

Suggested issue comment

Welcome to APM, and great catch! You found the exact code location that needs changing -- that is exactly the kind of research that makes a PR easy to review.

The symmetry gap is real: Claude supports user-scope instructions, and Copilot CLI should too. The path to remove `copilot-instructions.md` from `unsupported_user_primitives` and implement the user-scope resolution follows the Claude pattern in `targets.py`.

Concrete steps:

1. Find how Claude's user-scope instruction path is resolved in `targets.py` and mirror the pattern for Copilot CLI.
2. Determine the correct user-scope path for `copilot-instructions.md` (typically `~/.config/github-copilot/` or a platform-specific equivalent -- check the Copilot CLI docs for the authoritative location).
3. Apply path security guards (`ensure_path_within(user_home)`) for user-scope writes.
4. Add tests for user-scope install targeting Copilot CLI.
5. Update the multi-target reference in `docs/src/content/docs/`.

If you are not sure of the correct user-scope path, open a draft PR with your findings and the maintainers will help fill in the platform specifics. Happy to review!

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is apm install -g to bootstrap Copilot CLI instructions for a team. The current asymmetry (Claude: supported, Copilot CLI: not supported at user scope) is a jarring inconsistency that breaks the "one install, every target" promise. The author has identified the exact code location. This maps to a real and concrete user need for team bootstrapping workflows.

Supply Chain Security Expert -- Risk-Surface Reviewer

User-scope writes to ~/.config/github-copilot/ or equivalent. Path containment is critical: ensure_path_within(user_home) must be applied. Symlink resolution must be used (a symlink in the user home pointing outside could be exploited). No new threat surface if the Claude user-scope pattern is followed correctly. No theme/security required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author's author_association is NONE -- first-time contributor who did research before filing. Reply is warm, acknowledges the research, and gives a concrete 5-step implementation path. The "open a draft PR with findings" fallback lowers the barrier if the user-scope path is unclear. This is an excellent contributor engagement moment.

Python Architect -- Architecture Reviewer

Not activated -- adding user-scope support for Copilot CLI instructions follows the established target pattern in targets.py. No cross-cutting design decision required; the Claude user-scope path is the reference implementation.

Doc Writer -- Documentation Reviewer

The multi-target reference in docs/src/content/docs/ needs to be updated to reflect user-scope support for Copilot CLI. area/docs-site secondary label is warranted. The implementing PR must include docs per APM's Rule 1.

APM CEO -- Triage Arbiter

Closes a concrete symmetry gap in APM's target coverage. Copilot CLI is a primary APM target -- any limitation relative to Claude weakens the "one manifest, every target" story. Accept for 0.9.4. The author is well-positioned to take this on with the concrete steps in the reply.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Remove copilot-instructions.md from unsupported_user_primitives in targets.py, implement user-scope path resolution mirroring the Claude pattern, and add tests and docs.",
  "comment_markdown": "Welcome to APM, and great catch! You found the exact code location that needs changing -- that is exactly the kind of research that makes a PR easy to review.\n\nThe symmetry gap is real: Claude supports user-scope instructions, and Copilot CLI should too. The path to remove `copilot-instructions.md` from `unsupported_user_primitives` and implement the user-scope resolution follows the Claude pattern in `targets.py`.\n\nConcrete steps:\n\n1. Find how Claude's user-scope instruction path is resolved in `targets.py` and mirror the pattern for Copilot CLI.\n2. Determine the correct user-scope path for `copilot-instructions.md` (typically `~/.config/github-copilot/` or a platform-specific equivalent -- check the Copilot CLI docs for the authoritative location).\n3. Apply path security guards (`ensure_path_within(user_home)`) for user-scope writes.\n4. Add tests for user-scope install targeting Copilot CLI.\n5. Update the multi-target reference in `docs/src/content/docs/`.\n\nIf you are not sure of the correct user-scope path, open a draft PR with your findings and the maintainers will help fill in the platform specifics. Happy to review!"
}

---

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