Cursor plugin specification and official plugins
TypeScript
feat: add pr-review-canvas and docs-canvas plugins
Alex Vandak Maloney3b1d0271a91f
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.jsonindex 4df6677e..f3adf100 100644--- a/.cursor-plugin/marketplace.json+++ b/.cursor-plugin/marketplace.json@@ -42,6 +42,16 @@"name": "cli-for-agent","source": "cli-for-agent","description": "Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run."+ },+ {+ "name": "pr-review-canvas",+ "source": "pr-review-canvas",+ "description": "Render PR diffs as interactive Cursor Canvases organized for reviewer comprehension — groups changes by importance, separates boilerplate from core logic, and highlights tricky or unexpected code."+ },+ {+ "name": "docs-canvas",+ "source": "docs-canvas",+ "description": "Render documentation — architecture notes, API references, runbooks, and codebase walkthroughs — as a navigable Cursor Canvas with sections, table of contents, diagrams, and cross-references."}]}diff --git a/README.md b/README.mdindex e84e9a02..01f0fdcd 100644--- a/README.md+++ b/README.md@@ -11,6 +11,8 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc| `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Scaffold and validate new Cursor plugins. || `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality. || `cli-for-agent` | [CLI for Agents](cli-for-agent/) | Cursor | Developer Tools | Patterns for designing CLIs that coding agents can run reliably: flags, help with examples, pipelines, errors, idempotency, dry-run. |+| `pr-review-canvas` | [PR Review Canvas](pr-review-canvas/) | Cursor | Developer Tools | Render PR diffs as interactive Cursor Canvases organized for reviewer comprehension — groups changes by importance, separates boilerplate from core logic, and highlights tricky or unexpected code. |+| `docs-canvas` | [Docs Canvas](docs-canvas/) | Cursor | Developer Tools | Render documentation — architecture notes, API references, runbooks, and codebase walkthroughs — as a navigable Cursor Canvas with sections, table of contents, diagrams, and cross-references. |Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `[email protected]` in the manifest).diff --git a/docs-canvas/.cursor-plugin/plugin.json b/docs-canvas/.cursor-plugin/plugin.jsonnew file mode 100644index 00000000..0753370e--- /dev/null+++ b/docs-canvas/.cursor-plugin/plugin.json@@ -0,0 +1,28 @@+{+ "name": "docs-canvas",+ "displayName": "Docs Canvas",+ "version": "0.1.0",+ "description": "Render documentation — architecture notes, API references, runbooks, and codebase walkthroughs — as a navigable Cursor Canvas with sections, table of contents, diagrams, and cross-references.",+ "author": {+ "name": "Cursor",+ "email": "[email protected]"+ },+ "homepage": "https://github.com/cursor/plugins/tree/main/docs-canvas",+ "repository": "https://github.com/cursor/plugins",+ "license": "MIT",+ "keywords": [+ "cursor-plugin",+ "canvas",+ "documentation",+ "docs",+ "architecture",+ "reference"+ ],+ "category": "developer-tools",+ "tags": [+ "canvas",+ "documentation",+ "workflow"+ ],+ "skills": "./skills/"+}diff --git a/docs-canvas/CHANGELOG.md b/docs-canvas/CHANGELOG.mdnew file mode 100644index 00000000..ab578906--- /dev/null+++ b/docs-canvas/CHANGELOG.md@@ -0,0 +1,7 @@+# Changelog++All notable changes to this plugin will be documented here.++## 0.1.0 — initial release++- Added the `docs-canvas` skill: initial scaffold for rendering documentation (architecture notes, API references, runbooks, codebase walkthroughs) as a navigable Cursor Canvas with overview, table of contents, body sections, and references. Skill body is deliberately a starting outline and expected to iterate.diff --git a/docs-canvas/LICENSE b/docs-canvas/LICENSEnew file mode 100644index 00000000..ca2bba77--- /dev/null+++ b/docs-canvas/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Cursor++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/docs-canvas/README.md b/docs-canvas/README.mdnew file mode 100644index 00000000..577bdbf0--- /dev/null+++ b/docs-canvas/README.md@@ -0,0 +1,39 @@+# Docs Canvas++Cursor plugin for rendering documentation — architecture notes, API references, runbooks, and codebase walkthroughs — as a navigable Cursor Canvas instead of a flat markdown file.++## Status++This plugin is an **initial scaffold**. The skill structure is complete and the Canvas welcome page will surface it in the marketplace, but the skill body is intentionally a starting outline rather than a fully-tuned playbook. Expect iteration as the "docs on a canvas" pattern matures.++## What it includes++- `docs-canvas`: build a Canvas that presents structured documentation with an overview card, a navigable table of contents, mixed prose/code/diagram sections, and a references block.++## When to use++- Rendering architecture notes, design docs, or RFCs as something you can scan, not just read top-to-bottom.+- Turning a directory of markdown docs, or a single large doc, into a Canvas with jump navigation.+- Answering a codebase question with a layout richer than a single reply — sections, diagrams, tables, callouts.++Trigger it with phrases like "docs canvas", "documentation overview", "architecture walkthrough", "API reference page", or "render this doc as an interactive canvas".++## How it's organized++The skill expects a docs canvas to lead with:++1. **Overview** — short summary card: purpose, scope, audience.+2. **Table of contents** — sticky/pinned list of sections the reader can jump to.+3. **Body sections** — one per logical unit (architecture, API, examples, gotchas), mixing prose, code blocks, diagrams, callouts.+4. **References** — links to related docs, source files, RFCs, external material.++Those are a floor, not a ceiling — the skill encourages reaching for whatever representation (diagrams, tables, decision trees, worked examples) actually helps the reader for the specific topic.++## Requirements++- Cursor with Canvas enabled.+- Source material: a directory of markdown files, a single doc URL, an inline outline, or a codebase question to answer.++## License++MITdiff --git a/docs-canvas/skills/docs-canvas/SKILL.md b/docs-canvas/skills/docs-canvas/SKILL.mdnew file mode 100644index 00000000..f4336aaa--- /dev/null+++ b/docs-canvas/skills/docs-canvas/SKILL.md@@ -0,0 +1,54 @@+---+name: docs-canvas+description: >-+ Render a documentation-style Cursor Canvas that organizes architecture+ notes, API references, walkthroughs, and how-tos into a navigable layout+ with sections, tables of contents, and cross-references. Use when the+ user asks for a docs canvas, documentation overview, architecture+ walkthrough, API reference page, or wants to render structured+ documentation as an interactive canvas.+---++# Docs Canvas++Build a canvas that presents documentation — architecture notes, API references, design docs, runbooks, or codebase walkthroughs — as an interactive, navigable surface rather than as a flat markdown file.++> **Status:** placeholder. The skill structure is in place so the canvas+> welcome page can surface this plugin via the marketplace query, but the+> full skill body still needs to be written. Treat the steps below as a+> starting outline and refine as the docs canvas pattern matures.++## Prerequisites++Read `~/.cursor/skills-cursor/canvas/SKILL.md` first. It contains the generation policy, design guidance, slop rules, self-check, and file-path conventions you must follow. The full component and hook surface is declared in `~/.cursor/skills-cursor/canvas/sdk/index.d.ts` and its sibling `.d.ts` files — read them to discover exact exports and prop shapes rather than guessing.++## Gather the source material++Accept any of: a directory of markdown files, a single doc URL, an inline outline, or a question to answer from the codebase. Collect headings, code blocks, diagrams, and any cross-references between documents.++## Plan the canvas layout++Decide the top-level structure before writing any components. A docs canvas usually has:++1. **Overview** — A short summary card with the purpose of the doc, scope, and audience.+2. **Table of contents** — Navigable list of sections, ideally pinned or sticky so the reader can jump around.+3. **Body sections** — One section per logical unit (architecture, API, examples, gotchas). Each section can mix prose, code blocks, diagrams, and callouts.+4. **References** — Links to related docs, source files, RFCs, and external material.++## Render with canvas primitives++Prefer built-in canvas components over raw HTML:++- Use cards/sections to group related content visually.+- Use code blocks with syntax highlighting for snippets.+- Use diagrams (DAG layout, mermaid) for architecture.+- Use callouts for "Important", "Warning", "Note", "Deprecated".+- Use tables for API parameter lists and option matrices.++## Tone and content++Write reader-facing prose. Lead with the answer or the headline, then explain. Keep examples small and runnable. Cite source files with `code references` so readers can jump in.++## Be creative++The sections above are a floor, not a ceiling. The goal is the fastest possible path for the reader to understand the topic — so look at the source material in front of you and ask what representation would actually help. A diagram, a sequence chart, a side-by-side comparison, a decision tree, a glossary, a curated FAQ, a single large worked example — whatever fits.diff --git a/pr-review-canvas/.cursor-plugin/plugin.json b/pr-review-canvas/.cursor-plugin/plugin.jsonnew file mode 100644index 00000000..c8819d72--- /dev/null+++ b/pr-review-canvas/.cursor-plugin/plugin.json@@ -0,0 +1,29 @@+{+ "name": "pr-review-canvas",+ "displayName": "PR Review Canvas",+ "version": "0.1.0",+ "description": "Render PR diffs as interactive Cursor Canvases organized for reviewer comprehension — groups changes by importance, separates boilerplate from core logic, and highlights tricky or unexpected code.",+ "author": {+ "name": "Cursor",+ "email": "[email protected]"+ },+ "homepage": "https://github.com/cursor/plugins/tree/main/pr-review-canvas",+ "repository": "https://github.com/cursor/plugins",+ "license": "MIT",+ "keywords": [+ "cursor-plugin",+ "canvas",+ "pr-review",+ "code-review",+ "diff",+ "pull-request"+ ],+ "category": "developer-tools",+ "tags": [+ "canvas",+ "code-review",+ "pull-request",+ "workflow"+ ],+ "skills": "./skills/"+}diff --git a/pr-review-canvas/CHANGELOG.md b/pr-review-canvas/CHANGELOG.mdnew file mode 100644index 00000000..faa31c09--- /dev/null+++ b/pr-review-canvas/CHANGELOG.md@@ -0,0 +1,7 @@+# Changelog++All notable changes to this plugin will be documented here.++## 0.1.0 — initial release++- Added the `pr-review-canvas` skill: render a PR diff as a Cursor Canvas organised by reviewer importance, with pseudocode, example traces, and inline callouts for tricky hunks.diff --git a/pr-review-canvas/LICENSE b/pr-review-canvas/LICENSEnew file mode 100644index 00000000..ca2bba77--- /dev/null+++ b/pr-review-canvas/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Cursor++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/pr-review-canvas/README.md b/pr-review-canvas/README.mdnew file mode 100644index 00000000..0d7698a5--- /dev/null+++ b/pr-review-canvas/README.md@@ -0,0 +1,34 @@+# PR Review Canvas++Cursor plugin for rendering pull request diffs as an interactive Cursor Canvas organised for reviewer comprehension rather than file-tree order.++## What it includes++- `pr-review-canvas`: build a Canvas that presents a PR diff with core logic up top, wiring/integration condensed in the middle, and boilerplate summarised at the bottom; add pseudocode, example traces, and inline callouts for the parts that are genuinely tricky.++## When to use++- Reviewing a pull request and you want a walkthrough that surfaces the real risk, not a file-by-file diff.+- Summarising a stack of PRs for a human reviewer.+- Asking for a diff walkthrough, change-set overview, or "what actually changed here" view.++Trigger it with phrases like "PR review canvas", "review this PR on a canvas", "walk me through this diff on a canvas", or by pointing the agent at a PR URL / branch ref.++## How it's organized++The skill groups changes by reviewer value:++1. **Core logic** — new behaviour, algorithm changes, state transitions, API surface changes. Full diffs with context.+2. **Wiring & integration** — route registration, DI, config plumbing. Condensed.+3. **Boilerplate & mechanical** — imports, renames, generated code, formatting. Summarised as a list, no inline diffs unless directly relevant.++It then layers in pseudocode for dense logic, concrete before/after example traces for behaviour changes that are hard to predict from the diff, and inline callouts (`Subtle`, `Breaking`, `Race condition`, `Perf`) for genuinely surprising or risky hunks.++## Requirements++- Cursor with Canvas enabled.+- Access to the diff source: a local branch/ref (`git diff`), a GitHub PR URL or number (`gh pr diff`), or a Graphite stack (`gt` CLI / `gh`).++## License++MITdiff --git a/pr-review-canvas/skills/pr-review-canvas/SKILL.md b/pr-review-canvas/skills/pr-review-canvas/SKILL.mdnew file mode 100644index 00000000..2c873a64--- /dev/null+++ b/pr-review-canvas/skills/pr-review-canvas/SKILL.md@@ -0,0 +1,64 @@+---+name: pr-review-canvas+description: >-+ Render a PR diff review as a Cursor Canvas that groups changes by+ reviewer importance, separates boilerplate from core logic, and+ highlights tricky or unexpected code. Use when reviewing a pull+ request, summarizing a diff for review, or when the user asks for a+ PR review canvas, diff walkthrough, or change-set overview.+---++# PR Review Canvas++Build a canvas that presents a PR diff reorganized for reviewer comprehension — not in file-tree order.++## Prerequisites++Read `~/.cursor/skills-cursor/canvas/SKILL.md` first. It contains the generation policy, design guidance, slop rules, self-check, and file-path conventions you must follow. The full component and hook surface is declared in `~/.cursor/skills-cursor/canvas/sdk/index.d.ts` and its sibling `.d.ts` files — read them to discover exact exports and prop shapes rather than guessing.++## Gather the diff++Accept any of: a local branch/ref (`git diff`), a GitHub PR URL or number (`gh pr diff`), or a Graphite stack link (`gt` CLI or `gh`). Collect every file's path, additions, deletions, and hunks.++## Group changes for comprehension++Do **not** present files in alphabetical or tree order. Reorganize into sections ordered by reviewer value:++1. **Core logic** — New behavior, algorithm changes, state transitions, API surface changes. Show full diffs with surrounding context.+2. **Wiring & integration** — Route registration, dependency injection, config plumbing that connects the core logic. Condensed — enough to confirm correctness.+3. **Boilerplate & mechanical** — Import reordering, renames, generated code, formatting, type re-exports. Summarize as a list of file names and stats. No inline diffs unless specifically relevant.++Lead with core logic. The reviewer's attention is freshest at the top.++## Distill complex logic into pseudocode++When a core change involves dense or intricate logic — deeply nested conditions, state machines, retry/backoff flows, multi-step transformations — add a short pseudocode summary next to the diff. The pseudocode should strip away language syntax, error handling, and boilerplate to expose the essential algorithm or control flow in a few lines. This lets the reviewer confirm intent before reading the real code.++Only do this when the actual diff is hard to scan. Straightforward changes don't need a pseudocode mirror.++## Trace tricky logic on a concrete example++Pseudocode shows the shape of the change; an example trace shows it executing. When a hunk changes behavior in a way that's hard to predict from reading it — reordered effects, new short-circuits, altered edge cases — pick a concrete input and walk it through both the old and new code paths side-by-side, highlighting the step where they diverge and what the observable outcome is. Keep the input small and realistic.++Use this for genuinely surprising behavior changes, not every core hunk.++## Call attention to tricky things++When a hunk contains something surprising, risky, or easy to miss, visually separate it from the surrounding diff and pair it with a short tag (e.g. "Subtle", "Breaking", "Race condition", "Perf") and a one-sentence explanation so the reviewer sees the concern and the code together.++Reserve these callouts for genuinely tricky items — overuse destroys signal.++## Tone and content++Write reviewer-facing commentary, not a changelog. Focus on:+- **Why** something changed, not just what changed.+- Interactions between files — e.g. "The new validator in `core.ts` is invoked by the route added in `routes.ts`."+- Anything the diff alone doesn't make obvious.++Keep commentary terse. One or two sentences per note.++## Be creative++The sections above are a floor, not a ceiling. The goal is the fastest possible path for the reviewer to understand this specific change — so look at the diff in front of you and ask what representation would actually help. A tiny state diagram, a before/after call graph, a table of input→output pairs, a timeline of commits, a confidence annotation per file, a single large callout with everything else collapsed — whatever fits the change.++The canvas SDK has charts, tables, diff views, DAG layout, cards, stats, interactive state, and more. Reach for whichever components best serve the change at hand. A review of a refactor looks different from a review of a bug fix looks different from a review of a new feature — let the canvas reflect that.