diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
new file mode 100644
index 00000000..eaa1539a
--- /dev/null
+++ b/.agents/plugins/marketplace.json
@@ -0,0 +1,20 @@
+{
+  "name": "hack-dance",
+  "interface": {
+    "displayName": "Hack Dance"
+  },
+  "plugins": [
+    {
+      "name": "hack",
+      "source": {
+        "source": "local",
+        "path": "./plugins/hack"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 00000000..d87b0fbb
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,16 @@
+{
+  "name": "hack-dance",
+  "description": "Official Hack plugins for local-first development workflows.",
+  "owner": {
+    "name": "Hack Dance LLC"
+  },
+  "plugins": [
+    {
+      "name": "hack",
+      "source": "./plugins/hack",
+      "description": "Operate and onboard Hack-managed local development environments.",
+      "category": "development",
+      "tags": ["local-development", "docker", "developer-tools", "agents"]
+    }
+  ]
+}
diff --git a/.claude/settings.json b/.claude/settings.json
index 0f0432cc..7035b1aa 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -11,12 +11,5 @@
         ]
       }
     ]
-  },
-  "mcpServers": {
-    "hack": {
-      "type": "stdio",
-      "command": "hack",
-      "args": ["mcp", "serve"]
-    }
   }
 }
diff --git a/.codex/config.toml b/.codex/config.toml
deleted file mode 100644
index 5b5944fa..00000000
--- a/.codex/config.toml
+++ /dev/null
@@ -1,3 +0,0 @@
-[mcp_servers.hack]
-command = "hack"
-args = ["mcp", "serve"]
diff --git a/.codex/skills/hack-init/SKILL.md b/.codex/skills/hack-init/SKILL.md
deleted file mode 100644
index 7e0f7aca..00000000
--- a/.codex/skills/hack-init/SKILL.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-name: hack-init
-description: >
-  Stand up or adopt hack in a project (agent-assisted onboarding).
-  Trigger when asked to set a repo up with hack, migrate a project onto
-  hack, or finish/repair a partial hack setup.
----
-
-# hack init (agent-assisted onboarding)
-
-The full onboarding prompt is generated by the hack CLI — do not improvise the steps.
-
-1. Fetch the canonical onboarding prompt:
-   - With shell access: run `hack agent onboard` (works for new and existing projects).
-   - Without shell access: fetch the `hack-init` MCP prompt from the hack MCP server.
-2. Follow the printed prompt phase by phase (inventory, setup, platform nuances, running things, verification).
-3. Finish only when `hack doctor` is clean and every routable service responds.
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
new file mode 100644
index 00000000..384d2e1d
--- /dev/null
+++ b/.cursor-plugin/marketplace.json
@@ -0,0 +1,16 @@
+{
+  "name": "hack-dance",
+  "owner": {
+    "name": "Hack Dance LLC"
+  },
+  "metadata": {
+    "description": "Official Hack plugins for local-first development workflows."
+  },
+  "plugins": [
+    {
+      "name": "hack",
+      "source": "plugins/hack",
+      "description": "Operate and onboard Hack-managed local development environments."
+    }
+  ]
+}
diff --git a/.releaserc.json b/.releaserc.json
index 26c199a4..9ea15c38 100644
--- a/.releaserc.json
+++ b/.releaserc.json
@@ -24,7 +24,10 @@
           "packages/db/package.json",
           "services/auth-broker/package.json",
           "bun.lock",
-          "apps/macos/Config/Base.xcconfig"
+          "apps/macos/Config/Base.xcconfig",
+          "plugins/hack/.codex-plugin/plugin.json",
+          "plugins/hack/.claude-plugin/plugin.json",
+          "plugins/hack/.cursor-plugin/plugin.json"
         ],
         "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
       }
diff --git a/AGENTS.md b/AGENTS.md
index 44041bc8..307b4cc3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -210,11 +210,11 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
+- Content revision: `6ef36575c6e7` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -366,7 +366,7 @@ Docker compose notes:
 - Use `docker compose -f .hack/docker-compose.yml exec <service> <cmd>` only if you need exec into a running container.
 
 Agent integration maintenance:
-- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, Cursor/Claude integrations, shared global skills, and MCP).
 - When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
@@ -376,9 +376,9 @@ Agent integration maintenance:
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 Agent setup (CLI-first):
-- Cursor rules: `hack setup cursor`
-- Claude hooks: `hack setup claude`
-- Codex skill: `hack setup codex`
+- Cursor plugin: run `hack setup cursor`, then install Hack with `/add-plugin` or enable it from Settings > Plugins as directed.
+- Claude Code plugin: run `hack setup claude`, then install or enable `hack@hack-dance` as directed.
+- Codex plugin: run `hack setup codex`, then install or enable Hack from `/plugins` as directed.
 - Refresh all local agent integrations: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
diff --git a/CLAUDE.md b/CLAUDE.md
index e78dc3c7..98e70794 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -80,11 +80,11 @@ This project uses Obsidian for project context, specs, research, and progress tr
 Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
 
 Integration freshness:
-- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
+- Content revision: `6ef36575c6e7` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -236,7 +236,7 @@ Docker compose notes:
 - Use `docker compose -f .hack/docker-compose.yml exec <service> <cmd>` only if you need exec into a running container.
 
 Agent integration maintenance:
-- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, Cursor/Claude integrations, shared global skills, and MCP).
 - When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
@@ -246,9 +246,9 @@ Agent integration maintenance:
 - When changing hack itself: interface or behavior changes must update docs/ in the same change (regenerate the CLI reference with `bun run docs:cli-reference`).
 
 Agent setup (CLI-first):
-- Cursor rules: `hack setup cursor`
-- Claude hooks: `hack setup claude`
-- Codex skill: `hack setup codex`
+- Cursor plugin: run `hack setup cursor`, then install Hack with `/add-plugin` or enable it from Settings > Plugins as directed.
+- Claude Code plugin: run `hack setup claude`, then install or enable `hack@hack-dance` as directed.
+- Codex plugin: run `hack setup codex`, then install or enable Hack from `/plugins` as directed.
 - Refresh all local agent integrations: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
diff --git a/README.md b/README.md
index 77823204..37571e4d 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,8 @@ the branch — review a PR while your main checkout keeps running.
 **Built for agents.** `hack init --with claude|codex` hands setup to an agent.
 Machine surfaces are first-class: `--json` envelopes with stable error codes,
 `--no-interactive`, and agent instructions that sync themselves into
-AGENTS.md/CLAUDE.md, Cursor rules, and Codex skills.
+AGENTS.md/CLAUDE.md. Cursor, Claude Code, and Codex support ship as native,
+user-installed Hack plugins from this repository's marketplaces.
 
 ## More than ports
 
diff --git a/docs/README.md b/docs/README.md
index fc4a54b4..bd8919a9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -59,7 +59,7 @@ This section is easy to find, but it does not lead the product story.
 - Working notes and historical design docs live in `docs/plans/`; they are not the supported product contract
 - Root scripts orchestrate workspace tasks through Turbo
 - Package-local commands remain available via `bun run --cwd <workspace> <script>`
-- Agent-facing docs and setup output are generated from `src/agents/instruction-source.ts` via `src/agents/*` and `src/mcp/agent-docs.ts`; update the canonical source (not the rendered surfaces) when changing AGENTS/Codex/MCP guidance.
+- Agent-facing docs, bundled Codex/Claude/Cursor plugin content, and setup output are generated from `src/agents/instruction-source.ts` via `src/agents/*` and `src/mcp/agent-docs.ts`; update the canonical source (not the rendered surfaces) when changing agent guidance.
 - The generated [CLI reference](reference/cli.md) is rendered from the command spec (`bun run docs:cli-reference`); a drift test fails when it is stale.
 - End-to-end coverage that backs docs claims lives in `tests/e2e/` (`bun run test:e2e:local`).
 - `.factory/validation/` contains historical evidence from retired hosted/web/integration work and is not the current product contract.
diff --git a/docs/cli.md b/docs/cli.md
index 0a772891..f12e41b8 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -23,7 +23,8 @@ terminal).
 - `hack doctor` / `hack doctor --fix` — validate and repair local setup
 - `hack daemon` — optional local daemon for faster JSON status/ps
 - `hack agent onboard` — agent-assisted onboarding for existing projects
-- `hack setup` — install/refresh agent integrations (Cursor rules, Claude hooks, Codex skill, MCP)
+- `hack setup` — check/prepare native Cursor, Claude Code, and Codex plugins; refresh project
+  instructions; or explicitly configure standalone MCP
 - `hack tickets` — deprecated compatibility surface for existing Tickets data
 
 Interactive diagnostics use compact status rows: healthy groups stay on one line, while warnings
@@ -66,8 +67,9 @@ See [Beta workflows](beta.md) for guides on this surface.
   apply documented defaults or fail fast with `E_INTERACTIVE_REQUIRED`.
 - `NO_COLOR` (or `HACK_NO_COLOR`) disables colored/decorated output.
 
-Generated agent docs, Cursor rules, Codex skills, and the shared `~/.ai/skills/hack-cli` skill carry
-the Hack CLI version that generated them. Audit both project and global surfaces with
+Generated agent docs, native plugin content, and the shared `~/.ai/skills/hack-cli` skill carry the Hack CLI
+version that generated them. Native agent plugins are versioned with the Hack release and installed once
+from the `hack-dance/hack` marketplace. Audit project and global generated surfaces with
 `hack setup sync --all-scopes --check`; repair them with `hack setup sync --all-scopes`, then reload
 the agent session so it stops using cached guidance. Interactive project commands also report drift
 before auto-repair instead of repairing silently.
diff --git a/docs/docs-ia.md b/docs/docs-ia.md
index eed86c9f..93d6e808 100644
--- a/docs/docs-ia.md
+++ b/docs/docs-ia.md
@@ -21,8 +21,9 @@ remote/control-plane features.
 - `docs/guides/global-settings.md` — global config
 - `docs/guides/agent-first-setup.md` — agent-assisted onboarding (`hack init --with`, `hack agent onboard`)
 - `docs/guides/prerequisite-detection-matrix.md` — environment prerequisite checks
-- Generated agent-facing guidance: `AGENTS.md`/`CLAUDE.md` snippets, `.codex/skills/hack-cli/SKILL.md`,
-  and `hack-init` skill/MCP prompt content, all rendered from `src/agents/instruction-source.ts`
+- Generated agent-facing guidance: `AGENTS.md`/`CLAUDE.md` snippets, the Hack plugin's bundled
+  `hack-cli` skill, and `hack-init` skill/MCP prompt content, all rendered from
+  `src/agents/instruction-source.ts`
   (canonical source) via `src/agents/*` and `src/mcp/agent-docs.ts`.
 
 New docs belong here when they describe supported v3 CLI surface a user hits without opting into
@@ -92,7 +93,7 @@ extend `hack` (authoring extensions, SDK usage) rather than how to use it.
 
 `docs/reference/cli.md` is generated from the command specs (`bun run docs:cli-reference`) and
 must not be hand-edited. Agent-facing instruction surfaces (`AGENTS.md`/`CLAUDE.md` snippets, the
-Codex skill, Cursor rules, the session primer) are all rendered from the canonical section list in
+native plugin skills/rules, the session primer) are all rendered from the canonical section list in
 `src/agents/instruction-source.ts`; update that file, not the individual renderers, when agent
 guidance needs to change, then regenerate.
 
diff --git a/docs/guides/agent-first-setup.md b/docs/guides/agent-first-setup.md
index 94beaad8..4893668a 100644
--- a/docs/guides/agent-first-setup.md
+++ b/docs/guides/agent-first-setup.md
@@ -11,7 +11,7 @@ your installed version.
 | --- | --- |
 | A fresh repo + an agent CLI installed | `hack init --with claude\|codex\|both` |
 | An existing hack project | `hack agent onboard` (prints the prompt) |
-| An agent session with the hack skills installed | `/hack-init` |
+| A Codex session with the Hack plugin installed | `/hack-init` |
 | A no-shell MCP client | the `hack-init` MCP prompt (`hack setup mcp`) |
 
 ## New repo: `hack init --with`
@@ -42,11 +42,11 @@ when present.
 
 ## Agent-side skill: `/hack-init`
 
-`hack setup claude` and `hack setup codex` install a thin `hack-init` skill
-(`.claude/skills/hack-init/SKILL.md` / `.codex/skills/hack-init/SKILL.md`).
-The skill tells the agent to run `hack agent onboard` (or fetch the `hack-init`
-MCP prompt) and follow it — the content stays in the CLI, so installed skills
-never go stale on substance.
+The official Hack plugins for Cursor, Claude Code, and Codex bundle the same `hack-init` skill;
+run `hack setup cursor`, `hack setup claude`, or `hack setup codex` for exact marketplace guidance.
+The skill tells the agent to run `hack agent onboard` (or fetch the
+`hack-init` MCP prompt) and follow it — the content stays in the CLI, so installed skills never go
+stale on substance.
 
 ## What the prompt covers
 
diff --git a/docs/integrations.md b/docs/integrations.md
index b27a0dc1..e88b7ce4 100644
--- a/docs/integrations.md
+++ b/docs/integrations.md
@@ -8,6 +8,8 @@ What remains:
 - local sessions and runtime orchestration
 - optional coding-agent setup helpers: `hack init --with claude|codex|both`, `hack agent onboard` /
   `hack agent init` / `hack agent prime`, and `hack setup sync --all-scopes`
+- user-installed native Hack plugins for Cursor, Claude Code, and Codex, all generated from the
+  same `hack-cli`, `hack-init`, rules, hooks, and `hack mcp serve` sources
 
 `hack setup sync` keeps interactive output compact: it summarizes each scope and only expands the
 path and reason for stale, missing, or failed artifacts. Exit status remains the automation contract,
@@ -31,14 +33,89 @@ Recommended replacements:
 - GitHub: native `git` and `gh`
 - planning systems: keep them outside Hack and use the tracker selected by the project
 
+## Native agent plugins
+
+The repository is a marketplace for all three supported plugin clients. Each client reads its own
+native manifest while the payload under `plugins/hack/` is shared and versioned with Hack.
+
+### Cursor
+
+Add the GitHub marketplace:
+
+```bash
+cursor-agent plugin marketplace add hack-dance/hack
+```
+
+Open `/add-plugin` in Cursor and install **Hack** from the **Hack Dance** marketplace. Cursor bundles
+the generated Hack rule, both skills, and the MCP server. `hack setup cursor --check` verifies the
+installed plugin when the Cursor Agent CLI is available. `hack setup cursor` retains every legacy
+rule and standalone MCP entry while the plugin is missing or disabled and exits nonzero with install
+guidance. Once the plugin is enabled, setup removes only matching generated copies; edited rules and
+customized MCP entries remain protected.
+
+### Claude Code
+
+Add and install the GitHub marketplace:
+
+```bash
+claude plugin marketplace add hack-dance/hack \
+  --sparse .claude-plugin \
+  --sparse plugins/hack
+claude plugin install hack@hack-dance
+```
+
+Start a new Claude Code session after installation. The plugin bundles the SessionStart/PreCompact
+primer hooks, both skills, and the MCP server. `hack setup claude --check` verifies the installed and
+enabled plugin. While it is missing or disabled, `hack setup claude` exits nonzero and retains the
+legacy hooks, generated `.claude/skills/hack-init` skill, and standalone MCP entries. Cleanup starts
+only after the plugin is enabled and still preserves user-edited content.
+
+### Codex
+
+Add the upstream Git marketplace once:
+
+```bash
+codex plugin marketplace add hack-dance/hack \
+  --sparse .agents/plugins \
+  --sparse plugins/hack
+```
+
+Open `/plugins`, install and enable **Hack** from the **Hack Dance** marketplace, then start a new
+Codex session. `hack setup codex --check` verifies the installed/enabled state; `hack setup codex`
+retains the legacy `.codex/skills/hack-cli`, `.codex/skills/hack-init`, and standalone Codex MCP
+entries until the plugin is enabled. It then removes only unmodified generated copies. User-edited
+legacy skills and customized MCP entries are never deleted.
+
+For all three commands, `--global` selects where legacy standalone artifacts are audited or removed;
+plugin installation state itself is client-wide. `--remove` removes only legacy Hack-managed
+artifacts and never uninstalls the native plugin from the client.
+
+If an enabled plugin is ready but setup finds customized legacy rules, skills, hooks, or MCP
+entries, it preserves that content, prints a warning, and exits nonzero. The same incomplete-cutover
+result applies to `hack setup sync`, automatic sync, and interactive `hack init` until the duplicate
+legacy integration is reconciled manually.
+
+Interactive `hack init` uses the same readiness contract. If a selected client executable, plugin,
+or enabled state is missing, init still writes the project files but prints a warning and exits
+nonzero so automation cannot interpret the optional integration step as successful.
+
+The plugins are cached and enabled by their clients. Projects keep only their `.hack/` configuration
+and genuinely project-specific agent guidance. Upgrade the Codex marketplace with
+`codex plugin marketplace upgrade hack-dance`, then start a new session to load the new plugin
+version.
+
 ## Agent integration freshness
 
-Hack maintains project instructions plus global Cursor, Claude, Codex, and shared `~/.ai/skills`
-surfaces. Generated guidance identifies the CLI version that rendered it.
+Hack maintains project instructions plus shared `~/.ai/skills` surfaces. Generated guidance
+identifies the CLI version that rendered it. Native plugin installation is managed by each client;
+`setup sync` retains legacy Cursor, Claude Code, and Codex copies until the corresponding plugin is
+enabled, then cleans up only exact generated content.
 
 - Audit without writing: `hack setup sync --all-scopes --check`
 - Repair project and global integrations: `hack setup sync --all-scopes`
 - After repair: reload the agent session so cached rules are discarded
 
-Interactive project commands announce detected drift before auto-repair. `hack agent prime` performs
-the same read-only audit at session start and prints a warning before any Hack operating guidance.
+Interactive project commands announce detected drift before auto-repair. Automatic sync checks each
+native plugin before legacy cleanup and remains warning-only when the plugin is unavailable.
+`hack agent prime` performs the same read-only audit at session start and prints a warning before any
+Hack operating guidance.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index afda0668..18e3ed67 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1642,9 +1642,9 @@ hack setup <subcommand> [options]
 | Command | Summary |
 | --- | --- |
 | `hack setup tmux` | Install the recommended tmux binding for hack workspaces |
-| `hack setup cursor` | Install Cursor rules for hack CLI usage |
-| `hack setup claude` | Install Claude Code hooks for hack CLI usage |
-| `hack setup codex` | Install Codex skill for hack CLI usage |
+| `hack setup cursor` | Check or prepare the official Hack plugin for Cursor |
+| `hack setup claude` | Check or prepare the official Hack plugin for Claude Code |
+| `hack setup codex` | Check or prepare the official Hack plugin for Codex |
 | `hack setup tickets` | Remove or audit the deprecated Hack Tickets skill |
 | `hack setup agents` | Install AGENTS.md / CLAUDE.md snippets for hack CLI usage |
 | `hack setup sync` | Refresh project/global agent guidance and remove deprecated artifacts |
@@ -1680,7 +1680,7 @@ hack setup tmux [options]
 
 ## `hack setup cursor`
 
-Install Cursor rules for hack CLI usage
+Check or prepare the official Hack plugin for Cursor
 
 ### Usage
 
@@ -1702,7 +1702,7 @@ hack setup cursor [options]
 
 ## `hack setup claude`
 
-Install Claude Code hooks for hack CLI usage
+Check or prepare the official Hack plugin for Claude Code
 
 ### Usage
 
@@ -1724,7 +1724,7 @@ hack setup claude [options]
 
 ## `hack setup codex`
 
-Install Codex skill for hack CLI usage
+Check or prepare the official Hack plugin for Codex
 
 ### Usage
 
diff --git a/package.json b/package.json
index b34603bb..8ba7b737 100644
--- a/package.json
+++ b/package.json
@@ -62,7 +62,9 @@
     "test:e2e:gateway": "bun run scripts/gateway-e2e.ts",
     "test:e2e:dispatch": "bun run scripts/dispatch-e2e.ts",
     "test:e2e:railway": "bun run scripts/railway-node-e2e.ts",
-    "docs:cli-reference": "bun run scripts/generate-cli-reference.ts"
+    "docs:cli-reference": "bun run scripts/generate-cli-reference.ts",
+    "generate:agent-plugins": "bun run scripts/generate-agent-plugins.ts",
+    "generate:codex-plugin": "bun run scripts/generate-agent-plugins.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
diff --git a/plugins/hack/.claude-plugin/plugin.json b/plugins/hack/.claude-plugin/plugin.json
new file mode 100644
index 00000000..323e4cbe
--- /dev/null
+++ b/plugins/hack/.claude-plugin/plugin.json
@@ -0,0 +1,17 @@
+{
+  "name": "hack",
+  "displayName": "Hack",
+  "version": "3.5.1",
+  "description": "Operate and onboard Hack-managed local development environments.",
+  "author": {
+    "name": "Hack Dance LLC",
+    "url": "https://github.com/hack-dance"
+  },
+  "homepage": "https://github.com/hack-dance/hack",
+  "repository": "https://github.com/hack-dance/hack",
+  "license": "MIT",
+  "keywords": ["local-development", "docker", "developer-tools", "agents"],
+  "skills": "./skills/",
+  "hooks": "./hooks/claude-hooks.json",
+  "mcpServers": "./.mcp.json"
+}
diff --git a/plugins/hack/.codex-plugin/plugin.json b/plugins/hack/.codex-plugin/plugin.json
new file mode 100644
index 00000000..784e9187
--- /dev/null
+++ b/plugins/hack/.codex-plugin/plugin.json
@@ -0,0 +1,30 @@
+{
+  "name": "hack",
+  "version": "3.5.1",
+  "description": "Operate and onboard Hack-managed local development environments.",
+  "author": {
+    "name": "Hack Dance LLC",
+    "url": "https://github.com/hack-dance"
+  },
+  "homepage": "https://github.com/hack-dance/hack",
+  "repository": "https://github.com/hack-dance/hack",
+  "license": "MIT",
+  "keywords": ["local-development", "docker", "developer-tools", "agents"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Hack",
+    "shortDescription": "Run local development through Hack",
+    "longDescription": "Operate Hack-managed services, logs, environments, workspaces, and agent-assisted project onboarding from Codex.",
+    "developerName": "Hack Dance LLC",
+    "category": "Developer Tools",
+    "capabilities": ["Local development", "Project onboarding", "MCP tools"],
+    "websiteURL": "https://github.com/hack-dance/hack",
+    "defaultPrompt": [
+      "Start this Hack project and verify its services.",
+      "Set this repository up to run with Hack.",
+      "Diagnose this Hack project's local runtime."
+    ],
+    "brandColor": "#FF5C35"
+  },
+  "mcpServers": "./.mcp.json"
+}
diff --git a/plugins/hack/.cursor-plugin/plugin.json b/plugins/hack/.cursor-plugin/plugin.json
new file mode 100644
index 00000000..58e5c59e
--- /dev/null
+++ b/plugins/hack/.cursor-plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+  "name": "hack",
+  "displayName": "Hack",
+  "version": "3.5.1",
+  "description": "Operate and onboard Hack-managed local development environments.",
+  "author": {
+    "name": "Hack Dance LLC"
+  },
+  "publisher": "Hack Dance LLC",
+  "homepage": "https://github.com/hack-dance/hack",
+  "repository": "https://github.com/hack-dance/hack",
+  "license": "MIT",
+  "keywords": ["local-development", "docker", "developer-tools", "agents"],
+  "category": "developer-tools",
+  "tags": ["local-development", "docker", "agents"],
+  "skills": "./skills/",
+  "rules": "./rules/",
+  "mcpServers": "./.mcp.json"
+}
diff --git a/.cursor/mcp.json b/plugins/hack/.mcp.json
similarity index 100%
rename from .cursor/mcp.json
rename to plugins/hack/.mcp.json
diff --git a/plugins/hack/README.md b/plugins/hack/README.md
new file mode 100644
index 00000000..a80c1c5b
--- /dev/null
+++ b/plugins/hack/README.md
@@ -0,0 +1,23 @@
+# Hack agent plugin
+
+Operate and onboard [Hack](https://github.com/hack-dance/hack)-managed local development
+environments from Cursor, Claude Code, or Codex.
+
+The plugin bundles:
+
+- `hack-cli`: local runtime, environment, logs, sessions, and diagnostic guidance
+- `hack-init`: agent-assisted onboarding through `hack agent onboard`
+- `hack mcp serve`: the no-shell MCP fallback
+- client-native Cursor rules and Claude Code primer hooks
+
+The `hack` executable must be installed and available on `PATH`. Plugin skills prefer the CLI when
+shell access is available and use MCP only when it is not.
+
+## Installation
+
+See the repository's [agent integration guide](../../docs/integrations.md) for the native marketplace
+commands for Cursor, Claude Code, and Codex. Start a new agent session after installing or updating
+the plugin.
+
+This directory is generated and versioned with the Hack CLI release. Update canonical guidance in
+`src/agents/instruction-source.ts`, then run `bun run generate:agent-plugins`.
diff --git a/plugins/hack/hooks/claude-hooks.json b/plugins/hack/hooks/claude-hooks.json
new file mode 100644
index 00000000..213c9669
--- /dev/null
+++ b/plugins/hack/hooks/claude-hooks.json
@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "hack agent prime"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "hack agent prime"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.cursor/rules/hack.mdc b/plugins/hack/rules/hack.mdc
similarity index 96%
rename from .cursor/rules/hack.mdc
rename to plugins/hack/rules/hack.mdc
index 27737fc4..19f084ec 100644
--- a/.cursor/rules/hack.mdc
+++ b/plugins/hack/rules/hack.mdc
@@ -1,3 +1,8 @@
+---
+description: Operate Hack-managed local development environments through the hack CLI.
+alwaysApply: true
+---
+
 # hack CLI
 # Auto-generated by 'hack setup cursor' - do not remove these markers
 # BEGIN HACK INTEGRATION
@@ -7,11 +12,11 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
+- Content revision: `6ef36575c6e7` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -91,7 +96,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 ## Agent integration maintenance
 
-- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, Cursor/Claude integrations, shared global skills, and MCP).
 - When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
diff --git a/.codex/skills/hack-cli/SKILL.md b/plugins/hack/skills/hack-cli/SKILL.md
similarity index 96%
rename from .codex/skills/hack-cli/SKILL.md
rename to plugins/hack/skills/hack-cli/SKILL.md
index f1b5013e..8c3e631b 100644
--- a/.codex/skills/hack-cli/SKILL.md
+++ b/plugins/hack/skills/hack-cli/SKILL.md
@@ -12,11 +12,11 @@ Use `hack` as the primary interface for local-first development.
 
 ## Integration freshness
 
-- These instructions were generated by hack CLI v3.5.0; treat cached rules from another version as potentially stale.
+- These instructions were generated by hack CLI v3.5.1; treat cached rules from another version as potentially stale.
 - At session start, audit project and global integrations with `hack setup sync --all-scopes --check`.
 - If anything is stale, missing, or deprecated, run `hack setup sync --all-scopes`, then reload the agent session so cached instructions are replaced.
 - Never copy or hand-edit generated Hack rules to refresh them; update the CLI and run the sync command.
-- Content revision: `1319d93c89c3` (version alone is not a freshness guarantee).
+- Content revision: `6ef36575c6e7` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -190,7 +190,7 @@ Use `hack` as the primary interface for local-first development.
 
 ## Agent integration maintenance
 
-- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).
+- Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, Cursor/Claude integrations, shared global skills, and MCP).
 - When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.
 - Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.
 - Refresh project + user integrations: `hack setup sync --all-scopes`
@@ -201,9 +201,9 @@ Use `hack` as the primary interface for local-first development.
 
 ## Agent setup (CLI-first)
 
-- Cursor rules: `hack setup cursor`
-- Claude hooks: `hack setup claude`
-- Codex skill: `hack setup codex`
+- Cursor plugin: run `hack setup cursor`, then install Hack with `/add-plugin` or enable it from Settings > Plugins as directed.
+- Claude Code plugin: run `hack setup claude`, then install or enable `hack@hack-dance` as directed.
+- Codex plugin: run `hack setup codex`, then install or enable Hack from `/plugins` as directed.
 - Refresh all local agent integrations: `hack setup sync --all-scopes`
 - Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
diff --git a/.claude/skills/hack-init/SKILL.md b/plugins/hack/skills/hack-init/SKILL.md
similarity index 100%
rename from .claude/skills/hack-init/SKILL.md
rename to plugins/hack/skills/hack-init/SKILL.md
diff --git a/scripts/generate-agent-plugins.ts b/scripts/generate-agent-plugins.ts
new file mode 100644
index 00000000..e252b0c4
--- /dev/null
+++ b/scripts/generate-agent-plugins.ts
@@ -0,0 +1,64 @@
+import { dirname, resolve } from "node:path";
+
+import { renderCodexSkill } from "../src/agents/codex-skill.ts";
+import { renderCursorPluginRule } from "../src/agents/cursor.ts";
+import { renderHackInitSkill } from "../src/agents/hack-init-skill.ts";
+
+export async function generateAgentPlugins({
+  repoRoot,
+  version,
+}: {
+  readonly repoRoot: string;
+  readonly version: string;
+}): Promise<void> {
+  const pluginRoot = resolve(repoRoot, "plugins", "hack");
+
+  const generatedSkills = [
+    {
+      path: resolve(pluginRoot, "skills", "hack-cli", "SKILL.md"),
+      content: renderCodexSkill(),
+    },
+    {
+      path: resolve(pluginRoot, "skills", "hack-init", "SKILL.md"),
+      content: renderHackInitSkill(),
+    },
+    {
+      path: resolve(pluginRoot, "rules", "hack.mdc"),
+      content: renderCursorPluginRule(),
+    },
+  ] as const;
+
+  for (const skill of generatedSkills) {
+    await Bun.$`mkdir -p ${dirname(skill.path)}`;
+    await Bun.write(skill.path, skill.content);
+  }
+
+  const manifestPaths = [
+    resolve(pluginRoot, ".codex-plugin", "plugin.json"),
+    resolve(pluginRoot, ".claude-plugin", "plugin.json"),
+    resolve(pluginRoot, ".cursor-plugin", "plugin.json"),
+  ] as const;
+
+  for (const manifestPath of manifestPaths) {
+    const manifest = (await Bun.file(manifestPath).json()) as Record<
+      string,
+      unknown
+    >;
+    manifest.version = version;
+    await Bun.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    await Bun.$`bun x biome format --write ${manifestPath}`.quiet();
+  }
+}
+
+if (import.meta.main) {
+  const repoRoot = resolve(import.meta.dir, "..");
+  const packageJson = await Bun.file(resolve(repoRoot, "package.json")).json();
+  if (
+    typeof packageJson !== "object" ||
+    packageJson === null ||
+    typeof packageJson.version !== "string"
+  ) {
+    throw new Error("package.json is missing a string version");
+  }
+  await generateAgentPlugins({ repoRoot, version: packageJson.version });
+}
diff --git a/scripts/prepare-release.ts b/scripts/prepare-release.ts
index c06d1b39..e9c69bd0 100644
--- a/scripts/prepare-release.ts
+++ b/scripts/prepare-release.ts
@@ -3,6 +3,8 @@
 import { readdir } from "node:fs/promises";
 import { resolve } from "node:path";
 
+import { generateAgentPlugins } from "./generate-agent-plugins.ts";
+
 interface Args {
   readonly version: string | null;
 }
@@ -62,6 +64,9 @@ async function main({ args }: { readonly args: Args }): Promise<number> {
     rootPackageJson: pkg,
   });
 
+  await generateAgentPlugins({ repoRoot, version: nextVersion });
+  process.stdout.write(`Updated agent plugin manifests: ${nextVersion}\n`);
+
   // Update macOS app version in Base.xcconfig
   const xconfigPath = resolve(repoRoot, "apps/macos/Config/Base.xcconfig");
   try {
diff --git a/src/agents/claude-plugin.ts b/src/agents/claude-plugin.ts
new file mode 100644
index 00000000..0c38382d
--- /dev/null
+++ b/src/agents/claude-plugin.ts
@@ -0,0 +1,260 @@
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { pathExists, readTextFile } from "../lib/fs.ts";
+import { isRecord } from "../lib/guards.ts";
+import { type ExecResult, exec, findExecutableInPath } from "../lib/shell.ts";
+import {
+  checkDeprecatedPluginMcpConfig,
+  removeDeprecatedPluginMcpConfig,
+} from "../mcp/install.ts";
+import { checkClaudeHooks, removeClaudeHooks } from "./claude.ts";
+import { renderHackInitSkill } from "./hack-init-skill.ts";
+import { normalizeInstructionText } from "./instruction-source.ts";
+import {
+  type AgentPluginResult,
+  checkNativeAgentPlugin,
+  mergeLegacyCleanupResults,
+  prepareNativeAgentPlugin,
+} from "./plugin-lifecycle.ts";
+
+export type ClaudePluginScope = "project" | "user";
+
+export type ClaudePluginResult = AgentPluginResult<ClaudePluginScope>;
+
+type ClaudeCommand = (command: readonly string[]) => Promise<ExecResult>;
+
+const PLUGIN_ID = "hack@hack-dance";
+const MARKETPLACE_COMMAND =
+  "claude plugin marketplace add hack-dance/hack --sparse .claude-plugin plugins/hack";
+const PLUGIN_GUIDANCE = [
+  `Add the Hack marketplace with: ${MARKETPLACE_COMMAND}`,
+  `Then install it with: claude plugin install ${PLUGIN_ID}`,
+  "Start a new Claude Code session after installation.",
+].join(" ");
+
+/** Check whether the official Hack plugin is installed and enabled in Claude Code. */
+export async function checkHackClaudePlugin(opts: {
+  readonly scope: ClaudePluginScope;
+  readonly runClaudeCommand?: ClaudeCommand;
+}): Promise<ClaudePluginResult> {
+  const hasClaude = opts.runClaudeCommand || findExecutableInPath("claude");
+  return await checkNativeAgentPlugin({
+    scope: opts.scope,
+    pluginId: PLUGIN_ID,
+    runCommand: hasClaude
+      ? (opts.runClaudeCommand ?? runClaudePluginList)
+      : null,
+    missingExecutableMessage: `Claude Code is not installed. After installing it, ${PLUGIN_GUIDANCE}`,
+    inspectErrorMessage: "Could not inspect installed Claude Code plugins.",
+    missingPluginMessage: `The Hack Claude Code plugin is not installed. ${PLUGIN_GUIDANCE}`,
+    disabledPluginMessage:
+      "The Hack Claude Code plugin is installed but disabled. Enable it with claude plugin enable hack@hack-dance, then start a new session.",
+    parseState: parseClaudePluginState,
+  });
+}
+
+/** Remove generated standalone Claude integration artifacts and report plugin state. */
+export async function prepareHackClaudePlugin(opts: {
+  readonly scope: ClaudePluginScope;
+  readonly projectRoot?: string;
+  readonly runClaudeCommand?: ClaudeCommand;
+}): Promise<ClaudePluginResult> {
+  return await prepareNativeAgentPlugin({
+    cleanup: async () => await removeDeprecatedHackClaudeIntegration(opts),
+    check: async () => await checkHackClaudePlugin(opts),
+  });
+}
+
+/** Report generated standalone Claude artifacts superseded by the plugin. */
+export async function checkDeprecatedHackClaudeIntegration(opts: {
+  readonly scope: ClaudePluginScope;
+  readonly projectRoot?: string;
+}): Promise<ClaudePluginResult> {
+  const resolvedSkill = resolveLegacySkill(opts);
+  if (!resolvedSkill.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolvedSkill.path,
+      message: resolvedSkill.message,
+    };
+  }
+  const [hooks, skillExists, mcp] = await Promise.all([
+    checkClaudeHooks({ ...opts, checkSkill: false }),
+    pathExists(resolvedSkill.path),
+    checkDeprecatedPluginMcpConfig({ target: "claude", ...opts }),
+  ]);
+  if (hooks.status === "error" || mcp.status === "error") {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: hooks.status === "error" ? hooks.path : (mcp.path ?? PLUGIN_ID),
+      message: hooks.status === "error" ? hooks.message : mcp.message,
+    };
+  }
+  const hasDeprecatedHooks =
+    hooks.status === "noop" || hooks.status === "stale";
+  const deprecated =
+    hasDeprecatedHooks || skillExists || mcp.status === "deprecated";
+  return deprecated
+    ? {
+        scope: opts.scope,
+        status: "deprecated",
+        path: hasDeprecatedHooks ? hooks.path : resolvedSkill.path,
+        message:
+          "Standalone Claude Code hooks, skill, or MCP config are deprecated; the Hack plugin bundles them.",
+      }
+    : { scope: opts.scope, status: "absent", path: resolvedSkill.path };
+}
+
+/** Safely remove generated standalone Claude artifacts, preserving edited skill/MCP content. */
+export async function removeDeprecatedHackClaudeIntegration(opts: {
+  readonly scope: ClaudePluginScope;
+  readonly projectRoot?: string;
+}): Promise<ClaudePluginResult> {
+  const resolvedSkill = resolveLegacySkill(opts);
+  if (!resolvedSkill.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolvedSkill.path,
+      message: resolvedSkill.message,
+    };
+  }
+  const hooks = await removeClaudeHooks({ ...opts, removeSkill: false });
+  if (hooks.status === "error") {
+    return {
+      scope: hooks.scope,
+      status: "error",
+      path: hooks.path,
+      message: hooks.message,
+    };
+  }
+  const skill = await removeGeneratedSkill({ path: resolvedSkill.path });
+  const mcp = await removeDeprecatedPluginMcpConfig({
+    target: "claude",
+    ...opts,
+  });
+  let skillStatus: "absent" | "removed" | "preserved" = "absent";
+  if (skill.removed) {
+    skillStatus = "removed";
+  } else if (skill.preserved) {
+    skillStatus = "preserved";
+  }
+  return mergeLegacyCleanupResults({
+    scope: opts.scope,
+    fallbackPath: skill.path,
+    results: [
+      hooks,
+      {
+        status: skillStatus,
+        path: skill.path,
+        message: skill.message,
+      },
+      mcp,
+    ],
+  });
+}
+
+async function runClaudePluginList(
+  command: readonly string[]
+): Promise<ExecResult> {
+  return await exec(["claude", ...command], {
+    stdin: "ignore",
+    timeoutMs: 10_000,
+  });
+}
+
+function parsePluginList(opts: { readonly json: string }):
+  | {
+      readonly ok: true;
+      readonly plugins: readonly {
+        readonly id: string;
+        readonly enabled: boolean;
+      }[];
+    }
+  | { readonly ok: false; readonly message: string } {
+  try {
+    const value: unknown = JSON.parse(opts.json);
+    if (!Array.isArray(value)) {
+      return {
+        ok: false,
+        message: "Claude Code returned an unexpected plugin list response.",
+      };
+    }
+    const plugins = value.flatMap((entry) => {
+      if (!(isRecord(entry) && typeof entry.id === "string")) {
+        return [];
+      }
+      return [{ id: entry.id, enabled: entry.enabled === true }];
+    });
+    return { ok: true, plugins };
+  } catch {
+    return {
+      ok: false,
+      message: "Claude Code returned invalid JSON while listing plugins.",
+    };
+  }
+}
+
+function parseClaudePluginState(opts: { readonly json: string }) {
+  const parsed = parsePluginList(opts);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const plugin = parsed.plugins.find((entry) => entry.id === PLUGIN_ID);
+  return {
+    ok: true as const,
+    installed: Boolean(plugin),
+    enabled: plugin?.enabled === true,
+  };
+}
+
+function resolveLegacySkill(opts: {
+  readonly scope: ClaudePluginScope;
+  readonly projectRoot?: string;
+}):
+  | { readonly ok: true; readonly path: string }
+  | { readonly ok: false; readonly path: string; readonly message: string } {
+  const root =
+    opts.scope === "user" ? process.env.HOME?.trim() : opts.projectRoot;
+  if (!root) {
+    return {
+      ok: false,
+      path: ".claude/skills/hack-init/SKILL.md",
+      message:
+        opts.scope === "user"
+          ? "HOME is not set; cannot resolve legacy Claude Code skill."
+          : "Missing project root for project-scoped Claude Code skill.",
+    };
+  }
+  return {
+    ok: true,
+    path: resolve(root, ".claude", "skills", "hack-init", "SKILL.md"),
+  };
+}
+
+async function removeGeneratedSkill(opts: { readonly path: string }): Promise<{
+  readonly path: string;
+  readonly removed: boolean;
+  readonly preserved: boolean;
+  readonly message?: string;
+}> {
+  const content = await readTextFile(opts.path);
+  if (!content) {
+    return { path: opts.path, removed: false, preserved: false };
+  }
+  const actual = normalizeInstructionText({ text: content });
+  const expected = normalizeInstructionText({ text: renderHackInitSkill() });
+  if (actual !== expected) {
+    return {
+      path: opts.path,
+      removed: false,
+      preserved: true,
+      message: `Preserved user-modified legacy Claude Code skill: ${opts.path}`,
+    };
+  }
+  await rm(resolve(opts.path, ".."), { recursive: true, force: true });
+  return { path: opts.path, removed: true, preserved: false };
+}
diff --git a/src/agents/claude.ts b/src/agents/claude.ts
index 610b9823..a1795150 100644
--- a/src/agents/claude.ts
+++ b/src/agents/claude.ts
@@ -101,6 +101,7 @@ export async function installClaudeHooks(opts: {
 export async function checkClaudeHooks(opts: {
   readonly scope: ClaudeScope;
   readonly projectRoot?: string;
+  readonly checkSkill?: boolean;
 }): Promise<ClaudeHookResult> {
   const resolved = resolveClaudeSettingsPath(opts);
   if (!resolved.ok) {
@@ -127,9 +128,24 @@ export async function checkClaudeHooks(opts: {
     };
   }
 
+  const hasAny = hasSomeHooks({
+    settings: settings.value,
+    command: HOOK_COMMAND,
+  });
   const hasAll = hasHooks({ settings: settings.value, command: HOOK_COMMAND });
   if (!hasAll) {
-    return { scope: opts.scope, status: "missing", path };
+    return {
+      scope: opts.scope,
+      status: hasAny ? "stale" : "missing",
+      path,
+      message: hasAny
+        ? "Only part of the legacy Hack Claude hook integration is installed."
+        : undefined,
+    };
+  }
+
+  if (opts.checkSkill === false) {
+    return { scope: opts.scope, status: "noop", path };
   }
 
   const initResult = await checkHackInitSkill({
@@ -157,6 +173,7 @@ export async function checkClaudeHooks(opts: {
 export async function removeClaudeHooks(opts: {
   readonly scope: ClaudeScope;
   readonly projectRoot?: string;
+  readonly removeSkill?: boolean;
 }): Promise<ClaudeHookResult> {
   const resolved = resolveClaudeSettingsPath(opts);
   if (!resolved.ok) {
@@ -169,12 +186,15 @@ export async function removeClaudeHooks(opts: {
   }
 
   const path = resolved.path;
-  const initResult = await removeHackInitSkill({
-    client: "claude",
-    scope: opts.scope,
-    projectRoot: opts.projectRoot,
-  });
-  const initRemoved = initResult.status === "removed";
+  const initResult =
+    opts.removeSkill === false
+      ? null
+      : await removeHackInitSkill({
+          client: "claude",
+          scope: opts.scope,
+          projectRoot: opts.projectRoot,
+        });
+  const initRemoved = initResult?.status === "removed";
 
   if (!(await pathExists(path))) {
     const status = initRemoved ? "removed" : "missing";
@@ -298,6 +318,17 @@ function hasHooks(opts: {
   });
 }
 
+function hasSomeHooks(opts: {
+  readonly settings: Record<string, unknown>;
+  readonly command: string;
+}): boolean {
+  const hooks = resolveHooksMap(opts.settings);
+  return HOOK_EVENTS.some((event) => {
+    const eventHooks = resolveEventHooks({ hooks, event });
+    return eventHasCommand({ eventHooks, command: opts.command });
+  });
+}
+
 function removeHooks(opts: {
   readonly settings: Record<string, unknown>;
   readonly command: string;
diff --git a/src/agents/codex-plugin.ts b/src/agents/codex-plugin.ts
new file mode 100644
index 00000000..50ada710
--- /dev/null
+++ b/src/agents/codex-plugin.ts
@@ -0,0 +1,342 @@
+import { createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { pathExists, readTextFile } from "../lib/fs.ts";
+import { isRecord } from "../lib/guards.ts";
+import { type ExecResult, exec, findExecutableInPath } from "../lib/shell.ts";
+import {
+  checkDeprecatedCodexMcpConfig,
+  removeDeprecatedCodexMcpConfig,
+} from "../mcp/install.ts";
+import { renderCodexSkill } from "./codex-skill.ts";
+import { renderHackInitSkill } from "./hack-init-skill.ts";
+import { normalizeInstructionText } from "./instruction-source.ts";
+import {
+  type AgentPluginResult,
+  checkNativeAgentPlugin,
+  mergeLegacyCleanupResults,
+  prepareNativeAgentPlugin,
+} from "./plugin-lifecycle.ts";
+
+export type CodexPluginScope = "project" | "user";
+
+export type CodexPluginResult = AgentPluginResult<CodexPluginScope>;
+
+type CodexCommand = (command: readonly string[]) => Promise<ExecResult>;
+
+const PLUGIN_ID = "hack@hack-dance";
+const MARKETPLACE_COMMAND =
+  "codex plugin marketplace add hack-dance/hack --sparse .agents/plugins --sparse plugins/hack";
+const PLUGIN_GUIDANCE = [
+  `Add the Hack marketplace with: ${MARKETPLACE_COMMAND}`,
+  "Then open /plugins, install and enable Hack, and start a new Codex session.",
+].join(" ");
+
+/** Check whether the official Hack plugin is installed and enabled in Codex. */
+export async function checkHackCodexPlugin(opts: {
+  readonly scope: CodexPluginScope;
+  readonly runCodexCommand?: CodexCommand;
+}): Promise<CodexPluginResult> {
+  const hasCodex = opts.runCodexCommand || findExecutableInPath("codex");
+  return await checkNativeAgentPlugin({
+    scope: opts.scope,
+    pluginId: PLUGIN_ID,
+    runCommand: hasCodex ? (opts.runCodexCommand ?? runCodexPluginList) : null,
+    missingExecutableMessage: `Codex is not installed. After installing Codex, ${PLUGIN_GUIDANCE}`,
+    inspectErrorMessage: "Could not inspect installed Codex plugins.",
+    missingPluginMessage: `The Hack Codex plugin is not installed. ${PLUGIN_GUIDANCE}`,
+    disabledPluginMessage:
+      "The Hack Codex plugin is installed but disabled. Enable it in /plugins, then start a new session.",
+    parseState: parseCodexPluginState,
+  });
+}
+
+/**
+ * Prepare Codex integration without mutating Codex's plugin registry.
+ *
+ * Matching legacy generated skills are removed. User-modified copies are
+ * preserved, and missing plugin installation is returned as guidance rather
+ * than silently installing external state.
+ */
+export async function prepareHackCodexPlugin(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+  readonly runCodexCommand?: CodexCommand;
+}): Promise<CodexPluginResult> {
+  return await prepareNativeAgentPlugin({
+    cleanup: async () => await removeDeprecatedHackCodexIntegration(opts),
+    check: async () => await checkHackCodexPlugin(opts),
+  });
+}
+
+/** Report all standalone Codex artifacts superseded by the plugin. */
+export async function checkDeprecatedHackCodexIntegration(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CodexPluginResult> {
+  const [skills, mcp] = await Promise.all([
+    checkDeprecatedCodexSkills(opts),
+    checkDeprecatedCodexMcpConfig(opts),
+  ]);
+  if (skills.status === "error") {
+    return skills;
+  }
+  if (mcp.status === "error") {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: mcp.path ?? PLUGIN_ID,
+      message: mcp.message,
+    };
+  }
+
+  const deprecated =
+    skills.status === "deprecated" || mcp.status === "deprecated";
+  return deprecated
+    ? {
+        scope: opts.scope,
+        status: "deprecated",
+        path:
+          skills.status === "deprecated"
+            ? skills.path
+            : (mcp.path ?? PLUGIN_ID),
+        message:
+          "Standalone Codex skills or MCP config are deprecated; the Hack plugin bundles them.",
+      }
+    : { scope: opts.scope, status: "absent", path: skills.path };
+}
+
+/** Remove safe-to-delete skill and MCP artifacts from the pre-plugin integration. */
+export async function removeDeprecatedHackCodexIntegration(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CodexPluginResult> {
+  const [skills, mcp] = await Promise.all([
+    removeDeprecatedCodexSkills(opts),
+    removeDeprecatedCodexMcpConfig(opts),
+  ]);
+  return mergeLegacyCleanupResults({
+    scope: opts.scope,
+    fallbackPath: PLUGIN_ID,
+    results: [skills, mcp],
+  });
+}
+
+/** Report project/user Codex skills generated by older Hack releases. */
+export async function checkDeprecatedCodexSkills(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CodexPluginResult> {
+  const resolved = resolveLegacySkills(opts);
+  if (!resolved.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolved.path,
+      message: resolved.message,
+    };
+  }
+  const existing: string[] = [];
+  for (const skill of resolved.skills) {
+    if (await pathExists(skill.path)) {
+      existing.push(skill.path);
+    }
+  }
+  if (existing.length === 0) {
+    return { scope: opts.scope, status: "absent", path: resolved.root };
+  }
+  return {
+    scope: opts.scope,
+    status: "deprecated",
+    path: existing[0] ?? resolved.root,
+    message:
+      "Legacy generated Codex skills are installed. Run hack setup sync to remove unmodified copies; edited copies are preserved.",
+  };
+}
+
+/** Remove only legacy Codex skills whose contents still match Hack's renderer. */
+export async function removeDeprecatedCodexSkills(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CodexPluginResult> {
+  const resolved = resolveLegacySkills(opts);
+  if (!resolved.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolved.path,
+      message: resolved.message,
+    };
+  }
+
+  const removed: string[] = [];
+  const preserved: string[] = [];
+  for (const skill of resolved.skills) {
+    const content = await readTextFile(skill.path);
+    if (!content) {
+      continue;
+    }
+    const fingerprint = fingerprintSkill({ content });
+    const currentFingerprint = fingerprintSkill({ content: skill.expected });
+    if (
+      fingerprint !== currentFingerprint &&
+      !skill.legacyFingerprints.includes(fingerprint)
+    ) {
+      preserved.push(skill.path);
+      continue;
+    }
+    await rm(resolve(skill.path, ".."), { recursive: true, force: true });
+    removed.push(skill.path);
+  }
+
+  const message =
+    preserved.length > 0
+      ? `Preserved user-modified legacy Codex skills: ${preserved.join(", ")}`
+      : undefined;
+  if (removed.length > 0) {
+    return {
+      scope: opts.scope,
+      status: "removed",
+      path: removed[0] ?? resolved.root,
+      message,
+    };
+  }
+  if (preserved.length > 0) {
+    return {
+      scope: opts.scope,
+      status: "preserved",
+      path: preserved[0] ?? resolved.root,
+      message,
+    };
+  }
+  return { scope: opts.scope, status: "absent", path: resolved.root };
+}
+
+async function runCodexPluginList(
+  command: readonly string[]
+): Promise<ExecResult> {
+  return await exec(["codex", ...command], {
+    stdin: "ignore",
+    timeoutMs: 10_000,
+  });
+}
+
+function parsePluginList(opts: { readonly json: string }):
+  | {
+      readonly ok: true;
+      readonly plugins: readonly {
+        readonly name: string;
+        readonly marketplaceName: string;
+        readonly installed: boolean;
+        readonly enabled: boolean;
+      }[];
+    }
+  | { readonly ok: false; readonly message: string } {
+  try {
+    const value: unknown = JSON.parse(opts.json);
+    if (!(isRecord(value) && Array.isArray(value.installed))) {
+      return {
+        ok: false,
+        message: "Codex returned an unexpected plugin list response.",
+      };
+    }
+    const plugins = value.installed.flatMap((entry) => {
+      if (
+        !isRecord(entry) ||
+        typeof entry.name !== "string" ||
+        typeof entry.marketplaceName !== "string"
+      ) {
+        return [];
+      }
+      return [
+        {
+          name: entry.name,
+          marketplaceName: entry.marketplaceName,
+          installed: entry.installed === true,
+          enabled: entry.enabled === true,
+        },
+      ];
+    });
+    return { ok: true, plugins };
+  } catch {
+    return {
+      ok: false,
+      message: "Codex returned invalid JSON while listing plugins.",
+    };
+  }
+}
+
+function parseCodexPluginState(opts: { readonly json: string }) {
+  const parsed = parsePluginList(opts);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const plugin = parsed.plugins.find(
+    (entry) =>
+      entry.name === "hack" &&
+      entry.marketplaceName === "hack-dance" &&
+      entry.installed
+  );
+  return {
+    ok: true as const,
+    installed: Boolean(plugin),
+    enabled: plugin?.enabled === true,
+  };
+}
+
+function resolveLegacySkills(opts: {
+  readonly scope: CodexPluginScope;
+  readonly projectRoot?: string;
+}):
+  | {
+      readonly ok: true;
+      readonly root: string;
+      readonly skills: readonly {
+        readonly path: string;
+        readonly expected: string;
+        readonly legacyFingerprints: readonly string[];
+      }[];
+    }
+  | { readonly ok: false; readonly path: string; readonly message: string } {
+  const root =
+    opts.scope === "user" ? process.env.HOME?.trim() : opts.projectRoot;
+  if (!root) {
+    return {
+      ok: false,
+      path: ".codex/skills",
+      message:
+        opts.scope === "user"
+          ? "HOME is not set; cannot resolve legacy Codex skills."
+          : "Missing project root for project-scoped Codex skills.",
+    };
+  }
+  const skillsRoot = resolve(root, ".codex", "skills");
+  return {
+    ok: true,
+    root: skillsRoot,
+    skills: [
+      {
+        path: resolve(skillsRoot, "hack-cli", "SKILL.md"),
+        expected: renderCodexSkill(),
+        legacyFingerprints: [
+          "b86781701ccea462513224112ceccc4bebbdc5a0de25c8b651d1a5f2215c4d25",
+          "6d90537002bbf64ee15a835bdb3cc458e6342a0fd7dd09a710a2cf2e5374217b",
+        ],
+      },
+      {
+        path: resolve(skillsRoot, "hack-init", "SKILL.md"),
+        expected: renderHackInitSkill(),
+        legacyFingerprints: [
+          "cd15fb6d8ed8e25071d05e756570f66b53f3a3bacbaab1ce2357440d0ae0a5d6",
+        ],
+      },
+    ],
+  };
+}
+
+function fingerprintSkill(opts: { readonly content: string }): string {
+  return createHash("sha256")
+    .update(normalizeInstructionText({ text: opts.content }))
+    .digest("hex");
+}
diff --git a/src/agents/codex-skill.ts b/src/agents/codex-skill.ts
index 4f8b80fa..a8a177d5 100644
--- a/src/agents/codex-skill.ts
+++ b/src/agents/codex-skill.ts
@@ -1,194 +1,13 @@
-import { rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-
-import {
-  ensureDir,
-  pathExists,
-  readTextFile,
-  writeTextFileIfChanged,
-} from "../lib/fs.ts";
-import {
-  checkHackInitSkill,
-  installHackInitSkill,
-  removeHackInitSkill,
-} from "./hack-init-skill.ts";
-import {
-  normalizeInstructionText,
-  renderInstructionSections,
-} from "./instruction-source.ts";
-
-export type CodexSkillScope = "project" | "user";
-
-export type CodexSkillResult = {
-  readonly scope: CodexSkillScope;
-  readonly status:
-    | "created"
-    | "updated"
-    | "noop"
-    | "stale"
-    | "removed"
-    | "missing"
-    | "error";
-  readonly path: string;
-  readonly message?: string;
-};
-
-const SKILL_NAME = "hack-cli";
-const SKILL_FILENAME = "SKILL.md";
-const SKILL_DIR = ".codex/skills";
-const HACK_CLI_MARKER_REGEX = /name:\s*hack-cli\b/i;
-
-/**
- * Install or update the Codex skills for hack usage.
- *
- * Writes the main `hack-cli` skill and the companion `/hack-init` onboarding
- * skill. The returned path points at the main skill; the status reflects both
- * artifacts (any change reports as created/updated).
- */
-export async function installCodexSkill(opts: {
-  readonly scope: CodexSkillScope;
-  readonly projectRoot?: string;
-}): Promise<CodexSkillResult> {
-  const resolved = resolveCodexSkillPath(opts);
-  if (!resolved.ok) {
-    return {
-      scope: opts.scope,
-      status: "error",
-      path: resolved.path ?? SKILL_FILENAME,
-      message: resolved.message,
-    };
-  }
-
-  const path = resolved.path;
-  await ensureDir(dirname(path));
-  const existed = await pathExists(path);
-  const result = await writeTextFileIfChanged(path, renderCodexSkill());
-
-  const initResult = await installHackInitSkill({
-    client: "codex",
-    scope: opts.scope,
-    projectRoot: opts.projectRoot,
-  });
-  if (initResult.status === "error") {
-    return {
-      scope: opts.scope,
-      status: "error",
-      path: initResult.path,
-      message: initResult.message,
-    };
-  }
-
-  const initChanged =
-    initResult.status === "created" || initResult.status === "updated";
-  const status = resolveInstallStatus({
-    changed: result.changed || initChanged,
-    existed,
-  });
-  return { scope: opts.scope, status, path };
-}
+import { renderInstructionSections } from "./instruction-source.ts";
 
 /**
- * Check whether the Codex skill is installed and current.
+ * Render the `hack-cli` skill bundled by the official Hack agent plugins.
  *
- * Reports `stale` when the skill file exists but its content no longer
- * matches the current render (normalized comparison).
- */
-export async function checkCodexSkill(opts: {
-  readonly scope: CodexSkillScope;
-  readonly projectRoot?: string;
-}): Promise<CodexSkillResult> {
-  const resolved = resolveCodexSkillPath(opts);
-  if (!resolved.ok) {
-    return {
-      scope: opts.scope,
-      status: "error",
-      path: resolved.path ?? SKILL_FILENAME,
-      message: resolved.message,
-    };
-  }
-
-  const path = resolved.path;
-  const content = await readTextFile(path);
-  if (!content) {
-    return { scope: opts.scope, status: "missing", path };
-  }
-
-  if (!HACK_CLI_MARKER_REGEX.test(content)) {
-    return { scope: opts.scope, status: "error", path };
-  }
-
-  const current = normalizeInstructionText({ text: renderCodexSkill() });
-  if (normalizeInstructionText({ text: content }) !== current) {
-    return {
-      scope: opts.scope,
-      status: "stale",
-      path,
-      message: "Codex skill content is out of date. Run: hack setup codex",
-    };
-  }
-
-  const initResult = await checkHackInitSkill({
-    client: "codex",
-    scope: opts.scope,
-    projectRoot: opts.projectRoot,
-  });
-  if (initResult.status !== "noop") {
-    return {
-      scope: opts.scope,
-      status: initResult.status === "error" ? "error" : "stale",
-      path: initResult.path,
-      message:
-        initResult.message ??
-        "hack-init skill is missing or out of date. Run: hack setup codex",
-    };
-  }
-
-  return { scope: opts.scope, status: "noop", path };
-}
-
-/**
- * Remove the Codex skill for hack CLI usage.
- */
-export async function removeCodexSkill(opts: {
-  readonly scope: CodexSkillScope;
-  readonly projectRoot?: string;
-}): Promise<CodexSkillResult> {
-  const resolved = resolveCodexSkillPath(opts);
-  if (!resolved.ok) {
-    return {
-      scope: opts.scope,
-      status: "error",
-      path: resolved.path ?? SKILL_FILENAME,
-      message: resolved.message,
-    };
-  }
-
-  const path = resolved.path;
-  const skillDir = resolve(path, "..");
-
-  const initResult = await removeHackInitSkill({
-    client: "codex",
-    scope: opts.scope,
-    projectRoot: opts.projectRoot,
-  });
-
-  if (!(await pathExists(path))) {
-    const status = initResult.status === "removed" ? "removed" : "missing";
-    return { scope: opts.scope, status, path };
-  }
-
-  await rm(skillDir, { recursive: true, force: true });
-  return { scope: opts.scope, status: "removed", path };
-}
-
-/**
- * Render the Codex skill template for hack CLI usage.
- *
- * Frontmatter and top-level framing live here; the instructional content is
- * the `skill`-tagged sections from the shared instruction source.
+ * The committed plugin copy is generated from this function so the plugin,
+ * CLI release, and other agent-facing surfaces share one instruction source.
  */
 export function renderCodexSkill(): string {
-  const lines = [
+  return [
     "---",
     "name: hack-cli",
     "description: >",
@@ -203,49 +22,5 @@ export function renderCodexSkill(): string {
     "",
     renderInstructionSections({ surface: "skill", headingStyle: "markdown" }),
     "",
-  ];
-
-  return lines.join("\n");
-}
-
-function resolveCodexSkillPath(opts: {
-  readonly scope: CodexSkillScope;
-  readonly projectRoot?: string;
-}):
-  | { readonly ok: true; readonly path: string }
-  | { readonly ok: false; readonly message: string; readonly path?: string } {
-  if (opts.scope === "project" && !opts.projectRoot) {
-    return {
-      ok: false,
-      message: "Missing project root for project-scoped Codex skill.",
-    };
-  }
-
-  const root = opts.scope === "user" ? resolveHomeDir() : opts.projectRoot;
-  if (!root) {
-    return {
-      ok: false,
-      message: "HOME is not set; cannot resolve Codex skill path.",
-    };
-  }
-
-  return {
-    ok: true,
-    path: resolve(root, SKILL_DIR, SKILL_NAME, SKILL_FILENAME),
-  };
-}
-
-function resolveHomeDir(): string | null {
-  const home = (process.env.HOME ?? "").trim();
-  return home.length > 0 ? home : null;
-}
-
-function resolveInstallStatus(opts: {
-  readonly changed: boolean;
-  readonly existed: boolean;
-}): "created" | "updated" | "noop" {
-  if (!opts.changed) {
-    return "noop";
-  }
-  return opts.existed ? "updated" : "created";
+  ].join("\n");
 }
diff --git a/src/agents/cursor-plugin.ts b/src/agents/cursor-plugin.ts
new file mode 100644
index 00000000..799712d6
--- /dev/null
+++ b/src/agents/cursor-plugin.ts
@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { readTextFile } from "../lib/fs.ts";
+import { isRecord } from "../lib/guards.ts";
+import { type ExecResult, exec, findExecutableInPath } from "../lib/shell.ts";
+import {
+  checkDeprecatedPluginMcpConfig,
+  removeDeprecatedPluginMcpConfig,
+} from "../mcp/install.ts";
+import { renderCursorRules } from "./cursor.ts";
+import { normalizeInstructionText } from "./instruction-source.ts";
+import {
+  type AgentPluginResult,
+  checkNativeAgentPlugin,
+  mergeLegacyCleanupResults,
+  prepareNativeAgentPlugin,
+} from "./plugin-lifecycle.ts";
+
+export type CursorPluginScope = "project" | "user";
+
+export type CursorPluginResult = AgentPluginResult<CursorPluginScope>;
+
+type CursorCommand = (command: readonly string[]) => Promise<ExecResult>;
+
+const PLUGIN_ID = "hack@hack-dance";
+const MARKETPLACE_COMMAND =
+  "cursor-agent plugin marketplace add hack-dance/hack";
+const PLUGIN_GUIDANCE = [
+  `Add the Hack marketplace with: ${MARKETPLACE_COMMAND}`,
+  "Then open /add-plugin in Cursor and install Hack from the Hack Dance marketplace.",
+  "Start a new Cursor session after installation.",
+].join(" ");
+const LEGACY_RULE_FINGERPRINTS = new Set([
+  "1b2d92dbd4ef71c9a4a96d270cf4aaf38059ee907b5ccb38db8457ec031862a4",
+  "f5b8078be4d7aec0df32f8334ad5a45acc4632541527dcae4e1f6e5144f05922",
+  "c79b88aacda891f9cfe76c7addfce704129dd5bc72415dc3aa5fd262a6e46396",
+]);
+
+/** Check whether the official Hack plugin is installed and enabled in Cursor. */
+export async function checkHackCursorPlugin(opts: {
+  readonly scope: CursorPluginScope;
+  readonly runCursorCommand?: CursorCommand;
+}): Promise<CursorPluginResult> {
+  const executable = findCursorExecutable();
+  return await checkNativeAgentPlugin({
+    scope: opts.scope,
+    pluginId: PLUGIN_ID,
+    runCommand:
+      opts.runCursorCommand ??
+      (executable ? createCursorCommand({ executable }) : null),
+    missingExecutableMessage: `Cursor Agent CLI is not installed. ${PLUGIN_GUIDANCE}`,
+    inspectErrorMessage: "Could not inspect installed Cursor plugins.",
+    missingPluginMessage: `The Hack Cursor plugin is not installed. ${PLUGIN_GUIDANCE}`,
+    disabledPluginMessage:
+      "The Hack Cursor plugin is installed but disabled. Enable it from Settings > Plugins, then start a new session.",
+    parseState: parseCursorPluginState,
+  });
+}
+
+/** Remove generated standalone Cursor artifacts and report plugin state. */
+export async function prepareHackCursorPlugin(opts: {
+  readonly scope: CursorPluginScope;
+  readonly projectRoot?: string;
+  readonly runCursorCommand?: CursorCommand;
+}): Promise<CursorPluginResult> {
+  return await prepareNativeAgentPlugin({
+    cleanup: async () => await removeDeprecatedHackCursorIntegration(opts),
+    check: async () => await checkHackCursorPlugin(opts),
+  });
+}
+
+/** Report generated standalone Cursor rules or MCP config superseded by the plugin. */
+export async function checkDeprecatedHackCursorIntegration(opts: {
+  readonly scope: CursorPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CursorPluginResult> {
+  const resolved = resolveLegacyRule(opts);
+  if (!resolved.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolved.path,
+      message: resolved.message,
+    };
+  }
+  const [rule, mcp] = await Promise.all([
+    readTextFile(resolved.path),
+    checkDeprecatedPluginMcpConfig({ target: "cursor", ...opts }),
+  ]);
+  if (mcp.status === "error") {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: mcp.path ?? resolved.path,
+      message: mcp.message,
+    };
+  }
+  return rule || mcp.status === "deprecated"
+    ? {
+        scope: opts.scope,
+        status: "deprecated",
+        path: rule ? resolved.path : (mcp.path ?? resolved.path),
+        message:
+          "Standalone Cursor rules or MCP config are deprecated; the Hack plugin bundles them.",
+      }
+    : { scope: opts.scope, status: "absent", path: resolved.path };
+}
+
+/** Safely remove generated standalone Cursor artifacts, preserving edited content. */
+export async function removeDeprecatedHackCursorIntegration(opts: {
+  readonly scope: CursorPluginScope;
+  readonly projectRoot?: string;
+}): Promise<CursorPluginResult> {
+  const resolved = resolveLegacyRule(opts);
+  if (!resolved.ok) {
+    return {
+      scope: opts.scope,
+      status: "error",
+      path: resolved.path,
+      message: resolved.message,
+    };
+  }
+  const content = await readTextFile(resolved.path);
+  let ruleStatus: "absent" | "removed" | "preserved" = "absent";
+  let ruleMessage: string | undefined;
+  if (content) {
+    const actual = normalizeInstructionText({ text: content });
+    const expected = normalizeInstructionText({ text: renderCursorRules() });
+    const fingerprint = createHash("sha256").update(actual).digest("hex");
+    if (actual === expected || LEGACY_RULE_FINGERPRINTS.has(fingerprint)) {
+      await unlink(resolved.path);
+      ruleStatus = "removed";
+    } else {
+      ruleStatus = "preserved";
+      ruleMessage = `Preserved user-modified legacy Cursor rules: ${resolved.path}`;
+    }
+  }
+  const mcp = await removeDeprecatedPluginMcpConfig({
+    target: "cursor",
+    ...opts,
+  });
+  return mergeLegacyCleanupResults({
+    scope: opts.scope,
+    fallbackPath: resolved.path,
+    results: [
+      { status: ruleStatus, path: resolved.path, message: ruleMessage },
+      mcp,
+    ],
+  });
+}
+
+function findCursorExecutable(): string | null {
+  for (const name of ["cursor-agent", "agent", "cursor"] as const) {
+    const executable = findExecutableInPath(name);
+    if (executable) {
+      return executable;
+    }
+  }
+  return null;
+}
+
+function createCursorCommand(opts: {
+  readonly executable: string;
+}): CursorCommand {
+  return async (command) =>
+    await exec([opts.executable, ...command], {
+      stdin: "ignore",
+      timeoutMs: 10_000,
+    });
+}
+
+function parsePluginList(opts: { readonly json: string }):
+  | {
+      readonly ok: true;
+      readonly plugins: readonly {
+        readonly id: string;
+        readonly enabled: boolean;
+      }[];
+    }
+  | { readonly ok: false; readonly message: string } {
+  try {
+    const value: unknown = JSON.parse(opts.json);
+    let entries: unknown[] | null = null;
+    if (Array.isArray(value)) {
+      entries = value;
+    } else if (isRecord(value) && Array.isArray(value.installed)) {
+      entries = value.installed;
+    }
+    if (!entries) {
+      return {
+        ok: false,
+        message: "Cursor returned an unexpected plugin list response.",
+      };
+    }
+    const plugins = entries.flatMap((entry) => {
+      if (!isRecord(entry)) {
+        return [];
+      }
+      const id = typeof entry.id === "string" ? entry.id : null;
+      if (!id) {
+        return [];
+      }
+      return [{ id, enabled: entry.enabled !== false }];
+    });
+    return { ok: true, plugins };
+  } catch {
+    return {
+      ok: false,
+      message: "Cursor returned invalid JSON while listing plugins.",
+    };
+  }
+}
+
+function parseCursorPluginState(opts: { readonly json: string }) {
+  const parsed = parsePluginList(opts);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const plugin = parsed.plugins.find((entry) => entry.id === PLUGIN_ID);
+  return {
+    ok: true as const,
+    installed: Boolean(plugin),
+    enabled: plugin?.enabled === true,
+  };
+}
+
+function resolveLegacyRule(opts: {
+  readonly scope: CursorPluginScope;
+  readonly projectRoot?: string;
+}):
+  | { readonly ok: true; readonly path: string }
+  | { readonly ok: false; readonly path: string; readonly message: string } {
+  const root =
+    opts.scope === "user" ? process.env.HOME?.trim() : opts.projectRoot;
+  if (!root) {
+    return {
+      ok: false,
+      path: ".cursor/rules/hack.mdc",
+      message:
+        opts.scope === "user"
+          ? "HOME is not set; cannot resolve legacy Cursor rules."
+          : "Missing project root for project-scoped Cursor rules.",
+    };
+  }
+  return { ok: true, path: resolve(root, ".cursor", "rules", "hack.mdc") };
+}
diff --git a/src/agents/cursor.ts b/src/agents/cursor.ts
index e8b94b5a..702287cd 100644
--- a/src/agents/cursor.ts
+++ b/src/agents/cursor.ts
@@ -157,6 +157,18 @@ export function renderCursorRules(): string {
   return lines.join("\n");
 }
 
+/** Render the native Cursor plugin rule with required marketplace metadata. */
+export function renderCursorPluginRule(): string {
+  return [
+    "---",
+    "description: Operate Hack-managed local development environments through the hack CLI.",
+    "alwaysApply: true",
+    "---",
+    "",
+    renderCursorRules(),
+  ].join("\n");
+}
+
 function resolveCursorRulesPath(opts: {
   readonly scope: CursorScope;
   readonly projectRoot?: string;
diff --git a/src/agents/hack-init-skill.ts b/src/agents/hack-init-skill.ts
index 8043c594..b70f5b0a 100644
--- a/src/agents/hack-init-skill.ts
+++ b/src/agents/hack-init-skill.ts
@@ -15,11 +15,11 @@ import { normalizeInstructionText } from "./instruction-source.ts";
  * `hack-init` MCP prompt and follow it. The onboarding content itself lives in
  * `src/agents/onboarding-prompt.ts` — never in the installed skill file.
  *
- * Installed for both Claude Code (`.claude/skills/hack-init/SKILL.md`) and
- * Codex (`.codex/skills/hack-init/SKILL.md`) at project or user scope.
+ * Bundled in the native Hack plugins. The standalone Claude installer remains
+ * only for recognizing and safely migrating artifacts from older releases.
  */
 
-export type HackInitSkillClient = "claude" | "codex";
+export type HackInitSkillClient = "claude";
 
 export type HackInitSkillScope = "project" | "user";
 
@@ -43,12 +43,10 @@ const SKILL_FILENAME = "SKILL.md";
 
 const SKILL_DIRS: Readonly<Record<HackInitSkillClient, string>> = {
   claude: ".claude/skills",
-  codex: ".codex/skills",
 };
 
 const SETUP_COMMANDS: Readonly<Record<HackInitSkillClient, string>> = {
   claude: "hack setup claude",
-  codex: "hack setup codex",
 };
 
 /**
diff --git a/src/agents/instruction-source.ts b/src/agents/instruction-source.ts
index ae1ea2a2..0becdc08 100644
--- a/src/agents/instruction-source.ts
+++ b/src/agents/instruction-source.ts
@@ -2,8 +2,8 @@
  * Single source of truth for hack CLI agent instructions.
  *
  * Every generated agent-facing instruction surface (AGENTS.md/CLAUDE.md
- * snippet, Codex skill, Cursor rules, session primer) renders from the
- * sections defined here. Surface-specific framing (frontmatter, markers,
+ * snippet, bundled native plugin skills/rules, session primer) renders from
+ * the sections defined here. Surface-specific framing (frontmatter, markers,
  * top-level headings) stays in each renderer; the canonical section titles
  * and bullets live here so content can never drift between surfaces.
  */
@@ -307,7 +307,7 @@ export const INSTRUCTION_SECTIONS: readonly InstructionSection[] = [
     title: "Agent integration maintenance",
     surfaces: ALL_SURFACES,
     bullets: [
-      "Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, client skills/rules, shared global skills, and MCP).",
+      "Project-level hack commands auto-check integration drift and attempt auto-sync (project docs, Cursor/Claude integrations, shared global skills, and MCP).",
       "When drift is detected, Hack reports it before repair and tells the agent to reload after repair; it never silently leaves the session using cached rules.",
       "Set `HACK_SETUP_SYNC_MODE=warn` to only warn, or `HACK_SETUP_SYNC_MODE=off` to disable.",
       "Refresh project + user integrations: `hack setup sync --all-scopes`",
@@ -322,9 +322,9 @@ export const INSTRUCTION_SECTIONS: readonly InstructionSection[] = [
     title: "Agent setup (CLI-first)",
     surfaces: ["docs", "skill", "primer"],
     bullets: [
-      "Cursor rules: `hack setup cursor`",
-      "Claude hooks: `hack setup claude`",
-      "Codex skill: `hack setup codex`",
+      "Cursor plugin: run `hack setup cursor`, then install Hack with `/add-plugin` or enable it from Settings > Plugins as directed.",
+      "Claude Code plugin: run `hack setup claude`, then install or enable `hack@hack-dance` as directed.",
+      "Codex plugin: run `hack setup codex`, then install or enable Hack from `/plugins` as directed.",
       "Refresh all local agent integrations: `hack setup sync --all-scopes`",
       "Agent-assisted onboarding: `hack init --with claude|codex|both` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.",
       "Init prompt: `hack agent init` (use --client cursor|claude|codex to open)",
diff --git a/src/agents/integration-revision.ts b/src/agents/integration-revision.ts
index 886f2f91..30f26fb5 100644
--- a/src/agents/integration-revision.ts
+++ b/src/agents/integration-revision.ts
@@ -3,4 +3,4 @@
  * source test recomputes this value and fails whenever guidance changes
  * without a revision update.
  */
-export const HACK_AGENT_INTEGRATION_CONTENT_REVISION = "1319d93c89c3";
+export const HACK_AGENT_INTEGRATION_CONTENT_REVISION = "6ef36575c6e7";
diff --git a/src/agents/plugin-lifecycle.ts b/src/agents/plugin-lifecycle.ts
new file mode 100644
index 00000000..c8ef702a
--- /dev/null
+++ b/src/agents/plugin-lifecycle.ts
@@ -0,0 +1,243 @@
+import type { ExecResult } from "../lib/shell.ts";
+
+export type AgentPluginStatus =
+  | "noop"
+  | "missing"
+  | "stale"
+  | "deprecated"
+  | "removed"
+  | "preserved"
+  | "absent"
+  | "error";
+
+export type AgentPluginResult<TScope extends string> = {
+  readonly scope: TScope;
+  readonly status: AgentPluginStatus;
+  readonly path: string;
+  readonly message?: string;
+  readonly cleanupStatus?: AgentPluginStatus;
+};
+
+export type AgentPluginCommand = (
+  command: readonly string[]
+) => Promise<ExecResult>;
+
+export type ParsedAgentPluginState =
+  | {
+      readonly ok: true;
+      readonly installed: boolean;
+      readonly enabled: boolean;
+    }
+  | { readonly ok: false; readonly message: string };
+
+export type AgentPluginInstallOutcome =
+  | "error"
+  | "warning"
+  | "unchanged"
+  | "updated";
+
+/** Map lifecycle states to honest setup/onboarding presentation semantics. */
+export function resolveAgentPluginInstallOutcome({
+  status,
+  cleanupStatus,
+}: {
+  readonly status: string;
+  readonly cleanupStatus?: string;
+}): AgentPluginInstallOutcome {
+  if (status === "error" || cleanupStatus === "error") {
+    return "error";
+  }
+  if (
+    ["missing", "stale", "deprecated"].includes(status) ||
+    cleanupStatus === "preserved"
+  ) {
+    return "warning";
+  }
+  if (cleanupStatus === "removed") {
+    return "updated";
+  }
+  if (["noop", "preserved", "absent"].includes(status)) {
+    return "unchanged";
+  }
+  return "updated";
+}
+
+/** Apply the common native-plugin state machine to client-specific CLI output. */
+export async function checkNativeAgentPlugin<TScope extends string>({
+  scope,
+  pluginId,
+  runCommand,
+  missingExecutableMessage,
+  inspectErrorMessage,
+  missingPluginMessage,
+  disabledPluginMessage,
+  parseState,
+}: {
+  readonly scope: TScope;
+  readonly pluginId: string;
+  readonly runCommand: AgentPluginCommand | null;
+  readonly missingExecutableMessage: string;
+  readonly inspectErrorMessage: string;
+  readonly missingPluginMessage: string;
+  readonly disabledPluginMessage: string;
+  readonly parseState: (opts: {
+    readonly json: string;
+  }) => ParsedAgentPluginState;
+}): Promise<AgentPluginResult<TScope>> {
+  if (!runCommand) {
+    return {
+      scope,
+      status: "missing",
+      path: pluginId,
+      message: missingExecutableMessage,
+    };
+  }
+
+  const commandResult = await runCommand(["plugin", "list", "--json"]);
+  if (commandResult.exitCode !== 0) {
+    return {
+      scope,
+      status: "error",
+      path: pluginId,
+      message: commandResult.stderr.trim() || inspectErrorMessage,
+    };
+  }
+
+  const parsed = parseState({ json: commandResult.stdout });
+  if (!parsed.ok) {
+    return {
+      scope,
+      status: "error",
+      path: pluginId,
+      message: parsed.message,
+    };
+  }
+  if (!parsed.installed) {
+    return {
+      scope,
+      status: "missing",
+      path: pluginId,
+      message: missingPluginMessage,
+    };
+  }
+  if (!parsed.enabled) {
+    return {
+      scope,
+      status: "stale",
+      path: pluginId,
+      message: disabledPluginMessage,
+    };
+  }
+  return { scope, status: "noop", path: pluginId };
+}
+
+/** Remove superseded artifacts before reporting the current plugin state. */
+export async function prepareNativeAgentPlugin<TScope extends string>({
+  cleanup,
+  check,
+}: {
+  readonly cleanup: () => Promise<AgentPluginResult<TScope>>;
+  readonly check: () => Promise<AgentPluginResult<TScope>>;
+}): Promise<AgentPluginResult<TScope>> {
+  const pluginResult = await check();
+  if (pluginResult.status !== "noop") {
+    return pluginResult;
+  }
+  const cleanupResult = await cleanup();
+  if (cleanupResult.status === "error") {
+    return cleanupResult;
+  }
+  return mergePluginPreparation({
+    cleanup: cleanupResult,
+    plugin: pluginResult,
+  });
+}
+
+/** Report plugin readiness first, then any legacy artifacts blocking cutover. */
+export async function checkNativeAgentPluginCutover<TScope extends string>({
+  check,
+  checkLegacy,
+}: {
+  readonly check: () => Promise<AgentPluginResult<TScope>>;
+  readonly checkLegacy: () => Promise<AgentPluginResult<TScope>>;
+}): Promise<AgentPluginResult<TScope>> {
+  const pluginResult = await check();
+  if (pluginResult.status !== "noop") {
+    return pluginResult;
+  }
+  return await checkLegacy();
+}
+
+/** Collapse independent legacy cleanup outcomes using consistent precedence. */
+export function mergeLegacyCleanupResults<TScope extends string>({
+  scope,
+  fallbackPath,
+  results,
+}: {
+  readonly scope: TScope;
+  readonly fallbackPath: string;
+  readonly results: readonly {
+    readonly status: AgentPluginStatus | "updated";
+    readonly path?: string;
+    readonly message?: string;
+  }[];
+}): AgentPluginResult<TScope> {
+  const error = results.find((result) => result.status === "error");
+  const preserved = results.find((result) => result.status === "preserved");
+  const removed = results.find((result) => result.status === "removed");
+  const messages = results.flatMap((result) =>
+    typeof result.message === "string" ? [result.message] : []
+  );
+  const path =
+    error?.path ??
+    preserved?.path ??
+    removed?.path ??
+    results.find((result) => result.status !== "absent")?.path ??
+    results.find((result) => result.path)?.path ??
+    fallbackPath;
+
+  let status: AgentPluginResult<TScope>["status"] = "absent";
+  if (error) {
+    status = "error";
+  } else if (preserved) {
+    status = "preserved";
+  } else if (removed) {
+    status = "removed";
+  }
+
+  return {
+    scope,
+    status,
+    path,
+    message: messages.length > 0 ? messages.join(" ") : undefined,
+  };
+}
+
+/**
+ * Preserve plugin readiness as the primary outcome while retaining the
+ * independent legacy-cleanup result for callers that need both facts.
+ */
+export function mergePluginPreparation<TScope extends string>({
+  cleanup,
+  plugin,
+}: {
+  readonly cleanup: AgentPluginResult<TScope>;
+  readonly plugin: AgentPluginResult<TScope>;
+}): AgentPluginResult<TScope> {
+  const cleanupMessage =
+    cleanup.message ??
+    (cleanup.status === "removed"
+      ? "Removed deprecated standalone integration artifacts."
+      : undefined);
+  const messages = [cleanupMessage, plugin.message].filter(
+    (message): message is string => typeof message === "string"
+  );
+
+  return {
+    scope: plugin.scope,
+    status: plugin.status,
+    cleanupStatus: cleanup.status,
+    path: plugin.path,
+    message: messages.length > 0 ? messages.join(" ") : undefined,
+  };
+}
diff --git a/src/cli/integration-sync.ts b/src/cli/integration-sync.ts
index 7caa9a06..dd4e4cde 100644
--- a/src/cli/integration-sync.ts
+++ b/src/cli/integration-sync.ts
@@ -1,6 +1,18 @@
-import { checkClaudeHooks, installClaudeHooks } from "../agents/claude.ts";
-import { checkCodexSkill, installCodexSkill } from "../agents/codex-skill.ts";
-import { checkCursorRules, installCursorRules } from "../agents/cursor.ts";
+import {
+  checkDeprecatedHackClaudeIntegration,
+  checkHackClaudePlugin,
+  removeDeprecatedHackClaudeIntegration,
+} from "../agents/claude-plugin.ts";
+import {
+  checkDeprecatedHackCodexIntegration,
+  checkHackCodexPlugin,
+  removeDeprecatedHackCodexIntegration,
+} from "../agents/codex-plugin.ts";
+import {
+  checkDeprecatedHackCursorIntegration,
+  checkHackCursorPlugin,
+  removeDeprecatedHackCursorIntegration,
+} from "../agents/cursor-plugin.ts";
 import { HACK_AGENT_INTEGRATION_CLI_VERSION } from "../agents/instruction-source.ts";
 import {
   checkDeprecatedSharedHackSkills,
@@ -22,12 +34,6 @@ import {
   checkAgentDocs,
   upsertAgentDocs,
 } from "../mcp/agent-docs.ts";
-import {
-  checkMcpConfig,
-  installMcpConfig,
-  type McpCheckResult,
-  type McpInstallResult,
-} from "../mcp/install.ts";
 import { logger } from "../ui/logger.ts";
 
 type IntegrationSyncMode = "auto" | "warn" | "off";
@@ -180,16 +186,23 @@ async function detectIntegrationDrift(opts: {
     ticketsDocs,
     sharedSkill,
     deprecatedSharedSkills,
-    mcpProject,
-    mcpUser,
     docs,
   ] = await Promise.all([
-    checkCursorRules({ scope: "project", projectRoot: opts.projectRoot }),
-    checkCursorRules({ scope: "user" }),
-    checkClaudeHooks({ scope: "project", projectRoot: opts.projectRoot }),
-    checkClaudeHooks({ scope: "user" }),
-    checkCodexSkill({ scope: "project", projectRoot: opts.projectRoot }),
-    checkCodexSkill({ scope: "user" }),
+    checkDeprecatedHackCursorIntegration({
+      scope: "project",
+      projectRoot: opts.projectRoot,
+    }),
+    checkDeprecatedHackCursorIntegration({ scope: "user" }),
+    checkDeprecatedHackClaudeIntegration({
+      scope: "project",
+      projectRoot: opts.projectRoot,
+    }),
+    checkDeprecatedHackClaudeIntegration({ scope: "user" }),
+    checkDeprecatedHackCodexIntegration({
+      scope: "project",
+      projectRoot: opts.projectRoot,
+    }),
+    checkDeprecatedHackCodexIntegration({ scope: "user" }),
     checkDeprecatedTicketsSkill({
       scope: "project",
       projectRoot: opts.projectRoot,
@@ -201,15 +214,6 @@ async function detectIntegrationDrift(opts: {
     }),
     checkSharedHackSkill(),
     checkDeprecatedSharedHackSkills(),
-    checkMcpConfig({
-      scope: "project",
-      projectRoot: opts.projectRoot,
-      targets: ["cursor", "claude", "codex"],
-    }),
-    checkMcpConfig({
-      scope: "user",
-      targets: ["cursor", "claude", "codex"],
-    }),
     checkAgentDocs({
       projectRoot: opts.projectRoot,
       targets: ["agents", "claude"],
@@ -231,7 +235,6 @@ async function detectIntegrationDrift(opts: {
   const singleDrift = singleChecks.some((status) =>
     hasSingleCheckDrift(status)
   );
-  const mcpDrift = hasMcpDrift({ checks: [...mcpProject, ...mcpUser] });
   const docsDrift = hasDocDrift({ checks: docs });
   const deprecatedDocsDrift = ticketsDocs.some(
     (check) => check.status !== "noop" && check.status !== "absent"
@@ -242,11 +245,7 @@ async function detectIntegrationDrift(opts: {
 
   return {
     hasDrift:
-      singleDrift ||
-      mcpDrift ||
-      docsDrift ||
-      deprecatedDocsDrift ||
-      deprecatedSharedDrift,
+      singleDrift || docsDrift || deprecatedDocsDrift || deprecatedSharedDrift,
   };
 }
 
@@ -254,12 +253,6 @@ function hasSingleCheckDrift(status: string): boolean {
   return status !== "noop" && status !== "absent";
 }
 
-function hasMcpDrift(opts: {
-  readonly checks: readonly McpCheckResult[];
-}): boolean {
-  return opts.checks.some((check) => check.status !== "present");
-}
-
 function hasDocDrift(opts: {
   readonly checks: readonly AgentDocCheckResult[];
 }): boolean {
@@ -270,27 +263,52 @@ async function autoSyncIntegrations(opts: {
   readonly projectRoot: string;
 }): Promise<{ readonly ok: boolean }> {
   const [
-    cursorProject,
-    cursorUser,
-    claudeProject,
-    claudeUser,
-    codexProject,
-    codexUser,
+    cursorStatuses,
+    claudeStatuses,
+    codexStatuses,
     ticketsProject,
     ticketsUser,
     ticketsDocs,
     sharedSkill,
     deprecatedSharedSkills,
-    mcpProject,
-    mcpUser,
     docs,
   ] = await Promise.all([
-    installCursorRules({ scope: "project", projectRoot: opts.projectRoot }),
-    installCursorRules({ scope: "user" }),
-    installClaudeHooks({ scope: "project", projectRoot: opts.projectRoot }),
-    installClaudeHooks({ scope: "user" }),
-    installCodexSkill({ scope: "project", projectRoot: opts.projectRoot }),
-    installCodexSkill({ scope: "user" }),
+    syncLegacyScopesWhenPluginReady({
+      check: async () => await checkHackCursorPlugin({ scope: "user" }),
+      cleanups: [
+        async () =>
+          await removeDeprecatedHackCursorIntegration({
+            scope: "project",
+            projectRoot: opts.projectRoot,
+          }),
+        async () =>
+          await removeDeprecatedHackCursorIntegration({ scope: "user" }),
+      ],
+    }),
+    syncLegacyScopesWhenPluginReady({
+      check: async () => await checkHackClaudePlugin({ scope: "user" }),
+      cleanups: [
+        async () =>
+          await removeDeprecatedHackClaudeIntegration({
+            scope: "project",
+            projectRoot: opts.projectRoot,
+          }),
+        async () =>
+          await removeDeprecatedHackClaudeIntegration({ scope: "user" }),
+      ],
+    }),
+    syncLegacyScopesWhenPluginReady({
+      check: async () => await checkHackCodexPlugin({ scope: "user" }),
+      cleanups: [
+        async () =>
+          await removeDeprecatedHackCodexIntegration({
+            scope: "project",
+            projectRoot: opts.projectRoot,
+          }),
+        async () =>
+          await removeDeprecatedHackCodexIntegration({ scope: "user" }),
+      ],
+    }),
     removeTicketsSkill({ scope: "project", projectRoot: opts.projectRoot }),
     removeTicketsSkill({ scope: "user" }),
     removeTicketsAgentDocs({
@@ -299,38 +317,28 @@ async function autoSyncIntegrations(opts: {
     }),
     installSharedHackSkill(),
     removeDeprecatedSharedHackSkills(),
-    installMcpConfig({
-      scope: "project",
-      projectRoot: opts.projectRoot,
-      targets: ["cursor", "claude", "codex"],
-    }),
-    installMcpConfig({
-      scope: "user",
-      targets: ["cursor", "claude", "codex"],
-    }),
     upsertAgentDocs({
       projectRoot: opts.projectRoot,
       targets: ["agents", "claude"],
     }),
   ]);
 
+  const nativeStatuses = [
+    ...cursorStatuses,
+    ...claudeStatuses,
+    ...codexStatuses,
+  ] as const;
   const singleStatuses = [
-    cursorProject.status,
-    cursorUser.status,
-    claudeProject.status,
-    claudeUser.status,
-    codexProject.status,
-    codexUser.status,
     ticketsProject.status,
     ticketsUser.status,
     sharedSkill.status,
   ] as const;
+  const nativeErrors = nativeStatuses.some((status) =>
+    hasNativeSyncFailure(status)
+  );
   const singleErrors = singleStatuses.some((status) =>
     hasSingleInstallError(status)
   );
-  const mcpErrors = hasMcpInstallErrors({
-    results: [...mcpProject, ...mcpUser],
-  });
   const docsErrors = hasDocInstallErrors({ results: docs });
   const ticketsDocsErrors = hasDocInstallErrors({ results: ticketsDocs });
   const deprecatedSharedErrors = deprecatedSharedSkills.some(
@@ -340,7 +348,7 @@ async function autoSyncIntegrations(opts: {
   return {
     ok: !(
       singleErrors ||
-      mcpErrors ||
+      nativeErrors ||
       docsErrors ||
       ticketsDocsErrors ||
       deprecatedSharedErrors
@@ -352,10 +360,28 @@ function hasSingleInstallError(status: string): boolean {
   return status === "error";
 }
 
-function hasMcpInstallErrors(opts: {
-  readonly results: readonly McpInstallResult[];
-}): boolean {
-  return opts.results.some((result) => result.status === "error");
+function hasNativeSyncFailure(status: string): boolean {
+  return ["error", "missing", "stale", "deprecated", "preserved"].includes(
+    status
+  );
+}
+
+/** Gate automatic project/user cleanup behind one native-plugin readiness check. */
+export async function syncLegacyScopesWhenPluginReady({
+  check,
+  cleanups,
+}: {
+  readonly check: () => Promise<{ readonly status: string }>;
+  readonly cleanups: readonly (() => Promise<{ readonly status: string }>)[];
+}): Promise<readonly string[]> {
+  const plugin = await check();
+  if (plugin.status !== "noop") {
+    return [plugin.status];
+  }
+  const results = await Promise.all(
+    cleanups.map(async (cleanup) => await cleanup())
+  );
+  return results.map((result) => result.status);
 }
 
 function hasDocInstallErrors(opts: {
diff --git a/src/commands/project.ts b/src/commands/project.ts
index 7084b291..81afdb02 100644
--- a/src/commands/project.ts
+++ b/src/commands/project.ts
@@ -11,9 +11,9 @@ import {
   text,
 } from "@clack/prompts";
 import { YAML } from "bun";
-import { installClaudeHooks } from "../agents/claude.ts";
-import { installCodexSkill } from "../agents/codex-skill.ts";
-import { installCursorRules } from "../agents/cursor.ts";
+import { prepareHackClaudePlugin } from "../agents/claude-plugin.ts";
+import { prepareHackCodexPlugin } from "../agents/codex-plugin.ts";
+import { prepareHackCursorPlugin } from "../agents/cursor-plugin.ts";
 import {
   type OnboardingWith,
   parseOnboardingWith,
@@ -23,6 +23,7 @@ import {
   type OnboardingMode,
   renderOnboardingPrompt,
 } from "../agents/onboarding-prompt.ts";
+import { resolveAgentPluginInstallOutcome } from "../agents/plugin-lifecycle.ts";
 import { composeLogBackend, lokiLogBackend } from "../backends/log-backend.ts";
 import { composeRuntimeBackend } from "../backends/runtime-backend.ts";
 import type { CliContext, CommandArgs } from "../cli/command.ts";
@@ -3999,7 +4000,9 @@ async function handleInit({
     );
   }
 
-  await maybeSetupAgentIntegrations({ repoRoot });
+  const agentIntegrationsReady = await maybeSetupAgentIntegrations({
+    repoRoot,
+  });
 
   note(
     [
@@ -4026,7 +4029,7 @@ async function handleInit({
     });
   }
 
-  return 0;
+  return agentIntegrationsReady ? 0 : 1;
 }
 
 async function handleInitAuto({
@@ -4318,77 +4321,65 @@ type SetupIntegration = "cursor" | "claude" | "codex" | "agents" | "mcp";
 
 async function maybeSetupAgentIntegrations(opts: {
   readonly repoRoot: string;
-}): Promise<void> {
+}): Promise<boolean> {
   if (!canPrompt()) {
-    return;
+    return true;
   }
   const shouldSetup = await confirm({
     message: "Set up coding agent integrations? (Cursor/Claude/Codex)",
     initialValue: true,
   });
   if (isCancel(shouldSetup) || !shouldSetup) {
-    return;
+    return true;
   }
 
   const selected = await multiselect<SetupIntegration>({
     message: "Select integrations to install:",
     required: true,
     options: [
-      { value: "cursor", label: "Cursor rules (.cursor/rules/hack.mdc)" },
-      {
-        value: "claude",
-        label: "Claude Code hooks (.claude/settings.local.json)",
-      },
-      { value: "codex", label: "Codex skill (.codex/skills/hack-cli)" },
+      { value: "cursor", label: "Hack Cursor plugin (user-installed)" },
+      { value: "claude", label: "Hack Claude Code plugin (user-installed)" },
+      { value: "codex", label: "Hack Codex plugin (user-installed)" },
       { value: "agents", label: "AGENTS.md / CLAUDE.md snippets" },
-      { value: "mcp", label: "MCP config (no-shell clients)" },
+      { value: "mcp", label: "Standalone MCP config (advanced)" },
     ],
     initialValues: ["cursor", "claude", "codex"],
   });
   if (isCancel(selected) || selected.length === 0) {
-    return;
+    return true;
   }
 
   const selection = new Set(selected);
-
-  if (selection.has("cursor")) {
-    const result = await installCursorRules({
-      scope: "project",
-      projectRoot: opts.repoRoot,
-    });
-    logInstallResult({
-      label: "Cursor rules",
-      status: result.status,
-      path: result.path,
-      message: result.message,
-    });
-  }
-
-  if (selection.has("claude")) {
-    const result = await installClaudeHooks({
-      scope: "project",
-      projectRoot: opts.repoRoot,
-    });
-    logInstallResult({
-      label: "Claude hooks",
-      status: result.status,
-      path: result.path,
-      message: result.message,
-    });
-  }
-
-  if (selection.has("codex")) {
-    const result = await installCodexSkill({
-      scope: "project",
-      projectRoot: opts.repoRoot,
-    });
-    logInstallResult({
-      label: "Codex skill",
-      status: result.status,
-      path: result.path,
-      message: result.message,
-    });
-  }
+  const pluginResults = await Promise.all([
+    prepareSelectedAgentPlugin({
+      selected: selection.has("cursor"),
+      label: "Hack Cursor plugin",
+      prepare: async () =>
+        await prepareHackCursorPlugin({
+          scope: "project",
+          projectRoot: opts.repoRoot,
+        }),
+    }),
+    prepareSelectedAgentPlugin({
+      selected: selection.has("claude"),
+      label: "Hack Claude Code plugin",
+      prepare: async () =>
+        await prepareHackClaudePlugin({
+          scope: "project",
+          projectRoot: opts.repoRoot,
+        }),
+    }),
+    prepareSelectedAgentPlugin({
+      selected: selection.has("codex"),
+      label: "Hack Codex plugin",
+      prepare: async () =>
+        await prepareHackCodexPlugin({
+          scope: "project",
+          projectRoot: opts.repoRoot,
+        }),
+    }),
+  ]);
+  let integrationsReady = pluginResults.every(Boolean);
 
   if (selection.has("agents")) {
     const results = await upsertAgentDocs({
@@ -4396,21 +4387,22 @@ async function maybeSetupAgentIntegrations(opts: {
       targets: ["agents", "claude"],
     });
     for (const result of results) {
-      logInstallResult({
-        label: "Agent docs",
-        status: result.status,
-        path: result.path,
-        message: result.message,
-      });
+      integrationsReady =
+        logInstallResult({
+          label: "Agent docs",
+          status: result.status,
+          path: result.path,
+          message: result.message,
+        }) && integrationsReady;
     }
   }
 
   if (selection.has("mcp")) {
     const targetHints = selected.filter(
-      (value) => value === "cursor" || value === "claude" || value === "codex"
+      (value) => value === "cursor" || value === "claude"
     );
     const targets = (
-      targetHints.length > 0 ? targetHints : ["cursor", "claude", "codex"]
+      targetHints.length > 0 ? targetHints : ["cursor", "claude"]
     ) as McpTarget[];
 
     const results = await installMcpConfig({
@@ -4420,33 +4412,82 @@ async function maybeSetupAgentIntegrations(opts: {
     });
 
     for (const result of results) {
-      logInstallResult({
-        label: "MCP config",
-        status: result.status,
-        path: result.path ?? "unknown path",
-        message: result.message,
-      });
+      integrationsReady =
+        logInstallResult({
+          label: "MCP config",
+          status: result.status,
+          path: result.path ?? "unknown path",
+          message: result.message,
+        }) && integrationsReady;
     }
   }
+
+  return integrationsReady;
 }
 
-function logInstallResult(opts: {
+async function prepareSelectedAgentPlugin({
+  selected,
+  label,
+  prepare,
+}: {
+  readonly selected: boolean;
+  readonly label: string;
+  readonly prepare: () => Promise<{
+    readonly status: string;
+    readonly cleanupStatus?: string;
+    readonly path: string;
+    readonly message?: string;
+  }>;
+}): Promise<boolean> {
+  if (!selected) {
+    return true;
+  }
+  const result = await prepare();
+  return logInstallResult({
+    label,
+    status: result.status,
+    cleanupStatus: result.cleanupStatus,
+    path: result.path,
+    message: result.message,
+  });
+}
+
+export function logInstallResult(opts: {
   readonly label: string;
   readonly status: string;
+  readonly cleanupStatus?: string;
   readonly path: string;
   readonly message?: string;
-}): void {
-  if (opts.status === "error") {
+}): boolean {
+  const outcome = resolveAgentPluginInstallOutcome({
+    status: opts.status,
+    cleanupStatus: opts.cleanupStatus,
+  });
+  if (outcome === "error") {
     logger.warn({ message: opts.message ?? `Failed to update ${opts.label}` });
-    return;
+    return false;
   }
 
-  if (opts.status === "noop") {
-    logger.info({ message: `No changes for ${opts.label} (${opts.path})` });
-    return;
+  if (outcome === "warning") {
+    logger.warn({
+      message:
+        opts.message ??
+        `${opts.label} is not ready (${opts.status}) at ${opts.path}`,
+    });
+    return false;
   }
 
-  logger.success({ message: `Updated ${opts.label} at ${opts.path}` });
+  if (outcome === "unchanged") {
+    logger.info({
+      message: opts.message ?? `No changes for ${opts.label} (${opts.path})`,
+    });
+    return true;
+  }
+
+  logger.success({
+    message: opts.message ?? `Updated ${opts.label} at ${opts.path}`,
+  });
+  return true;
 }
 
 // Exported for direct unit-testing of the auto (non-interactive) discovery
diff --git a/src/commands/setup.ts b/src/commands/setup.ts
index 594cb3c5..aa13c22a 100644
--- a/src/commands/setup.ts
+++ b/src/commands/setup.ts
@@ -7,20 +7,28 @@ import { isCancel, select, text } from "@clack/prompts";
 const LEADING_NEWLINES_PATTERN = /^\n+/;
 
 import {
-  checkClaudeHooks,
-  installClaudeHooks,
-  removeClaudeHooks,
-} from "../agents/claude.ts";
+  checkDeprecatedHackClaudeIntegration,
+  checkHackClaudePlugin,
+  prepareHackClaudePlugin,
+  removeDeprecatedHackClaudeIntegration,
+} from "../agents/claude-plugin.ts";
 import {
-  checkCodexSkill,
-  installCodexSkill,
-  removeCodexSkill,
-} from "../agents/codex-skill.ts";
+  checkDeprecatedHackCodexIntegration,
+  checkHackCodexPlugin,
+  prepareHackCodexPlugin,
+  removeDeprecatedHackCodexIntegration,
+} from "../agents/codex-plugin.ts";
 import {
-  checkCursorRules,
-  installCursorRules,
-  removeCursorRules,
-} from "../agents/cursor.ts";
+  checkDeprecatedHackCursorIntegration,
+  checkHackCursorPlugin,
+  prepareHackCursorPlugin,
+  removeDeprecatedHackCursorIntegration,
+} from "../agents/cursor-plugin.ts";
+import {
+  type AgentPluginResult,
+  checkNativeAgentPluginCutover,
+  resolveAgentPluginInstallOutcome,
+} from "../agents/plugin-lifecycle.ts";
 import {
   checkDeprecatedSharedHackSkills,
   checkSharedHackSkill,
@@ -176,6 +184,7 @@ type SetupMcpArgs = CommandArgs<typeof setupMcpOptions, readonly []>;
 
 type SetupMultiLogResult = {
   readonly status: string;
+  readonly cleanupStatus?: string;
   readonly path?: string;
   readonly message?: string;
 };
@@ -191,7 +200,7 @@ const tmuxSpec = defineCommand({
 
 const cursorSpec = defineCommand({
   name: "cursor",
-  summary: "Install Cursor rules for hack CLI usage",
+  summary: "Check or prepare the official Hack plugin for Cursor",
   group: "Agents",
   options: setupCursorOptions,
   positionals: [],
@@ -200,7 +209,7 @@ const cursorSpec = defineCommand({
 
 const claudeSpec = defineCommand({
   name: "claude",
-  summary: "Install Claude Code hooks for hack CLI usage",
+  summary: "Check or prepare the official Hack plugin for Claude Code",
   group: "Agents",
   options: setupClaudeOptions,
   positionals: [],
@@ -209,7 +218,7 @@ const claudeSpec = defineCommand({
 
 const codexSpec = defineCommand({
   name: "codex",
-  summary: "Install Codex skill for hack CLI usage",
+  summary: "Check or prepare the official Hack plugin for Codex",
   group: "Agents",
   options: setupCodexOptions,
   positionals: [],
@@ -535,26 +544,13 @@ async function handleSetupCursor({
   readonly ctx: CliContext;
   readonly args: SetupCursorArgs;
 }): Promise<number> {
-  const action = resolveAction(args.options);
-  const scope = resolveScope({ global: args.options.global === true });
-  const projectRoot =
-    scope === "project"
-      ? await resolveSetupRoot({ ctx, pathOpt: args.options.path })
-      : undefined;
-
-  let result: Awaited<ReturnType<typeof checkCursorRules>>;
-  if (action === "check") {
-    result = await checkCursorRules({ scope, projectRoot });
-  } else if (action === "remove") {
-    result = await removeCursorRules({ scope, projectRoot });
-  } else {
-    result = await installCursorRules({ scope, projectRoot });
-  }
-
-  return logSingleResult({
-    action,
-    okMessage: "Cursor integration",
-    result,
+  return await handleNativePluginSetup({
+    ctx,
+    options: args.options,
+    okMessage: "Hack Cursor plugin",
+    check: checkHackCursorPlugin,
+    prepare: prepareHackCursorPlugin,
+    remove: removeDeprecatedHackCursorIntegration,
   });
 }
 
@@ -565,26 +561,13 @@ async function handleSetupClaude({
   readonly ctx: CliContext;
   readonly args: SetupClaudeArgs;
 }): Promise<number> {
-  const action = resolveAction(args.options);
-  const scope = resolveScope({ global: args.options.global === true });
-  const projectRoot =
-    scope === "project"
-      ? await resolveSetupRoot({ ctx, pathOpt: args.options.path })
-      : undefined;
-
-  let result: Awaited<ReturnType<typeof checkClaudeHooks>>;
-  if (action === "check") {
-    result = await checkClaudeHooks({ scope, projectRoot });
-  } else if (action === "remove") {
-    result = await removeClaudeHooks({ scope, projectRoot });
-  } else {
-    result = await installClaudeHooks({ scope, projectRoot });
-  }
-
-  return logSingleResult({
-    action,
-    okMessage: "Claude integration",
-    result,
+  return await handleNativePluginSetup({
+    ctx,
+    options: args.options,
+    okMessage: "Hack Claude Code plugin",
+    check: checkHackClaudePlugin,
+    prepare: prepareHackClaudePlugin,
+    remove: removeDeprecatedHackClaudeIntegration,
   });
 }
 
@@ -595,27 +578,60 @@ async function handleSetupCodex({
   readonly ctx: CliContext;
   readonly args: SetupCodexArgs;
 }): Promise<number> {
-  const action = resolveAction(args.options);
-  const scope = resolveScope({ global: args.options.global === true });
+  return await handleNativePluginSetup({
+    ctx,
+    options: args.options,
+    okMessage: "Hack Codex plugin",
+    check: checkHackCodexPlugin,
+    prepare: prepareHackCodexPlugin,
+    remove: removeDeprecatedHackCodexIntegration,
+  });
+}
+
+async function handleNativePluginSetup({
+  ctx,
+  options,
+  okMessage,
+  check,
+  prepare,
+  remove,
+}: {
+  readonly ctx: CliContext;
+  readonly options: {
+    readonly check: boolean;
+    readonly remove: boolean;
+    readonly global: boolean;
+    readonly path: string | undefined;
+  };
+  readonly okMessage: string;
+  readonly check: (opts: {
+    readonly scope: "project" | "user";
+  }) => Promise<AgentPluginResult<"project" | "user">>;
+  readonly prepare: (opts: {
+    readonly scope: "project" | "user";
+    readonly projectRoot?: string;
+  }) => Promise<AgentPluginResult<"project" | "user">>;
+  readonly remove: (opts: {
+    readonly scope: "project" | "user";
+    readonly projectRoot?: string;
+  }) => Promise<AgentPluginResult<"project" | "user">>;
+}): Promise<number> {
+  const action = resolveAction(options);
+  const scope = resolveScope({ global: options.global });
   const projectRoot =
     scope === "project"
-      ? await resolveSetupRoot({ ctx, pathOpt: args.options.path })
+      ? await resolveSetupRoot({ ctx, pathOpt: options.path })
       : undefined;
 
-  let result: Awaited<ReturnType<typeof checkCodexSkill>>;
+  let result: AgentPluginResult<"project" | "user">;
   if (action === "check") {
-    result = await checkCodexSkill({ scope, projectRoot });
+    result = await check({ scope });
   } else if (action === "remove") {
-    result = await removeCodexSkill({ scope, projectRoot });
+    result = await remove({ scope, projectRoot });
   } else {
-    result = await installCodexSkill({ scope, projectRoot });
+    result = await prepare({ scope, projectRoot });
   }
-
-  return logSingleResult({
-    action,
-    okMessage: "Codex integration",
-    result,
-  });
+  return logSingleResult({ action, okMessage, result });
 }
 
 async function handleSetupTickets({
@@ -712,6 +728,7 @@ type SetupSyncAction = "install" | "check" | "remove";
 type SetupSyncGroup = {
   readonly label: string;
   readonly results: readonly SetupMultiLogResult[];
+  readonly requiresReadyPlugin?: boolean;
 };
 
 type SetupSyncScopeResult = {
@@ -725,16 +742,38 @@ export function buildSetupSyncScopeResult(input: {
   readonly groups: readonly SetupSyncGroup[];
 }): SetupSyncScopeResult {
   const entries = input.groups.flatMap((group) =>
-    group.results.map((result) => ({ ...result, label: group.label }))
+    group.results.map((result) => {
+      const status =
+        input.action === "install" &&
+        result.status === "noop" &&
+        ["removed", "preserved"].includes(result.cleanupStatus ?? "")
+          ? (result.cleanupStatus ?? result.status)
+          : result.status;
+      return {
+        ...result,
+        status,
+        label: group.label,
+        requiresReadyPlugin: group.requiresReadyPlugin === true,
+      };
+    })
   );
   const failures = entries.filter((entry) => {
     if (entry.status === "error") {
       return true;
     }
-    return (
-      input.action === "check" &&
-      ["missing", "stale", "deprecated"].includes(entry.status)
-    );
+    if (input.action === "check") {
+      return ["missing", "stale", "deprecated"].includes(entry.status);
+    }
+    if (input.action === "install") {
+      if (entry.status === "preserved") {
+        return true;
+      }
+      return (
+        entry.requiresReadyPlugin &&
+        ["missing", "stale", "deprecated"].includes(entry.status)
+      );
+    }
+    return entry.status === "preserved";
   });
   const errorCount = failures.filter(
     (entry) => entry.status === "error"
@@ -760,6 +799,9 @@ export function buildSetupSyncScopeResult(input: {
     const changed = entries.filter((entry) =>
       ["created", "updated", "removed"].includes(entry.status)
     ).length;
+    if (failures.length > 0) {
+      return `${entries.length - failures.length}/${entries.length} current`;
+    }
     return changed === 0 ? "already current" : `${changed} updated`;
   })();
   const detail = failures
@@ -836,18 +878,44 @@ async function runProjectScopeSync(opts: {
   readonly projectRoot: string;
 }): Promise<SetupSyncScopeResult> {
   const { action, projectRoot } = opts;
-  let cursorResult: Awaited<ReturnType<typeof checkCursorRules>>;
-  let claudeResult: Awaited<ReturnType<typeof checkClaudeHooks>>;
-  let codexResult: Awaited<ReturnType<typeof checkCodexSkill>>;
+  let cursorResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackCursorIntegration>
+  >;
+  let claudeResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackClaudeIntegration>
+  >;
+  let codexResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackCodexIntegration>
+  >;
   let ticketsResult: TicketsSkillResult;
   let ticketsDocsResults: SetupMultiLogResult[];
-  let mcpResults: SetupMultiLogResult[];
   let docsResults: SetupMultiLogResult[];
 
   if (action === "check") {
-    cursorResult = await checkCursorRules({ scope: "project", projectRoot });
-    claudeResult = await checkClaudeHooks({ scope: "project", projectRoot });
-    codexResult = await checkCodexSkill({ scope: "project", projectRoot });
+    cursorResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackCursorPlugin({ scope: "project" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackCursorIntegration({
+          scope: "project",
+          projectRoot,
+        }),
+    });
+    claudeResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackClaudePlugin({ scope: "project" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackClaudeIntegration({
+          scope: "project",
+          projectRoot,
+        }),
+    });
+    codexResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackCodexPlugin({ scope: "project" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackCodexIntegration({
+          scope: "project",
+          projectRoot,
+        }),
+    });
     ticketsResult = await checkDeprecatedTicketsSkill({
       scope: "project",
       projectRoot,
@@ -856,47 +924,50 @@ async function runProjectScopeSync(opts: {
       projectRoot,
       targets: ["agents", "claude"],
     });
-    mcpResults = await checkMcpConfig({
-      scope: "project",
-      targets: ["cursor", "claude", "codex"],
-      projectRoot,
-    });
     docsResults = await checkAgentDocs({
       projectRoot,
       targets: ["agents", "claude"],
     });
   } else if (action === "remove") {
-    cursorResult = await removeCursorRules({ scope: "project", projectRoot });
-    claudeResult = await removeClaudeHooks({ scope: "project", projectRoot });
-    codexResult = await removeCodexSkill({ scope: "project", projectRoot });
-    ticketsResult = await removeTicketsSkill({ scope: "project", projectRoot });
-    ticketsDocsResults = await removeTicketsAgentDocs({
+    cursorResult = await removeDeprecatedHackCursorIntegration({
+      scope: "project",
       projectRoot,
-      targets: ["agents", "claude"],
     });
-    mcpResults = await removeMcpConfig({
+    claudeResult = await removeDeprecatedHackClaudeIntegration({
       scope: "project",
-      targets: ["cursor", "claude", "codex"],
       projectRoot,
     });
-    docsResults = await removeAgentDocs({
+    codexResult = await removeDeprecatedHackCodexIntegration({
+      scope: "project",
       projectRoot,
-      targets: ["agents", "claude"],
     });
-  } else {
-    cursorResult = await installCursorRules({ scope: "project", projectRoot });
-    claudeResult = await installClaudeHooks({ scope: "project", projectRoot });
-    codexResult = await installCodexSkill({ scope: "project", projectRoot });
     ticketsResult = await removeTicketsSkill({ scope: "project", projectRoot });
     ticketsDocsResults = await removeTicketsAgentDocs({
       projectRoot,
       targets: ["agents", "claude"],
     });
-    mcpResults = await installMcpConfig({
+    docsResults = await removeAgentDocs({
+      projectRoot,
+      targets: ["agents", "claude"],
+    });
+  } else {
+    cursorResult = await prepareHackCursorPlugin({
+      scope: "project",
+      projectRoot,
+    });
+    claudeResult = await prepareHackClaudePlugin({
+      scope: "project",
+      projectRoot,
+    });
+    codexResult = await prepareHackCodexPlugin({
       scope: "project",
-      targets: ["cursor", "claude", "codex"],
       projectRoot,
     });
+    ticketsResult = await removeTicketsSkill({ scope: "project", projectRoot });
+    ticketsDocsResults = await removeTicketsAgentDocs({
+      projectRoot,
+      targets: ["agents", "claude"],
+    });
     docsResults = await upsertAgentDocs({
       projectRoot,
       targets: ["agents", "claude"],
@@ -907,12 +978,32 @@ async function runProjectScopeSync(opts: {
     action,
     scope: "Project",
     groups: [
-      { label: "Cursor", results: [cursorResult] },
-      { label: "Claude", results: [claudeResult] },
-      { label: "Codex", results: [codexResult] },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Cursor plugin"
+            : "Deprecated Cursor integration",
+        results: [cursorResult],
+        requiresReadyPlugin: true,
+      },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Claude Code plugin"
+            : "Deprecated Claude integration",
+        results: [claudeResult],
+        requiresReadyPlugin: true,
+      },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Codex plugin"
+            : "Deprecated Codex integration",
+        results: [codexResult],
+        requiresReadyPlugin: true,
+      },
       { label: "Deprecated Tickets skill", results: [ticketsResult] },
       { label: "Deprecated Tickets instructions", results: ticketsDocsResults },
-      { label: "MCP config", results: mcpResults },
       { label: "Agent docs", results: docsResults },
     ],
   });
@@ -927,60 +1018,89 @@ async function runUserScopeSync(opts: {
   readonly action: SetupSyncAction;
 }): Promise<SetupSyncScopeResult> {
   const { action } = opts;
-  let cursorResult: Awaited<ReturnType<typeof checkCursorRules>>;
-  let claudeResult: Awaited<ReturnType<typeof checkClaudeHooks>>;
-  let codexResult: Awaited<ReturnType<typeof checkCodexSkill>>;
+  let cursorResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackCursorIntegration>
+  >;
+  let claudeResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackClaudeIntegration>
+  >;
+  let codexResult: Awaited<
+    ReturnType<typeof checkDeprecatedHackCodexIntegration>
+  >;
   let ticketsResult: TicketsSkillResult;
   let sharedSkillResult: SetupMultiLogResult & { readonly path: string };
   let legacySharedResults: SetupMultiLogResult[];
-  let mcpResults: SetupMultiLogResult[];
 
   if (action === "check") {
-    cursorResult = await checkCursorRules({ scope: "user" });
-    claudeResult = await checkClaudeHooks({ scope: "user" });
-    codexResult = await checkCodexSkill({ scope: "user" });
+    cursorResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackCursorPlugin({ scope: "user" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackCursorIntegration({ scope: "user" }),
+    });
+    claudeResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackClaudePlugin({ scope: "user" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackClaudeIntegration({ scope: "user" }),
+    });
+    codexResult = await checkNativeAgentPluginCutover({
+      check: async () => await checkHackCodexPlugin({ scope: "user" }),
+      checkLegacy: async () =>
+        await checkDeprecatedHackCodexIntegration({ scope: "user" }),
+    });
     ticketsResult = await checkDeprecatedTicketsSkill({ scope: "user" });
     sharedSkillResult = await checkSharedHackSkill();
     legacySharedResults = await checkDeprecatedSharedHackSkills();
-    mcpResults = await checkMcpConfig({
+  } else if (action === "remove") {
+    cursorResult = await removeDeprecatedHackCursorIntegration({
       scope: "user",
-      targets: ["cursor", "claude", "codex"],
     });
-  } else if (action === "remove") {
-    cursorResult = await removeCursorRules({ scope: "user" });
-    claudeResult = await removeClaudeHooks({ scope: "user" });
-    codexResult = await removeCodexSkill({ scope: "user" });
+    claudeResult = await removeDeprecatedHackClaudeIntegration({
+      scope: "user",
+    });
+    codexResult = await removeDeprecatedHackCodexIntegration({ scope: "user" });
     ticketsResult = await removeTicketsSkill({ scope: "user" });
     sharedSkillResult = await removeSharedHackSkill();
     legacySharedResults = await removeDeprecatedSharedHackSkills();
-    mcpResults = await removeMcpConfig({
-      scope: "user",
-      targets: ["cursor", "claude", "codex"],
-    });
   } else {
-    cursorResult = await installCursorRules({ scope: "user" });
-    claudeResult = await installClaudeHooks({ scope: "user" });
-    codexResult = await installCodexSkill({ scope: "user" });
+    cursorResult = await prepareHackCursorPlugin({ scope: "user" });
+    claudeResult = await prepareHackClaudePlugin({ scope: "user" });
+    codexResult = await prepareHackCodexPlugin({ scope: "user" });
     ticketsResult = await removeTicketsSkill({ scope: "user" });
     sharedSkillResult = await installSharedHackSkill();
     legacySharedResults = await removeDeprecatedSharedHackSkills();
-    mcpResults = await installMcpConfig({
-      scope: "user",
-      targets: ["cursor", "claude", "codex"],
-    });
   }
 
   return buildSetupSyncScopeResult({
     action,
     scope: "Global",
     groups: [
-      { label: "Cursor", results: [cursorResult] },
-      { label: "Claude", results: [claudeResult] },
-      { label: "Codex", results: [codexResult] },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Cursor plugin"
+            : "Deprecated Cursor integration",
+        results: [cursorResult],
+        requiresReadyPlugin: true,
+      },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Claude Code plugin"
+            : "Deprecated Claude integration",
+        results: [claudeResult],
+        requiresReadyPlugin: true,
+      },
+      {
+        label:
+          action !== "remove"
+            ? "Hack Codex plugin"
+            : "Deprecated Codex integration",
+        results: [codexResult],
+        requiresReadyPlugin: true,
+      },
       { label: "Shared Hack skill", results: [sharedSkillResult] },
       { label: "Deprecated Tickets skill", results: [ticketsResult] },
       { label: "Deprecated shared Hack skills", results: legacySharedResults },
-      { label: "MCP config", results: mcpResults },
     ],
   });
 }
@@ -1135,6 +1255,7 @@ function logSingleResult(opts: {
   readonly okMessage: string;
   readonly result: {
     readonly status: string;
+    readonly cleanupStatus?: string;
     readonly path: string;
     readonly message?: string;
   };
@@ -1157,25 +1278,62 @@ function logSingleResult(opts: {
   if (opts.action === "remove") {
     if (opts.result.status === "removed") {
       logger.success({
-        message: `Removed ${opts.okMessage} at ${opts.result.path}`,
+        message:
+          opts.result.message ??
+          `Removed ${opts.okMessage} at ${opts.result.path}`,
       });
       return 0;
     }
     logger.info({
-      message: `No ${opts.okMessage} found at ${opts.result.path}`,
+      message:
+        opts.result.message ??
+        `No ${opts.okMessage} found at ${opts.result.path}`,
     });
     return 0;
   }
 
-  if (opts.result.status === "noop") {
+  if (["missing", "stale", "deprecated"].includes(opts.result.status)) {
+    logger.warn({
+      message:
+        opts.result.message ??
+        `${opts.okMessage} requires attention at ${opts.result.path}`,
+    });
+    return 1;
+  }
+
+  const outcome = resolveAgentPluginInstallOutcome({
+    status: opts.result.status,
+    cleanupStatus: opts.result.cleanupStatus,
+  });
+  if (outcome === "warning") {
+    logger.warn({
+      message:
+        opts.result.message ??
+        `${opts.okMessage} is not ready (${opts.result.status}) at ${opts.result.path}`,
+    });
+    return 1;
+  }
+
+  if (outcome === "unchanged") {
+    if (opts.result.cleanupStatus === "removed") {
+      logger.success({
+        message:
+          opts.result.message ??
+          `Updated ${opts.okMessage} at ${opts.result.path}`,
+      });
+      return 0;
+    }
     logger.info({
-      message: `No changes for ${opts.okMessage} (${opts.result.path})`,
+      message:
+        opts.result.message ??
+        `No changes for ${opts.okMessage} (${opts.result.path})`,
     });
     return 0;
   }
 
   logger.success({
-    message: `Updated ${opts.okMessage} at ${opts.result.path}`,
+    message:
+      opts.result.message ?? `Updated ${opts.okMessage} at ${opts.result.path}`,
   });
   return 0;
 }
@@ -1196,7 +1354,9 @@ function logCheckResult(opts: {
   }
   if (opts.result.status === "missing") {
     logger.warn({
-      message: `${opts.okMessage} not installed at ${opts.path}`,
+      message:
+        opts.result.message ??
+        `${opts.okMessage} not installed at ${opts.path}`,
     });
     return 1;
   }
diff --git a/src/mcp/install.ts b/src/mcp/install.ts
index 75f73c40..dce972c7 100644
--- a/src/mcp/install.ts
+++ b/src/mcp/install.ts
@@ -1,10 +1,11 @@
+import { unlink } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
 import { ensureDir, readTextFile, writeTextFileIfChanged } from "../lib/fs.ts";
 import { isRecord } from "../lib/guards.ts";
 
 const CODEX_SERVER_BLOCK_PATTERN =
-  /^\s*\[mcp_servers\.hack\][\s\S]*?(?=^\s*\[|\s*$)/m;
+  /^[ \t]*\[mcp_servers\.hack\][ \t]*(?:\r?\n(?![ \t]*\[)[^\r\n]*)*(?:\r?\n)?/m;
 const CODEX_SERVER_HEADER_PATTERN = /^\s*\[mcp_servers\.hack\]\s*$/m;
 
 export type McpTarget = "claude" | "codex" | "cursor";
@@ -34,6 +35,22 @@ export type McpRemoveResult = {
   readonly message?: string;
 };
 
+export type DeprecatedCodexMcpResult = {
+  readonly target: "codex";
+  readonly scope: McpInstallScope;
+  readonly status: "deprecated" | "absent" | "removed" | "preserved" | "error";
+  readonly path?: string;
+  readonly message?: string;
+};
+
+export type DeprecatedPluginMcpResult = {
+  readonly target: "claude" | "cursor";
+  readonly scope: McpInstallScope;
+  readonly status: "deprecated" | "absent" | "removed" | "preserved" | "error";
+  readonly path?: string;
+  readonly message?: string;
+};
+
 export type McpConfigSnippet =
   | {
       readonly ok: true;
@@ -205,6 +222,208 @@ export async function removeMcpConfig(opts: {
   return results;
 }
 
+/** Report standalone Codex MCP config superseded by the Hack plugin. */
+export async function checkDeprecatedCodexMcpConfig(opts: {
+  readonly scope: McpInstallScope;
+  readonly projectRoot?: string;
+}): Promise<DeprecatedCodexMcpResult> {
+  const resolved = resolveConfigPath({ target: "codex", ...opts });
+  if (!resolved.ok) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "error",
+      message: resolved.message,
+    };
+  }
+  const text = await readTextFile(resolved.path);
+  if (!(text && hasCodexServerBlock(text))) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "absent",
+      path: resolved.path,
+    };
+  }
+  return {
+    target: "codex",
+    scope: opts.scope,
+    status: "deprecated",
+    path: resolved.path,
+    message:
+      "Standalone Hack MCP config for Codex is deprecated; the Hack plugin bundles this server.",
+  };
+}
+
+/** Remove a standalone Codex MCP block only when it matches Hack's renderer. */
+export async function removeDeprecatedCodexMcpConfig(opts: {
+  readonly scope: McpInstallScope;
+  readonly projectRoot?: string;
+}): Promise<DeprecatedCodexMcpResult> {
+  const resolved = resolveConfigPath({ target: "codex", ...opts });
+  if (!resolved.ok) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "error",
+      message: resolved.message,
+    };
+  }
+  const text = await readTextFile(resolved.path);
+  if (!text) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "absent",
+      path: resolved.path,
+    };
+  }
+  const block = text.match(CODEX_SERVER_BLOCK_PATTERN)?.[0];
+  if (!block) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "absent",
+      path: resolved.path,
+    };
+  }
+  if (block.trim() !== renderCodexTomlBlock()) {
+    return {
+      target: "codex",
+      scope: opts.scope,
+      status: "preserved",
+      path: resolved.path,
+      message: "Preserved user-modified standalone Hack MCP config for Codex.",
+    };
+  }
+  const next = text.replace(CODEX_SERVER_BLOCK_PATTERN, "").trimEnd();
+  const normalized = next.length === 0 ? "" : `${next}\n`;
+  const result = await writeTextFileIfChanged(resolved.path, normalized);
+  return {
+    target: "codex",
+    scope: opts.scope,
+    status: result.changed ? "removed" : "absent",
+    path: resolved.path,
+  };
+}
+
+/** Report standalone Claude/Cursor MCP config superseded by a native plugin. */
+export async function checkDeprecatedPluginMcpConfig(opts: {
+  readonly target: "claude" | "cursor";
+  readonly scope: McpInstallScope;
+  readonly projectRoot?: string;
+}): Promise<DeprecatedPluginMcpResult> {
+  const resolved = resolveConfigPath(opts);
+  if (!resolved.ok) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "error",
+      message: resolved.message,
+    };
+  }
+  const parsed = await readMcpJsonConfig({ path: resolved.path });
+  if (!parsed.ok) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: parsed.status,
+      path: resolved.path,
+      message: parsed.message,
+    };
+  }
+  if (!Object.hasOwn(parsed.mcpServers, SERVER_NAME)) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "absent",
+      path: resolved.path,
+    };
+  }
+  return {
+    target: opts.target,
+    scope: opts.scope,
+    status: "deprecated",
+    path: resolved.path,
+    message: `Standalone Hack MCP config for ${formatTarget(opts.target)} is deprecated; the Hack plugin bundles this server.`,
+  };
+}
+
+/** Remove only generated standalone Claude/Cursor MCP entries. */
+export async function removeDeprecatedPluginMcpConfig(opts: {
+  readonly target: "claude" | "cursor";
+  readonly scope: McpInstallScope;
+  readonly projectRoot?: string;
+}): Promise<DeprecatedPluginMcpResult> {
+  const resolved = resolveConfigPath(opts);
+  if (!resolved.ok) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "error",
+      message: resolved.message,
+    };
+  }
+  const parsed = await readMcpJsonConfig({ path: resolved.path });
+  if (!parsed.ok) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: parsed.status,
+      path: resolved.path,
+      message: parsed.message,
+    };
+  }
+  const existing = parsed.mcpServers[SERVER_NAME];
+  if (existing === undefined) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "absent",
+      path: resolved.path,
+    };
+  }
+  const expected =
+    opts.target === "claude" ? buildClaudeEntry() : buildCursorEntry();
+  if (JSON.stringify(existing) !== JSON.stringify(expected)) {
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "preserved",
+      path: resolved.path,
+      message: `Preserved user-modified standalone Hack MCP config for ${formatTarget(opts.target)}.`,
+    };
+  }
+
+  const mcpServers = { ...parsed.mcpServers };
+  delete mcpServers[SERVER_NAME];
+  const next = { ...parsed.value };
+  if (Object.keys(mcpServers).length === 0) {
+    next.mcpServers = undefined;
+  } else {
+    next.mcpServers = mcpServers;
+  }
+  if (Object.values(next).every((value) => value === undefined)) {
+    await unlink(resolved.path);
+    return {
+      target: opts.target,
+      scope: opts.scope,
+      status: "removed",
+      path: resolved.path,
+    };
+  }
+  const result = await writeTextFileIfChanged(
+    resolved.path,
+    `${JSON.stringify(next, null, 2)}\n`
+  );
+  return {
+    target: opts.target,
+    scope: opts.scope,
+    status: result.changed ? "removed" : "absent",
+    path: resolved.path,
+  };
+}
+
 export function renderMcpConfigSnippet(opts: {
   readonly target: McpTarget;
   readonly scope: McpInstallScope;
@@ -443,6 +662,39 @@ function parseJsonObject(text: string):
   }
 }
 
+async function readMcpJsonConfig(opts: { readonly path: string }): Promise<
+  | {
+      readonly ok: true;
+      readonly value: Record<string, unknown>;
+      readonly mcpServers: Record<string, unknown>;
+    }
+  | {
+      readonly ok: false;
+      readonly status: "absent" | "error";
+      readonly message?: string;
+    }
+> {
+  const text = await readTextFile(opts.path);
+  if (!text) {
+    return { ok: false, status: "absent" };
+  }
+  const parsed = parseJsonObject(text);
+  if (!parsed.ok) {
+    return { ok: false, status: "error", message: parsed.message };
+  }
+  return {
+    ok: true,
+    value: parsed.value,
+    mcpServers: isRecord(parsed.value.mcpServers)
+      ? parsed.value.mcpServers
+      : {},
+  };
+}
+
+function formatTarget(target: "claude" | "cursor"): string {
+  return target === "claude" ? "Claude Code" : "Cursor";
+}
+
 function createOkParseResult(opts: {
   readonly value: Record<string, unknown>;
 }): {
diff --git a/tests/agent-instruction-source.test.ts b/tests/agent-instruction-source.test.ts
index 201dd1bb..c15b1dc1 100644
--- a/tests/agent-instruction-source.test.ts
+++ b/tests/agent-instruction-source.test.ts
@@ -3,11 +3,7 @@ import { createHash } from "node:crypto";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import {
-  checkCodexSkill,
-  installCodexSkill,
-  renderCodexSkill,
-} from "../src/agents/codex-skill.ts";
+import { renderCodexSkill } from "../src/agents/codex-skill.ts";
 import {
   checkCursorRules,
   installCursorRules,
@@ -226,25 +222,15 @@ test("checkCursorRules detects content drift as stale", async () => {
   expect(stale.status).toBe("stale");
 });
 
-test("checkCodexSkill detects content drift as stale", async () => {
-  const repoRoot = await setupTempRepo();
-  await installCodexSkill({ scope: "project", projectRoot: repoRoot });
-
-  const fresh = await checkCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(fresh.status).toBe("noop");
-
-  const skillPath = join(repoRoot, ".codex", "skills", "hack-cli", "SKILL.md");
-  const content = await Bun.file(skillPath).text();
-  await Bun.write(
-    skillPath,
-    content.replace("## Standard workflow", "## Old workflow")
+test("bundled Codex skill matches the canonical renderer", async () => {
+  const skillPath = join(
+    import.meta.dir,
+    "..",
+    "plugins",
+    "hack",
+    "skills",
+    "hack-cli",
+    "SKILL.md"
   );
-  const stale = await checkCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(stale.status).toBe("stale");
+  expect(await Bun.file(skillPath).text()).toBe(renderCodexSkill());
 });
diff --git a/tests/agent-plugin-cutover.test.ts b/tests/agent-plugin-cutover.test.ts
new file mode 100644
index 00000000..216cf211
--- /dev/null
+++ b/tests/agent-plugin-cutover.test.ts
@@ -0,0 +1,479 @@
+import { afterEach, expect, test } from "bun:test";
+import { chmod, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { installClaudeHooks } from "../src/agents/claude.ts";
+import { prepareHackClaudePlugin } from "../src/agents/claude-plugin.ts";
+import { prepareHackCodexPlugin } from "../src/agents/codex-plugin.ts";
+import { renderCodexSkill } from "../src/agents/codex-skill.ts";
+import { installCursorRules } from "../src/agents/cursor.ts";
+import { prepareHackCursorPlugin } from "../src/agents/cursor-plugin.ts";
+import type { AgentPluginResult } from "../src/agents/plugin-lifecycle.ts";
+import { runCli } from "../src/cli/run.ts";
+import { logInstallResult } from "../src/commands/project.ts";
+import { installMcpConfig } from "../src/mcp/install.ts";
+
+type PluginState = "missing" | "disabled" | "enabled";
+type Scope = "project" | "user";
+type LegacyKind = "generated" | "customized-primary" | "customized-mcp";
+
+type LegacyArtifacts = {
+  readonly primaryPath: string;
+  readonly mcpPath: string;
+};
+
+type CutoverAdapter = {
+  readonly name: string;
+  readonly mcpMarker: string;
+  readonly installLegacy: (opts: {
+    readonly root: string;
+    readonly scope: Scope;
+  }) => Promise<LegacyArtifacts>;
+  readonly customizeMcp: (opts: { readonly path: string }) => Promise<void>;
+  readonly prepare: (opts: {
+    readonly root: string;
+    readonly scope: Scope;
+    readonly state: PluginState;
+  }) => Promise<AgentPluginResult<Scope>>;
+  readonly hasCompleteLegacyIntegration: (opts: {
+    readonly root: string;
+    readonly scope: Scope;
+  }) => Promise<boolean>;
+};
+
+const adapters: readonly CutoverAdapter[] = [
+  {
+    name: "cursor",
+    mcpMarker: '"hack"',
+    installLegacy: async ({ root, scope }) => {
+      await installCursorRules({
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+      });
+      await installMcpConfig({
+        targets: ["cursor"],
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+      });
+      return {
+        primaryPath: join(root, ".cursor", "rules", "hack.mdc"),
+        mcpPath: join(root, ".cursor", "mcp.json"),
+      };
+    },
+    customizeMcp: customizeJsonMcp,
+    prepare: async ({ root, scope, state }) =>
+      await prepareHackCursorPlugin({
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+        runCursorCommand: async () => ({
+          exitCode: 0,
+          stdout: JSON.stringify(
+            state === "missing"
+              ? []
+              : [{ id: "hack@hack-dance", enabled: state === "enabled" }]
+          ),
+          stderr: "",
+        }),
+      }),
+    hasCompleteLegacyIntegration: async ({ root }) => {
+      const rulePath = join(root, ".cursor", "rules", "hack.mdc");
+      const mcpPath = join(root, ".cursor", "mcp.json");
+      return (
+        (await Bun.file(rulePath).exists()) &&
+        (await fileContains({ path: mcpPath, text: '"hack"' }))
+      );
+    },
+  },
+  {
+    name: "claude",
+    mcpMarker: '"hack"',
+    installLegacy: async ({ root, scope }) => {
+      await installClaudeHooks({
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+      });
+      await installMcpConfig({
+        targets: ["claude"],
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+      });
+      return {
+        primaryPath: join(root, ".claude", "skills", "hack-init", "SKILL.md"),
+        mcpPath: join(root, ".claude", "settings.json"),
+      };
+    },
+    customizeMcp: customizeJsonMcp,
+    prepare: async ({ root, scope, state }) =>
+      await prepareHackClaudePlugin({
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+        runClaudeCommand: async () => ({
+          exitCode: 0,
+          stdout: JSON.stringify(
+            state === "missing"
+              ? []
+              : [{ id: "hack@hack-dance", enabled: state === "enabled" }]
+          ),
+          stderr: "",
+        }),
+      }),
+    hasCompleteLegacyIntegration: async ({ root, scope }) => {
+      const skillPath = join(
+        root,
+        ".claude",
+        "skills",
+        "hack-init",
+        "SKILL.md"
+      );
+      const hooksPath = join(
+        root,
+        ".claude",
+        scope === "user" ? "settings.json" : "settings.local.json"
+      );
+      const mcpPath = join(root, ".claude", "settings.json");
+      return (
+        (await Bun.file(skillPath).exists()) &&
+        (await fileContains({ path: hooksPath, text: "hack agent prime" })) &&
+        (await fileContains({ path: mcpPath, text: '"hack"' }))
+      );
+    },
+  },
+  {
+    name: "codex",
+    mcpMarker: "mcp_servers.hack",
+    installLegacy: async ({ root, scope }) => {
+      const skillPath = join(root, ".codex", "skills", "hack-cli", "SKILL.md");
+      await mkdir(dirname(skillPath), { recursive: true });
+      await Bun.write(skillPath, renderCodexSkill());
+      await installMcpConfig({
+        targets: ["codex"],
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+      });
+      return {
+        primaryPath: skillPath,
+        mcpPath: join(root, ".codex", "config.toml"),
+      };
+    },
+    customizeMcp: async ({ path }) => {
+      const content = await Bun.file(path).text();
+      await Bun.write(
+        path,
+        content.replace('command = "hack"', 'command = "custom-hack"')
+      );
+    },
+    prepare: async ({ root, scope, state }) =>
+      await prepareHackCodexPlugin({
+        scope,
+        projectRoot: scope === "project" ? root : undefined,
+        runCodexCommand: async () => ({
+          exitCode: 0,
+          stdout: JSON.stringify({
+            installed:
+              state === "missing"
+                ? []
+                : [
+                    {
+                      name: "hack",
+                      marketplaceName: "hack-dance",
+                      installed: true,
+                      enabled: state === "enabled",
+                    },
+                  ],
+          }),
+          stderr: "",
+        }),
+      }),
+    hasCompleteLegacyIntegration: async ({ root }) => {
+      const skillPath = join(root, ".codex", "skills", "hack-cli", "SKILL.md");
+      const mcpPath = join(root, ".codex", "config.toml");
+      return (
+        (await Bun.file(skillPath).exists()) &&
+        (await fileContains({ path: mcpPath, text: "mcp_servers.hack" }))
+      );
+    },
+  },
+];
+
+let tempDir: string | null = null;
+const originalHome = process.env.HOME;
+const originalPath = process.env.PATH;
+const originalHackHome = process.env.HACK_HOME;
+const originalNoInteractive = process.env.HACK_NO_INTERACTIVE;
+const originalSyncMode = process.env.HACK_SETUP_SYNC_MODE;
+
+afterEach(async () => {
+  process.env.HOME = originalHome;
+  restoreEnv({ key: "PATH", value: originalPath });
+  restoreEnv({ key: "HACK_HOME", value: originalHackHome });
+  restoreEnv({ key: "HACK_NO_INTERACTIVE", value: originalNoInteractive });
+  restoreEnv({ key: "HACK_SETUP_SYNC_MODE", value: originalSyncMode });
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+test("direct setup commands reject preserved customizations for every client and scope", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-plugin-setup-command-"));
+  const binDir = await installReadyPluginStubs({ root: tempDir });
+  process.env.PATH = [binDir, originalPath].filter(Boolean).join(delimiter);
+  process.env.HACK_NO_INTERACTIVE = "1";
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+
+  for (const adapter of adapters) {
+    for (const scope of ["project", "user"] as const) {
+      for (const kind of ["customized-primary", "customized-mcp"] as const) {
+        const root = join(tempDir, "commands", adapter.name, scope, kind);
+        await mkdir(root, { recursive: true });
+        process.env.HOME = root;
+        process.env.HACK_HOME = join(root, ".hack-home");
+        const artifacts = await adapter.installLegacy({ root, scope });
+        const customizedPath =
+          kind === "customized-primary"
+            ? artifacts.primaryPath
+            : artifacts.mcpPath;
+        if (kind === "customized-primary") {
+          const content = await Bun.file(customizedPath).text();
+          await Bun.write(customizedPath, `${content}\nUser customization\n`);
+        } else {
+          await adapter.customizeMcp({ path: customizedPath });
+        }
+        const customizedBytes = await Bun.file(customizedPath).bytes();
+
+        const exitCode = await runCli([
+          "setup",
+          adapter.name,
+          ...(scope === "project" ? ["--path", root] : ["--global"]),
+        ]);
+        const context = `${adapter.name}/${scope}/${kind}`;
+        expect(exitCode, context).toBe(1);
+        if (kind === "customized-primary") {
+          expect(await Bun.file(customizedPath).bytes(), context).toEqual(
+            customizedBytes
+          );
+        } else {
+          expect(
+            await fileContains({ path: customizedPath, text: "custom-hack" }),
+            context
+          ).toBe(true);
+        }
+      }
+    }
+  }
+});
+
+test("setup sync rejects preserved customizations for every client and scope", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-plugin-sync-command-"));
+  const binDir = await installReadyPluginStubs({ root: tempDir });
+  process.env.PATH = [binDir, originalPath].filter(Boolean).join(delimiter);
+  process.env.HACK_NO_INTERACTIVE = "1";
+  process.env.HACK_SETUP_SYNC_MODE = "off";
+
+  for (const kind of ["customized-primary", "customized-mcp"] as const) {
+    const caseRoot = join(tempDir, kind);
+    const projectRoot = join(caseRoot, "repo");
+    const userRoot = join(caseRoot, "home");
+    await mkdir(projectRoot, { recursive: true });
+    await mkdir(userRoot, { recursive: true });
+    process.env.HOME = userRoot;
+    process.env.HACK_HOME = join(userRoot, ".hack-home");
+
+    const customizedArtifacts: Array<{
+      readonly path: string;
+      readonly content: string;
+    }> = [];
+    for (const adapter of adapters) {
+      for (const scope of ["project", "user"] as const) {
+        const root = scope === "project" ? projectRoot : userRoot;
+        const artifacts = await adapter.installLegacy({ root, scope });
+        const path =
+          kind === "customized-primary"
+            ? artifacts.primaryPath
+            : artifacts.mcpPath;
+        if (kind === "customized-primary") {
+          const content = await Bun.file(path).text();
+          await Bun.write(path, `${content}\nUser customization\n`);
+        } else {
+          await adapter.customizeMcp({ path });
+        }
+        customizedArtifacts.push({
+          path,
+          content: await Bun.file(path).text(),
+        });
+      }
+    }
+
+    const exitCode = await runCli([
+      "setup",
+      "sync",
+      "--all-scopes",
+      "--path",
+      projectRoot,
+    ]);
+    expect(exitCode, kind).toBe(1);
+    for (const artifact of customizedArtifacts) {
+      if (kind === "customized-primary") {
+        expect(await Bun.file(artifact.path).text(), artifact.path).toBe(
+          artifact.content
+        );
+      } else {
+        expect(
+          await fileContains({ path: artifact.path, text: "custom-hack" }),
+          artifact.path
+        ).toBe(true);
+      }
+    }
+  }
+});
+
+test("interactive init treats preserved plugin cleanup as incomplete", () => {
+  expect(
+    logInstallResult({
+      label: "Hack Codex plugin",
+      status: "noop",
+      cleanupStatus: "preserved",
+      path: "/repo/.codex/config.toml",
+      message: "Preserved customized MCP config.",
+    })
+  ).toBe(false);
+});
+
+test("native plugin cutover preserves legacy integrations until readiness", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-plugin-cutover-"));
+
+  for (const adapter of adapters) {
+    for (const state of ["missing", "disabled", "enabled"] as const) {
+      for (const scope of ["project", "user"] as const) {
+        for (const kind of [
+          "generated",
+          "customized-primary",
+          "customized-mcp",
+        ] as const satisfies readonly LegacyKind[]) {
+          const root = join(tempDir, adapter.name, state, scope, kind);
+          await mkdir(root, { recursive: true });
+          process.env.HOME = root;
+          const artifacts = await adapter.installLegacy({ root, scope });
+          if (kind === "customized-primary") {
+            const content = await Bun.file(artifacts.primaryPath).text();
+            await Bun.write(
+              artifacts.primaryPath,
+              `${content}\nUser customization\n`
+            );
+          } else if (kind === "customized-mcp") {
+            await adapter.customizeMcp({ path: artifacts.mcpPath });
+          }
+
+          const result = await adapter.prepare({ root, scope, state });
+          const context = `${adapter.name}/${state}/${scope}/${kind}`;
+          if (state !== "enabled") {
+            expect(result.status, context).toBe(
+              state === "missing" ? "missing" : "stale"
+            );
+            expect(result.cleanupStatus, context).toBeUndefined();
+            expect(
+              await adapter.hasCompleteLegacyIntegration({ root, scope }),
+              context
+            ).toBe(true);
+            continue;
+          }
+
+          expect(result.status, context).toBe("noop");
+          expect(result.cleanupStatus, context).toBe(
+            kind === "generated" ? "removed" : "preserved"
+          );
+          expect(await Bun.file(artifacts.primaryPath).exists(), context).toBe(
+            kind === "customized-primary"
+          );
+          expect(
+            await fileContains({
+              path: artifacts.mcpPath,
+              text: adapter.mcpMarker,
+            }),
+            context
+          ).toBe(kind === "customized-mcp");
+          expect(
+            await adapter.hasCompleteLegacyIntegration({ root, scope }),
+            context
+          ).toBe(false);
+        }
+      }
+    }
+  }
+});
+
+async function customizeJsonMcp({ path }: { readonly path: string }) {
+  const config = (await Bun.file(path).json()) as {
+    mcpServers: Record<string, { command: string }>;
+  };
+  config.mcpServers.hack = { command: "custom-hack" };
+  await Bun.write(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+async function installReadyPluginStubs({
+  root,
+}: {
+  readonly root: string;
+}): Promise<string> {
+  const binDir = join(root, "bin");
+  await mkdir(binDir, { recursive: true });
+  const clients = [
+    {
+      name: "cursor-agent",
+      output: [{ id: "hack@hack-dance", enabled: true }],
+    },
+    {
+      name: "claude",
+      output: [{ id: "hack@hack-dance", enabled: true }],
+    },
+    {
+      name: "codex",
+      output: {
+        installed: [
+          {
+            name: "hack",
+            marketplaceName: "hack-dance",
+            installed: true,
+            enabled: true,
+          },
+        ],
+      },
+    },
+  ] as const;
+  for (const client of clients) {
+    const path = join(binDir, client.name);
+    await Bun.write(
+      path,
+      `#!/bin/sh\nprintf '%s\\n' '${JSON.stringify(client.output)}'\n`
+    );
+    await chmod(path, 0o755);
+  }
+  return binDir;
+}
+
+function restoreEnv({
+  key,
+  value,
+}: {
+  readonly key: string;
+  readonly value: string | undefined;
+}): void {
+  if (value === undefined) {
+    Reflect.deleteProperty(process.env, key);
+    return;
+  }
+  process.env[key] = value;
+}
+
+async function fileContains({
+  path,
+  text,
+}: {
+  readonly path: string;
+  readonly text: string;
+}): Promise<boolean> {
+  if (!(await Bun.file(path).exists())) {
+    return false;
+  }
+  return (await Bun.file(path).text()).includes(text);
+}
diff --git a/tests/agent-plugin-generation.test.ts b/tests/agent-plugin-generation.test.ts
new file mode 100644
index 00000000..3b929007
--- /dev/null
+++ b/tests/agent-plugin-generation.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { generateAgentPlugins } from "../scripts/generate-agent-plugins.ts";
+
+let tempDir: string | null = null;
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+test("release generation applies the requested version to every client manifest", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-agent-plugins-"));
+  const pluginRoot = join(tempDir, "plugins", "hack");
+  const manifestDirectories = [
+    ".codex-plugin",
+    ".claude-plugin",
+    ".cursor-plugin",
+  ] as const;
+
+  for (const manifestDirectory of manifestDirectories) {
+    const directory = join(pluginRoot, manifestDirectory);
+    await mkdir(directory, { recursive: true });
+    await Bun.write(
+      join(directory, "plugin.json"),
+      JSON.stringify({ name: "hack", version: "0.0.0" })
+    );
+  }
+
+  await generateAgentPlugins({ repoRoot: tempDir, version: "9.8.7" });
+
+  for (const manifestDirectory of manifestDirectories) {
+    const manifest = await Bun.file(
+      join(pluginRoot, manifestDirectory, "plugin.json")
+    ).json();
+    expect(manifest.version).toBe("9.8.7");
+  }
+});
+
+test("semantic-release commits all generated client manifests", async () => {
+  const releaseConfig = await Bun.file(
+    join(import.meta.dir, "..", ".releaserc.json")
+  ).json();
+  const gitPlugin = releaseConfig.plugins.find(
+    (plugin: unknown) =>
+      Array.isArray(plugin) && plugin[0] === "@semantic-release/git"
+  );
+  expect(gitPlugin).toBeDefined();
+  const assets = gitPlugin?.[1]?.assets as string[];
+  expect(assets).toContain("plugins/hack/.codex-plugin/plugin.json");
+  expect(assets).toContain("plugins/hack/.claude-plugin/plugin.json");
+  expect(assets).toContain("plugins/hack/.cursor-plugin/plugin.json");
+});
diff --git a/tests/claude-plugin.test.ts b/tests/claude-plugin.test.ts
new file mode 100644
index 00000000..7973e60c
--- /dev/null
+++ b/tests/claude-plugin.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { installClaudeHooks } from "../src/agents/claude.ts";
+import {
+  checkDeprecatedHackClaudeIntegration,
+  checkHackClaudePlugin,
+  prepareHackClaudePlugin,
+  removeDeprecatedHackClaudeIntegration,
+} from "../src/agents/claude-plugin.ts";
+import { installMcpConfig } from "../src/mcp/install.ts";
+
+let tempDir: string | null = null;
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+test("checkHackClaudePlugin detects enabled, disabled, and missing states", async () => {
+  const enabled = await checkHackClaudePlugin({
+    scope: "user",
+    runClaudeCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify([
+        { id: "hack@hack-dance", enabled: true, scope: "user" },
+      ]),
+      stderr: "",
+    }),
+  });
+  expect(enabled.status).toBe("noop");
+
+  const disabled = await checkHackClaudePlugin({
+    scope: "user",
+    runClaudeCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify([{ id: "hack@hack-dance", enabled: false }]),
+      stderr: "",
+    }),
+  });
+  expect(disabled.status).toBe("stale");
+
+  const missing = await checkHackClaudePlugin({
+    scope: "user",
+    runClaudeCommand: async () => ({
+      exitCode: 0,
+      stdout: "[]",
+      stderr: "",
+    }),
+  });
+  expect(missing.status).toBe("missing");
+  expect(missing.message).toContain(
+    "claude plugin marketplace add hack-dance/hack"
+  );
+});
+
+test("Claude plugin migration removes generated hooks, skill, and MCP", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-claude-plugin-"));
+  await installClaudeHooks({ scope: "project", projectRoot: tempDir });
+  await installMcpConfig({
+    targets: ["claude"],
+    scope: "project",
+    projectRoot: tempDir,
+  });
+
+  const result = await removeDeprecatedHackClaudeIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(result.status).toBe("removed");
+  expect(
+    await Bun.file(
+      join(tempDir, ".claude", "skills", "hack-init", "SKILL.md")
+    ).exists()
+  ).toBe(false);
+
+  const localSettings = await Bun.file(
+    join(tempDir, ".claude", "settings.local.json")
+  ).json();
+  expect(localSettings.hooks.SessionStart).toEqual([]);
+  expect(
+    await Bun.file(join(tempDir, ".claude", "settings.json")).exists()
+  ).toBe(false);
+});
+
+test("Claude plugin migration detects and removes a partial legacy hook install", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-claude-plugin-"));
+  const settingsPath = join(tempDir, ".claude", "settings.local.json");
+  await mkdir(join(tempDir, ".claude"), { recursive: true });
+  await Bun.write(
+    settingsPath,
+    JSON.stringify({
+      hooks: {
+        SessionStart: [
+          { hooks: [{ type: "command", command: "hack agent prime" }] },
+        ],
+      },
+    })
+  );
+
+  const deprecated = await checkDeprecatedHackClaudeIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(deprecated.status).toBe("deprecated");
+
+  const removed = await removeDeprecatedHackClaudeIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(removed.status).toBe("removed");
+  const settings = await Bun.file(settingsPath).json();
+  expect(settings.hooks.SessionStart).toEqual([]);
+});
+
+test("Claude preparation preserves legacy hooks when the plugin is missing", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-claude-plugin-"));
+  await installClaudeHooks({ scope: "project", projectRoot: tempDir });
+
+  const result = await prepareHackClaudePlugin({
+    scope: "project",
+    projectRoot: tempDir,
+    runClaudeCommand: async () => ({ exitCode: 0, stdout: "[]", stderr: "" }),
+  });
+  expect(result.status).toBe("missing");
+  expect(result.cleanupStatus).toBeUndefined();
+  expect(result.message).toContain("not installed");
+  expect(
+    await Bun.file(join(tempDir, ".claude", "settings.local.json")).exists()
+  ).toBe(true);
+});
+
+test("Claude plugin manifests match the CLI package version", async () => {
+  const repoRoot = join(import.meta.dir, "..");
+  const packageJson = await Bun.file(join(repoRoot, "package.json")).json();
+  const manifest = await Bun.file(
+    join(repoRoot, "plugins", "hack", ".claude-plugin", "plugin.json")
+  ).json();
+  expect(manifest.version).toBe(packageJson.version);
+});
diff --git a/tests/codex-plugin.test.ts b/tests/codex-plugin.test.ts
new file mode 100644
index 00000000..9a6334e7
--- /dev/null
+++ b/tests/codex-plugin.test.ts
@@ -0,0 +1,177 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  checkDeprecatedCodexSkills,
+  checkDeprecatedHackCodexIntegration,
+  checkHackCodexPlugin,
+  prepareHackCodexPlugin,
+  removeDeprecatedCodexSkills,
+  removeDeprecatedHackCodexIntegration,
+} from "../src/agents/codex-plugin.ts";
+import { renderCodexSkill } from "../src/agents/codex-skill.ts";
+import { renderHackInitSkill } from "../src/agents/hack-init-skill.ts";
+import { installMcpConfig } from "../src/mcp/install.ts";
+
+let tempDir: string | null = null;
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+test("checkHackCodexPlugin detects enabled, disabled, and missing states", async () => {
+  const runCodexCommand = async () => ({
+    exitCode: 0,
+    stdout: JSON.stringify({
+      installed: [
+        {
+          name: "hack",
+          marketplaceName: "hack-dance",
+          installed: true,
+          enabled: true,
+        },
+      ],
+    }),
+    stderr: "",
+  });
+  const enabled = await checkHackCodexPlugin({
+    scope: "user",
+    runCodexCommand,
+  });
+  expect(enabled.status).toBe("noop");
+
+  const disabled = await checkHackCodexPlugin({
+    scope: "user",
+    runCodexCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify({
+        installed: [
+          {
+            name: "hack",
+            marketplaceName: "hack-dance",
+            installed: true,
+            enabled: false,
+          },
+        ],
+      }),
+      stderr: "",
+    }),
+  });
+  expect(disabled.status).toBe("stale");
+
+  const missing = await checkHackCodexPlugin({
+    scope: "user",
+    runCodexCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify({ installed: [] }),
+      stderr: "",
+    }),
+  });
+  expect(missing.status).toBe("missing");
+  expect(missing.message).toContain(
+    "codex plugin marketplace add hack-dance/hack"
+  );
+});
+
+test("legacy cleanup removes generated skills and preserves edited copies", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-codex-plugin-"));
+  const cliPath = join(tempDir, ".codex", "skills", "hack-cli", "SKILL.md");
+  const initPath = join(tempDir, ".codex", "skills", "hack-init", "SKILL.md");
+  await Bun.write(cliPath, renderCodexSkill());
+  await Bun.write(
+    initPath,
+    renderHackInitSkill().replace("hack agent onboard", "custom onboard")
+  );
+
+  const deprecated = await checkDeprecatedCodexSkills({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(deprecated.status).toBe("deprecated");
+
+  const cleanup = await removeDeprecatedCodexSkills({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(cleanup.status).toBe("removed");
+  expect(await Bun.file(cliPath).exists()).toBe(false);
+  expect(await Bun.file(initPath).exists()).toBe(true);
+  expect(cleanup.message).toContain("Preserved user-modified");
+});
+
+test("legacy integration cleanup removes generated skills and Codex MCP config", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-codex-plugin-"));
+  const skillPath = join(tempDir, ".codex", "skills", "hack-cli", "SKILL.md");
+  const configPath = join(tempDir, ".codex", "config.toml");
+  await Bun.write(skillPath, renderCodexSkill());
+  await installMcpConfig({
+    targets: ["codex"],
+    scope: "project",
+    projectRoot: tempDir,
+  });
+
+  const result = await removeDeprecatedHackCodexIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(result.status).toBe("removed");
+  expect(await Bun.file(skillPath).exists()).toBe(false);
+  expect(await Bun.file(configPath).text()).toBe("");
+});
+
+test("Codex legacy check covers skills and MCP as one integration", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-codex-plugin-"));
+  await installMcpConfig({
+    targets: ["codex"],
+    scope: "project",
+    projectRoot: tempDir,
+  });
+
+  const result = await checkDeprecatedHackCodexIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(result.status).toBe("deprecated");
+  expect(result.message).toContain("skills or MCP config");
+});
+
+test("Codex preparation preserves legacy skills when the plugin is missing", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-codex-plugin-"));
+  const skillPath = join(tempDir, ".codex", "skills", "hack-cli", "SKILL.md");
+  await Bun.write(skillPath, renderCodexSkill());
+
+  const result = await prepareHackCodexPlugin({
+    scope: "project",
+    projectRoot: tempDir,
+    runCodexCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify({ installed: [] }),
+      stderr: "",
+    }),
+  });
+  expect(result.status).toBe("missing");
+  expect(result.cleanupStatus).toBeUndefined();
+  expect(await Bun.file(skillPath).exists()).toBe(true);
+});
+
+test("plugin manifest version matches the CLI package", async () => {
+  const packageJson = await Bun.file(
+    join(import.meta.dir, "..", "package.json")
+  ).json();
+  const manifest = await Bun.file(
+    join(
+      import.meta.dir,
+      "..",
+      "plugins",
+      "hack",
+      ".codex-plugin",
+      "plugin.json"
+    )
+  ).json();
+  expect(manifest.version).toBe(packageJson.version);
+});
diff --git a/tests/cursor-plugin.test.ts b/tests/cursor-plugin.test.ts
new file mode 100644
index 00000000..14fae8f6
--- /dev/null
+++ b/tests/cursor-plugin.test.ts
@@ -0,0 +1,103 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { installCursorRules } from "../src/agents/cursor.ts";
+import {
+  checkHackCursorPlugin,
+  prepareHackCursorPlugin,
+  removeDeprecatedHackCursorIntegration,
+} from "../src/agents/cursor-plugin.ts";
+import { installMcpConfig } from "../src/mcp/install.ts";
+
+let tempDir: string | null = null;
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+test("checkHackCursorPlugin detects enabled, disabled, and missing states", async () => {
+  const enabled = await checkHackCursorPlugin({
+    scope: "user",
+    runCursorCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify([{ id: "hack@hack-dance", enabled: true }]),
+      stderr: "",
+    }),
+  });
+  expect(enabled.status).toBe("noop");
+
+  const disabled = await checkHackCursorPlugin({
+    scope: "user",
+    runCursorCommand: async () => ({
+      exitCode: 0,
+      stdout: JSON.stringify([{ id: "hack@hack-dance", enabled: false }]),
+      stderr: "",
+    }),
+  });
+  expect(disabled.status).toBe("stale");
+
+  const missing = await checkHackCursorPlugin({
+    scope: "user",
+    runCursorCommand: async () => ({ exitCode: 0, stdout: "[]", stderr: "" }),
+  });
+  expect(missing.status).toBe("missing");
+  expect(missing.message).toContain(
+    "cursor-agent plugin marketplace add hack-dance/hack"
+  );
+});
+
+test("Cursor plugin migration removes generated rules and MCP", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-cursor-plugin-"));
+  await installCursorRules({ scope: "project", projectRoot: tempDir });
+  await installMcpConfig({
+    targets: ["cursor"],
+    scope: "project",
+    projectRoot: tempDir,
+  });
+
+  const result = await removeDeprecatedHackCursorIntegration({
+    scope: "project",
+    projectRoot: tempDir,
+  });
+  expect(result.status).toBe("removed");
+  expect(
+    await Bun.file(join(tempDir, ".cursor", "rules", "hack.mdc")).exists()
+  ).toBe(false);
+  expect(await Bun.file(join(tempDir, ".cursor", "mcp.json")).exists()).toBe(
+    false
+  );
+});
+
+test("Cursor preparation preserves legacy rules when the plugin is missing", async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "hack-cursor-plugin-"));
+  await installCursorRules({ scope: "project", projectRoot: tempDir });
+
+  const result = await prepareHackCursorPlugin({
+    scope: "project",
+    projectRoot: tempDir,
+    runCursorCommand: async () => ({ exitCode: 0, stdout: "[]", stderr: "" }),
+  });
+  expect(result.status).toBe("missing");
+  expect(result.cleanupStatus).toBeUndefined();
+  expect(
+    await Bun.file(join(tempDir, ".cursor", "rules", "hack.mdc")).exists()
+  ).toBe(true);
+});
+
+test("Cursor plugin manifests match the CLI package version", async () => {
+  const repoRoot = join(import.meta.dir, "..");
+  const packageJson = await Bun.file(join(repoRoot, "package.json")).json();
+  const manifest = await Bun.file(
+    join(repoRoot, "plugins", "hack", ".cursor-plugin", "plugin.json")
+  ).json();
+  expect(manifest.version).toBe(packageJson.version);
+  const rule = await Bun.file(
+    join(repoRoot, "plugins", "hack", "rules", "hack.mdc")
+  ).text();
+  expect(rule).toStartWith("---\ndescription:");
+  expect(rule).toContain("alwaysApply: true");
+});
diff --git a/tests/e2e/scenarios/agent-docs-sync.ts b/tests/e2e/scenarios/agent-docs-sync.ts
index 2b778a53..e0ded37d 100644
--- a/tests/e2e/scenarios/agent-docs-sync.ts
+++ b/tests/e2e/scenarios/agent-docs-sync.ts
@@ -1,5 +1,5 @@
-import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { chmod, mkdir } from "node:fs/promises";
+import { delimiter, join } from "node:path";
 
 import { createMonorepoFixture } from "../fixture.ts";
 import { expect, expectExit, type Scenario } from "../harness.ts";
@@ -195,8 +195,17 @@ export const agentDocsSyncScenario: Scenario = {
     });
     expectExit({
       result: fullSync,
-      codes: [0],
-      message: "hack setup sync (project scope) should succeed",
+      codes: [1],
+      message:
+        "sync should remain non-successful while native plugins are unavailable",
+    });
+    expect({
+      that:
+        fullSync.combined.includes("Hack Cursor plugin") &&
+        fullSync.combined.includes("Hack Claude Code plugin") &&
+        fullSync.combined.includes("Hack Codex plugin"),
+      message: "sync should identify every unavailable native plugin",
+      result: fullSync,
     });
     const fullSyncCheck = await ctx.cli({
       args: ["setup", "sync", "--all-scopes", "--check"],
@@ -205,27 +214,38 @@ export const agentDocsSyncScenario: Scenario = {
     });
     expectExit({
       result: fullSyncCheck,
-      codes: [0],
+      codes: [1],
+      message:
+        "sync check should remain non-successful while native plugins are unavailable",
+    });
+    expect({
+      that: !(
+        fullSyncCheck.combined.toLowerCase().includes("deprecated tickets") ||
+        fullSyncCheck.combined.toLowerCase().includes("out of date")
+      ),
       message:
-        "hack setup sync --check right after hack setup sync should be clean",
+        "missing plugins must not prevent generated docs and deprecated Tickets artifacts from reconciling",
+      result: fullSyncCheck,
     });
 
-    const currentPrime = await ctx.cli({
+    const reconciledPrime = await ctx.cli({
       args: ["agent", "prime"],
       cwd: fixture.root,
       env: isolatedUserEnv,
     });
     expectExit({
-      result: currentPrime,
+      result: reconciledPrime,
       codes: [0],
-      message: "agent primer should render after project/global repair",
+      message:
+        "agent primer should render after generated guidance reconciliation",
     });
     expect({
-      that: currentPrime.stdout.includes(
+      that: reconciledPrime.stdout.includes(
         "Hack agent integration freshness: current"
       ),
-      message: "agent primer should report current guidance after repair",
-      result: currentPrime,
+      message:
+        "generated guidance should be current even while setup separately reports unavailable plugins",
+      result: reconciledPrime,
     });
 
     const syncedAgents = await Bun.file(agentsPath).text();
@@ -247,6 +267,44 @@ export const agentDocsSyncScenario: Scenario = {
       });
     }
 
+    const readyPluginEnv = await createReadyPluginEnv({
+      tempRoot: ctx.tempRoot,
+      home: ctx.hackHome,
+    });
+    const readySync = await ctx.cli({
+      args: ["setup", "sync", "--all-scopes"],
+      cwd: fixture.root,
+      env: readyPluginEnv,
+    });
+    expectExit({
+      result: readySync,
+      codes: [0],
+      message: "sync should succeed after every native plugin is ready",
+    });
+    const readyCheck = await ctx.cli({
+      args: ["setup", "sync", "--all-scopes", "--check"],
+      cwd: fixture.root,
+      env: readyPluginEnv,
+    });
+    expectExit({
+      result: readyCheck,
+      codes: [0],
+      message: "sync check should be clean after ready-plugin reconciliation",
+    });
+    const currentPrime = await ctx.cli({
+      args: ["agent", "prime"],
+      cwd: fixture.root,
+      env: readyPluginEnv,
+    });
+    expect({
+      that: currentPrime.stdout.includes(
+        "Hack agent integration freshness: current"
+      ),
+      message:
+        "agent primer should report current guidance after plugin readiness",
+      result: currentPrime,
+    });
+
     await Bun.write(
       agentsPath,
       syncedAgents.replace(
@@ -257,7 +315,7 @@ export const agentDocsSyncScenario: Scenario = {
     const autoRepair = await ctx.cli({
       args: ["config", "get", "name"],
       cwd: fixture.root,
-      env: { ...isolatedUserEnv, HACK_SETUP_SYNC_MODE: "auto" },
+      env: { ...readyPluginEnv, HACK_SETUP_SYNC_MODE: "auto" },
     });
     expectExit({
       result: autoRepair,
@@ -282,3 +340,50 @@ export const agentDocsSyncScenario: Scenario = {
     });
   },
 };
+
+async function createReadyPluginEnv({
+  tempRoot,
+  home,
+}: {
+  readonly tempRoot: string;
+  readonly home: string;
+}): Promise<Record<string, string>> {
+  const binDir = join(tempRoot, "ready-agent-plugins");
+  await mkdir(binDir, { recursive: true });
+  const clients = [
+    {
+      name: "cursor-agent",
+      output: [{ id: "hack@hack-dance", enabled: true }],
+    },
+    {
+      name: "claude",
+      output: [{ id: "hack@hack-dance", enabled: true }],
+    },
+    {
+      name: "codex",
+      output: {
+        installed: [
+          {
+            name: "hack",
+            marketplaceName: "hack-dance",
+            installed: true,
+            enabled: true,
+          },
+        ],
+      },
+    },
+  ] as const;
+  for (const client of clients) {
+    const path = join(binDir, client.name);
+    await Bun.write(
+      path,
+      `#!/bin/sh\nprintf '%s\\n' '${JSON.stringify(client.output)}'\n`
+    );
+    await chmod(path, 0o755);
+  }
+
+  return {
+    HOME: home,
+    PATH: [binDir, process.env.PATH].filter(Boolean).join(delimiter),
+  };
+}
diff --git a/tests/hack-init-skill.test.ts b/tests/hack-init-skill.test.ts
index efc8a168..24017a28 100644
--- a/tests/hack-init-skill.test.ts
+++ b/tests/hack-init-skill.test.ts
@@ -8,11 +8,6 @@ import {
   installClaudeHooks,
   removeClaudeHooks,
 } from "../src/agents/claude.ts";
-import {
-  checkCodexSkill,
-  installCodexSkill,
-  removeCodexSkill,
-} from "../src/agents/codex-skill.ts";
 import {
   checkHackInitSkill,
   installHackInitSkill,
@@ -55,7 +50,7 @@ test("renderHackInitSkill is a thin pointer to the CLI prompt source", () => {
   expect(skill).not.toContain("## Phase 1");
 });
 
-test("installHackInitSkill writes project-scoped skills for both clients", async () => {
+test("installHackInitSkill writes the project-scoped Claude skill", async () => {
   const repoRoot = await setupTempDir();
 
   const claude = await installHackInitSkill({
@@ -63,20 +58,10 @@ test("installHackInitSkill writes project-scoped skills for both clients", async
     scope: "project",
     projectRoot: repoRoot,
   });
-  const codex = await installHackInitSkill({
-    client: "codex",
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-
   expect(claude.status).toBe("created");
-  expect(codex.status).toBe("created");
   expect(claude.path).toBe(
     join(repoRoot, ".claude", "skills", "hack-init", "SKILL.md")
   );
-  expect(codex.path).toBe(
-    join(repoRoot, ".codex", "skills", "hack-init", "SKILL.md")
-  );
 
   const content = await Bun.file(claude.path).text();
   expect(content).toContain("name: hack-init");
@@ -101,37 +86,43 @@ test("checkHackInitSkill reports noop, stale, and missing", async () => {
   const repoRoot = await setupTempDir();
 
   const missing = await checkHackInitSkill({
-    client: "codex",
+    client: "claude",
     scope: "project",
     projectRoot: repoRoot,
   });
   expect(missing.status).toBe("missing");
 
   await installHackInitSkill({
-    client: "codex",
+    client: "claude",
     scope: "project",
     projectRoot: repoRoot,
   });
   const fresh = await checkHackInitSkill({
-    client: "codex",
+    client: "claude",
     scope: "project",
     projectRoot: repoRoot,
   });
   expect(fresh.status).toBe("noop");
 
-  const skillPath = join(repoRoot, ".codex", "skills", "hack-init", "SKILL.md");
+  const skillPath = join(
+    repoRoot,
+    ".claude",
+    "skills",
+    "hack-init",
+    "SKILL.md"
+  );
   const content = await Bun.file(skillPath).text();
   await Bun.write(
     skillPath,
     content.replace("hack agent onboard", "hack agent old-command")
   );
   const stale = await checkHackInitSkill({
-    client: "codex",
+    client: "claude",
     scope: "project",
     projectRoot: repoRoot,
   });
   expect(stale.status).toBe("stale");
-  expect(stale.message).toContain("hack setup codex");
+  expect(stale.message).toContain("hack setup claude");
 });
 
 test("removeHackInitSkill deletes the skill directory", async () => {
@@ -157,46 +148,6 @@ test("removeHackInitSkill deletes the skill directory", async () => {
   expect(gone.status).toBe("missing");
 });
 
-test("installCodexSkill also installs the hack-init skill and detects its drift", async () => {
-  const repoRoot = await setupTempDir();
-
-  const installed = await installCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(installed.status).toBe("created");
-
-  const initSkillPath = join(
-    repoRoot,
-    ".codex",
-    "skills",
-    "hack-init",
-    "SKILL.md"
-  );
-  const content = await Bun.file(initSkillPath).text();
-  expect(content).toContain("name: hack-init");
-
-  const fresh = await checkCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(fresh.status).toBe("noop");
-
-  await Bun.write(initSkillPath, content.replace("hack agent onboard", "nope"));
-  const stale = await checkCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(stale.status).toBe("stale");
-
-  const removed = await removeCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-  expect(removed.status).toBe("removed");
-  expect(await Bun.file(initSkillPath).exists()).toBe(false);
-});
-
 test("installClaudeHooks also installs the hack-init skill and detects its drift", async () => {
   const repoRoot = await setupTempDir();
 
diff --git a/tests/integration-sync.test.ts b/tests/integration-sync.test.ts
new file mode 100644
index 00000000..a24a7453
--- /dev/null
+++ b/tests/integration-sync.test.ts
@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+
+import { syncLegacyScopesWhenPluginReady } from "../src/cli/integration-sync.ts";
+
+test("automatic integration sync leaves both scopes untouched until plugin readiness", async () => {
+  let cleanupCalls = 0;
+  const statuses = await syncLegacyScopesWhenPluginReady({
+    check: async () => ({ status: "stale" }),
+    cleanups: [
+      async () => {
+        cleanupCalls += 1;
+        return { status: "removed" };
+      },
+      async () => {
+        cleanupCalls += 1;
+        return { status: "removed" };
+      },
+    ],
+  });
+
+  expect(statuses).toEqual(["stale"]);
+  expect(cleanupCalls).toBe(0);
+});
+
+test("automatic integration sync cleans both scopes after plugin readiness", async () => {
+  let cleanupCalls = 0;
+  const statuses = await syncLegacyScopesWhenPluginReady({
+    check: async () => ({ status: "noop" }),
+    cleanups: [
+      async () => {
+        cleanupCalls += 1;
+        return { status: "removed" };
+      },
+      async () => {
+        cleanupCalls += 1;
+        return { status: "absent" };
+      },
+    ],
+  });
+
+  expect(statuses).toEqual(["removed", "absent"]);
+  expect(cleanupCalls).toBe(2);
+});
+
+test("automatic integration sync retains preserved cleanup as incomplete", async () => {
+  const statuses = await syncLegacyScopesWhenPluginReady({
+    check: async () => ({ status: "noop" }),
+    cleanups: [
+      async () => ({ status: "removed" }),
+      async () => ({ status: "preserved" }),
+    ],
+  });
+
+  expect(statuses).toEqual(["removed", "preserved"]);
+});
diff --git a/tests/mcp-install.test.ts b/tests/mcp-install.test.ts
index 03c74cd1..85a9a4db 100644
--- a/tests/mcp-install.test.ts
+++ b/tests/mcp-install.test.ts
@@ -3,7 +3,13 @@ import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { installMcpConfig } from "../src/mcp/install.ts";
+import {
+  checkDeprecatedCodexMcpConfig,
+  checkDeprecatedPluginMcpConfig,
+  installMcpConfig,
+  removeDeprecatedCodexMcpConfig,
+  removeDeprecatedPluginMcpConfig,
+} from "../src/mcp/install.ts";
 
 let tempDir: string | null = null;
 const originalHome = process.env.HOME;
@@ -69,6 +75,62 @@ test("installMcpConfig is idempotent for codex", async () => {
   expect(codexText).toContain('args = ["mcp", "serve"]');
 });
 
+test("deprecated Codex MCP cleanup removes generated config", async () => {
+  await setupTempHome();
+  await installMcpConfig({ targets: ["codex"], scope: "user" });
+
+  const check = await checkDeprecatedCodexMcpConfig({ scope: "user" });
+  expect(check.status).toBe("deprecated");
+
+  const removed = await removeDeprecatedCodexMcpConfig({ scope: "user" });
+  expect(removed.status).toBe("removed");
+  const absent = await checkDeprecatedCodexMcpConfig({ scope: "user" });
+  expect(absent.status).toBe("absent");
+});
+
+test("deprecated Codex MCP cleanup preserves customized config", async () => {
+  const homeDir = await setupTempHome();
+  const codexPath = join(homeDir, ".codex", "config.toml");
+  await Bun.write(
+    codexPath,
+    '[mcp_servers.hack]\ncommand = "custom-hack"\nargs = ["mcp", "serve"]\n'
+  );
+
+  const result = await removeDeprecatedCodexMcpConfig({ scope: "user" });
+  expect(result.status).toBe("preserved");
+  expect(await Bun.file(codexPath).text()).toContain('command = "custom-hack"');
+});
+
+test("plugin MCP cleanup removes generated entries and preserves customized entries", async () => {
+  const homeDir = await setupTempHome();
+  await installMcpConfig({ targets: ["cursor", "claude"], scope: "user" });
+
+  const deprecated = await checkDeprecatedPluginMcpConfig({
+    target: "cursor",
+    scope: "user",
+  });
+  expect(deprecated.status).toBe("deprecated");
+  const cursorResult = await removeDeprecatedPluginMcpConfig({
+    target: "cursor",
+    scope: "user",
+  });
+  expect(cursorResult.status).toBe("removed");
+  expect(await Bun.file(join(homeDir, ".cursor", "mcp.json")).exists()).toBe(
+    false
+  );
+
+  const claudePath = join(homeDir, ".claude", "settings.json");
+  const claude = await Bun.file(claudePath).json();
+  claude.mcpServers.hack.command = "custom-hack";
+  await Bun.write(claudePath, `${JSON.stringify(claude, null, 2)}\n`);
+  const claudeResult = await removeDeprecatedPluginMcpConfig({
+    target: "claude",
+    scope: "user",
+  });
+  expect(claudeResult.status).toBe("preserved");
+  expect(await Bun.file(claudePath).text()).toContain("custom-hack");
+});
+
 async function setupTempHome(): Promise<string> {
   tempDir = await mkdtemp(join(tmpdir(), "hack-mcp-install-"));
   const homeDir = join(tempDir, "home");
diff --git a/tests/plugin-lifecycle.test.ts b/tests/plugin-lifecycle.test.ts
new file mode 100644
index 00000000..2b4ea943
--- /dev/null
+++ b/tests/plugin-lifecycle.test.ts
@@ -0,0 +1,169 @@
+import { expect, test } from "bun:test";
+
+import {
+  checkNativeAgentPlugin,
+  checkNativeAgentPluginCutover,
+  mergeLegacyCleanupResults,
+  prepareNativeAgentPlugin,
+  resolveAgentPluginInstallOutcome,
+} from "../src/agents/plugin-lifecycle.ts";
+
+test("native plugin checks map client state to lifecycle results", async () => {
+  const result = await checkNativeAgentPlugin({
+    scope: "user",
+    pluginId: "hack@example",
+    runCommand: async () => ({
+      exitCode: 0,
+      stdout: "client output",
+      stderr: "",
+    }),
+    missingExecutableMessage: "missing executable",
+    inspectErrorMessage: "inspection failed",
+    missingPluginMessage: "missing plugin",
+    disabledPluginMessage: "disabled plugin",
+    parseState: ({ json }) => ({
+      ok: true,
+      installed: json === "client output",
+      enabled: false,
+    }),
+  });
+
+  expect(result).toEqual({
+    scope: "user",
+    status: "stale",
+    path: "hack@example",
+    message: "disabled plugin",
+  });
+});
+
+test("native plugin checks report a missing client executable without inspection", async () => {
+  let parsed = false;
+  const result = await checkNativeAgentPlugin({
+    scope: "project",
+    pluginId: "hack@example",
+    runCommand: null,
+    missingExecutableMessage: "client executable is missing",
+    inspectErrorMessage: "inspection failed",
+    missingPluginMessage: "missing plugin",
+    disabledPluginMessage: "disabled plugin",
+    parseState: () => {
+      parsed = true;
+      return { ok: true, installed: true, enabled: true };
+    },
+  });
+
+  expect(result.status).toBe("missing");
+  expect(result.message).toBe("client executable is missing");
+  expect(parsed).toBe(false);
+});
+
+test("native plugin preparation skips cleanup until the plugin is ready", async () => {
+  let cleanupCalled = false;
+  const result = await prepareNativeAgentPlugin({
+    cleanup: async () => {
+      cleanupCalled = true;
+      return {
+        scope: "project",
+        status: "removed" as const,
+        path: "/legacy",
+      };
+    },
+    check: async () => ({
+      scope: "project",
+      status: "missing",
+      path: "hack@example",
+      message: "install plugin",
+    }),
+  });
+
+  expect(result.status).toBe("missing");
+  expect(result.cleanupStatus).toBeUndefined();
+  expect(result.message).toContain("install plugin");
+  expect(cleanupCalled).toBe(false);
+});
+
+test("cutover checks report readiness before inspecting legacy artifacts", async () => {
+  let legacyChecked = false;
+  const result = await checkNativeAgentPluginCutover({
+    check: async () => ({
+      scope: "user",
+      status: "stale",
+      path: "hack@example",
+    }),
+    checkLegacy: async () => {
+      legacyChecked = true;
+      return {
+        scope: "user",
+        status: "deprecated" as const,
+        path: "/legacy",
+      };
+    },
+  });
+
+  expect(result.status).toBe("stale");
+  expect(legacyChecked).toBe(false);
+});
+
+test("legacy cleanup aggregation gives errors precedence over mutations", () => {
+  const result = mergeLegacyCleanupResults({
+    scope: "project",
+    fallbackPath: "/fallback",
+    results: [
+      { status: "removed", path: "/removed" },
+      { status: "error", path: "/failed", message: "cleanup failed" },
+    ],
+  });
+
+  expect(result).toEqual({
+    scope: "project",
+    status: "error",
+    path: "/failed",
+    message: "cleanup failed",
+  });
+});
+
+test("legacy cleanup aggregation gives preserved content precedence over removals", () => {
+  const result = mergeLegacyCleanupResults({
+    scope: "project",
+    fallbackPath: "/fallback",
+    results: [
+      { status: "removed", path: "/generated" },
+      {
+        status: "preserved",
+        path: "/customized",
+        message: "Preserved customized content.",
+      },
+    ],
+  });
+
+  expect(result).toEqual({
+    scope: "project",
+    status: "preserved",
+    path: "/customized",
+    message: "Preserved customized content.",
+  });
+});
+
+test("unavailable plugins are warning outcomes instead of successful installs", () => {
+  for (const status of ["missing", "stale", "deprecated"] as const) {
+    expect(resolveAgentPluginInstallOutcome({ status })).toBe("warning");
+  }
+  expect(resolveAgentPluginInstallOutcome({ status: "noop" })).toBe(
+    "unchanged"
+  );
+  expect(resolveAgentPluginInstallOutcome({ status: "removed" })).toBe(
+    "updated"
+  );
+  expect(
+    resolveAgentPluginInstallOutcome({
+      status: "noop",
+      cleanupStatus: "preserved",
+    })
+  ).toBe("warning");
+  expect(
+    resolveAgentPluginInstallOutcome({
+      status: "noop",
+      cleanupStatus: "removed",
+    })
+  ).toBe("updated");
+});
diff --git a/tests/setup.test.ts b/tests/setup.test.ts
index fd0c88b0..8290faa7 100644
--- a/tests/setup.test.ts
+++ b/tests/setup.test.ts
@@ -3,7 +3,6 @@ import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { installClaudeHooks } from "../src/agents/claude.ts";
-import { installCodexSkill } from "../src/agents/codex-skill.ts";
 import { installCursorRules } from "../src/agents/cursor.ts";
 import {
   buildInitAssistantReport,
@@ -61,26 +60,6 @@ test("installClaudeHooks writes settings.local.json hooks", async () => {
   expect(containsCommand(preCompactHooks, "hack agent prime")).toBe(true);
 });
 
-test("installCodexSkill writes SKILL.md with hack-cli frontmatter", async () => {
-  const repoRoot = await setupTempRepo();
-  const result = await installCodexSkill({
-    scope: "project",
-    projectRoot: repoRoot,
-  });
-
-  expect(result.status).toBe("created");
-  const skillPath = join(repoRoot, ".codex", "skills", "hack-cli", "SKILL.md");
-  const content = await Bun.file(skillPath).text();
-  expect(content).toContain("name: hack-cli");
-  expect(content).toContain("hack setup cursor");
-  expect(content).toContain("## Product boundary");
-  expect(content).toContain(
-    "Experimental and unsupported: remote/gateway/node/dispatch"
-  );
-  expect(content).toContain("singleton.ports");
-  expect(content).not.toContain(".hack/hack.env.json");
-});
-
 test("renderAgentPrimer is CLI-first and mentions MCP", () => {
   const primer = renderAgentPrimer();
   expect(primer).toContain("hack up --detach");
@@ -196,6 +175,103 @@ test("setup sync treats installed deprecated artifacts as actionable", () => {
   });
 });
 
+test("setup sync reports unavailable native plugins as non-success", () => {
+  const result = buildSetupSyncScopeResult({
+    action: "install",
+    scope: "Project",
+    groups: [
+      {
+        label: "Hack Cursor plugin",
+        requiresReadyPlugin: true,
+        results: [
+          {
+            status: "missing",
+            path: "hack@hack-dance",
+            message: "Install Hack with /add-plugin before migration.",
+          },
+        ],
+      },
+    ],
+  });
+
+  expect(result).toEqual({
+    exitCode: 1,
+    item: {
+      label: "Project",
+      status: "warn",
+      meta: "0/1 current",
+      detail:
+        "Hack Cursor plugin: Install Hack with /add-plugin before migration.",
+    },
+  });
+});
+
+test("setup sync does not treat absent deprecated artifacts as plugin failures", () => {
+  const result = buildSetupSyncScopeResult({
+    action: "install",
+    scope: "Global",
+    groups: [
+      {
+        label: "Deprecated Tickets skill",
+        results: [{ status: "missing", path: "<home>/hack-tickets" }],
+      },
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(result.item.status).toBe("ok");
+  expect(result.item.meta).toBe("already current");
+});
+
+test("setup sync counts plugin-gated legacy cleanup as an update", () => {
+  const result = buildSetupSyncScopeResult({
+    action: "install",
+    scope: "Project",
+    groups: [
+      {
+        label: "Hack Codex plugin",
+        requiresReadyPlugin: true,
+        results: [
+          {
+            status: "noop",
+            cleanupStatus: "removed",
+            path: "hack@hack-dance",
+          },
+        ],
+      },
+    ],
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(result.item.meta).toBe("1 updated");
+});
+
+test("setup sync reports preserved plugin cleanup as non-success", () => {
+  const result = buildSetupSyncScopeResult({
+    action: "install",
+    scope: "Project",
+    groups: [
+      {
+        label: "Hack Codex plugin",
+        requiresReadyPlugin: true,
+        results: [
+          {
+            status: "noop",
+            cleanupStatus: "preserved",
+            path: "/repo/.codex/config.toml",
+            message: "Preserved customized MCP config.",
+          },
+        ],
+      },
+    ],
+  });
+
+  expect(result.exitCode).toBe(1);
+  expect(result.item.status).toBe("warn");
+  expect(result.item.meta).toBe("0/1 current");
+  expect(result.item.detail).toContain("Preserved customized MCP config.");
+});
+
 test("buildInitAssistantReport captures repo signals", async () => {
   const repoRoot = await setupTempRepo();
   await Bun.write(