apm compile should emit .github/copilot-instructions.md (dogfood gap)

[danielmeppiel]

The dogfood opportunity

APM the package manager compiles .apm/instructions/ into multiple agent-tool formats: AGENTS.md (Codex / Cursor / Aider / Copilot fallback), CLAUDE.md (Claude Code), and .github/instructions/*.instructions.md (scoped per-pattern Copilot format with applyTo: frontmatter). That's the core "write-once, run-anywhere" value prop.

APM the OSS project does not yet eat its own dogfood. This repo currently:

• Has .apm/instructions/python.md (one file, source of truth for Python conventions) — already compiled into .github/instructions/python.instructions.md automatically. Good.
• Hand-authors .github/copilot-instructions.md (26 lines, top-level Copilot pointer with project philosophy, review-panel directive, dev-iteration commands, etc.) — NOT compiled, must be maintained by hand.
• Does NOT yet ship AGENTS.md ([FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695, PR docs: create AGENTS.md with CI-enforced rules for coding agents #754 in flight).
• Does NOT yet ship CLAUDE.md despite Claude Code being the highest-share agent tool today.

This is exactly the format-fragmentation pain APM was built to solve, so the contradiction is becoming visible to anyone who reads our repo (see PR #754 conversation).

The proposed fix

Move all top-level contributing-guide content (currently in .github/copilot-instructions.md) into a single source: .apm/instructions/contributing.md (or similar). Then apm compile should emit:

Output file	Reader(s)	APM today
AGENTS.md	Codex CLI, Cursor, Aider, OpenAI Codex, Copilot (root fallback)	Already supported
CLAUDE.md	Claude Code	Already supported
.github/instructions/*.instructions.md	GitHub Copilot (scoped, applyTo:)	Already supported
.github/copilot-instructions.md	GitHub Copilot (root prose)	GAP — file this issue

Once that compile target exists, this repo can:

1. Move .github/copilot-instructions.md content into .apm/instructions/contributing.md (or split into focused files).
2. Add .gitignore entries for the generated outputs OR commit them with a CI staleness guard.
3. Run apm compile in pre-commit + CI.
4. Delete every hand-authored top-level instruction file.

Why this matters beyond this repo

The README claim becomes provable on our own repository. Every contributor sees the proof: one .apm/instructions/contributing.md edit lands in AGENTS.md, CLAUDE.md, and the Copilot files in the same commit. That's the demo we should be running on every PR.

It also unblocks PR #754 (#695): instead of hand-authoring AGENTS.md, the PR becomes "convert top-level instructions to APM-compiled," which is a much stronger release-notes beat.

Out of scope (for now)

• Compile-target plugins for .cursor/rules/, .windsurf/rules/, .aider.conf.yml, etc. — these are already covered by other compile targets or out-of-scope.
• Changing the per-file scoped .github/instructions/*.instructions.md format — keep as-is, it's the most powerful Copilot format.

Acceptance criteria

• apm compile emits .github/copilot-instructions.md from one or more .apm/instructions/*.md files (likely a designated "root" or "general" instruction file, or aggregating non-applyTo:-scoped content).
• targets.py Copilot profile lists copilot-instructions.md alongside its existing .github/ outputs.
• Compile is idempotent and round-trips cleanly with apm compile --check style staleness detection (or whatever the existing convention is).
• Tests: at least one fixture proving the emission, one proving round-trip stability.

References

• PR docs: create AGENTS.md with CI-enforced rules for coding agents #754 (AGENTS.md adoption): docs: create AGENTS.md with CI-enforced rules for coding agents #754
• Issue [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695 (original AGENTS.md request): [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695
• src/apm_cli/core/target_detection.py:216-221 (existing AGENTS.md/CLAUDE.md emission)
• src/apm_cli/integration/instruction_integrator.py:28 (existing .github/instructions/ emission)

good first issue candidate — small surface, well-defined, and the contributor gets a high-visibility win (their code generates a file every contributor sees).