feat(agents): ship a skills-only hack plugin and an opt-in hack-mcp plugin

.agents/plugins/marketplace.json

@@ -15,6 +15,18 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools"
+    },
+    {
+      "name": "hack-mcp",
+      "source": {
+        "source": "local",
+        "path": "./plugins/hack-mcp"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -11,6 +11,13 @@
       "description": "Operate and onboard Hack-managed local development environments.",
       "category": "development",
       "tags": ["local-development", "docker", "developer-tools", "agents"]
+    },
+    {
+      "name": "hack-mcp",
+      "source": "./plugins/hack-mcp",
+      "description": "Opt-in Hack MCP server (`hack mcp serve`) for agent clients without shell access.",
+      "category": "development",
+      "tags": ["local-development", "developer-tools", "agents", "mcp"]
     }
   ]
 }

.claude/skills/hack-init/SKILL.md

@@ -12,6 +12,6 @@ Fetch the current onboarding guidance from the installed Hack CLI.
 
 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.
+   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
 2. Apply the relevant phases to the authorized workflow; preserve native approvals, credential safety, and runtime ownership.
 3. Verify the requested services and host workflows. Report remaining blockers; unrelated optional integration warnings do not prevent completion.

.codex/skills/hack-cli/SKILL.md

@@ -14,7 +14,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
+- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -186,13 +186,12 @@ Use `hack` as the primary interface for local-first development.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 
-## Agent setup (CLI-first)
+## Agent setup (plugin-first)
 
-- Cursor rules: `hack setup cursor`
-- Claude hooks: `hack setup claude`
-- Codex skill: `hack setup codex`
+- Default integration: the optional `hack` plugin, installed through the client's plugin manager, ships skills, Claude primer hooks and a Cursor rule. It ships no MCP server, and Hack commands never install plugins.
+- MCP is opt-in, only for clients without shell access and only when explicitly selected: add the separate `hack-mcp` plugin, or use `hack setup mcp` (client and scope via `hack mcp install --help`). Do not configure other clients as a side effect.
+- Standalone export is an opt-in alternative to the plugin: `hack setup cursor` (rules), `hack setup claude` (hooks and skill), `hack setup codex` (skills) or `hack setup agents` (AGENTS.md/CLAUDE.md snippets). Use one integration path per client.
+- Setup and onboarding never write AGENTS.md, CLAUDE.md, rule files, or repository skill copies unless the user asks for them.
 - Agent-assisted onboarding: `hack init --with claude|codex` (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)
 - Init patterns: `hack agent patterns`
-- MCP (no-shell only): `hack setup mcp`
-- MCP install: choose the requested client and scope with `hack mcp install --help`; do not configure other clients as a side effect.

.codex/skills/hack-init/SKILL.md

@@ -12,6 +12,6 @@ Fetch the current onboarding guidance from the installed Hack CLI.
 
 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.
+   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
 2. Apply the relevant phases to the authorized workflow; preserve native approvals, credential safety, and runtime ownership.
 3. Verify the requested services and host workflows. Report remaining blockers; unrelated optional integration warnings do not prevent completion.

.cursor-plugin/marketplace.json

@@ -11,6 +11,11 @@
       "name": "hack",
       "source": "plugins/hack",
       "description": "Operate and onboard Hack-managed local development environments."
+    },
+    {
+      "name": "hack-mcp",
+      "source": "plugins/hack-mcp",
+      "description": "Opt-in Hack MCP server (`hack mcp serve`) for agent clients without shell access."
     }
   ]
 }

.cursor/rules/hack.mdc

@@ -9,7 +9,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
+- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

.releaserc.json

@@ -24,7 +24,8 @@
           "packages/db/package.json",
           "services/auth-broker/package.json",
           "bun.lock",
-          "plugins/hack"
+          "plugins/hack",
+          "plugins/hack-mcp"
         ],
         "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
       }

README.md

@@ -46,9 +46,11 @@ linked git worktree, `hack up` automatically becomes a separate instance named a
 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.
+Machine surfaces are first-class: `--json` envelopes with stable error codes and
+`--no-interactive`. The optional `hack` plugin for Codex, Claude Code, and Cursor
+gives agents Hack skills through the client's plugin manager, without writing into
+your repository. Clients without shell access can add the separate `hack-mcp`
+plugin. See [agent plugin setup](docs/integrations.md#optional-native-plugins).
 
 ## More than ports
 
@@ -114,6 +116,18 @@ hack up --detach
 hack open
 ```
 
+Using a coding agent? Install the optional `hack` plugin for its skills:
+
+```bash
+codex plugin marketplace add hack-dance/hack && codex plugin add hack@hack-dance
+# or, in Claude Code:
+claude plugin marketplace add hack-dance/hack --sparse .claude-plugin plugins/hack plugins/hack-mcp
+claude plugin install hack@hack-dance
+```
+
+In Cursor, install Hack from Customize. Add `hack-mcp` only for a client without
+shell access.
+
 When something looks wrong:
 
 ```bash
@@ -151,6 +165,3 @@ experimental — hidden behind `hack help --all`.
 ## License
 
 See [LICENSE](./LICENSE).
-
-Optional native plugins for Codex, Claude Code, and Cursor bundle Hack skills and MCP.
-See [agent plugin setup](docs/integrations.md#optional-native-plugins). Existing standalone setup remains supported.

docs/agent-guidance.md

@@ -4,7 +4,7 @@ Hack owns Hack-specific instructions. User and project policy continues to own m
 selection, general coding standards, work-unit planning, evolution, and writeback.
 Do not ship provider model pins or copy global instruction packs into this plugin.
 `tests/agent-plugin-generation.test.ts` enforces this for the generated guidance
-surfaces (`plugins/hack`, the client marketplace manifests, `.agents`, and the
+surfaces (`plugins/hack`, `plugins/hack-mcp`, the client marketplace manifests, `.agents`, and the
 example agent configuration): no model, model-override or reasoning-effort keys, no
 permission, approval or sandbox overrides, no output-style settings, and hooks that
 run only `hack agent prime`. See [model-policy ownership](reference/agent-client-capabilities.md#model-policy-ownership).
@@ -23,11 +23,14 @@ run only `hack agent prime`. See [model-policy ownership](reference/agent-client
 | `src/agents/install-skill.ts`, `remote-bootstrap-skill.ts` | Plugin installation/channel selection and fresh-host/cloud setup skills |
 | `src/agents/focused-skills.ts` | Plugin `hack-branches`, `hack-env` and `hack-diagnose` skills, composed from canonical section ids, and the plugin `hack-cli` routing description |
 | `src/agents/error-code-reference.ts` | `hack-diagnose` error-code reference, rendered from the exported `HACK_ERROR_CODES` registry in `src/lib/cli-result.ts` |
-| `scripts/generate-agent-plugins.ts` | Portable plugin/MCP manifests, three client compatibility manifests, seven skills, and Cursor rule |
-
-The portable plugin manifest derives identity and effective OpenAI presentation
-from `.codex-plugin/plugin.json`; portable MCP derives from `.mcp.json` with an
-explicit transport. Keep launch selection identical across both formats. These
+| `scripts/generate-agent-plugins.ts` | Skills-only `hack` plugin (portable manifest, three client compatibility manifests, seven skills, Cursor rule) and the complete opt-in `hack-mcp` plugin |
+
+The `hack` plugin is skills-only: the generator refuses a client manifest that
+declares `mcpServers` and removes stale `.mcp.json`/`mcp.json` files from it. Each
+portable plugin manifest derives identity and effective OpenAI presentation from
+its package's `.codex-plugin/plugin.json`. Every `hack-mcp` file renders from
+code; its `.mcp.json` and portable `mcp.json` (with an explicit transport) both
+come from `HACK_MCP_SERVER`, so launch selection stays identical. These
 plugin workflow skills complement the existing standalone setup; personal local
 plugin installation does not synchronize skills into a cloud repository.
 

docs/guides/agent-first-setup.md

@@ -11,8 +11,8 @@ 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 no-shell MCP client | the `hack-init` MCP prompt (`hack setup mcp`) |
+| An agent session with the `hack` plugin installed | `/hack-init` |
+| A no-shell client with Hack MCP explicitly installed (`hack-mcp` plugin or `hack setup mcp`) | the `hack-init` MCP prompt |
 
 ## New repo: `hack init --with`
 
@@ -42,11 +42,18 @@ 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
-fetch guidance matching the installed CLI.
+The optional `hack` plugin ships a thin `hack-init` skill; install the plugin
+through your client's plugin manager (see
+[Optional native plugins](../integrations.md#optional-native-plugins)). The skill
+tells the agent to run `hack agent onboard` and follow the printed prompt. Without
+shell access it fetches the `hack-init` MCP prompt only when a Hack MCP server, such
+as the opt-in `hack-mcp` plugin, is installed; otherwise it reports that blocker.
+The content stays in the CLI, so the skill fetches guidance matching the installed
+CLI.
+
+A client that cannot use the plugin can export the same skill into a chosen scope as
+an explicit opt-in (`hack setup claude` or `hack setup codex`). Onboarding itself
+never installs it.
 
 ## MCP request lifetime