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

    acceptedDirection approved, safe to start workenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions