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).

[sergio-sisternes-epam]

Noting that PR #754 (AGENTS.md) is on hold pending this issue. Daniel's review on #754 requests that AGENTS.md be generated via apm compile from .apm/instructions/contributing.md rather than hand-authored, which depends on .github/copilot-instructions.md becoming a compile target (this issue).

We'll pick up #754 once #792 lands. Happy to contribute to #792 if helpful.

[danielmeppiel]

Heads-up: PR #823 is a stepping stone toward what this issue envisions — it migrates the repository's own skills/agents/instructions from .github/ to .apm/ as the source of truth, with apm install --target copilot regenerating the deployed artifacts. copilot-instructions.md is intentionally out of scope for #823 and remains tracked here.

One correction worth pinning before this issue lands a final design, though:

proposal to gitignore the generated .github/<type>/ outputs

I'd push back on that fork. The deployed .github/<type>/ tree must always remain committed, because:

1. Raw Copilot CLI users without APM installed rely on .github/skills/, .github/agents/, .github/instructions/ for native primitive discovery. Gitignoring breaks the zero-tools contributor onboarding path that Copilot promises.
2. PR reviewers need the deployed output visible in the diff to catch link-resolver rewrites, target-format drift, and integrator-introduced regressions. Hiding the artifact hides the bugs.
3. CI staleness guard is the correct enforcement primitive, not gitignore. A workflow that runs apm install --target copilot and asserts a clean git diff catches drift without compromising reviewability or the no-APM-installed UX.

This stance is now codified in PR #823's commit message and PR body. Happy to land a follow-up CI staleness check workflow once #823 merges.

[sergio-sisternes-epam]

Hey @danielmeppiel — looping you in before I open a PR, because this one touches a few things you'll want to weigh in on.

I'm planning to close #792 and #695 together in a single PR that turns microsoft/apm into the canonical dogfood example. Supersedes my closed #754 (thanks again for the review — the dogfood-first framing is exactly the right move).

Scope in one PR

1. apm compile should emit .github/copilot-instructions.md (dogfood gap) #792: new .github/copilot-instructions.md compile target. Aggregates instructions with empty/absent applyTo: (currently dropped by the distributed compiler — I'm treating that as a deliberate semantic change, not just an additive emitter).
2. apm compile --check flag for CI drift detection. Strictly read-only, implies --local-only, exit codes 0 clean / 1 drift / 2 compile error. Uses DiagnosticCollector with a new CATEGORY_DRIFT for structured output. Silent on success, summary-first on failure.
3. Root apm.yml + .apm/ populated with all ~33 current primitives (6 instructions, 7 prompts, 1 chatmode, 8 skills, 10 agents, plus the content of today's hand-written copilot-instructions.md as a new root-scoped instruction).
4. Regenerate AGENTS.md, CLAUDE.md, and every .github/** agent-tool output via apm compile. Closes [FEATURE] Create root AGENTS.md documenting all CI-enforced rules for coding agents #695. Commits 1–6 separated so the regeneration-only commit is easy to audit.
5. Tier 1 CI step running apm compile --check. Copy-paste remediation block on failure. New "Recompiling agent outputs" section in CONTRIBUTING.md. .gitattributes linguist-generated=true so GitHub collapses the regen diff.

Calls I'd value your pushback on

• Instruction source naming. I'm mandating *.instructions.md (double extension) inside .apm/instructions/ because the current discovery globs only match that shape (discovery.py:31, parser.py:85). Our existing .apm/instructions/python.md is actually a latent discovery bug — never picked up. The PR renames it. Happy to widen discovery instead if you'd rather .md be canonical, but my read is double-extension is where the tool already lives.
• Generated-file header on every compile output. AGENTS.md / CLAUDE.md emitters already stamp <!-- Generated by APM CLI -->. I'm extending that to copilot-instructions.md and distributed outputs too, with wording <!-- Generated by apm compile — do not edit. Modify .apm/ sources and recompile. -->. Acceptance criterion becomes "content-equivalent modulo header" rather than strict byte-identical. This is the main guardrail against contributors muscle-memory-editing .github/** post-merge.
• Security scope. An APM panel review flagged four pre-existing path-traversal gaps in the compilation subsystem. One of them (link_resolver._resolve_path accepts absolute paths + no containment check) is reachable from --check via fork-PR content inlined into CI logs, so I'm fixing that in-PR (~5 lines, first path_security import into compilation/). The other three (apm.yml output path unvalidated, applyTo: frontmatter as filesystem path, full path_security integration across all compile write paths) I'm planning to file as a dedicated security follow-up issue before this PR merges — labelled security, P1. Shout if you'd rather bundle them in, but my bias is surgical here so the dogfood PR doesn't balloon.
• Chatmode deferral. I'm shipping oss-architect.chatmode.md as-is under .apm/chatmodes/ — no migration to .agent.md in this PR. Filing a separate tracking issue for the .chatmode.md deprecation. Happy to fold it in if you think the dogfood story reads worse carrying a legacy primitive; my call is 1-of-33 is noise not signal.
• Single PR vs staged. I know this is a big PR (9 commits, ~33 regenerated outputs). Single is deliberate — the "before vs after" story only lands in one diff. Commits are structured so each builds cleanly and reviewers can walk the sequence. Let me know if you'd rather see it split.

Planning to start implementation this week unless you want to push back on any of the above. Full plan + commit structure written up locally; happy to paste the breakdown into a Draft PR description if that's easier to react to than prose here.