Skip to content

[FEATURE] apm install should deploy .instructions.md files into .github/instructions/ #112

@chris-cheshire

Description

@chris-cheshire

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

When running apm install, .instructions.md primitives from APM packages are downloaded into apm_modules/ but are never deployed to .github/instructions/. This means VS Code Copilot (which natively reads .github/instructions/*.instructions.md files per the VS Code instructions spec) never picks them up automatically after install.

Currently, apm compile is the only path that processes instructions — compiling them into AGENTS.md/CLAUDE.md. But this excludes VS Code Copilot's native per-file instruction loading, which is distinct from AGENTS.md and supports applyTo: frontmatter for scoped, file-type-specific context.

Describe the solution you'd like

apm install should include an InstructionsIntegrator (analogous to the existing AgentIntegrator, PromptIntegrator, SkillIntegrator) that:

  1. Finds *.instructions.md files in installed packages (from .apm/instructions/ subdirectories, mirroring how AgentIntegrator searches .apm/agents/)
  2. Copies them to .github/instructions/ with an -apm suffix (e.g. python-apm.instructions.md) to distinguish APM-managed files from hand-authored ones
  3. Adds .github/instructions/*-apm.instructions.md to .gitignore (consistent with how agents are handled)
  4. Cleans up orphaned files on apm uninstall (same sync pattern as other integrators)

This would make the following work end-to-end without requiring a separate apm compile step for VS Code users:

apm install FrancisCrickInstitute/lyra  # deploys python-apm.instructions.md → .github/instructions/
# VS Code Copilot now reads it automatically

Describe alternatives you've considered

  1. Committing instructions directly to .github/instructions/ — works, but bypasses APM's dependency management (no versioning, no transitive resolution, no apm uninstall cleanup).
  2. Relying solely on apm compileAGENTS.md — this serves a different purpose (universal agent context) and doesn't leverage VS Code's native applyTo: scoping for *.instructions.md files.
  3. Dual deployment — deploy to both AGENTS.md (via compile) AND .github/instructions/ (via install). Both paths serve different runtimes and are complementary, not redundant.

Additional context

The README documents instructions as a first-class primitive and explicitly lists them in the apm install.github/ integration story:

apm install → integrates prompts, agents, and skills into .github/ and .claude/

Instructions are conspicuously absent from that list, while the install source code confirms no InstructionsIntegrator exists in src/apm_cli/integration/ — the __init__.py exports only PromptIntegrator, AgentIntegrator, SkillIntegrator, and SkillTransformer.

VS Code's .github/instructions/ spec: https://code.visualstudio.com/docs/copilot/copilot-customization#_use-instructionsmd-files

Metadata

Metadata

Assignees

No one assigned

    Labels

    acceptedDeprecated: use status/accepted. Kept for issue history; will be removed in milestone 0.10.0.enhancementDeprecated: use type/feature. Kept for issue history; will be removed in milestone 0.10.0.

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions