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

docs/cli-reference.md

@@ -212,7 +212,7 @@ When you run `apm install`, APM automatically integrates primitives from install
 
 - **Prompts**: `.prompt.md` files → `.github/prompts/*-apm.prompt.md`
 - **Agents**: `.agent.md` files → `.github/agents/*-apm.agent.md`
-- **Chatmodes**: `.chatmode.md` files → `.github/agents/*-apm.chatmode.md`
+- **Chatmodes**: `.chatmode.md` files → `.github/agents/*-apm.agent.md` (renamed to modern format)
 - **Control**: Disable with `apm config set auto-integrate false`
 - **Smart updates**: Only updates when package version/commit changes
 - **Naming**: Integrated files use `-apm` suffix (e.g., `accessibility-audit-apm.prompt.md`)
@@ -222,6 +222,7 @@ When you run `apm install`, APM automatically integrates primitives from install
 
 APM also integrates with Claude Code when `.claude/` directory exists:
 
+- **Agents**: `.agent.md` and `.chatmode.md` files → `.claude/agents/*-apm.md`
 - **Commands**: `.prompt.md` files → `.claude/commands/*-apm.md`
 
 **Skill Integration:**
@@ -235,6 +236,7 @@ Skills are copied directly to target directories:
 ```
 ✓ microsoft/apm-sample-package
   ├─ 3 prompts integrated → .github/prompts/
+  ├─ 1 agents integrated → .claude/agents/
   └─ 3 commands integrated → .claude/commands/
 ```
 
@@ -273,7 +275,7 @@ apm uninstall microsoft/apm-sample-package --dry-run
 | Transitive deps | `apm_modules/` (orphaned transitive dependencies) |
 | Integrated prompts | `.github/prompts/*-apm.prompt.md` |
 | Integrated agents | `.github/agents/*-apm.agent.md` |
-| Integrated chatmodes | `.github/agents/*-apm.chatmode.md` |
+| Integrated chatmodes | `.github/agents/*-apm.agent.md` |
 | Claude commands | `.claude/commands/*-apm.md` |
 | Skill folders | `.github/skills/{folder-name}/` |
 | Lockfile entries | `apm.lock` (removed packages + orphaned transitives) |

docs/integrations.md

@@ -223,8 +223,27 @@ When you run `apm install`, APM integrates package primitives into Claude's nati
 
 | Location | Purpose |
 |----------|---------||
-| `.claude/commands/*.md` | Slash commands from installed packages (from `.prompt.md` files) |
-| `.github/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
+| `.claude/agents/*-apm.md` | Sub-agents from installed packages (from `.agent.md` files) |
+| `.claude/commands/*-apm.md` | Slash commands from installed packages (from `.prompt.md` files) |
+| `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
+
+### Automatic Agent Integration
+
+APM automatically deploys agent files from installed packages into `.claude/agents/`:
+
+```bash
+# Install a package with agents
+apm install danielmeppiel/design-guidelines
+
+# Result:
+# .claude/agents/security-apm.md    → Sub-agent available for Claude Code
+```
+
+**How it works:**
+1. `apm install` detects `.agent.md` and `.chatmode.md` files in the package
+2. Copies each to `.claude/agents/` as `.md` files with `-apm` suffix
+3. Updates `.gitignore` to exclude generated agents
+4. `apm uninstall` automatically removes the package's agents
 
 ### Automatic Command Integration
 
@@ -303,7 +322,7 @@ Review the current design for accessibility and UI standards.
 ### Example Workflow
 
 ```bash
-# 1. Install packages (integrates commands and skills automatically)
+# 1. Install packages (integrates agents, commands, and skills automatically)
 apm install microsoft/apm-sample-package
 apm install github/awesome-copilot/skills/review-and-refactor
 
@@ -315,19 +334,20 @@ apm compile --target claude
 #    /gdpr-assessment → Runs GDPR compliance check
 
 # 4. CLAUDE.md provides project instructions automatically
-# 5. Skills in .github/skills/ are available for agents to reference
+# 5. Agents in .claude/agents/ are available as sub-agents
+# 6. Skills in .claude/skills/ are available for agents to reference
 ```
 
 ### Claude Desktop Integration
 
-Skills installed to `.github/skills/` are automatically available for AI agents. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files.
+Skills installed to `.claude/skills/` are automatically available for Claude Code. Each skill folder contains a `SKILL.md` that defines the skill's capabilities and any supporting files.
 
 ### Cleanup and Sync
 
-APM maintains synchronization between packages and Claude commands:
+APM maintains synchronization between packages and Claude primitives:
 
-- **Install**: Adds commands for new packages
-- **Uninstall**: Removes only that package's commands  
+- **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
 - **Virtual Packages**: Individual files and skills (e.g., `github/awesome-copilot/skills/review-and-refactor`) are tracked and removed correctly
 

src/apm_cli/cli.py

@@ -1339,6 +1339,11 @@ def _find_transitive_orphans(lockfile, removed_urls):
                 result = integrator.sync_integration(apm_package, project_root)
                 agents_cleaned = result.get("files_removed", 0)
 
+            if Path(".claude/agents").exists():
+                integrator = AgentIntegrator()
+                result = integrator.sync_integration_claude(apm_package, project_root)
+                agents_cleaned += result.get("files_removed", 0)
+
             if Path(".github/skills").exists() or Path(".claude/skills").exists():
                 integrator = SkillIntegrator()
                 result = integrator.sync_integration(apm_package, project_root)
@@ -1383,6 +1388,8 @@ def _find_transitive_orphans(lockfile, removed_urls):
                         prompt_integrator.integrate_package_prompts(pkg_info, project_root)
                     if agent_integrator.should_integrate(project_root):
                         agent_integrator.integrate_package_agents(pkg_info, project_root)
+                        if Path(".claude").exists():
+                            agent_integrator.integrate_package_agents_claude(pkg_info, project_root)
                     skill_integrator.integrate_package_skill(pkg_info, project_root)
                     if command_integrator.should_integrate(project_root):
                         command_integrator.integrate_package_commands(pkg_info, project_root)
@@ -1831,8 +1838,24 @@ def matches_filter(dep):
                                     f"  └─ {instruction_count} instruction(s) ready (compile via `apm compile`)"
                                 )
 
-                            # Claude-specific integration (commands)
+                            # Claude-specific integration (agents + commands)
                             if integrate_claude:
+                                # Integrate agents to .claude/agents/
+                                claude_agent_result = (
+                                    agent_integrator.integrate_package_agents_claude(
+                                        cached_package_info, project_root
+                                    )
+                                )
+                                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
+
+                                # Generate Claude commands from prompts
                                 command_result = (
                                     command_integrator.integrate_package_commands(
                                         cached_package_info, project_root
@@ -2000,8 +2023,23 @@ def matches_filter(dep):
                                     f"  └─ {instruction_count} instruction(s) ready (compile via `apm compile`)"
                                 )
 
-                            # Claude-specific integration (commands)
+                            # Claude-specific integration (agents + commands)
                             if integrate_claude:
+                                # Integrate agents to .claude/agents/
+                                claude_agent_result = (
+                                    agent_integrator.integrate_package_agents_claude(
+                                        package_info, project_root
+                                    )
+                                )
+                                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
+
                                 # Generate Claude commands from prompts
                                 command_result = (
                                     command_integrator.integrate_package_commands(
@@ -2075,6 +2113,19 @@ def matches_filter(dep):
         if gitignore_updated:
             _rich_info("Updated .gitignore for integrated primitives")
 
+        # Update .gitignore for integrated Claude agents if any were integrated
+        if integrate_claude and total_agents_integrated > 0:
+            try:
+                updated = agent_integrator.update_gitignore_for_integrated_agents_claude(
+                    project_root
+                )
+                if updated:
+                    _rich_info(
+                        "Updated .gitignore for integrated Claude agents (*-apm.md)"
+                    )
+            except Exception as e:
+                _rich_warning(f"Could not update .gitignore for Claude agents: {e}")
+
         # Show link resolution stats if any were resolved
         if total_links_resolved > 0:
             _rich_info(f"✓ Resolved {total_links_resolved} context file links")

src/apm_cli/core/target_detection.py

@@ -133,7 +133,7 @@ def get_target_description(target: TargetType) -> str:
     """
     descriptions = {
         "vscode": "AGENTS.md + .github/prompts/ + .github/agents/",
-        "claude": "CLAUDE.md + .claude/commands/ + SKILL.md",
+        "claude": "CLAUDE.md + .claude/commands/ + .claude/agents/ + .claude/skills/",
         "all": "AGENTS.md + CLAUDE.md + .github/ + .claude/",
         "minimal": "AGENTS.md only (create .github/ or .claude/ for full integration)",
     }