epic: APM integration — make agentrc output distributable and governed

[danielmeppiel]

Why

AI coding agents are only as effective as the context they receive. agentrc solves the creation problem — it analyzes real code and generates tailored instructions. But creation without distribution is a dead end. Teams need to share instructions across repos, govern what agent packages are allowed, and audit them in CI.

APM (Agent Package Manager) solves the distribution problem — transitive dependency resolution, security scanning, multi-platform compilation, and enterprise policy enforcement for agent primitives.

Together: agentrc generates. APM distributes. Neither tool needs the other to be useful, but together they close a loop that neither closes alone.

What

This epic tracks the first wave of agentrc × APM integration:

1. Readiness scoring — agentrc scores repos on APM adoption (feat(readiness): Add APM (Agent Package Manager) awareness to ai-tooling pillar #91)
2. Init bridge — agentrc init detects APM and offers to set it up (feat(init): bridge to APM during init for cross-team distribution #93)
3. Cross-documentation — README sections establishing the ecosystem narrative

Key design principles

• agentrc never writes apm.yml — it delegates to apm init (APM owns its manifest)
• Formats are compatible by default — .instructions.md files work in both tools without conversion
• Explicit opt-in — APM is suggested, never imposed; --yes skips it entirely
• Subprocess integration — tools call each other via CLI, respecting the Python/TypeScript boundary

Child issues

• feat(readiness): Add APM (Agent Package Manager) awareness to ai-tooling pillar #91 — feat(readiness): Add APM awareness to ai-tooling pillar → PR feat(readiness): add APM awareness to ai-tooling pillar #92
• feat(init): bridge to APM during init for cross-team distribution #93 — feat(init): Bridge to APM during init → PR feat(init): bridge to APM during init for cross-team distribution #94
• Cross-documentation (README updates) → PR docs: add APM ecosystem section to README #95

[danielmeppiel]

E2E Verification Report

Tested all APM integration paths locally with apm in PATH. All scenarios pass.

PR #92 — Readiness Criteria

Scenario	apm-config	apm-locked-deps	apm-ci-integration
Full APM setup (apm.yml + lockfile + microsoft/apm-action in CI)	✅ pass	✅ pass	✅ pass
Partial (apm.yml only, no lockfile, no CI)	✅ pass	❌ fail — actionable message	❌ fail — actionable message
No APM setup	❌ fail — recommends APM with URL	⏭️ skip	⏭️ skip

Failure messages are clear and actionable:

• "apm.yml found but dependencies are not locked. Run \apm install` to generate apm.lock.yaml."`
• "No APM step found in CI. Add \microsoft/apm-action` to your workflow to audit agent packages on every PR."`

PR #94 — Init Bridge

Scenario	Result
--yes + APM installed + no apm.yml	✅ Auto-runs apm init --yes, creates apm.yml
Existing apm.yml	✅ Skips (file unchanged)
--json mode	✅ Skips entirely
Full agentrc init --yes E2E	✅ All files generated: instructions, MCP, VS Code settings, agentrc.config.json, apm.yml

PR #95 — Cross-documentation

README-only change, no runtime behavior to test. Verified rendering locally.

Review comments addressed

All latest Copilot review feedback resolved:

• PR feat(readiness): add APM awareness to ai-tooling pillar #92: evidence glob updated to *.{yml,yaml}
• PR feat(init): bridge to APM during init for cross-team distribution #94: description updated for Option B (--yes includes APM), test file mentioned
• PR docs: add APM ecosystem section to README #95: "AgentRC" capitalized in prose (not backticked CLI name)