feat: Deploy agents to .claude/agents/ during install

[Copilot]

🚀 New Feature

Description

apm install now deploys agent files (.agent.md, .chatmode.md) to .claude/agents/ as native Claude sub-agents when Claude integration is active. Previously, agents were only deployed to .github/agents/ — Claude Code never discovered them.

apm install pkg-with-agents
# .github/agents/security-apm.agent.md  ← VSCode (existing)
# .claude/agents/security-apm.md        ← Claude Code (new)

Changes Made

• Feature implementation
  • AgentIntegrator: integrate_package_agents_claude(), sync_integration_claude(), get_target_filename_claude(), update_gitignore_for_integrated_agents_claude()
  • cli.py: Both cached and fresh-download integration paths now call Claude agent integration when integrate_claude is True; uninstall sync cleans .claude/agents/ and re-integrates
  • target_detection.py: Updated Claude target description
• Tests added — 16 new unit tests in TestClaudeAgentIntegration (812 total pass)
• Documentation updated — integrations.md and cli-reference.md

Key design decisions:

• Claude sub-agents use .md extension (not .agent.md) per Claude Code spec
• -apm suffix convention preserved for tracking/cleanup
• Skills already deploy to .claude/skills/ via existing T7 compatibility — no changes needed

Testing

• Manual testing completed
• All existing tests pass (812 unit tests)
• New tests added and passing
• CodeQL: 0 alerts

Checklist

• LABEL: Apply enhancement or feature label to this PR
• Code follows project style guidelines
• Documentation updated (if needed)
• CHANGELOG.md updated (for significant features)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[FEATURE] Compile should deploy agents and skills to .claude/ for Claude Code target</issue_title>
<issue_description>## Summary

apm compile --target claude currently only generates distributed CLAUDE.md files from instructions. It does not deploy agents or skills from apm_modules/ into .claude/agents/ or .claude/skills/. These primitives are left stranded in apm_modules/ and never reach Claude Code's native discovery directories.

Current behavior

apm install pkg   → fetches into apm_modules/     ✅
apm compile       → merges instructions → CLAUDE.md  ✅
                  → agents?  not deployed             ❌
                  → skills?  not deployed             ❌

After compile, .claude/ contains no agents or skills from installed packages. Claude Code never discovers them.

Desired behavior

apm compile --target claude should produce a complete, ready-to-use .claude/ directory:

apm_modules/.apm/agents/*.md         →  .claude/agents/
apm_modules/.apm/skills/*/SKILL.md   →  .claude/skills/
apm_modules/.apm/instructions/*.md   →  CLAUDE.md (distributed, already works)

One command. Everything deployed. Claude Code picks it up on next session.

Why this belongs in compile, not install

1. Install fetches. Compile deploys.

apm install should do one job: resolve dependencies and populate apm_modules/. This mirrors npm install populating node_modules/ without modifying the app's source tree.

apm compile is where apm_modules/ content gets transformed and placed for the target platform. This is the step that understands target-specific output layouts.

2. Different targets need different output layouts

The same .apm/ package contents need to land in different places depending on the target:

Source	--target vscode	--target claude
.apm/agents/	.github/agents/	.claude/agents/
.apm/skills/	.github/skills/	.claude/skills/
.apm/instructions/	AGENTS.md (distributed)	CLAUDE.md (distributed)

Target awareness is a compile-time concern. The package format (.apm/) is target-agnostic by design.

3. Claude Code's architecture requires discrete files, not merged markdown

Claude Code manages context through on-demand agent spawning. This is fundamentally different from tools that pre-load all instructions:

• Agents (.claude/agents/) are self-contained context capsules. Claude reads the description, spawns the agent into a fresh context window only when a request matches. The main thread stays lean.
• Skills (.claude/skills/) are specialized capabilities that Claude discovers and activates on demand.
• Instructions (CLAUDE.md) are lightweight, always-loaded guidance.

Agents and skills are discrete primitives — they should be placed as individual files, not merged into CLAUDE.md. The current compile treats everything as instructions to merge. It should recognize the different primitive types and handle each appropriately for the target.

4. Enables a clean rebuild cycle

apm compile --target claude --clean   # wipe and regenerate from apm_modules/

This makes .claude/ a derived artifact — fully reproducible from apm.yml + apm_modules/. Similar to how build output is regenerated from source and dependencies.

Reproduction steps

apm install dev.azure.com/org/project/shared-configs  # package with agents + skills
apm compile --target claude --verbose
ls .claude/agents/    # empty — agents not deployed
ls .claude/skills/    # empty — skills not deployed

Principle

Match the output format to how the target platform actually consumes it. Claude Code consumes agents as files in a directory, not as blocks in a markdown document. Compile should respect that.</issue_description>

<agent_instructions>Please consider the current existing integration implementation with .github and with .claude, and add support for skills and agents for claude. GitHub Agentic Workflows (workflows) are defined here: https://github.github.com/gh-aw/</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@danielmeppiel That's right - it should be `apm install` integrating the primitives into `.claude` in the same way it happens today for `.github`. Reason to put it into install is because I'd rather deprecate the `compile` command ASAP in favor of a configurable, single `install` command that just works. I'd argue that's better UX than having to tap into two different commands.

For reference:

• Subagents Claude spec: https://code.claude.com/docs/en/sub-agents
• Commands spec (akin to prompts, already integrated - now merged into Skills): For built-in commands like /help and /compact, see interactive mode...

• Fixes [FEATURE] Compile should deploy agents and skills to .claude/ for Claude Code target #94

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR extends the install-time integration pipeline so that package agent files are also deployed into Claude Code’s native discovery directory (.claude/agents/), ensuring Claude can find installed sub-agents (in addition to the existing VSCode/Copilot .github/agents/ integration).

Changes:

• Add Claude agent deployment support to AgentIntegrator (target filename mapping to *-apm.md, sync cleanup, .gitignore helper).
• Wire Claude agent integration into both cached and freshly-downloaded install paths, and include .claude/agents cleanup in uninstall sync.
• Update Claude target description + documentation + add unit tests for Claude agent integration.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
uv.lock	Bumps local editable apm-cli version reference to 0.7.3.
tests/unit/integration/test_agent_integrator.py	Adds unit tests covering .claude/agents integration behavior and naming.
src/apm_cli/integration/agent_integrator.py	Implements Claude agent integration (.claude/agents/) + cleanup + .gitignore helper.
src/apm_cli/core/target_detection.py	Updates Claude target output description to include .claude/agents/ and .claude/skills/.
src/apm_cli/cli.py	Calls Claude agent integration during install and cleans Claude agents during uninstall sync.
docs/integrations.md	Documents Claude agent integration and updates Claude integration narrative.
docs/cli-reference.md	Updates CLI reference to include Claude agent integration mapping and example output.

Comments suppressed due to low confidence (2)

docs/integrations.md:352

• In the Claude cleanup section, the Uninstall bullet says it removes only the package's agents and commands, but apm uninstall also cleans up/re-integrates skills (and other APM-managed primitives) as part of the sync step. Adjust this bullet so it doesn’t imply skills are left behind.

- **Install**: Adds agents, commands, and skills for new packages
- **Uninstall**: Removes only that package's agents and commands  
- **Update**: Refreshes commands when package version changes

src/apm_cli/cli.py:1663

• total_agents_integrated is used as a single counter for both VSCode agents (.github/agents) and Claude agents (.claude/agents). When both integrations are active (target=all), the same package agent will be counted twice, and this shared counter is also used to decide whether to update .gitignore for Claude agents. Consider tracking separate counters (e.g., total_vscode_agents_integrated and total_claude_agents_integrated) or renaming/adjusting the logic so counts and .gitignore updates reflect what was actually integrated per target.

                                if claude_agent_result.files_integrated > 0:
                                    total_agents_integrated += (
                                        claude_agent_result.files_integrated
                                    )
                                    _rich_info(
                                        f"  └─ {claude_agent_result.files_integrated} agents integrated → .claude/agents/"
                                    )
                                total_links_resolved += claude_agent_result.links_resolved