@brainervirus/workit-cursor 0.7.1 → 0.8.1

package/.cursor-plugin/plugin.json

@@ -2,7 +2,32 @@
   "name": "workit",
   "displayName": "Workit",
   "description": "OpenCode-style verify, PR, changelog, commit, and session handoff for Cursor",
-  "version": "0.7.1",
+  "version": "0.8.1",
+  "author": {
+    "name": "Cristhofer Pincetti"
+  },
+  "publisher": "BrainerVirus",
+  "homepage": "https://github.com/BrainerVirus/workit",
+  "repository": "https://github.com/BrainerVirus/workit",
+  "license": "MIT",
+  "logo": "assets/logo.svg",
+  "keywords": [
+    "agent",
+    "cursor",
+    "mcp",
+    "workflow",
+    "workit"
+  ],
+  "category": "Developer Tools",
+  "tags": [
+    "workflow",
+    "agent",
+    "mcp",
+    "pr",
+    "changelog",
+    "commit",
+    "handoff"
+  ],
   "skills": [
     "skills/",
     "vendor/superpowers/skills/"

package/README.md

@@ -1,21 +1,103 @@
 # @brainervirus/workit-cursor
 
-Cursor plugin for workit — MCP server, hooks, rules, and skills for agentic coding workflows (specs, plans, YouTrack, CI-gated commits).
+Cursor plugin for workit — MCP server, session-start hook, rules, and skills for agentic coding workflows (specs, plans, YouTrack, CI-gated commits).
 
 ## Install
 
-Run the installer (recommended) or add the MCP server manually:
+**Wizard (recommended)** — configures Cursor and/or OpenCode and installs the platform packages:
 
 ```bash
 npx @brainervirus/workit-cli init
 ```
 
+**npm (package)** — the package is published as `@brainervirus/workit-cursor`; its `.cursor-plugin/plugin.json` identifies the plugin as `workit` (display name `Workit`) and registers its MCP server, hook, rules, and skills. A local (non-npm) install lives at `~/.cursor/plugins/local/workit` and writes `enabled_plugins.workit = true`; the installer migrates exact legacy `workflow-toolkit` entries only after the replacement succeeds.
+
+**Marketplace** — see [Marketplace](#marketplace).
+
+**Manual** — add the MCP server to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "workit": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=@brainervirus/workit-cursor@0.8.0",
+        "workit-cursor-mcp",
+        "${workspaceFolder}"
+      ]
+    }
+  }
+}
+```
+
+### Requirements
+
+- **Node.js ≥ 22** — the MCP server and session-start hook are self-contained Node bundles invoked through `npx`.
+- **Network** — `npx -y …@0.8.0` resolves and downloads the package on first run in each environment; a machine that cannot reach the npm registry cannot start the MCP server or hook (see [Runtime](#runtime)).
+
 ## What it provides
 
-- MCP server (41 `workflow_*` tools)
-- Session-start contract hook
-- Canonical rules (locale, branch policy, doc delivery)
-- The same 12 `wk-*` skills as OpenCode
+- MCP server exposing the `workflow_*` tools (branch setup, PR create/context, docs validate/promote, YouTrack post/log/time, templates, rules, presentation, doctor, handoff).
+- Session-start contract hook.
+- 4 rules and 12 `wk-*` skills (plus 14 sanitized Superpowers skills).
+
+## Host limitations
+
+Cursor adapts workit through policy-only confirmation: approvals and commits are recorded as policy decisions (`attested: false`) rather than fabricated delegated identity, and subagent-driven plan execution is not supported on this host. OpenCode records native `question` receipts and runs delegated tasks; see the root [README](../../README.md#host-capabilities) for the full host-capability matrix.
+
+## Configuration
+
+- Plugin metadata: `packages/workit-cursor/.cursor-plugin/plugin.json` (`name: "workit"`, `displayName: "Workit"`).
+- MCP server: `mcp.json`.
+- Session-start hook: `hooks/hooks-cursor.json`.
+- Rules: `rules/` (`ask-question-only.mdc`, `cursor-todowrite.mdc`, `no-worktrees.mdc`, `sdd-docs-path.mdc`).
+- Skills: `skills/` (12 `wk-*`) and `vendor/superpowers/skills/` (14).
+
+## Runtime
+
+Cursor launches the MCP server and session-start hook through `npx`, so the shipped manifests contain no repository-relative `dist` paths:
+
+- **MCP server** — `npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-mcp ${workspaceFolder}`. It speaks the MCP stdio protocol; `stdout` is reserved for protocol messages and diagnostics go to `stderr`.
+- **Session-start hook** — `npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-session-start`. It emits valid hook output and a diagnostic on runtime failure, and remains fail-open where Cursor's hook contract requires startup continuity.
+- `npx` startup or network failure is surfaced by Cursor as an MCP/hook startup failure; Workit never silently substitutes stale local runtime code.
+
+The runtime runs from the exact reviewed pin `@0.8.0`: Cursor reviews plugin metadata from Git, while npm serves the pinned runtime. Bumping the pin is a deliberate reviewed update, made only after the target npm version is public — never a mutable `latest` dist-tag. See [Update review](#update-review).
+
+## Security and data handling
+
+- **Secrets** — tokens are stored in files with mode 600 (`~/.config/workit/*.token`) and are never printed by tools; edit them locally.
+- **Logs** — a persistent JSONL journal records redacted structured diagnostics under the configuration directory; Cursor keeps `stderr` diagnostics for protocol safety, and `stdout` remains reserved for the MCP/hook protocol (the logger never writes to it).
+- **External interactions** — Git/VCS (branch resolution, PR/MR creation) and YouTrack (task updates, time logging) happen only when you invoke the corresponding tools; local setup copies files under `~/.cursor/plugins/local/workit` and `~/.config/workit/`.
+
+## Plugin layout
+
+| Path | Contents |
+| --- | --- |
+| `mcp/` + `dist/mcp-server.js` | MCP server entry (built). |
+| `hooks/` | session-start hook manifest. |
+| `rules/` | 4 `.mdc` rules. |
+| `skills/` | 12 `wk-*` skills. |
+| `vendor/superpowers/skills/` | 14 sanitized Superpowers skills. |
+| `.cursor-plugin/plugin.json` | authoritative plugin manifest. |
+
+## Package scripts
+
+```bash
+bun run build   # bundle dist/mcp-server.js, dist/cursor-session-start.js, sanitize vendor skills
+```
+
+From the repository root, `bun run validate:cursor-marketplace` validates the tracked Marketplace artifact against the official Cursor JSON schemas and clean-checkout invariants (component paths, frontmatter, logo, sanitized vendor parity, no ignored-`dist` runtime references).
+
+## Marketplace
+
+The repository root carries `.cursor-plugin/marketplace.json`, indexing `packages/workit-cursor` (plugin `workit` / `Workit`). Cursor installs Marketplace plugins from Git and does not build the repository, so all declared skills, rules, and assets are tracked and validated in CI — the runtime is launched from npm as described in [Runtime](#runtime).
+
+- **Installing from Marketplace** — a Marketplace admin adds the repository URL through Cursor's authenticated publisher flow; end users then install the plugin from the Cursor Marketplace UI, which reads `.cursor-plugin/plugin.json` and the tracked components directly from Git.
+- **Submission** — Marketplace submission is a separate, later authenticated action at `https://cursor.com/marketplace/publish`. It is **not** performed here and no publication or acceptance is claimed; the repository is kept validated and submission-ready.
+- **Update review** — Git plugin metadata (manifest, rules, skills, assets) is reviewed by Cursor on Marketplace updates, while the npm runtime is pinned to the exact reviewed `@0.8.0`. Bumping that pin in `mcp.json` / `hooks-cursor.json` is a deliberate reviewed change: only after the target npm version is public, never a mutable `latest` dist-tag.
+- **Troubleshooting** — `workit doctor` (or the `workflow_doctor` tool) reports installation health including runtime, token, VCS/YouTrack, and log-writability checks; it exits nonzero on failure. An MCP/hook startup failure with no network is an `npx`/registry reachability issue, not a Workit defect.
 
 ## Docs
 

package/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#111827"/>
+  <path d="M18 33l10 10 18-20" fill="none" stroke="#34d399" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/mcp-server.js

@@ -21826,7 +21826,7 @@ var SUPPORT_MATRIX;
 var init_support_matrix = __esm(() => {
   SUPPORT_MATRIX = {
     bun: "1.3.14",
-    node: { minimum: "20", current: "22" },
+    node: { minimum: "22", current: "22" },
     opencode: { minimum: "1.15.0", current: "1.17.7" },
     os: ["ubuntu-latest", "macos-latest", "windows-latest"]
   };
@@ -21837,9 +21837,15 @@ function isWorkitPlugin(value) {
   const s = String(value).replaceAll("\\", "/");
   const url = s.startsWith("file://") || s.startsWith("git+file://");
   const pkgPath = s.includes("/packages/workit-opencode/") || s.includes("/packages/workit-cursor/") || s.includes("/node_modules/@brainervirus/workit-opencode/") || s.includes("/node_modules/@brainervirus/workit-cursor/");
-  return named(s, "workflow-toolkit") || named(s, "workflow-toolkit-opencode") || named(s, "local/workflow-toolkit") || named(s, "@brainervirus/workit-opencode") || named(s, "@brainervirus/workit-cursor") || url && pkgPath || s.startsWith("git+file://") && s.includes("workflow-toolkit");
+  return named(s, "workflow-toolkit") || named(s, "workflow-toolkit-opencode") || named(s, "local/workflow-toolkit") || named(s, "workit") || named(s, "local/workit") || named(s, "@brainervirus/workit-opencode") || named(s, "@brainervirus/workit-cursor") || url && pkgPath || s.startsWith("git+file://") && s.includes("workflow-toolkit");
 }
-var named = (s, name) => s === name || s.startsWith(`${name}@`);
+function cursorHooksEntry(_packageDir) {
+  return {
+    command: `npx -y --package=${CURSOR_RUNTIME_PACKAGE} workit-cursor-session-start`,
+    args: []
+  };
+}
+var named = (s, name) => s === name || s.startsWith(`${name}@`), CURSOR_RUNTIME_PACKAGE = "@brainervirus/workit-cursor@0.8.0";
 var init_registration = () => {};
 
 // packages/workit-core/src/core/skill-manifests.ts
@@ -21940,7 +21946,7 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
     opencodeConfig: options.opencodeConfig ?? path9.join(home, ".config", "opencode", "opencode.json"),
     cursorSettings: options.cursorSettings ?? path9.join(home, ".cursor", "settings.json"),
     cursorMcp: options.cursorMcp ?? path9.join(home, ".cursor", "mcp.json"),
-    cursorPluginDir: options.cursorPluginDir ?? path9.join(home, ".cursor", "plugins", "local", "workflow-toolkit"),
+    cursorPluginDir: options.cursorPluginDir ?? path9.join(home, ".cursor", "plugins", "local", "workit"),
     env,
     installer: options.installer ?? false
   };
@@ -22108,7 +22114,6 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
       return [
         path9.join(pkg, "assets", "templates", "spec-template.md"),
         path9.join(pkg, "mcp.json"),
-        path9.join(pkg, "marketplace.json"),
         path9.join(pkg, ".cursor-plugin")
       ];
     case "cli":
@@ -22149,11 +22154,8 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
       return [[path9.join(pkg, "src", "plugin.ts"), path9.join(pkg, "dist", "plugin.js")]];
     case "cursor":
       return [
-        [path9.join(pkg, "dist", "mcp-server.js"), path9.join(pkg, "mcp", "run-server.sh")],
-        [
-          path9.join(pkg, "dist", "cursor-session-start.js"),
-          path9.join(pkg, "hooks", "session-start")
-        ]
+        [path9.join(pkg, "dist", "mcp-server.js")],
+        [path9.join(pkg, "dist", "cursor-session-start.js")]
       ];
     case "cli":
       return [[path9.join(pkg, "src", "index.tsx"), path9.join(pkg, "dist", "index.js")]];
@@ -22184,24 +22186,54 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
     return "invalid";
   }
   const executable = path9.basename(command).toLowerCase();
+  if (executable === "npx" || executable === "npx.exe" || executable === "npx.cmd") {
+    if (args[0] !== "-y")
+      return "invalid";
+    if (args[1] !== `--package=${CURSOR_RUNTIME_PACKAGE}`)
+      return "invalid";
+    if (args[2] !== "workit-cursor-mcp")
+      return "invalid";
+    return { kind: "npx" };
+  }
   if (executable !== "node" && executable !== "node.exe")
     return "invalid";
   return {
+    kind: "node",
     runtime: command,
     entry: path9.isAbsolute(args[0]) ? args[0] : path9.resolve(path9.dirname(res.cursorMcp), args[0])
   };
+}, canonicalCursorHook, registeredCursorHook = (res) => {
+  const hooksFile = path9.join(res.cursorPluginDir, "hooks", "hooks-cursor.json");
+  if (!existsSync5(hooksFile))
+    return "invalid";
+  const config2 = readJson(hooksFile);
+  if (!config2)
+    return "invalid";
+  const sessionStart = config2.hooks?.sessionStart;
+  if (!Array.isArray(sessionStart) || sessionStart.length !== 1)
+    return "invalid";
+  const entry = sessionStart[0];
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+    return "invalid";
+  return typeof entry.command === "string" ? entry.command : "invalid";
 }, checkLauncher = (res) => {
   const dev = res.dev;
   const hosts = hostsFor(res.host);
   const registered = hosts.includes("cursor") ? registeredCursorLauncher(res) : null;
-  const runtime = registered && registered !== "invalid" ? registered.runtime : "node";
+  const runtime = registered && registered !== "invalid" && registered.kind === "node" ? registered.runtime : "node";
   const missing = hosts.includes("cursor") ? ["dist/mcp-server.js", "dist/cursor-session-start.js"].map((rel) => path9.join(res.cursorPluginDir, rel)).filter((p) => !validNodeEntry(p, runtime, res.env)).map((p) => `cursor: ${p}`) : [];
   if (hosts.includes("cursor")) {
     if (registered === "invalid") {
       missing.push(`cursor: canonical workit MCP launcher in ${res.cursorMcp}`);
-    } else if (registered && !validNodeEntry(registered.entry, registered.runtime, res.env)) {
+    } else if (registered && registered.kind === "node" && !validNodeEntry(registered.entry, registered.runtime, res.env)) {
       missing.push(`cursor: registered ${registered.entry}`);
     }
+    const hook = registeredCursorHook(res);
+    if (hook === "invalid") {
+      missing.push(`cursor: canonical session-start hook in ${path9.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")}`);
+    } else if (hook !== null && hook !== canonicalCursorHook) {
+      missing.push(`cursor: canonical session-start hook in ${path9.join(res.cursorPluginDir, "hooks", "hooks-cursor.json")} (registered ${hook})`);
+    }
   }
   if (dev) {
     missing.push(...hosts.filter((h) => h !== "cursor").flatMap((h) => launcherSlotsFor(h, dev).filter((slot) => !slot.some((p) => existsSync5(p))).map((slot) => `${h}: ${slot.join(" or ")}`)));
@@ -22308,7 +22340,10 @@ var TOKEN_PLACEHOLDER2 = "YOUR_TOKEN_HERE", findDevFromCwd = (cwd) => {
       if (keys.length > 1)
         problems.push(`cursor enables ${keys.length} workit plugin identities (${keys.join(", ")})`);
     }
-    const dirs = Array.isArray(settings?.plugin_dirs) ? settings.plugin_dirs.map(String).filter((d) => isWorkitPlugin(d) || d.includes("workflow-toolkit")) : [];
+    const dirs = Array.isArray(settings?.plugin_dirs) ? settings.plugin_dirs.map(String).filter((d) => {
+      const n = d.replaceAll("\\", "/").replace(/\/+$/, "");
+      return isWorkitPlugin(d) || n.endsWith("local/workit") || n.endsWith("local/workflow-toolkit");
+    }) : [];
     if (dirs.length > 1)
       problems.push(`cursor plugin_dirs has ${dirs.length} workit entries`);
   }
@@ -22484,6 +22519,7 @@ var init_doctor = __esm(() => {
   init_registration();
   init_workspaces();
   init_skill_manifests();
+  canonicalCursorHook = cursorHooksEntry("").command;
   RUN_CHECKS = [
     checkRuntime,
     checkVersions,
@@ -25234,7 +25270,7 @@ var init_setup_state = __esm(() => {
 
 // packages/workit-core/src/core/setup.ts
 import {
-  chmodSync,
+  copyFileSync as copyFileSync2,
   cpSync as cpSync2,
   existsSync as existsSync17,
   mkdirSync as mkdirSync11,

package/hooks/hooks-cursor.json

@@ -3,8 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "node",
-        "args": ["./dist/cursor-session-start.js"]
+        "command": "npx -y --package=@brainervirus/workit-cursor@0.8.0 workit-cursor-session-start"
       }
     ]
   }

package/mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "workit": {
-      "command": "node",
-      "args": ["./dist/mcp-server.js", "${workspaceFolder}"]
+      "command": "npx",
+      "args": ["-y", "--package=@brainervirus/workit-cursor@0.8.0", "workit-cursor-mcp", "${workspaceFolder}"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-cursor",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "private": false,
   "description": "Workit Cursor plugin: MCP server, hooks, rules, marketplace manifest (thin over @brainervirus/workit-core)",
   "keywords": [
@@ -17,17 +17,18 @@
     "type": "git",
     "url": "https://github.com/BrainerVirus/workit.git"
   },
+  "bin": {
+    "workit-cursor-mcp": "./dist/mcp-server.js",
+    "workit-cursor-session-start": "./dist/cursor-session-start.js"
+  },
   "files": [
     "dist/",
     "assets/",
-    "mcp/run-server.sh",
     "mcp.json",
-    "marketplace.json",
     ".cursor-plugin/",
     "rules/",
     "skills/",
     "vendor/superpowers/skills/",
-    "hooks/session-start",
     "hooks/hooks-cursor.json"
   ],
   "type": "module",
@@ -38,11 +39,11 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^0.7.1",
+    "@brainervirus/workit-core": "^0.8.1",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   }
 }

package/skills/wk-implement/SKILL.md

@@ -18,7 +18,7 @@ Use the returned `tasks[]` as ground truth. Cache each `section_text` for subage
 
 ## Step 2 — Load execution contract
 
-Resolve plugin root: `WORKFLOW_TOOLKIT_ROOT` env or `~/.cursor/plugins/local/workflow-toolkit/`.
+Resolve plugin root: `WORKFLOW_TOOLKIT_ROOT` env or `~/.cursor/plugins/local/workit/`.
 
 Load `templates/execution-contract.md`. Substitute `<SPEC_PATH>`, `<PLAN_PATH>`, `<BRANCH>`, `<SDD_DIR>`, `<TASK_LIST>` from MCP. If template missing, stop with error.
 

package/hooks/session-start

@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-# sessionStart — inject Superpowers workflow contract (RL-09: NO network sync).
-# Prefer the self-contained Node bundle (dist/cursor-session-start.js); fall back
-# to the dev TS entry via Bun. Fail-open: a missing runtime must not break start.
-set -euo pipefail
-
-SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
-if [ -f "$SCRIPT_DIR/../dist/cursor-session-start.js" ] && command -v node >/dev/null 2>&1; then
-  exec node "$SCRIPT_DIR/../dist/cursor-session-start.js"
-fi
-
-BUN_BIN="${BUN:-}"
-if [ -z "$BUN_BIN" ]; then
-  for candidate in "$HOME/.bun/bin/bun" /usr/local/bin/bun /usr/bin/bun; do
-    [ -x "$candidate" ] && BUN_BIN="$candidate" && break
-  done
-fi
-if [ -z "$BUN_BIN" ] || [ ! -x "$BUN_BIN" ]; then
-  printf '{}\n'
-  exit 0
-fi
-exec "$BUN_BIN" "$SCRIPT_DIR/session-start.ts"

package/marketplace.json

@@ -1,10 +0,0 @@
-{
-  "name": "workit",
-  "displayName": "Workit",
-  "description": "Workflow rails for agentic coding: specs, plans, YouTrack, CI-gated commits",
-  "publisher": "cristhofer-pincetti",
-  "version": "0.7.1",
-  "homepage": "https://github.com/BrainerVirus/workit",
-  "repository": "https://github.com/BrainerVirus/workit.git",
-  "license": "MIT"
-}

package/mcp/run-server.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-# Cursor MCP launcher: prefer the self-contained Node bundle (dist/mcp-server.js);
-# fall back to the dev TS entry via Bun.
-set -euo pipefail
-MCP_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
-if [ -f "$MCP_DIR/../dist/mcp-server.js" ] && command -v node >/dev/null 2>&1; then
-  exec node "$MCP_DIR/../dist/mcp-server.js" "$@"
-fi
-exec "${BUN:-bun}" "$MCP_DIR/run-server.ts" "$@"