Discuss APM as a CodeGuard distribution option

[tybruno]

Context

CodeGuard today ships via per-IDE release ZIPs (Cursor, Windsurf, Copilot, etc.) and the CodeGuard MCP Server for centrally managed, live rules. Both paths work, but multi-IDE teams must pick the right ZIP, copy the right directories by hand, and keep several artifacts in sync when updating.

Microsoft APM (Agent Package Manager) offers a single package format that deploys instructions, skills, and agents to multiple harnesses from one manifest (apm.yml) with optional lockfile pinning (apm.lock.yaml).

Proposal

Add APM as a distribution option for CodeGuard — one apm install cosai-oasis/project-codeguard deploys rules, skills, and the reviewer agent to Cursor, Copilot, Claude, Windsurf, Codex, and others.

A reference implementation is in PR #113: #113

Questions for discussion

Before we decide whether APM should become the recommended install path (vs. one option among several), I'd like maintainer alignment on:

1. Fit with existing options — Should APM sit alongside ZIPs and MCP (additive), or eventually replace ZIP-based installs for most users?
2. Recommendation level — Is "recommended for multi-IDE teams" appropriate, or should docs stay neutral until APM adoption is clearer?
3. Tradeoffs
   • Pros: one command, lockfile integrity, apm audit --ci, enterprise policy support, fewer release artifacts to maintain per IDE
   • Cons: new dependency (APM CLI), Microsoft-maintained toolchain, less familiar to users who already use ZIP copy; fork PR CI requires maintainer approval to run workflows
4. Release / versioning — Should APM packages be published on every CodeGuard release tag alongside existing ZIPs?
5. MCP relationship — Docs currently position MCP for centrally managed live rules and APM for vendored, reproducible project context. Does that framing match maintainer intent?

Current install paths (unchanged by this discussion)

Path	Best for
Release ZIPs	Single IDE, no extra tooling
MCP Server	Central rule management, live updates
APM (proposed)	Multi-IDE teams, lockfile-pinned project context

Reference implementation (PR #113)

If direction is approved, PR #113 includes:

• .apm/ package layout + root apm.yml
• Converter emitter (src/emit_apm.py) integrated into the build
• scripts/validate_apm_install.sh + CI validation (brew-installed APM)
• Docs in docs/apm-install.md

Happy to adjust scope, wording, or recommendation level based on feedback here before merging.