Merge pull request #83 from Automattic/cursor-listing-flow

Document Cursor plugin listing flow

Author: chubes4

README.md

@@ -123,18 +123,22 @@ Cursor requires a standalone plugin repository. This repo remains the source of
 
 https://github.com/Automattic/wordpress-cursor-plugin
 
-Update `skills/` and the Cursor generator here, then export `plugins/cursor/`:
+Update `skills/` and the Cursor generator here, then verify the generated output:
 
 ```bash
 pnpm build
 pnpm verify
-pnpm export:cursor
+pnpm export:cursor -- --dry-run
 ```
 
-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, then submit the standalone repo to Cursor.
+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 a dry run:
+When maintainers are ready to update the standalone repository, run the non-dry-run export from a clean source worktree:
 
 ```bash
-pnpm export:cursor -- --dry-run
+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.

docs/contributor-workflows.md

@@ -100,20 +100,31 @@ Expected MCP server names are:
 
 Cursor output has an additional publishing workflow because Cursor consumes a standalone plugin repository.
 
+Reviewable dry run:
+
 ```bash
 pnpm build
 pnpm verify
-pnpm export:cursor
+pnpm export:cursor -- --dry-run
 ```
 
-Dry run:
+The dry run prints the subtree split, push target, and cleanup command without creating a local split branch, pushing to the standalone repository, or touching a standalone checkout.
+
+Maintainer export:
 
 ```bash
-pnpm export:cursor -- --dry-run
+pnpm export:cursor
 ```
 
 The export script pushes a subtree split of `plugins/cursor` to `Automattic/wordpress-cursor-plugin` on `sync/from-build-with-wordpress`. Open or update a pull request from that branch to the standalone repository's `main` branch.
 
+Before submitting or updating the Cursor listing:
+
+1. Confirm the standalone branch contains `.cursor-plugin/plugin.json`, `README.md`, `mcp.json`, `rules/wordpress-studio.mdc`, and the generated `skills/` tree.
+2. Review `.cursor-plugin/plugin.json` for the listing-facing `name`, `displayName`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, `rules`, `skills`, and `mcpServers` fields.
+3. Confirm the standalone README describes the generated package, export source of truth, and MCP setup.
+4. Submit to Cursor only after the standalone repository PR is accepted.
+
 ## Manual smoke testing
 
 After verification passes, manually test representative generated output when the change affects runtime behavior:
@@ -165,7 +176,7 @@ Before requesting review:
 - [ ] `pnpm verify` passes locally or in CI.
 - [ ] Generated package diffs are expected and bounded.
 - [ ] Documentation is updated for public contracts, setup commands, generated files, or integration behavior.
-- [ ] Cursor export has been run or intentionally not run when `plugins/cursor/` changes.
+- [ ] Cursor export dry run has been run when `plugins/cursor/` changes, and non-dry-run export is intentionally run or intentionally deferred.
 
 ## Contributor design principles
 

docs/generated-outputs.md

@@ -172,26 +172,37 @@ The verifier checks generated files rather than source style. It should fail whe
 
 When adding a new surface, add generator code and a verification function in the same change. The verification function should prove the public files that users or agent marketplaces consume.
 
-## Cursor export contract
+## Cursor export and listing contract
 
 Cursor requires a standalone plugin repository. Build with WordPress remains the source of truth and exports `plugins/cursor/` to `Automattic/wordpress-cursor-plugin`.
 
-Normal export:
+Reviewable dry run:
 
 ```bash
 pnpm build
 pnpm verify
-pnpm export:cursor
+pnpm export:cursor -- --dry-run
 ```
 
-Dry run:
+The dry run prints the subtree split, push target, and cleanup command without creating a local split branch, pushing to the standalone repository, or touching a standalone checkout.
+
+Maintainer export:
 
 ```bash
-pnpm export:cursor -- --dry-run
+pnpm export:cursor
 ```
 
 The export script uses `git subtree split --prefix=plugins/cursor` and pushes the result to the standalone repository branch `sync/from-build-with-wordpress`. Open or update a pull request from that branch into the standalone repository's `main` branch.
 
+Listing/submission checklist:
+
+1. Confirm `pnpm build` and `pnpm verify` pass in Build with WordPress.
+2. Confirm `pnpm export:cursor -- --dry-run` prints the expected `plugins/cursor` subtree split and `sync/from-build-with-wordpress` push target.
+3. Confirm the exported branch contains `.cursor-plugin/plugin.json`, `README.md`, `mcp.json`, `rules/wordpress-studio.mdc`, and every shared skill under `skills/`.
+4. Review Cursor listing metadata in `.cursor-plugin/plugin.json`: `name`, `displayName`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, `rules`, `skills`, and `mcpServers`.
+5. Open or update the standalone repository PR and wait for review before submitting or updating the Cursor listing.
+6. Submit to Cursor only from the accepted standalone repository state, not from unreviewed generated output.
+
 ## Maintenance checklist
 
 Before opening a generated-output pull request:
@@ -201,7 +212,7 @@ Before opening a generated-output pull request:
 3. Run `pnpm build`.
 4. Run `pnpm verify`.
 5. Inspect generated package diffs for unexpected churn.
-6. If Cursor output changed, run the Cursor export flow when maintainers are ready to update the standalone plugin repository.
+6. If Cursor output changed, run the dry-run Cursor export flow for review and the non-dry-run export only when maintainers are ready to update the standalone plugin repository.
 
 ## Related documentation
 

plugins/cursor/README.md

@@ -11,6 +11,22 @@ 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
 
+## 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.
+
+From the source repository, verify the generated output first:
+
+```bash
+pnpm build
+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.
+
+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.
+
 It ships the shared skills from this repo so all supported surfaces stay aligned while we iterate on surface-specific packaging details.
 
 ## Included skills

scripts/build-plugins.mjs

@@ -2024,7 +2024,23 @@ const pluginTargets = [
 - Cursor discovers persistent guidance from \`rules/\`
 - Cursor discovers MCP servers from root \`mcp.json\`
 - WordPress request routing stays shared across surfaces
-- Studio-backed site, theme, block, plugin, and audit workflows stay shared`,
+- Studio-backed site, theme, block, plugin, and audit workflows stay shared
+
+## 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.
+
+From the source repository, verify the generated output first:
+
+\`\`\`bash
+pnpm build
+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.
+
+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.`,
     includeMcpConfig: true,
     mcpConfigPath: "mcp.json",
     displayName: cursorPluginDisplayName,

scripts/verify-plugins.mjs

@@ -19,6 +19,17 @@ const pluginName = "wordpress-studio";
 const pluginDisplayName = "WordPress Studio";
 const cursorPluginName = pluginName;
 const cursorPluginDisplayName = pluginDisplayName;
+const cursorPluginRepository = "https://github.com/Automattic/wordpress-cursor-plugin";
+const cursorRequiredKeywords = [
+  "wordpress",
+  "studio",
+  "wp-cli",
+  "cursor",
+  "site-creator",
+  "theme-creator",
+  "block-creator",
+  "plugin-creator",
+];
 const codexRootDir = path.join(root, "plugins", "codex");
 const codexPluginDir = path.join(codexRootDir, "plugins", pluginName);
 const codexMarketplacePath = path.join(
@@ -226,6 +237,36 @@ async function verifyCursorPlugin(skillNames) {
     throw new Error("Cursor plugin manifest has the wrong display name");
   }
 
+  if (manifest.version !== "0.3.0") {
+    throw new Error("Cursor plugin manifest has the wrong version");
+  }
+
+  if (!manifest.description?.includes("WordPress sites and applications")) {
+    throw new Error("Cursor plugin manifest is missing the listing description");
+  }
+
+  if (manifest.author?.name !== "Automattic") {
+    throw new Error("Cursor plugin manifest has the wrong author");
+  }
+
+  if (manifest.homepage !== "https://developer.wordpress.com/") {
+    throw new Error("Cursor plugin manifest has the wrong homepage");
+  }
+
+  if (manifest.repository !== cursorPluginRepository) {
+    throw new Error("Cursor plugin manifest has the wrong repository");
+  }
+
+  if (manifest.license !== "GPL-2.0-or-later") {
+    throw new Error("Cursor plugin manifest has the wrong license");
+  }
+
+  for (const keyword of cursorRequiredKeywords) {
+    if (!manifest.keywords?.includes(keyword)) {
+      throw new Error(`Cursor plugin manifest is missing keyword ${keyword}`);
+    }
+  }
+
   if (manifest.rules !== "./rules/") {
     throw new Error("Cursor plugin manifest is missing the rules path");
   }