cursor-ide-stinger

# cursor-ide Stinger The knowledge repository for `cursor-ide-wasp-drone`. Covers Hivemind's real Cursor surface: the Cursor 1.7+ hooks harness, the first-party Cursor extension, registering the Wasp Nestmind MCP server in Cursor, and the `.cursor/` colony (rules, agents, skills, commands, model matrix) that this repo ships. This is the platform knowledge that keeps the colony working inside Cursor: the rules `.mdc` format, the hooks lifecycle, MCP registration, the agents/skills/commands layout, and the cursor harness install. ## When this stinger applies Load whenever `cursor-ide-wasp-drone` is invoked. Typical triggers (any of these phrases): - "wire the Cursor hooks" / "what does install-cursor do" / "hooks.json" / "Cursor 1.7 hooks" - "add a `.cursor/rules/*.mdc`" / "fix this rule" / "rule frontmatter" / "alwaysApply / globs" - "register the Wasp Nestmind MCP server in Cursor" / "mcp.json in Cursor" - "the cursor extension" / "harnesses/cursor/extension" / "the dashboard webview / status bar" - "the colony layout" / "where do agents/skills/commands live" / "the-pest-controller / the-smoker" - "model-comparison-matrix" Do NOT load for: - Code quality / typing of the TypeScript source itself (`typescript-node-wasp-drone`). - The MCP protocol internals of `src/mcp/server.ts`: tool schemas, transport (`mcp-protocol-wasp-drone`). - Harness wiring for Claude Code, Codex, Hermes, or other agents (`harness-integration-wasp-drone`). ## First action when loaded Read in order before acting: 1. **`guides/01-principles.md`**: the Wasp Nestmind Cursor surface map, the rules `.mdc` mental model, and the hard directives (idempotent hook merge, em-dash ban, Cursor field shape). 2. The task-specific guide: - `02` for `.cursor/rules/*.mdc` authoring. - `03` for registering the Wasp Nestmind MCP server in Cursor. - `04` for the Cursor hooks lifecycle (the 6 events + `install-cursor.ts`). - `05` for the `.cursor/` colony layout. - `06` for the cursor extension build. ## Folder layout ```text cursor-ide-stinger/ +- SKILL.md (this file, master index) +- guides/ | +- 01-principles.md (the Wasp Nestmind Cursor surface; rules model; hard directives) | +- 02-rule-file-authoring.md (.cursor/rules/*.mdc frontmatter, globs, activation modes) | +- 03-mcp-integration.md (registering the Wasp Nestmind MCP server in Cursor) | +- 04-cursor-hooks-lifecycle.md (hooks.json 1.7+, the 6 events, install-cursor.ts wiring) | +- 05-cursor-army-layout.md (.cursor/ rules + agents + skills + commands + model matrix) | +- 06-extension-development.md (harnesses/cursor/extension build, contributions, MCP/hooks surface) +- examples/ | +- rule-file-examples.md (worked .mdc examples, including this repo's live rules) | +- mcp-server-example.md (registering hivemind in Cursor mcp.json + the extension path) | +- hooks-wiring-example.md (a real ~/.cursor/hooks.json after install-cursor) +- templates/ | +- rule-file-template.mdc (canonical .mdc frontmatter template) | +- hooks-json-template.json (Cursor 1.7+ hooks.json wiring template) +- reports/ | +- README.md +- research/ (Cursor 1.7+ hooks/rules notes, dated 2026-06-16) +- research-plan.md +- research-summary.md +- index.md +- internal/ (live repo artifacts) +- external/ (Cursor hooks + rules docs) ``` ## Critical directives Stinger-level non-negotiables that `cursor-ide-wasp-drone` enforces on every invocation: - **Cursor's hooks.json schema differs from Claude/Codex.** Array entries under each event are command objects directly (`{ type, command, timeout }`), with NO outer `{ hooks: [...] }` wrapper and NO top-level `matcher` wrapper. See `guides/04`. - **Hook merges must stay idempotent and Windows-safe.** `install-cursor.ts` strips prior Hivemind entries (matched on a normalized `/.cursor/hivemind/bundle/` path so backslash paths on Windows do not duplicate) before re-adding, and only rewrites `hooks.json` when content changed so it does not perturb Cursor's trust fingerprint. - **`.cursor/rules/*.mdc` is the only rules format.** This repo ships `.mdc` rules with frontmatter (`description` / `globs` / `alwaysApply`). Never introduce a `.cursorrules` file here. - **Prefer `alwaysApply: false` with a narrow glob or a sharp `description`.** Reserve `alwaysApply: true` for short, always-true directives (this repo uses it only for `no-em-dashes.mdc`). - **NO em dashes, ever.** Write hyphens directly. This is enforced by `.cursor/rules/no-em-dashes.mdc` and applies to every file this Drone authors. ## Key facts by domain (quick reference) ### The Wasp Nestmind Cursor surface (what this repo actually ships) | Surface | Path | Purpose | |---|---|---| | Hook installer | `src/cli/install-cursor.ts` | Merges `~/.cursor/hooks.json`, copies the bundle to `~/.cursor/hivemind/bundle/` | | Hook bundle | `harnesses/cursor/bundle/` | Built hook scripts (`session-start.js`, `capture.js`, `pre-tool-use.js`, `graph-on-stop.js`, `session-end.js`) | | Extension | `harnesses/cursor/extension/` | First-party VS Code/Cursor extension: status bar, onboarding, dashboard webview, codebase graph, skill sync | | MCP server | `src/mcp/server.ts` | stdio server exposing `hivemind_search` / `hivemind_read` / `hivemind_index` | | Colony | `.cursor/` | `rules/*.mdc`, `agents/*.md`, `skills/<base>-stinger/`, `commands/`, `model-comparison-matrix.md` | ### Cursor 1.7+ hooks (`~/.cursor/hooks.json`) ```jsonc { "version": 1, "hooks": { "sessionStart": [{ "type": "command", "command": "node \"...bundle/session-start.js\"", "timeout": 30 }], "beforeSubmitPrompt": [{ "type": "command", "command": "node \"...bundle/capture.js\"", "timeout": 10 }], "preToolUse": [{ "type": "command", "command": "node \"...bundle/pre-tool-use.js\"", "timeout": 30, "matcher": "Shell" }], "postToolUse": [{ "type": "command", "command": "node \"...bundle/capture.js\"", "timeout": 15 }], "afterAgentResponse": [{ "type": "command", "command": "node \"...bundle/capture.js\"", "timeout": 15 }], "stop": [{ "...": "capture.js + graph-on-stop.js" }], "sessionEnd": [{ "...": "session-end.js + graph-on-stop.js" }] } } ``` Six lifecycle events are wired: `sessionStart`, `beforeSubmitPrompt`, `preToolUse` (Shell matcher rewrites grep/rg against `~/.deeplake/memory/` into a SQL fast path), `postToolUse`, `afterAgentResponse`, `stop`, and `sessionEnd`. `graph-on-stop.js` auto-builds the code graph on `stop` and `sessionEnd` (gated, async, never blocks Cursor). ### Rules (`.cursor/rules/*.mdc`) Cursor project rules are `.mdc` files with frontmatter. Activation is driven by three fields: | Mode | `alwaysApply` | `globs` | `description` | |---|---|---|---| | Always Apply | `true` | any | any | | Apply to Specific Files | `false` | set | any | | Apply Intelligently | `false` | unset | set | | Apply Manually | `false` | unset | unset | This repo's live rules: `no-em-dashes.mdc` (alwaysApply), `plan-construction-protocol.mdc`, `respect-agent-work-boundaries.mdc`. ### MCP registration in Cursor The Wasp Nestmind MCP server (`src/mcp/server.ts`, stdio) exposes `hivemind_search`, `hivemind_read`, `hivemind_index`. To use it inside Cursor, add a `mcpServers` entry to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) pointing at the built server. See `guides/03`. ## Pairing | Role | Artifact | |---|---| | This stinger | `.` | | Paired Drone | `../../agents/cursor-ide-wasp-drone.md` | | Harness Drone (other agents) | `../../agents/harness-integration-wasp-drone.md` | | MCP protocol Drone | `../../agents/mcp-protocol-wasp-drone.md` | | Orchestrator commands | `.cursor/commands/the-pest-controller.md`, `.cursor/commands/the-smoker.md` | ## Refresh cadence - Guides `01`-`06`: refresh on any Cursor major version, or when `install-cursor.ts` / the extension `package.json` changes. - Research folder: re-run on any Cursor 1.x hooks API change. --- *Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*