feat(agents): add optional native plugins and align Hack guidance

[vm]

Behavior

Add optional native Hack plugins for Codex, Claude Code, and Cursor. Each bundles the canonical Hack skills and MCP server, with Claude primer hooks and a relevance-selected Cursor rule. Existing standalone setup remains supported. Installation and updates never implicitly migrate or remove rules, skills, hooks, or MCP entries; scoped duplicate cleanup follows fresh-session verification and preserves customized content.

Bring the branch up to current local-first Hack and align contributor and consumer instructions. Claude imports one contributor baseline. Remove duplicated generic skill packs, retired hosted guidance, and repository-wide format-on-every-edit hooks. Scope retained native-app guidance to its unsupported source directory. Keep native approvals, secret handling, runtime ownership, protected branches, and publishing gates; remove redundant confirmation and optional-warning completion gates. Onboarding supports partial adoption and successful one-shot services without requiring broad env migration or weakened TLS/origin checks.

Release preparation regenerates the complete plugin bundle after the version bump. Regression coverage verifies manifest versions, canonical content, installed adapters, and generation during an actual release-preparation fixture. docs/agent-guidance.md maps ownership and regeneration paths. Model selection, global instructions, evolution, and writeback policy remain with the user's configuration.

Validation

• Local typecheck, quality/privacy checks, and compiled build pass.
• Bun 1.3.9 full CLI suite: 901 passed, 5 skipped, 0 failed (906 tests across 159 files). Compiled agent-docs E2E: passed. Plugin validation and changed-file lint: passed.
• Codex: isolated marketplace install/enable, then fresh app-server discovery of both plugin skills and MCP tools.
• Claude Code: strict manifest validation, isolated install/enable, then fresh-session discovery of both skills, successful primer hook, and connected plugin MCP. The isolated profile was unauthenticated, so this proves initialization rather than an authenticated model response.
• Cursor 3.18.25: local plugin copy loaded in Customize with two skills, one rule, and one MCP server exposing ten tools. External symlinks were rejected by the runtime; docs use the accepted local-copy path. The temporary copy was removed after validation. Public marketplace installation has not been proven on this branch.
• Exact-commit CI at a54249e5b2509553155972cc36ae269dd8ec54a5: run 34186117823 passed tests, secret scanning, runtime-image builds/smokes, and Docker E2E. Both previous review threads are resolved.

Release and boundaries

Use feat(agents) for the squash title: this adds an optional capability and should trigger a feature release. No runtime env/lifecycle semantics or default integration migration are introduced. Unsupported remote and macOS source remains available for explicit maintenance and is not added to default onboarding or CLI release gates.

The final branch includes merged PR #81 and the 4.0.3 release commit. All bundled manifests and generated version stamps were refreshed, with 18 focused generation/contract tests passing before the final full CI run.

[roodboi]

Requesting changes because the migration currently has no safe cutover boundary: a normal interactive Hack command can remove the working standalone integration before the native plugin is installed or enabled.

What I verified on this head:

• full bun test exits successfully
• the focused plugin/setup suite passes (48 tests, 193 assertions)
• bun run typecheck, bun run check, and git diff --check pass
• hosted CI is green across test, runtime-images, Docker E2E, and secret scan
• live codex plugin list --json and claude plugin list --json output match the new parsers

What still needs direct verification before merge:

1. Fresh marketplace add + plugin install for Codex, Claude Code, and Cursor using current stable clients.
2. A cutover matrix for plugin missing / disabled / enabled × project / user legacy artifacts × generated / customized artifacts. Missing or disabled must retain the working legacy integration; enabled may remove only exact generated copies.
3. After a new session, prove both skills, the Claude hooks / Cursor rule, and hack mcp serve are actually loaded from each installed plugin.
4. Exercise interactive hack init and hack setup output so missing/disabled plugins are warnings with non-success status.

Please also complete the PR description's Summary, Verification, Release Signal, Semantic Surfaces, and Risks sections. This is a user-facing feat and the release decision must be explicit per repository policy.

[roodboi]

Re-reviewed the two new commits (e21feee and 6808a21). The original unsafe-cleanup, missing-plugin success, Cursor guidance, and PR-description findings are substantially addressed.

What I verified on this head:

• focused plugin/cutover/setup suite: 36 tests, 217 assertions, 0 failures
• direct CLI TypeScript check and direct Ultracite check on all changed TS/test files
• CLI build and git diff --check
• the readiness matrix preserves legacy content while plugins are missing/disabled

Two false-green cases remain when the plugin is enabled but customized legacy content is preserved; see the inline comments. Please test enabled-plugin cutover with a customized primary artifact and customized MCP entry for all three clients, both scopes, through hack setup <client>, hack setup sync --all-scopes, automatic sync, and interactive hack init. Every path must preserve the customization, warn, and exit nonzero until the duplicate legacy integration is manually reconciled.

Hosted CI has not executed: run 243 is action_required with zero jobs, consistent with the fork workflow awaiting maintainer approval. Please approve/run CI and get it green. A live current-stable Cursor + Cursor Agent CLI marketplace/install/load check also remains outstanding before approval.

[roodboi]

CI is now running, and the main test/typecheck/build, runtime-image, and secret-scan jobs pass. Docker E2E fails deterministically in agent-docs-sync because this PR changed missing native plugins to a non-success sync result without updating the existing E2E contract. See the inline comment for the required coverage. After updating it, run bun run test:e2e:local:docker and keep the earlier customized-artifact cutover cases in scope.

[roodboi]

Re-reviewed 7f72688 plus the merge head 3d71e07.

Verified in an isolated checkout:

• focused plugin/cutover/setup suite: 27 tests, 307 assertions, 0 failures
• agent-docs-sync E2E passes locally, and hosted run 247's docker-e2e job is green
• CLI TypeScript, changed-file Ultracite, CLI build, and git diff --check pass
• customized primary and MCP artifacts are preserved and return non-success across all three clients and both scopes

The prior functional findings are fixed. One merge-generated artifact drift remains: the 3.5.2 merge left the new plugin manifests and bundled Codex skill at 3.5.1, producing four deterministic test failures. See the inline comment.

After regenerating, please run bun test tests/claude-plugin.test.ts tests/cursor-plugin.test.ts tests/codex-plugin.test.ts tests/agent-instruction-source.test.ts and get the hosted test job green. The existing live current-stable Cursor install/load verification thread also remains open.

[roodboi]

The requested version-generation and Cursor validation fixes are addressed. Reviewed the refreshed optional-plugin scope and contributor/consumer guidance audit. Local Bun 1.3.9 tests and compiled agent-docs E2E pass, and all four CI jobs pass at 6df4ff2. Fresh-client component loading is documented with its authentication and marketplace verification limits. No remaining blocking findings.

[roodboi]

Rechecked the branch after merging #81 and the 4.0.3 release commit. Conflict resolution preserved the previously reviewed content; the remaining changes refresh versioned generated assets. Focused generation tests and all four hosted CI jobs pass at a54249e. No remaining blocking findings.