Cursor plugin specification and official plugins
TypeScript
Plain-language pass over the skills and README
Cursor Agent74af145809e3
diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 3c0c4b68..dabd85fd 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -1,25 +1,25 @@# Origin AppsTwo skills for building on [Cursor Origin](https://cursor.com/docs/api/origin),-Cursor's code forge. They cover creating an Origin App, calling the API,-receiving webhooks, and bringing an existing GitHub App across. The plugin is+Cursor's code host. They cover creating an Origin App, calling the API,+receiving webhooks, and moving an existing GitHub App over. The plugin isskills only, so it runs in Cursor, Claude Code, Codex, and any agent thatreads [Agent Skills](https://agentskills.io).## What it includes-`origin-api` routes questions to the section of the Origin docs that answers-them and names the rules to check first (native versus mirrored repositories,-event subscriptions, webhook verification, scopes from the spec, opaque-tokens and IDs). Use it for any Origin work.+`origin-api` sends the agent to the section of the Origin docs that answers+its question and lists the rules to check first: native versus mirrored+repositories, event subscriptions, webhook verification, scopes from the+spec, opaque tokens and IDs. Use it for any Origin work.`port-github-app-to-origin` plans the move of an existing GitHub App. Run it-inside the app's repository. It reads what the app uses out of the code, maps-that onto the live Origin spec, and writes a porting brief: a capability-table, the webhook fields your handlers read and where each comes from on-Origin, the scopes to request, a first-run path, feedback for Cursor, and-the questions your team should settle first. It plans; it writes no code-unless you ask.+inside the app's repository. It reads what the app uses out of the code,+maps that onto the live Origin spec, and writes a porting brief with what+carries over and what does not, the webhook fields your handlers read and+where each comes from on Origin, the scopes to request, an end-to-end test+for your app, feedback for Cursor, and the questions your team has to+decide. It plans. It writes no code unless you ask.Both skills fetch the spec at run time and never name an endpoint from memory.@@ -46,8 +46,8 @@ refers to `origin-api`).## Requirements- Network access to `https://cursor.com/docs/api/origin/*` during the run.-- For the porting skill, read access to the app's source. Producing the brief- needs no Origin credentials. You follow the brief's hello-world path+- For the porting skill, read access to the app's source. Writing the brief+ needs no Origin credentials. You run the brief's end-to-end testafterwards.## Where the brief goesdiff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex e73c478d..d9094828 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -17,13 +17,14 @@ The docs are the source of truth. Do not name an endpoint, scope, event slug,header, or limit from memory. Where this file and the docs disagree, the docswin.-Under `https://cursor.com/docs/api/origin/`: `llms.txt` is the index and-links every section, endpoint, and webhook payload; `openapi.yaml` is the-contract (its `x-origin-*` extensions are summarized in "Endpoint-reference"); `llms-full.txt` is the whole reference in one file; `changelog`-says what moved. For one question, read `llms.txt` and fetch only the section-that answers it. Fetch `llms-full.txt` or `openapi.yaml` whole for broad work-such as a porting brief. Cite `operationId`s and section names.+The docs live under `https://cursor.com/docs/api/origin/`. `llms.txt` is+the index and links every section, endpoint, and webhook payload.+`openapi.yaml` is the contract, and "Endpoint reference" explains its+`x-origin-*` extensions. `llms-full.txt` is the whole reference in one file.+`changelog` says what moved. For one question, read `llms.txt` and fetch+only the section that answers it. Fetch `llms-full.txt` or `openapi.yaml`+whole when you need all of it, as a porting brief does. Cite `operationId`s+and section names.## Where to look@@ -33,7 +34,7 @@ such as a porting brief. Cite `operationId`s and section names.| Install flow and the callback receipt | "Installation", "Installation receipt" || Which scope an operation needs | `x-origin-scopes` on the operation; "Scopes" || What an installation can do on a mirrored repository | "Mirrored repositories" |-| Webhook headers, signature, envelope, retries, pausing, recovery | "Webhooks" |+| Webhook headers, signature, delivery format, retries, pausing, recovery | "Webhooks" || Which events exist and which arrive without subscribing | "Events" || Payload shapes | "Event payloads" || Pagination, errors, request IDs, repository paths, IDs | "Common conventions" |@@ -45,19 +46,19 @@ such as a porting brief. Cite `operationId`s and section names.## Rules to check first1. **Native or mirror.** An installation keeps its full scopes only on- native repositories and stable outbound mirrors, and some writes are- native-only (merging a pull request, changing the default branch); read- each operation's description for mirror limits. On a GitHub-sourced- mirror, every event except `repository.pushed` still arrives, and every- call beyond metadata and contents reads returns `403` ("Mirrored- repositories", "Events").-2. **Subscribe.** Only `installation.*` events arrive without a subscription;- a missing subscription is silence, not an error ("Events").+ native repositories (created on Origin) and stable outbound mirrors+ (Origin is the source and pushes to GitHub). Some writes work only on+ native repositories, such as merging a pull request or changing the+ default branch, so read each operation's description for mirror limits.+ On a repository mirrored from GitHub, every event except+ `repository.pushed` still arrives, and every call beyond metadata and+ contents reads returns `403` ("Mirrored repositories", "Events").+2. **Subscribe.** Only `installation.*` events arrive without a subscription.+ A missing subscription produces silence, not an error ("Events").3. **Verify, dedupe, acknowledge.** Verify the signature over the raw bodybefore parsing, dedupe on the delivery ID, return `2xx`, then process- ("Signature verification", "Retries", "Automatic disable"). The digest- step differs from Standard Webhooks; do not assume a generic verifier- passes.+ ("Signature verification", "Retries", "Automatic disable"). Origin signs+ a digest, which Standard Webhooks does not, so a generic verifier fails.4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`over the operations the app calls ("Scopes").5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDsdiff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex b177a46b..082b78bc 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -13,73 +13,76 @@ compatibility: >-# Port a GitHub App to an Origin App-Run inside the app's codebase. The output is a porting brief for the team plus-a Feedback for Cursor section they can send as is (`references/brief.md`).-This skill plans; it does not write or change code unless the user explicitly-asks after reading the brief. Follow the `origin-api` skill for the docs and-the rules to check first. Two rules on top:+Run this inside the app's codebase. The output is a porting brief for the+team plus a Feedback for Cursor section they can send as is+(`references/brief.md`). This skill plans. It does not write or change code+unless the user asks for that after reading the brief. Follow the+`origin-api` skill for the docs and the rules to check first. Two more rules:-1. **Discover, do not ask.** Read what the app uses out of the code. Anything- you cannot find becomes an open question.-2. **Feedback describes use cases, not the team's code.** Team-facing parts of- the brief may cite `file:line`. Feedback for Cursor names only what the- app needs to do and what Origin lacks for it, in Origin terms, with no file- paths, module names, framework internals, or repository names.+1. **Find it in the code, do not ask.** Read what the app uses out of its+ source. Anything you cannot find becomes a question for the team.+2. **Feedback describes use cases, not the team's code.** The team's parts of+ the brief may cite `file:line`. Feedback for Cursor says only what the app+ needs to do and what Origin lacks for it, in Origin terms, with no file+ paths, module names, framework details, or repository names.-## What to discover+## What to find-Record a `file:line` for each, and note what you looked for and did not find.+Record `file:line` for each item, and note what you looked for but did not+find.-- Declared permissions and events (manifest or IaC, if checked in; otherwise- derive from the calls).-- Webhook events handled, and every payload field each handler reads,- including fields used only for logging.-- REST and GraphQL call families, with the parameters and filters passed, the- response fields read, whether each runs per webhook or in a loop, and the- pagination style in use.-- Authentication: JWT algorithm, how the installation is identified after- install, token lifetime handling, any user sign-in and what it is for,- whether the app clones or pushes git.-- Webhook receiver: signature scheme, whether the raw body is available at- verification time, how deliveries are deduplicated.-- Calls a framework or helper library makes on the app's behalf (Probot's- receiver, token cache, and config loader; Octokit `App`'s installation and- repository listing; app-auth libraries). Read the dependency's docs and- list these as rows marked "from `<dependency>`".+- Declared permissions and events, from a manifest or infrastructure code+ if one is checked in. Otherwise derive them from the calls.+- Every webhook event the app handles, and every payload field each handler+ reads, including fields it only logs.+- Every REST and GraphQL call, with the parameters and filters the code+ passes, the response fields it reads, whether it runs on every webhook or+ in a loop, and how it paginates.+- Authentication: the JWT algorithm, how the app learns the installation ID+ after install, how it handles token expiry, any user sign-in and what it is+ for, and whether the app clones or pushes git.+- The webhook receiver: how it verifies signatures, whether it has the raw+ body when it verifies, and how it deduplicates deliveries.+- Calls a framework or library makes for the app. Probot's receiver, token+ cache, and config loader; Octokit `App`'s installation and repository+ listing; app-auth libraries. Read the dependency's docs and list these+ calls marked "from `<dependency>`".## How to map-Fetch `openapi.yaml` and `llms-full.txt` whole; a brief needs broad coverage.+Fetch `openapi.yaml` and `llms-full.txt` whole. A brief needs all of it.`rg -B1 -A4 'x-origin-scopes:' openapi.yaml` lists every operation with its-scope block; `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists every-event slug with its payload schema. Each endpoint and each payload family has-a docs section with its fields expanded to dotted paths.+scopes. `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists every event+slug with its payload schema. Each endpoint and each webhook payload type has+a docs section that spells out its fields as dotted paths.-- A name match is a candidate, not a result. Confirm by reading the- operation's description, parameters, and response fields against what the- code passes and reads. A missing parameter or field the code depends on is+- A matching name is a candidate, not an answer. Read the operation's+ description, parameters, and response fields against what the code passes+ and reads. If a parameter or field the code depends on is missing, that isa workaround or a gap, not a match.-- GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,- `/issues/{n}/labels` on a pull request) live under the pull request- endpoints. Used on real issues, see the crib in `references/brief.md`.-- GraphQL has no counterpart; decompose each document into REST calls and- record the fan-out.-- Scopes are the union of `x-origin-scopes.scopes` over the operations you- named, not a translation of the manifest.-- Each event and action pair maps to at most one slug in "Events"; the action- is part of the slug. A pair with no slug is not an event on Origin.-- For each payload field the code reads, record whether it is present, comes- from the envelope (`event.type` carries the action), needs a follow-up read- (say which operation and how many calls per event), is derivable, or is- absent. Payloads are snapshots; a field on the REST resource that the- payload lacks is a follow-up read.-- A capability the docs do not mention is not available today and gets a- question. A behavior the docs neither confirm nor deny gets a question plus- a first-run step that observes it, not an assumption carried over from- GitHub.+- GitHub's pull request calls that live under `/issues/{n}/…` (comments,+ labels) live under the pull request endpoints on Origin. If the code uses+ them on real issues, see "Where GitHub features live on Origin" in+ `references/brief.md`.+- Origin has no GraphQL. Break each query into REST calls and count the calls+ per event.+- The scopes to request are the union of `x-origin-scopes.scopes` over the+ operations you named. Do not translate the GitHub manifest.+- Each GitHub event and action pair maps to at most one slug in "Events". The+ action is part of the slug. A pair with no slug is not an event on Origin.+- For each payload field the code reads, record whether it is in the+ payload, in the delivery envelope around the payload (`event.type` carries+ the action), needs an extra read (say which operation and how many calls+ per event), can be computed from other fields, or is missing. Payloads are+ snapshots. A field the REST resource has but the payload lacks needs an+ extra read.+- A capability the docs never mention is not available today. Ask the team+ about it. A behavior the docs neither confirm nor deny gets a question plus+ a step in the end-to-end test that checks it. Do not assume it works the+ way it did on GitHub.## Before finishing-Every Origin claim resolves in the fetched files. Every gap has a feedback-entry naming a tradeoff. The feedback contains nothing that reveals the-team's internals. The summary names the native-or-mirror question.+Every claim about Origin points at something in the fetched files. Every gap+has a feedback entry that names its cost. The feedback reveals nothing about+the team's internals. The summary names the native-or-mirror question.diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief.md b/origin-apps/skills/port-github-app-to-origin/references/brief.mdindex ed6bd09a..34138071 100644--- a/origin-apps/skills/port-github-app-to-origin/references/brief.md+++ b/origin-apps/skills/port-github-app-to-origin/references/brief.md@@ -1,115 +1,128 @@-# The brief, the feedback, and the crib+# The brief and the feedback## The brief-One Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md` unless-the team's convention says otherwise); print its path. Budget about 800-words for a small app and about 2,000 for a large one; parts with nothing to-say collapse or disappear. Choose table shapes to fit the app. A good brief:--- leads with a summary: the verdict (ports as is, ports with workarounds,- blocked on X), the question that decides the rest (usually native or- mirror), and whether there is feedback for Cursor and if any of it blocks;-- lists only the capabilities that do not map straight across, each with- the Origin operation, slug, or docs section it maps to or a note that- nothing does, and closes the list with one line naming the rest- ("maps directly: 14 operations, covered by the scopes line"); shows a- payload field only when it is absent or needs a follow-up read; ends with- the scopes to request;-- gives an app-specific first-run path when it helps (events to select, the- mirror check, the first event and what it carries, the first write); skips- generic setup, which "Implementation checklist" covers;-- notes what drives the size of the port and how to roll it out (dual-run- or cutover), without time estimates;-- asks only what the team must decide, never restating a row;-- ends with two lines of provenance (spec `info.version` and fetch time;- codebase and commit) and then Feedback for Cursor, last and unnumbered.--Evidence for every app claim (`file:line`, or "from `<dependency>`"); every-Origin claim resolved against the fetched docs. If you want compact marks:-`maps` (a documented path exists), `workaround` (say the tradeoff),-`not-available` (nothing in the current spec; carries a question), `gap`-(produces a feedback entry).+Write one Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md`+unless the team names files differently) and print its path. Aim for about+800 words for a small app and about 2,000 for a large one. Leave out any part+that has nothing to say. Pick whatever table shape fits the app. A good brief:++- Opens with a summary. The verdict (ports as is, ports with workarounds, or+ blocked on X), the question that decides the rest (usually whether the+ repositories are native or mirrored), and whether there is feedback for+ Cursor and if any of it blocks the port.+- Lists only the capabilities that do not carry over as is. For each, the+ Origin operation, event slug, or docs section it maps to, or a note that+ nothing does. Closes the list with one line for the rest, such as "14+ operations map directly; see the scopes line". Shows a webhook payload+ field only when it is missing or needs an extra API call. Ends with the+ scopes to request.+- Describes an end-to-end test for this app when that helps. Which events to+ select, how to check the repository's mirror state, the first event that+ should arrive and what it should contain, the first write. Skip generic+ setup; the docs' "Implementation checklist" covers it.+- Says what makes the port big or small and how to roll it out (run both+ versions side by side, or cut over). No time estimates.+- Asks only the questions the team has to decide. Do not turn a finding into+ a question.+- Ends with two lines saying which spec version (`info.version` and fetch+ time) and which code commit the brief is based on, then Feedback for+ Cursor as the last section, without a number.++Back every claim about the app with `file:line`, or with "from+`<dependency>`" when a library does it for the app. Back every claim about+Origin with something in the fetched docs. If you want short labels in a+table, use plain ones: works as is, workaround (say the cost), not available+(ask the team), gap (write feedback).## Feedback for CursorCursor wants to hear what the team needs. Raise anything that blocks the-team's core flow, costs them correctness, security, or scale, or that they-would like Origin to do. The bar sorts items into feedback (a capability-Origin should add) and questions (decisions the team must make); it does not-decide whether to speak up.--A workaround reaches the same outcome by another route (a follow-up read, a-re-keyed identifier, a path change, a client-side filter, a marker the app-controls) and is often the right answer. It becomes a gap, and a feedback-entry, when its tradeoff is one of: fan-out that grows with repository or-activity size at the app's volume; a possibly wrong answer (heuristic own-row-matching, a pull request inferred from a SHA several versions share, a URL-whose format is not contractual); a broader scope, longer-lived token, or-user credential where an installation token should do; a change to what the-team's users see or can do; or a capability on the hello-world path or the-team's core flow. A state change the app exists to react to, with no event-and no other way to observe it, meets the bar. Something the docs never-mention is not available today and gets a question; it becomes feedback-only if it blocks the core flow.+team's main flow, costs them correctness, security, or scale, or that they+would like Origin to do. The tests below only sort items into feedback (a+capability Origin should add) and questions (decisions the team must make).+They never decide whether to speak up.++A workaround gets the same result another way, for example an extra read, a+different identifier, a changed path, filtering on the client, or a marker+the app controls. Often it is the right answer. It becomes a gap, and gets a+feedback entry, when it costs one of these:++- extra calls per event that grow with repository or activity size, at this+ app's volume;+- a possibly wrong answer, such as guessing which check run or comment is the+ app's own, inferring a pull request from a SHA that several versions+ share, or building a URL whose format the docs do not promise;+- a broader scope, a longer-lived token, or a user credential where an+ installation token should be enough;+- a change to what the team's users see or can do;+- a capability the app's main flow or its first end-to-end test depends on.++A state change the app exists to react to, with no event for it and no other+way to notice it, is also a gap. Something the docs never mention is not+available today and gets a question; it becomes feedback only if it blocks+the main flow.Not feedback, only a question or a note: a field or filter the code does not-use; a convention difference with a mechanical substitute; a documented+use; a convention that differs but has a mechanical substitute; a documenteddesign choice such as token lifetime or no GraphQL.-One entry per gap, in Origin terms, with nothing that reveals the team's-internals. When there is at least one, also write the section to-`ORIGIN-FEEDBACK.md` beside the brief; when there is none, no file and one-line saying so. The file carries no license header, repository name,-product name, or mention of another forge. A contradiction between the docs-and observed behavior goes in a short "Docs questions for Cursor" list at-the end of the feedback, not in the questions for the team. A suggested-shape:+Write one entry per gap, in Origin terms, with nothing that reveals the+team's internals. When there is at least one entry, also write the section+to `ORIGIN-FEEDBACK.md` next to the brief. When there is none, write no file+and say so in one line. The file carries no license header, repository name,+product name, or mention of another code host. If the docs and observed+behavior disagree, put that in a short "Docs questions for Cursor" list at+the end of the feedback, not in the team's questions. A suggested shape:```markdown### Feedback: <capability, in Origin terms>- **Use case:** the app needs to <do what, for whom>, <how often or at what volume>.- **Origin today:** <what is missing or costly; cite the closest operationId, slug, or section, or "no operation">.-- **Workaround considered:** <the route and the tradeoff that makes it insufficient, or "none found">.+- **Workaround considered:** <the route and the cost that makes it insufficient, or "none found">.- **Blocking?** yes / no, for which flow.- **Spec version checked:** <info.version>, <date>.```-Describe the capability rather than proposing scope, field, or route names.-The team sends the feedback, not you; before they do, they strip anything-that reveals their internals.--## Crib: where GitHub habits land on Origin--Check before calling anything a gap; confirm each in the fetched docs.--Documented path exists: install callback params → "Installation receipt";-RS256 app JWT → "App JWT"; long-lived installation tokens → "Installation-access token"; permissions → "Scopes" and `x-origin-scopes`; numeric IDs and-`/repositories/{id}` → "IDs", "Repository paths"; `Link` pagination and-totals → "Pagination"; commit statuses → check runs with a stable `key`-("Check runs"); `/issues/{n}/comments` and `/issues/{n}/labels` on a pull-request → the pull request endpoints; repository webhook CRUD → per-app-`events` on Create App / Update App; a single `pull_request` event with an-`action` field → one slug per action ("Events"); `x-github-*` headers and-HMAC → "Headers", "Signature verification"; inlined payload data (changed-files, before-SHA, URLs, profiles) → follow-up reads ("Resource references",-"Current limitations"); reviews keyed by commit SHA → `pullRequestVersion`;-finding own rows by actor → check-run `key`, or a marker the app controls;-writes on a repository mirrored from GitHub → metadata and contents reads-only, until it is a stable outbound mirror, and merging and default-branch-changes stay native-only ("Mirrored repositories"); user sign-in and acting-as a user → "Acting on behalf of users" (user confirmation receipt,-installation user tokens).--Not available in the current spec (question, and feedback if it blocks the-core flow): GraphQL (decompose); Issues (pull request comments, threads,-reviews, and labels cover the pull-request half); OAuth-app token mints;-arbitrary blob or tree writes (commit-from-files and pushes exist); user,-email, team, and member directory reads (reviewer identifiers resolve by-public id, email, or group slug); group membership and effective-permission-reads. For the last two, the workaround to name is a user token capped to a-repository and scopes: minting it returns `403` unless the user holds that-permission, so it doubles as a permission probe.--Crib rows go stale; the fetched docs win.+Describe the capability. Do not propose scope, field, or route names. The+team sends the feedback, not you, and they remove anything that reveals+their internals first.++## Where GitHub features live on Origin++Check this before calling anything a gap, then confirm in the fetched docs.+This list goes stale; the docs win.++Has an Origin equivalent: install callback parameters → "Installation+receipt"; RS256 app JWT → "App JWT"; long-lived installation tokens →+"Installation access token"; permissions → "Scopes" and `x-origin-scopes`;+numeric IDs and `/repositories/{id}` → "IDs", "Repository paths"; `Link`+pagination and total counts → "Pagination"; commit statuses → check runs+with a stable `key` ("Check runs"); `/issues/{n}/comments` and+`/issues/{n}/labels` on a pull request → the pull request endpoints;+repository webhook CRUD → the app's `events` list on Create App and Update+App; one `pull_request` event with an `action` field → one slug per action+("Events"); `x-github-*` headers and HMAC signatures → "Headers", "Signature+verification"; data GitHub inlines in payloads (changed files, before-SHA,+URLs, user profiles) → extra reads ("Resource references", "Current+limitations"); reviews keyed by commit SHA → `pullRequestVersion`; finding+the app's own check runs or comments by author → the check run `key`, or a+marker the app controls; user sign-in and acting as a user → "Acting on+behalf of users" (user confirmation receipt, installation user tokens).++Repositories mirrored from GitHub: an installation can only read metadata+and contents until the mirror becomes a stable outbound mirror (Origin is+the source and pushes to GitHub). Merging a pull request and changing the+default branch work only on native repositories, the ones created on Origin+("Mirrored repositories").++Not in the current spec (ask the team; feedback only if it blocks the main+flow): GraphQL (break each query into REST calls); Issues (pull request+comments, threads, reviews, and labels cover the pull request half);+OAuth-app token minting; writing arbitrary blobs or trees (commit-from-files+and pushes exist); looking up users, emails, teams, or members (reviewer+identifiers resolve by public id, email, or group slug); reading group+membership or a user's effective permission. For those last two, the+workaround to name is a user token limited to a repository and scopes.+Minting it returns `403` unless the user holds that permission, so it+doubles as a permission check.