IDE & Tool Integration

APM is designed to work seamlessly with your existing development tools and workflows. This guide covers integration patterns, supported AI runtimes, and compatibility with popular development tools.

APM + Spec-kit Integration

APM manages the context foundation and provides advanced context management for software projects. It works exceptionally well alongside Spec-kit for specification-driven development, as well as with other AI Native Development methodologies like vibe coding.

APM: Context Foundation

APM provides the infrastructure layer for AI development:

Context Packaging: Bundle project knowledge, standards, and patterns into reusable modules
Dynamic Loading: Smart context composition based on file patterns and current tasks
Performance Optimization: Optimized context delivery for large, complex projects
Memory Management: Strategic LLM token usage across conversations

Spec-kit: Specification Layer

When using Spec-kit for Specification-Driven Development (SDD), APM automatically integrates the Spec-kit constitution:

Constitution Injection: APM automatically injects the Spec-kit constitution.md into the compiled context layer (AGENTS.md)
Rule Enforcement: All coding agents respect the non-negotiable rules governing your project
Contextual Augmentation: APM embeds your team’s context modules into AGENTS.md after Spec-kit’s constitution
SDD Enhancement: Augments the Spec Driven Development process with additional context curated by your teams

Integrated Workflow

# 1. Set up APM contextual foundation
apm init my-project && apm compile

# 2. Use Spec-kit for specification-driven development
# Spec-kit constitution is automatically included in AGENTS.md

# 3. Run AI workflows with both SDD rules and team context
apm run implement-feature --param spec="user-auth" --param approach="sdd"

Key Benefits of Integration:

Universal Context: APM grounds any coding agent on context regardless of workflow
SDD Compatibility: Perfect for specification-driven development approaches
Flexible Workflows: Also works with traditional prompting and vibe coding
Team Knowledge: Combines constitutional rules with team-specific context

Supported AI Runtimes

APM manages AI runtime installation and provides seamless integration with multiple coding agents:

OpenAI Codex CLI

Terminal-native coding agent with GitHub Models support:

# Install and configure
apm runtime setup codex

Codex reads primitives from .github/ (instructions, agents, prompts, skills) the same way GitHub Copilot does. APM also configures MCP servers for Codex at ~/.codex/config.toml.

Features:

GitHub Models API backend
Terminal-native workflow
Real-time streaming output
Native MCP server support
Automatic .github/ primitive discovery

Best for: Teams preferring terminal workflows, custom model configurations

GitHub Copilot CLI

GitHub’s Copilot agent for the terminal:

# Install and configure
apm runtime setup copilot

Features:

Native MCP server integration via ~/.copilot/mcp-config.json
Multi-model switching
Advanced prompt engineering support
--allow-all-tools and --add-dir options

Best for: Teams using GitHub Copilot across IDE and terminal

Configuration:

runtime:
  copilot:
    model: "github/gpt-4o-mini"
    provider: "github-models"
    api_base: "https://models.github.ai"

LLM Library

Flexible runtime supporting multiple model providers:

# Install and configure
apm runtime setup llm

# Features
- Multiple model providers (OpenAI, Anthropic, Ollama)
- Local model support
- Custom plugin system
- Advanced configuration options
- Cost optimization features

Best for: Teams needing model flexibility, local development, cost optimization, custom integrations

Configuration:

runtime:
  llm:
    default_model: "gpt-4"
    providers:
      - openai
      - ollama
      - anthropic
    local_models:
      - "llama3:8b"
    cost_limits:
      daily_max: "$50"

Verify Installation

Check what runtimes are available and properly configured:

# List installed runtimes
apm runtime list

# Test runtime functionality
apm runtime test copilot
apm runtime test codex
apm runtime test llm

VS Code Integration

APM works natively with VS Code’s GitHub Copilot implementation.

Auto-Detection: VS Code integration is automatically enabled when a .github/ folder exists in your project. If neither .github/ nor .claude/ exists, apm install skips folder integration (packages are still installed to apm_modules/).

Native VS Code Primitives

VS Code implements core primitives for GitHub Copilot that APM integrates with:

Agents: AI personas and workflows with .agent.md files in .github/agents/ (legacy: .chatmode.md in .github/chatmodes/)
Instructions Files: Modular instructions with copilot-instructions.md and .instructions.md files
Prompt Files: Reusable task templates with .prompt.md files in .github/prompts/
Skills: Structured capabilities with SKILL.md in .github/skills/

Note: APM supports both the new .agent.md format and legacy .chatmode.md format. VS Code provides Quick Fix actions to migrate from .chatmode.md to .agent.md.

Automatic Prompt and Agent Integration

APM automatically integrates prompts and agents from installed packages into VS Code’s native structure:

# Install APM packages - integration happens automatically when .github/ exists
apm install microsoft/apm-sample-package

# Prompts are automatically integrated to:
# .github/prompts/*.prompt.md (verbatim copy, original filename preserved)

# Agents are automatically integrated to:
# .github/agents/*.agent.md (verbatim copy)

# Instructions are automatically integrated to:
# .github/instructions/*.instructions.md (verbatim copy, original filename)

# Hooks are automatically integrated to:
# .github/hooks/*.json (hook definitions with rewritten script paths)

How Auto-Integration Works:

Zero-Config: Always enabled, works automatically with no configuration needed
Auto-Cleanup: Removes integrated files when you uninstall or prune packages (tracked via deployed_files in apm.lock)
Collision Detection: If a local file has the same name as a package file, APM skips it with a warning (use --force to overwrite)
Always Overwrite: Package-owned files are always copied fresh — no version comparison
Link Resolution: Context links are resolved during integration

Integration Flow:

Run apm install to fetch APM packages
APM automatically creates .github/prompts/, .github/agents/, .github/instructions/, and .github/hooks/ directories as needed
Discovers .prompt.md, .agent.md, .instructions.md, and hook .json files in each package
Copies prompts to .github/prompts/ with their original filename (e.g., accessibility-audit.prompt.md)
Copies agents to .github/agents/ with their original filename (e.g., security.agent.md)
Copies instructions to .github/instructions/ with their original filename (e.g., python.instructions.md)
Copies hooks to .github/hooks/ with their original filename and copies referenced scripts
If a local file already exists with the same name, skips with a warning (use --force to overwrite)
Records all deployed files in apm.lock under deployed_files per package
VS Code automatically loads all prompts, agents, instructions, and hooks for your coding agents
Run apm uninstall to automatically remove integrated primitives (using deployed_files manifest)

Intent-First Discovery: Files keep their original names for natural autocomplete in VS Code:

Type /design — VS Code shows design-review.prompt.md
Type /accessibility — VS Code shows accessibility-audit.prompt.md
Search by what you want to do, not where it comes from

Example:

# Install package with auto-integration
apm install microsoft/apm-sample-package

# Result in VS Code:
# Prompts:
# .github/prompts/accessibility-audit.prompt.md  - Available in chat
# .github/prompts/design-review.prompt.md        - Available in chat
# .github/prompts/style-guide-check.prompt.md    - Available in chat

# Agents:
# .github/agents/design-reviewer.agent.md        - Available as chat mode
# .github/agents/accessibility-expert.agent.md   - Available as chat mode

# Instructions:
# .github/instructions/python.instructions.md    - Applied to matching files

# Use with natural autocomplete:
# Type: /design
# VS Code suggests: design-review.prompt.md

VS Code Native Features:

All integrated prompts appear in VS Code’s prompt picker
All integrated agents appear in VS Code’s chat mode selector
Native chat integration with primitives
Seamless /prompt command support
File-pattern based instruction application
Agent support for different personas and workflows

Compiled Context with AGENTS.md

In addition to file-level integration, apm compile produces an AGENTS.md file that provides comprehensive project context. This is useful for older Copilot versions or IDEs that do not support granular .github/ primitive discovery.

# Compile all local and dependency instructions into AGENTS.md
apm compile --target copilot

# Default distributed compilation creates focused AGENTS.md files per directory
# Use --single-agents for a single monolithic file (legacy mode)
apm compile --single-agents

AGENTS.md aggregates instructions, context, and optionally the Spec-kit constitution into a single document that GitHub Copilot reads as project-level guidance.

Claude Integration

APM provides first-class support for Claude Code and Claude Desktop through native format generation.

Auto-Detection: Claude integration is automatically enabled when a .claude/ folder exists in your project. If neither .github/ nor .claude/ exists, apm install skips folder integration (packages are still installed to apm_modules/).

Output Files for Claude

When you run apm compile, APM generates Claude-native files:

File	Purpose
`CLAUDE.md`	Project instructions for Claude (instructions only, using `@import` syntax)

When you run apm install, APM integrates package primitives into Claude’s native structure:

Location	Purpose
`.claude/agents/*.md`	Sub-agents from installed packages (from `.agent.md` files)
`.claude/commands/*.md`	Slash commands from installed packages (from `.prompt.md` files)
`.claude/skills/{folder}/`	Skills from packages with `SKILL.md` or `.apm/` primitives
`.claude/settings.json` (hooks key)	Hooks from installed packages (merged into settings)

Automatic Agent Integration

APM automatically deploys agent files from installed packages into .claude/agents/:

# Install a package with agents
apm install danielmeppiel/design-guidelines

# Result:
# .claude/agents/security.md -- Sub-agent available for Claude Code

How it works:

apm install detects .agent.md and .chatmode.md files in the package
Copies each to .claude/agents/ as .md files
apm uninstall automatically removes the package’s agents

Automatic Command Integration

APM automatically converts .prompt.md files from installed packages into Claude slash commands:

# Install a package with prompts
apm install microsoft/apm-sample-package

# Result:
# .claude/commands/accessibility-audit.md -- /accessibility-audit
# .claude/commands/design-review.md       -- /design-review

How it works:

apm install detects .prompt.md files in the package
Converts each to Claude command format in .claude/commands/
apm uninstall automatically removes the package’s commands

Automatic Skills Integration

APM automatically integrates skills from installed packages into .github/skills/:

# Install a package with skills
apm install ComposioHQ/awesome-claude-skills/mcp-builder

# Result:
# .github/skills/mcp-builder/SKILL.md -- Skill available for agents
# .github/skills/mcp-builder/...      -- Full skill folder copied

Skill Folder Naming: Uses the source folder name directly (e.g., mcp-builder, design-guidelines), not flattened paths.

How skill integration works:

apm install checks if the package contains a SKILL.md file
If SKILL.md exists: copies the entire skill folder to .github/skills/{folder-name}/ (primary location)
If a .claude/ directory exists: also copies to .claude/skills/{folder-name}/ for Claude compatibility
Sub-skills inside .apm/skills/ are promoted to top-level .github/skills/ entries
apm uninstall removes the skill folder from both locations

Automatic Hook Integration

APM automatically integrates hooks from installed packages. Hooks define lifecycle event handlers (e.g., PreToolUse, PostToolUse, Stop) supported by both VS Code Copilot and Claude Code.

Note: Hook packages must be authored in the target platform’s native format. APM handles path rewriting and file placement but does not translate between hook schema formats (e.g., Claude’s command key vs GitHub Copilot’s bash/powershell keys, or event name casing differences).

# Install a package with hooks
apm install anthropics/claude-plugins-official/plugins/hookify

# VS Code result (.github/hooks/):
# .github/hooks/hookify-hooks.json            -- Hook definitions
# .github/hooks/scripts/hookify/hooks/*.py    -- Referenced scripts

# Claude result (.claude/settings.json):
# Hooks merged into .claude/settings.json hooks key
# Scripts copied to .claude/hooks/hookify/

How hook integration works:

apm install discovers hook JSON files in .apm/hooks/ or hooks/ directories
For VS Code: copies hook JSON to .github/hooks/ and rewrites script paths
For Claude: merges hook definitions into .claude/settings.json under the hooks key
Copies referenced scripts to the target location
Rewrites ${CLAUDE_PLUGIN_ROOT} and relative script paths for the target platform
apm uninstall removes hook files and cleans up merged settings

Target-Specific Compilation

Generate only Claude formats when needed:

# Generate all formats (default)
apm compile

# Generate only Claude formats
apm compile --target claude
# Creates: CLAUDE.md (instructions only)

# Generate only VS Code/Copilot formats
apm compile --target copilot
# Creates: AGENTS.md (instructions only)

Remember: apm compile generates instruction files only. Use apm install to integrate prompts, agents, instructions, commands, and skills from packages.

Claude Command Format

Generated commands follow Claude’s native structure:

<!-- APM Managed: microsoft/apm-sample-package@abc123 -->
# Design Review

Review the current design for accessibility and UI standards.

## Instructions
[Content from original .prompt.md]

Example Workflow

# 1. Install packages (integrates agents, commands, and skills automatically)
apm install microsoft/apm-sample-package
apm install github/awesome-copilot/skills/review-and-refactor

# 2. Compile instructions for Claude
apm compile --target claude

# 3. In Claude Code, use:
#    /code-review     -- Runs the code review workflow
#    /gdpr-assessment -- Runs GDPR compliance check

# 4. CLAUDE.md provides project instructions automatically
# 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 the primary location; when a .claude/ directory exists, APM also copies skills to .claude/skills/ for compatibility. Each skill folder contains a SKILL.md that defines the skill’s capabilities and any supporting files.

Claude Desktop can use CLAUDE.md as its project instructions file. Run apm compile --target claude to generate CLAUDE.md with @import syntax for organized instruction loading.

Cleanup and Sync

APM maintains synchronization between packages and Claude primitives:

Install: Adds agents, commands, and skills for new packages, tracked via deployed_files in apm.lock
Uninstall: Removes only that package’s agents, commands, and skill directories (as tracked in apm.lock). User-authored files are preserved.
Update: Refreshes agents, commands, and skills when package version changes
Virtual Packages: Individual files and skills (e.g., github/awesome-copilot/skills/review-and-refactor) are tracked via apm.lock and removed correctly on uninstall

Other IDE Support

IDEs with GitHub Copilot

Any IDE with GitHub Copilot support works with APM’s file-level integration. APM deploys primitives to .github/, which Copilot discovers automatically:

apm install microsoft/apm-sample-package

# GitHub Copilot picks up:
# .github/prompts/*.prompt.md
# .github/agents/*.agent.md
# .github/instructions/*.instructions.md

Supported IDEs: JetBrains (IntelliJ, PyCharm, WebStorm, etc.), Visual Studio, VS Code, and any IDE with GitHub Copilot integration.

Cursor

Cursor does not follow the .github/ primitive structure. APM supports Cursor through compiled context output:

# Compile APM context into AGENTS.md (Cursor reads this format)
apm compile --target copilot

Cursor reads AGENTS.md as project-level context. The copilot compilation target (also aliased as agents) produces the format Cursor expects.

Setup options:

AGENTS.md (recommended): Run apm compile to generate AGENTS.md at the project root. Cursor discovers it automatically as project instructions.
Cursor Rules: Reference APM-managed instructions from .cursor-rules if your project uses Cursor’s native rules format. Point your rules at specific instruction files in .apm/instructions/ or at the compiled AGENTS.md.
Distributed compilation: APM’s default distributed strategy places focused AGENTS.md files in subdirectories, giving Cursor scoped context per area of the codebase.

# Preview what will be compiled
apm compile --dry-run

# Compile with source attribution for traceability
apm compile --verbose

# Watch mode: auto-recompile when primitives change
apm compile --watch

MCP (Model Context Protocol) Integration

APM provides first-class support for MCP servers, including registry-based servers that publish stdio packages (npm, pypi, docker) or HTTP/SSE remote endpoints.

Auto-Discovery from Packages

APM auto-discovers MCP server declarations from packages during apm install:

apm.yml dependencies: MCP servers listed under dependencies.mcp in a package’s apm.yml are collected automatically.
plugin.json: Packages with a plugin.json (at the root, .github/plugin/, or .claude-plugin/) are recognized as marketplace plugins. APM synthesizes an apm.yml from plugin.json metadata when no apm.yml exists.
Transitive collection: APM walks the dependency tree and collects MCP servers from all transitive packages.

Trust Model

APM enforces a trust boundary for MCP servers to prevent packages from silently injecting arbitrary server processes:

Dependency Type	Registry Servers	Self-Defined Servers
Direct (depth 1)	Auto-trusted	Auto-trusted
Transitive (depth > 1)	Auto-trusted	Skipped with warning

Self-defined servers are those declared with registry: false in apm.yml — they run arbitrary commands rather than resolving through the official MCP registry.

To trust self-defined servers from transitive dependencies, either:

Re-declare the server in your root apm.yml (recommended), or
Use the --trust-transitive-mcp flag:

# Trust self-defined MCP servers from transitive packages
apm install --trust-transitive-mcp

Client Configuration

APM configures MCP servers in the native config format for each supported client:

Client	Config Location	Format
VS Code	`.vscode/mcp.json`	JSON `servers` object
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	JSON `mcpServers` object
Codex CLI	`~/.codex/config.toml`	TOML `mcp_servers` section

Runtime targeting: APM detects which runtimes are installed and configures MCP servers for all of them. Use --runtime <name> or --exclude <name> to control which clients receive configuration.

# Install MCP dependencies for all detected runtimes
apm install

# Target only VS Code
apm install --runtime vscode

# Skip Codex configuration
apm install --exclude codex

# Install only MCP dependencies (skip APM packages)
apm install --only mcp

# Preview MCP configuration without writing
apm install --dry-run

APM also handles stale server cleanup: when a package is uninstalled or an MCP dependency is removed, APM removes the corresponding entries from all client configs.

Package Type Inference

The MCP registry API may return empty registry_name fields for packages. APM infers the package type from:

Explicit registry_name (when provided)
runtime_hint (e.g. npx to npm, uvx to pypi)
Package name patterns (e.g. @scope/name to npm, ghcr.io/... to docker, PascalCase.Name to nuget)

Supported Package Types

When installing registry MCP servers, APM selects the best available package for each runtime:

Package Registry	VS Code	Copilot CLI	Codex CLI
npm	Yes (npx)	Yes (npx)	Yes (npx)
pypi	Yes (uvx/python3)	Yes (uvx)	Yes (uvx)
docker	Yes	Yes	Yes
homebrew	—	Yes	Yes
Other (with runtime_hint)	Yes (generic)	Yes (generic)	Yes (generic)
HTTP/SSE remotes	Yes	Yes	Yes

MCP Server Declaration

# apm.yml - MCP dependencies
dependencies:
  mcp:
    # Simple registry references (resolved via MCP registry)
    - ghcr.io/github/github-mcp-server
    - ghcr.io/modelcontextprotocol/filesystem-server

    # Registry server with overlays
    - name: ghcr.io/modelcontextprotocol/postgres-server
      transport: stdio
      package: npm
      args: ["--connection-string", "postgresql://localhost/mydb"]

    # Self-defined server (not in registry)
    - name: my-internal-server
      registry: false
      transport: stdio
      command: python
      args: ["-m", "my_server"]
      env:
        PORT: "3000"

# Install MCP dependencies
apm install

# Search the MCP registry
apm mcp search github

# Show server details
apm mcp info ghcr.io/github/github-mcp-server

# List available MCP servers
apm mcp list

Roadmap

The following IDE integrations are planned for future releases:

JetBrains IDE support: Native integration with IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs
Windsurf support: Integration with the Windsurf AI coding environment
Cursor deeper integration: Enhanced support beyond AGENTS.md, including native Cursor rules generation

Getting Started — Set up APM in your environment
Key Concepts — Core APM concepts and terminology
CLI Reference — Complete command documentation
Review the VSCode Copilot Customization Guide for VSCode-specific features
Check the Spec-kit documentation for SDD integration details
Explore MCP servers for tool integration options