feat: native Cursor IDE integration

.gitignore

@@ -68,3 +68,4 @@ WIP
 skill-plan.md
 skill-strategy.md
 apm_modules/
+build/tmp/

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Native Cursor IDE integration — `apm install` deploys primitives to `.cursor/` when the directory exists: instructions→rules (`.mdc`), agents, skills, hooks (`hooks.json`), and MCP (`mcp.json`)
+- `TargetProfile` data layer (`src/apm_cli/integration/targets.py`) — data-driven target definitions for scalable multi-target architecture
+- `CursorClientAdapter` for MCP server management in `.cursor/mcp.json`
+
 ## [0.7.9] - 2026-03-13
 
 ### Added

README.md

@@ -4,7 +4,7 @@
 
 Think `package.json`, `requirements.txt`, or `Cargo.toml` — but for AI agent configuration.
 
-GitHub Copilot · Claude Code
+GitHub Copilot · Claude Code · Cursor
 
 **[Documentation](https://microsoft.github.io/apm/)** · **[Quick Start](https://microsoft.github.io/apm/getting-started/quick-start/)** · **[CLI Reference](https://microsoft.github.io/apm/reference/cli-commands/)**
 
@@ -40,7 +40,7 @@ apm install    # every agent is configured
 - **One manifest for everything** — instructions, skills, prompts, agents, hooks, plugins, MCP servers
 - **Install from anywhere** — GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, any git host
 - **Transitive dependencies** — packages can depend on packages; APM resolves the full tree
-- **Compile to standards** — `apm compile` produces `AGENTS.md` (GitHub Copilot) and `CLAUDE.md` (Claude Code)
+- **Compile to standards** — `apm compile` produces `AGENTS.md` (GitHub Copilot), `CLAUDE.md` (Claude Code), and `.cursor/rules/` (Cursor)
 - **Create & share** — `apm pack` bundles your current configuration as a zipped package
 - **CI/CD ready** — [GitHub Action](https://github.com/microsoft/apm-action) for automated workflows
 

docs/src/content/docs/enterprise/adoption-playbook.md

@@ -119,7 +119,7 @@ reach production.
    - name: Install APM packages
      run: apm install
 
-   # Optional: only needed if targeting Cursor, Codex, Gemini, or other
+   # Optional: only needed if targeting Codex, Gemini, or other
    # tools without native APM integration
    # - name: Compile configuration
    #   run: apm compile

docs/src/content/docs/enterprise/teams.md

@@ -152,5 +152,5 @@ For hands-on setup and deeper topics, start here:
 
 - [Quick Start](../../getting-started/installation/) — install APM and configure your first project in five minutes.
 - [Organization-Wide Packages](../../guides/org-packages/) — publish and maintain shared configuration packages across your organization.
-- [Compilation Guide](../../guides/compilation/) — optional: generate instruction files for tools without native APM integration (Cursor, Codex, Gemini).
+- [Compilation Guide](../../guides/compilation/) — optional: generate instruction files for tools without native APM integration (Codex, Gemini).
 - [Dependencies Guide](../../guides/dependencies/) — version constraints, lock file mechanics, and update workflows.

docs/src/content/docs/guides/compilation.md

@@ -4,7 +4,7 @@ sidebar:
   order: 1
 ---
 
-Compilation is **optional for most users**. If your team uses GitHub Copilot or Claude, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. `apm compile` is for teams that use Cursor, Codex, Gemini, or other tools that read single-root-file formats like `AGENTS.md` or `CLAUDE.md`. It is also useful when you want a consolidated view of all instructions in one file.
+Compilation is **optional for most users**. If your team uses GitHub Copilot, Claude, or Cursor, `apm install` deploys all primitives in their native format -- you can skip this guide entirely. `apm compile` is for teams that use Codex, Gemini, or other tools that read single-root-file formats like `AGENTS.md` or `CLAUDE.md`. It is also useful when you want a consolidated view of all instructions in one file.
 
 **Solving the AI agent scalability problem through constraint satisfaction optimization**
 
@@ -431,7 +431,7 @@ Different AI tools get different levels of support from `apm install` vs `apm co
 |---------|--------------------------|------------------------|---------------|
 | GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** |
 | Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
-| Cursor | -- | `.cursor/rules/` | Instructions via compile |
+| Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json` | `AGENTS.md` (optional) | **Full** |
 | Codex CLI | -- | `AGENTS.md` | Instructions via compile |
 | Gemini | -- | `GEMINI.md` | Instructions via compile |
 

docs/src/content/docs/guides/plugins.md

@@ -40,6 +40,7 @@ When you run `apm install owner/repo/plugin-name`:
    1. `plugin.json` (root)
    2. `.github/plugin/plugin.json` (GitHub Copilot format)
    3. `.claude-plugin/plugin.json` (Claude format)
+   4. `.cursor-plugin/plugin.json` (Cursor format)
 3. **Map Artifacts** - Plugin primitives from the repository root are mapped into `.apm/`:
    - `agents/` → `.apm/agents/`
    - `skills/` → `.apm/skills/`
@@ -107,10 +108,25 @@ plugin-repo/
     └── command-2.md
 ```
 
-**Priority Order**: APM checks for `plugin.json` in exactly three locations:
+#### Cursor Format
+```
+plugin-repo/
+├── .cursor-plugin/
+│   └── plugin.json       # Cursor location
+├── agents/
+│   └── agent-name.md
+├── skills/
+│   └── skill-name/
+│       └── SKILL.md
+└── rules/
+    └── my-rule.mdc
+```
+
+**Priority Order**: APM checks for `plugin.json` in these locations:
 1. `plugin.json` (root)
 2. `.github/plugin/plugin.json`
 3. `.claude-plugin/plugin.json`
+4. `.cursor-plugin/plugin.json`
 
 **Note**: Primitives (agents, skills, commands, instructions) are always located at the repository root, regardless of where `plugin.json` is located.
 
@@ -309,6 +325,7 @@ If APM doesn't recognize your plugin:
    - `plugin.json` (root)
    - `.github/plugin/plugin.json` (GitHub Copilot format)
    - `.claude-plugin/plugin.json` (Claude format)
+   - `.cursor-plugin/plugin.json` (Cursor format)
 2. Verify JSON is valid: `cat plugin.json | jq .`
 3. Ensure `name` field is present (only required field)
 4. Verify primitives are at the repository root (`agents/`, `skills/`, `commands/`)

docs/src/content/docs/guides/skills.md

@@ -42,7 +42,7 @@ When you run `apm install`, APM handles skill integration automatically:
 APM downloads packages to `apm_modules/owner/repo/` (or `apm_modules/owner/repo/skill-name/` for subdirectory packages).
 
 ### Step 2: Skill Integration
-APM copies skills directly to `.github/skills/` (primary) and `.claude/skills/` (compatibility):
+APM copies skills directly to `.github/skills/` (primary), `.claude/skills/`, and `.cursor/skills/` when those directories exist:
 
 | Package Type | Behavior |
 |--------------|----------|
@@ -51,8 +51,9 @@ APM copies skills directly to `.github/skills/` (primary) and `.claude/skills/`
 | **No SKILL.md and no primitives** | No skill folder created |
 
 **Target Directories:**
-- **Primary**: `.github/skills/{skill-name}/` — Works with Copilot, Cursor, Codex, Gemini
+- **Primary**: `.github/skills/{skill-name}/` — Works with Copilot, Codex, Gemini
 - **Compatibility**: `.claude/skills/{skill-name}/` — Only if `.claude/` folder already exists
+- **Compatibility**: `.cursor/skills/{skill-name}/` — Only if `.cursor/` folder already exists
 
 ### Skill Folder Naming
 
@@ -291,6 +292,7 @@ APM decides where to output skills based on project structure:
 |-----------|---------------|
 | `.github/` exists | `.github/skills/{skill-name}/SKILL.md` |
 | `.claude/` also exists | Also copies to `.claude/skills/{skill-name}/SKILL.md` |
+| `.cursor/` also exists | Also copies to `.cursor/skills/{skill-name}/SKILL.md` |
 | Neither exists | Creates `.github/skills/` |
 
 Override with:

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -34,7 +34,7 @@ When using Spec-kit for Specification-Driven Development (SDD), APM automaticall
 # 1. Set up APM contextual foundation
 apm init my-project && apm install
 
-# 2. Optional: compile for tools without native integration (Cursor, Codex, Gemini)
+# 2. Optional: compile for tools without native integration (Codex, Gemini)
 # Spec-kit constitution is automatically included in compiled AGENTS.md
 apm compile
 
@@ -148,7 +148,7 @@ apm install microsoft/apm-sample-package
 
 ### Optional: Compiled Context with AGENTS.md
 
-For tools that do not support granular `.github/` primitive discovery (such as Cursor, Codex, or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot or Claude, which read deployed primitives natively.
+For tools that do not support granular primitive discovery (such as Codex or Gemini), `apm compile` produces an `AGENTS.md` file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read deployed primitives natively.
 
 ```bash
 # Compile all local and dependency instructions into AGENTS.md
@@ -184,6 +184,17 @@ When you run `apm install`, APM integrates package primitives into Claude's nati
 | `.claude/skills/{folder}/` | Skills from packages with `SKILL.md` or `.apm/` primitives |
 | `.claude/settings.json` (hooks key) | Hooks from installed packages (merged into settings) |
 
+#### Cursor (`.cursor/`)
+
+| Location | Purpose |
+|----------|---------|
+| `.cursor/rules/*.mdc` | Instructions converted to Cursor rules format |
+| `.cursor/agents/*.md` | Sub-agents from installed packages |
+| `.cursor/skills/{name}/SKILL.md` | Skills from installed packages |
+| `.cursor/hooks.json` (hooks key) | Hooks from installed packages (merged into config) |
+| `.cursor/hooks/{pkg}/` | Referenced hook scripts |
+| `.cursor/mcp.json` | MCP server configurations |
+
 ### Automatic Agent Integration
 
 APM automatically deploys agent files from installed packages into `.claude/agents/`:
@@ -243,7 +254,7 @@ apm install ComposioHQ/awesome-claude-skills/mcp-builder
 
 ### 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.
+APM automatically integrates hooks from installed packages. Hooks define lifecycle event handlers (e.g., `PreToolUse`, `PostToolUse`, `Stop`) supported by VS Code Copilot, Claude Code, and Cursor.
 
 > **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).
 
@@ -258,19 +269,24 @@ apm install anthropics/claude-plugins-official/plugins/hookify
 # Claude result (.claude/settings.json):
 # Hooks merged into .claude/settings.json hooks key
 # Scripts copied to .claude/hooks/hookify/
+
+# Cursor result (.cursor/hooks.json) — only when .cursor/ exists:
+# Hooks merged into .cursor/hooks.json hooks key
+# Scripts copied to .cursor/hooks/hookify/
 ```
 
 **How hook integration works:**
 1. `apm install` discovers hook JSON files in `.apm/hooks/` or `hooks/` directories
 2. For VS Code: copies hook JSON to `.github/hooks/` and rewrites script paths
 3. For Claude: merges hook definitions into `.claude/settings.json` under the `hooks` key
-4. Copies referenced scripts to the target location
-5. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
-6. `apm uninstall` removes hook files and cleans up merged settings
+4. For Cursor: merges hook definitions into `.cursor/hooks.json` under the `hooks` key (only when `.cursor/` exists)
+5. Copies referenced scripts to the target location
+6. Rewrites `${CLAUDE_PLUGIN_ROOT}` and relative script paths for the target platform
+7. `apm uninstall` removes hook files and cleans up merged settings
 
 ### Optional: Target-Specific Compilation
 
-Compilation is optional for Copilot and Claude, which read deployed primitives natively. Use it when targeting tools like Cursor, Codex, or Gemini, or when you want a single merged instruction file:
+Compilation is optional for Copilot, Claude, and Cursor, which read deployed primitives natively. Use it when targeting tools like Codex or Gemini, or when you want a single merged instruction file:
 
 ```bash
 # Generate all formats (default)
@@ -354,22 +370,19 @@ apm install microsoft/apm-sample-package
 
 ### Cursor
 
-Cursor does not follow the `.github/` primitive structure. APM supports Cursor through compiled context output:
-
-```bash
-# 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**:
+APM natively integrates with Cursor when a `.cursor/` directory exists in your project. Run `apm install` and APM automatically deploys primitives to Cursor's native format:
 
-1. **AGENTS.md (recommended)**: Run `apm compile` to generate `AGENTS.md` at the project root. Cursor discovers it automatically as project instructions.
+| APM Primitive | Cursor Destination | Format |
+|---|---|---|
+| Instructions (`.instructions.md`) | `.cursor/rules/*.mdc` | Converted: `applyTo:` → `globs:` frontmatter |
+| Agents (`.agent.md`) | `.cursor/agents/*.md` | Markdown with YAML frontmatter |
+| Skills (`SKILL.md`) | `.cursor/skills/{name}/SKILL.md` | Identical (agentskills.io standard) |
+| Hooks (`.json`) | `.cursor/hooks.json` + `.cursor/hooks/{pkg}/` | Merged JSON config |
+| MCP servers | `.cursor/mcp.json` | Standard `mcpServers` JSON |
 
-2. **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`.
+**Setup**: Create a `.cursor/` directory in your project root (or use Cursor's settings), then run `apm install`. APM detects the directory and deploys automatically.
 
-3. **Distributed compilation**: APM's default distributed strategy places focused `AGENTS.md` files in subdirectories, giving Cursor scoped context per area of the codebase.
+**Fallback**: `apm compile` also generates `AGENTS.md` at the project root, which Cursor discovers as project-level context. This is useful for compiled/merged instruction output.
 
 ```bash
 # Preview what will be compiled
@@ -512,7 +525,7 @@ 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
+- **Cursor deeper integration**: Enhanced Cursor support including rule versioning and conflict resolution
 
 ## Related Resources
 

docs/src/content/docs/introduction/how-it-works.md

@@ -123,7 +123,7 @@ graph TD
 4. **AI Coding Agents** - Execute your compiled workflows (Copilot, Cursor, etc.)
 5. **Supporting Infrastructure** - MCP servers for tools, LLM models for execution
 
-GitHub Copilot and Claude read the deployed primitives natively. For other tools (Cursor, Codex, Gemini), `apm compile` generates an `agents.md` instruction file they can consume.
+GitHub Copilot and Claude read the deployed primitives natively. Cursor also receives native integration when `.cursor/` exists (rules, agents, skills, hooks, MCP). For other tools (Codex, Gemini), `apm compile` generates an `agents.md` instruction file they can consume.
 
 ## The Three Layers Explained
 
@@ -270,7 +270,7 @@ APM auto-detects the target based on project structure (`.github/` or `.claude/`
 
 For tools that read a single instructions file, `apm compile` merges your primitives into a portable document the tool can consume. This gives you instruction-level support rather than full primitive integration.
 
-- **Cursor** - compiled to `.cursor/rules/`
+- **Cursor** - native integration to `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json`
 - **Codex CLI** - compiled to `AGENTS.md`
 - **Gemini** - compiled to `GEMINI.md`
 

docs/src/content/docs/introduction/what-is-apm.md

@@ -147,7 +147,7 @@ supported tool:
 |---|---|---|---|
 | GitHub Copilot | `.github/instructions/`, `.github/prompts/`, agents, hooks, plugins, MCP | `AGENTS.md` (optional) | **Full** |
 | Claude | `.claude/` commands, skills, MCP | `CLAUDE.md` | **Full** |
-| Cursor | — | `.cursor/rules/` | Instructions via compile |
+| Cursor | `.cursor/rules/`, `.cursor/agents/`, skills, hooks, MCP | `.cursor/rules/` (also via compile) | **Full** |
 | Codex CLI | — | `AGENTS.md` | Instructions via compile |
 | Gemini | — | `GEMINI.md` | Instructions via compile |