Document Cursor native plugin testing

chubes4 · chubes4 · commit 3058a70afcb4 · 2026-06-18T13:57:16.000-04:00
diff --git a/README.md b/README.md
@@ -121,7 +121,7 @@ For manual smoke tests, open or copy the relevant folder from `plugins/` into th
 
 ## Cursor Publishing
 
-Cursor requires a standalone plugin repository. This repo remains the source of truth; the publishable Cursor repository lives at:
+Cursor requires a standalone native plugin repository. The generated Cursor package is not a VS Code extension, is not installed from a `.vsix`, and should not use VS Code Marketplace packaging or publishing tooling. This repo remains the source of truth; the publishable Cursor repository lives at:
 
 https://github.com/Automattic/wordpress-cursor-plugin
 
@@ -135,6 +135,16 @@ pnpm export:cursor -- --dry-run
 
 The dry run prints the exact subtree split and push commands without creating a split branch, pushing to the standalone repository, or mutating the standalone checkout.
 
+For local Cursor testing, install the generated package at Cursor's native local plugin path:
+
+```bash
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/wordpress-studio
+cp -R plugins/cursor ~/.cursor/plugins/local/wordpress-studio
+```
+
+Reload Cursor and confirm the local plugin contains `.cursor-plugin/plugin.json`, `README.md`, `mcp.json`, `rules/wordpress-studio.mdc`, and the full `skills/` tree. In Cursor's MCP or tools settings, confirm `wordpress-studio` and `wordpress-telemetry` are visible and enabled. In Cursor's rules and skills surfaces, confirm `rules/wordpress-studio.mdc` and the bundled WordPress skills are visible before submitting marketplace changes.
+
 When maintainers are ready to update the standalone repository, run the non-dry-run export from a clean source worktree:
 
 ```bash
@@ -143,4 +153,4 @@ pnpm export:cursor
 
 The export command runs `git subtree split --prefix=plugins/cursor` and pushes the result to `Automattic/wordpress-cursor-plugin` on `sync/from-build-with-wordpress`. Open or update a PR from that branch into the standalone repo's `main` branch.
 
-Before submitting or updating the Cursor listing, confirm the standalone branch includes the expected generated files, review `.cursor-plugin/plugin.json` listing metadata, verify the README and MCP setup match the generated source, and submit to Cursor only after the standalone repository PR is accepted.
+Before submitting or updating the Cursor listing, confirm the standalone branch includes the expected generated files, review `.cursor-plugin/plugin.json` listing metadata including rules, skills, and MCP server paths, verify the README and MCP setup match the generated source, repeat the local native-plugin test flow from `~/.cursor/plugins/local/wordpress-studio`, and submit to Cursor only after the standalone repository PR is accepted.
diff --git a/plugins/cursor/README.md b/plugins/cursor/README.md
@@ -2,7 +2,7 @@
 
 This Cursor plugin packages shared WordPress skills from the `build-with-wordpress` source repo as WordPress Studio.
 
-It is a Cursor plugin built from the same shared skills as the Codex and Claude Code plugins.
+It is a Cursor-native plugin built from the same shared skills as the Codex and Claude Code plugins. It is not a VS Code extension, it is not installed from a `.vsix`, and it should not be packaged with VS Code Marketplace tooling.
 
 - The generated `plugins/cursor/` folder uses Cursor's single-plugin layout
 - Cursor discovers plugin skills from `skills/`
@@ -11,6 +11,55 @@ It is a Cursor plugin built from the same shared skills as the Codex and Claude
 - WordPress request routing stays shared across surfaces
 - Studio-backed site, theme, block, plugin, and audit workflows stay shared
 
+## Local Cursor install and test flow
+
+Build the generated package first:
+
+```bash
+pnpm build
+```
+
+Install it into Cursor's local native plugin directory:
+
+```bash
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/wordpress-studio
+cp -R plugins/cursor ~/.cursor/plugins/local/wordpress-studio
+```
+
+For faster iteration from a source checkout, use a symlink instead of copying:
+
+```bash
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/wordpress-studio
+ln -s "$PWD/plugins/cursor" ~/.cursor/plugins/local/wordpress-studio
+```
+
+Reload Cursor after installing or updating the local plugin. The local plugin root should contain these files:
+
+- `.cursor-plugin/plugin.json`
+- `README.md`
+- `mcp.json`
+- `rules/wordpress-studio.mdc`
+- `skills/<skill>/SKILL.md` for each bundled skill
+
+## MCP visibility checks
+
+In Cursor's MCP or tools settings, confirm both plugin-provided servers are visible and enabled:
+
+- `wordpress-studio`, which launches `studio mcp`
+- `wordpress-telemetry`, which launches the bundled telemetry bootstrap from `mcp.json`
+
+If the servers are missing, inspect `~/.cursor/plugins/local/wordpress-studio/mcp.json`, confirm `studio --version` works in a normal shell, then reload Cursor.
+
+## Rules and skills visibility checks
+
+Confirm Cursor loads the plugin guidance before doing Marketplace or standalone-repo work:
+
+- The always-on rule from `rules/wordpress-studio.mdc` is available in Cursor's rules view or applies to WordPress requests.
+- The bundled skills are visible from the local plugin, including `wordpress-creator`, `site-creator`, `theme-creator`, `block-creator`, `plugin-creator`, `design-previews-creator`, `auditing`, and `studio`.
+- A WordPress site, theme, block, plugin, or audit request routes through the shared WordPress creator guidance and prefers Studio MCP tools before shell fallbacks.
+
 ## Standalone export and listing
 
 Build with WordPress is the source of truth for this generated package. The standalone Cursor plugin repository is https://github.com/Automattic/wordpress-cursor-plugin and should be updated through the repository export script, not by manually editing exported files.
@@ -23,9 +72,17 @@ pnpm verify
 pnpm export:cursor -- --dry-run
 ```
 
-When maintainers are ready to update the standalone repository, run `pnpm export:cursor` from a clean source worktree. The exporter creates a subtree split of `plugins/cursor/` and pushes it to `sync/from-build-with-wordpress` in the standalone repository.
+When maintainers are ready to update the standalone repository, run `pnpm export:cursor` from a clean source worktree. The exporter creates a subtree split of `plugins/cursor/` and pushes it to `sync/from-build-with-wordpress` in the standalone repository. Do not manually edit generated Cursor output in the standalone repository; fix the generator or shared skills here, rebuild, verify, and export.
+
+## Marketplace checklist
+
+Before submitting or updating the Cursor listing:
 
-Before submitting or updating the Cursor listing, confirm the exported standalone branch contains the expected `.cursor-plugin/plugin.json`, `README.md`, `mcp.json`, `rules/wordpress-studio.mdc`, and full `skills/` tree; review the listing-facing manifest fields for name, display name, version, description, author, homepage, repository, license, and keywords; then open or update the standalone repository pull request for review. Submit to Cursor only after the standalone repository PR is accepted.
+- Confirm the exported standalone branch contains the expected `.cursor-plugin/plugin.json`, `README.md`, `mcp.json`, `rules/wordpress-studio.mdc`, and full `skills/` tree.
+- Review the listing-facing manifest fields for name, display name, version, description, author, homepage, repository, license, keywords, rules, skills, and MCP server paths.
+- Install the standalone branch locally at `~/.cursor/plugins/local/wordpress-studio` and repeat the MCP, rules, and skills visibility checks above.
+- Open or update the standalone repository pull request from `sync/from-build-with-wordpress` into `main` and wait for review.
+- Submit to Cursor Marketplace only after the standalone repository PR is accepted and the local native-plugin test flow passes.
 
 It ships the shared skills from this repo so all supported surfaces stay aligned while we iterate on surface-specific packaging details.
 
diff --git a/scripts/build-plugins.mjs b/scripts/build-plugins.mjs
@@ -2179,7 +2179,7 @@ const pluginTargets = [
     manifestDir: ".cursor-plugin",
     manifestFileName: "plugin.json",
     manifestContents: cursorPluginManifest,
-    readmeIntro: `It is a Cursor plugin built from the same shared skills as the Codex and Claude Code plugins.
+    readmeIntro: `It is a Cursor-native plugin built from the same shared skills as the Codex and Claude Code plugins. It is not a VS Code extension, it is not installed from a \`.vsix\`, and it should not be packaged with VS Code Marketplace tooling.
 
 - The generated \`plugins/cursor/\` folder uses Cursor's single-plugin layout
 - Cursor discovers plugin skills from \`skills/\`
@@ -2188,6 +2188,55 @@ const pluginTargets = [
 - WordPress request routing stays shared across surfaces
 - Studio-backed site, theme, block, plugin, and audit workflows stay shared
 
+## Local Cursor install and test flow
+
+Build the generated package first:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
+Install it into Cursor's local native plugin directory:
+
+\`\`\`bash
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/wordpress-studio
+cp -R plugins/cursor ~/.cursor/plugins/local/wordpress-studio
+\`\`\`
+
+For faster iteration from a source checkout, use a symlink instead of copying:
+
+\`\`\`bash
+mkdir -p ~/.cursor/plugins/local
+rm -rf ~/.cursor/plugins/local/wordpress-studio
+ln -s "$PWD/plugins/cursor" ~/.cursor/plugins/local/wordpress-studio
+\`\`\`
+
+Reload Cursor after installing or updating the local plugin. The local plugin root should contain these files:
+
+- \`.cursor-plugin/plugin.json\`
+- \`README.md\`
+- \`mcp.json\`
+- \`rules/wordpress-studio.mdc\`
+- \`skills/<skill>/SKILL.md\` for each bundled skill
+
+## MCP visibility checks
+
+In Cursor's MCP or tools settings, confirm both plugin-provided servers are visible and enabled:
+
+- \`wordpress-studio\`, which launches \`studio mcp\`
+- \`wordpress-telemetry\`, which launches the bundled telemetry bootstrap from \`mcp.json\`
+
+If the servers are missing, inspect \`~/.cursor/plugins/local/wordpress-studio/mcp.json\`, confirm \`studio --version\` works in a normal shell, then reload Cursor.
+
+## Rules and skills visibility checks
+
+Confirm Cursor loads the plugin guidance before doing Marketplace or standalone-repo work:
+
+- The always-on rule from \`rules/wordpress-studio.mdc\` is available in Cursor's rules view or applies to WordPress requests.
+- The bundled skills are visible from the local plugin, including \`wordpress-creator\`, \`site-creator\`, \`theme-creator\`, \`block-creator\`, \`plugin-creator\`, \`design-previews-creator\`, \`auditing\`, and \`studio\`.
+- A WordPress site, theme, block, plugin, or audit request routes through the shared WordPress creator guidance and prefers Studio MCP tools before shell fallbacks.
+
 ## Standalone export and listing
 
 Build with WordPress is the source of truth for this generated package. The standalone Cursor plugin repository is https://github.com/Automattic/wordpress-cursor-plugin and should be updated through the repository export script, not by manually editing exported files.
@@ -2200,9 +2249,17 @@ pnpm verify
 pnpm export:cursor -- --dry-run
 \`\`\`
 
-When maintainers are ready to update the standalone repository, run \`pnpm export:cursor\` from a clean source worktree. The exporter creates a subtree split of \`plugins/cursor/\` and pushes it to \`sync/from-build-with-wordpress\` in the standalone repository.
+When maintainers are ready to update the standalone repository, run \`pnpm export:cursor\` from a clean source worktree. The exporter creates a subtree split of \`plugins/cursor/\` and pushes it to \`sync/from-build-with-wordpress\` in the standalone repository. Do not manually edit generated Cursor output in the standalone repository; fix the generator or shared skills here, rebuild, verify, and export.
+
+## Marketplace checklist
+
+Before submitting or updating the Cursor listing:
 
-Before submitting or updating the Cursor listing, confirm the exported standalone branch contains the expected \`.cursor-plugin/plugin.json\`, \`README.md\`, \`mcp.json\`, \`rules/wordpress-studio.mdc\`, and full \`skills/\` tree; review the listing-facing manifest fields for name, display name, version, description, author, homepage, repository, license, and keywords; then open or update the standalone repository pull request for review. Submit to Cursor only after the standalone repository PR is accepted.`,
+- Confirm the exported standalone branch contains the expected \`.cursor-plugin/plugin.json\`, \`README.md\`, \`mcp.json\`, \`rules/wordpress-studio.mdc\`, and full \`skills/\` tree.
+- Review the listing-facing manifest fields for name, display name, version, description, author, homepage, repository, license, keywords, rules, skills, and MCP server paths.
+- Install the standalone branch locally at \`~/.cursor/plugins/local/wordpress-studio\` and repeat the MCP, rules, and skills visibility checks above.
+- Open or update the standalone repository pull request from \`sync/from-build-with-wordpress\` into \`main\` and wait for review.
+- Submit to Cursor Marketplace only after the standalone repository PR is accepted and the local native-plugin test flow passes.`,
     includeMcpConfig: true,
     mcpConfigPath: "mcp.json",
     displayName: cursorPluginDisplayName,
diff --git a/scripts/verify-plugins.mjs b/scripts/verify-plugins.mjs
@@ -292,6 +292,28 @@ async function verifyCursorPlugin(skillNames) {
   if (!ruleRaw.includes("alwaysApply: true")) {
     throw new Error("Cursor rule is missing alwaysApply frontmatter");
   }
+
+  const readme = await readFile(path.join(cursorPluginDir, "README.md"), "utf8");
+  const requiredReadmePhrases = [
+    "Cursor-native plugin",
+    "not a VS Code extension",
+    "not installed from a `.vsix`",
+    "~/.cursor/plugins/local/wordpress-studio",
+    "Local Cursor install and test flow",
+    "MCP visibility checks",
+    "Rules and skills visibility checks",
+    "Marketplace checklist",
+    "wordpress-studio`, which launches `studio mcp`",
+    "wordpress-telemetry",
+    "Do not manually edit generated Cursor output",
+    "rules, skills, and MCP server paths",
+  ];
+
+  for (const phrase of requiredReadmePhrases) {
+    if (!readme.includes(phrase)) {
+      throw new Error(`Cursor README is missing required guidance: ${phrase}`);
+    }
+  }
 }
 
 async function verifyContinueOutput() {
