Cursor plugin specification and official plugins
TypeScript
Rename gap cards to feedback for Cursor
Cursor Agent6490acce4d7f
diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 32866b1b..22061a26 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -19,7 +19,7 @@ Origin work.App's repository. It reads what the app uses from GitHub out of the code, mapsthat onto the live spec, and writes a porting brief with a capability table,the webhook fields your handlers read and where each comes from on Origin,-the scopes to request, a hello-world path, the gaps worth raising with Cursor,+the scopes to request, a hello-world path, feedback for Cursor,and the questions to settle first. It plans. It writes no code and estimatesno time.@@ -83,8 +83,8 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/## Where the brief goesThe porting skill writes `ORIGIN-PORTING-BRIEF.md` at the repository root and-prints its path. The gap cards and questions in the brief are yours to send-through whatever contact route you have with Cursor; Cursor wants them.+prints its path. The feedback entries and questions in the brief are yours to+send through whatever contact route you have with Cursor; Cursor wants them.## Licensediff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 68f2ec55..5a1a44c9 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -46,7 +46,7 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeatslacks a field the REST resource has, read the resource; see the per-fieldnotes under `#event-payloads`. Name the call for each such field. Then:- Check `origin-isms.md` before writing `gap`. Check `gap-bar.md` before- writing any card.+ writing any feedback entry.- A GitHub feature the Origin docs do not mention is `unknown` with aquestion. The question is how the team tells Cursor they need it.- A behavior the code depends on that the docs neither confirm nor deny@@ -64,7 +64,7 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeats- [ ] Every Origin cell names an `operationId`, slug, or anchor thatexists in the files fetched in step 1.- - [ ] Every `gap` row has a card, and the card quotes one of the five+ - [ ] Every `gap` row has a feedback entry, and the entry quotes one of the fivetradeoff tests in `gap-bar.md`.- [ ] Every `unknown` row has a question in § 7.- [ ] No row `origin-isms.md` labels `reshaped` is labeled `gap`; every@@ -80,7 +80,7 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeatsWriting port code or adapters. Choosing a language, framework, or client.Estimating in time. Asking for anything the codebase contains. Sending gap-cards to Cursor yourself; the brief carries them and the team sends them.+feedback to Cursor yourself; the brief carries it and the team sends it.## Reference files@@ -90,5 +90,5 @@ cards to Cursor yourself; the brief carries them and the team sends them.| `references/discovery.md` | Scanning the codebase. || `references/spec-mapping.md` | Building the index. Matching calls, events, and fields. || `references/origin-isms.md` | Labeling a missing GitHub feature. |-| `references/gap-bar.md` | Deciding whether a difference earns a card, and writing it. |+| `references/gap-bar.md` | Deciding whether a difference is feedback for Cursor, and writing the entry. || `references/brief-template.md` | Writing the output. |diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md b/origin-apps/skills/port-github-app-to-origin/references/brief-template.mdindex d50e4408..a5ac56f5 100644--- a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md+++ b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md@@ -8,7 +8,7 @@ unless the team's docs convention says otherwise) and print its path. Fillevery section. An empty section says so in one line rather than disappearing.Cite spec `operationId`s and `llms-full.txt` anchors. Cite the team's code by`file:line`. One table row per capability, one line per follow-up field, one-card per gap. The team should be able to review it in one sitting.+feedback entry per gap. The team should be able to review it in one sitting.## Labels@@ -19,8 +19,8 @@ card per gap. The team should be able to review it in one sitting.| `same` | Same capability, same shape. A path or field rename at most. || `reshaped` | Same capability, different shape (pagination, identifier form, event granularity, key semantics). The code changes, the behavior does not. || `workaround` | Same outcome by a different route (follow-up read, client-side filter, marker). The Tradeoff column is mandatory. |-| `not-available` | Nothing in the current spec covers it (`origin-isms.md` or `#current-limitations`). Names the closest idiom and has a question in § 7; eligible for a card. |-| `gap` | No workaround, or one that fails `gap-bar.md`. Has a card in § 6. |+| `not-available` | Nothing in the current spec covers it (`origin-isms.md` or `#current-limitations`). Names the closest idiom and has a question in § 7; eligible for a feedback entry. |+| `gap` | No workaround, or one whose tradeoff meets the bar in `gap-bar.md`. Has a feedback entry in § 6. || `unknown` | Discovery or the spec could not answer. Has a question in § 7. || `preview` (suffix) | The row touches an element badged `x-cursor-visibility: PREVIEW` (`llms-full.txt#preview`). |@@ -30,7 +30,7 @@ card per gap. The team should be able to review it in one sitting.| --- | --- || S | Adapter or client layer. A path, header, identifier, or pagination rewrite, or a re-keyed lookup. || M | A new code path. A follow-up read where the payload used to suffice, a handshake step, a new handler, a data-model change for a new identifier or version concept. |-| L | A product or architecture change. A flow that depended on user OAuth, a customer-visible behavior, a dependency on native repositories, an open gap card. |+| L | A product or architecture change. A flow that depended on user OAuth, a customer-visible behavior, a dependency on native repositories, an open feedback entry. |## Template@@ -86,7 +86,7 @@ dependency makes on the app's behalf, marked as such.| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | none | none |The Origin column names an `operationId`, a slug, a `llms-full.txt` anchor,-or `none`. `workaround` rows fill Tradeoff. `gap` rows link their card.+or `none`. `workaround` rows fill Tradeoff. `gap` rows link their feedback entry.`not-available` rows name the closest idiom and their question. `unknown`rows name their question.@@ -127,15 +127,16 @@ each spec-silent behavior the brief depends on.first.7. Smallest write from § 3 succeeds with the scopes from the § 3 line.-## 6. Gaps worth raising+## 6. Feedback for Cursor-Zero or more cards in the `gap-bar.md` shape. If zero, write "No row met-the gap bar. The workarounds in § 3 carry their tradeoffs, and § 7 carries-the asks." Cursor reads both sections.+Capabilities Origin should add, one entry per `gap` row in the `gap-bar.md`+format. If none, write "No row met the feedback bar; the workarounds in § 3+carry their tradeoffs."## 7. Questions for the team-Always the first three, then what discovery left open.+Decisions the team must make before the port, not asks of Cursor. Always the+first three, then what discovery left open.1. Native repositories (or stable outbound mirrors), or repositories mirroredfrom GitHub? Decides whether the app receives events and can write.diff --git a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.mdindex c6828ba2..0b56fc54 100644--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md@@ -1,26 +1,28 @@-# The gap bar and the escalation card+# The feedback bar and the feedback formatCursor wants to hear what the team needs from Origin. Raise anything thatblocks the team's core flow, costs them correctness, security, or scale, orthat they would simply like Origin to do. The bar below decides whether an-item is a card or a question, not whether to speak up. Its other job is+item is feedback for Cursor or a question for the team, not whether to speak+up. Its other job isordering: put the asks that block the port ahead of the ones that areconveniences, so the important ones are read first. When a difference has aworkaround, writing the row as `workaround` with its tradeoff and a question-is often the right answer; a card adds the tradeoff analysis Cursor needs to-prioritize it.+is often the right answer; a feedback entry adds the tradeoff analysis Cursor+needs to prioritize it.- A difference is any row whose parity label is not `same`.- A workaround reaches the same outcome with the current API by another route. Afollow-up read, a re-keyed identifier, a path change, a client-side filter,a marker the app controls.- A gap is a difference with no workaround, or a workaround whose tradeoff- meets one of the five tests below. Gaps become cards; everything else the- team wants to raise becomes a question in § 7.+ meets one of the five tests below. Gaps become feedback entries in § 6:+ capabilities Origin should add. Things the team must decide go to § 7 as+ questions; the two sections do not repeat each other.## Nontrivial tradeoff-At least one should hold for a card. Quote it on the card.+At least one should hold for a feedback entry. Quote it in the entry.| Tradeoff | Test || --- | --- |@@ -30,21 +32,21 @@ At least one should hold for a card. Quote it on the card.| Customer-visible behavior | The workaround changes what the team's users see or can do, not how the code is organized. || Load-bearing | The capability sits on the hello-world path or the team's stated core flow. |-## Usually a workaround or a question, not a card+## Usually a workaround or a question, not feedback- Anything `origin-isms.md` labels `reshaped`: a documented path exists.- A field or filter the code does not use.- A GitHub convenience (`Link` pagination, numeric IDs, `html_url`) where theOrigin convention is a mechanical substitution.- Anything the changelog says shipped or the spec already carries. Re-read the- live spec before writing any card.+ live spec before writing any feedback entry.- A concept the Origin docs do not mention. That is `not-available` or`unknown` with a question; the team should still ask if they need it.- A GitHub Search query, when the spec has no search operation for thatresource. The idiom is a list operation with its filters plus a client-sidepredicate. A sorted list read that stops at a cutoff costs proportional to- the matches, not the collection. If that count meets the bar, the card is- usually about a filter rather than search.+ the matches, not the collection. If that count meets the bar, the feedback+ is usually about a filter rather than search.## One pattern that does meet the bar@@ -52,16 +54,16 @@ A state change the app reacts to that has no event, when reacting to exactlythat change is the app's purpose and the state is invisible until anunrelated event arrives. Reading it off the next snapshot fails on correctnessand customer-visible behavior when the app is a gate (a check, a block, a-notification). Write the card about the event. When the app only logs or+notification). Write the feedback entry about the event. When the app only logs ortidies up on that change, a question is enough.-## The card+## The feedback format-One per gap, in the brief's "Gaps worth raising" section. Write it so Cursor-can act without a call.+One entry per gap, in the brief's "Feedback for Cursor" section. Write it+so Cursor can act without a call.```markdown-### Gap: <capability, in Origin terms>+### Feedback: <capability, in Origin terms>- **GitHub call, event, or permission:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.- **What the app needs from it:** <data or effect, one sentence>.@@ -76,8 +78,9 @@ can act without a call.Describe the capability rather than proposing scope, field, or route names;that leaves Cursor free to fit it to the API's conventions. One capability-per card. Do not send cards yourself: the team decides what goes out, and-they are encouraged to send both the cards and the § 7 questions to Cursor+per entry. Do not send feedback yourself: the team decides what goes out,+and they are encouraged to send the feedback entries, and any § 7 questions+they want Cursor's view on, to Cursorthrough whatever contact route they have, quoting the spec version and anyrequest ID from failed calls (`llms-full.txt#errors`). A reply of "here isthe idiom" or "not planned" is useful too; record it in the brief with thediff --git a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.mdindex 576d2418..31329c29 100644--- a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md+++ b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md@@ -3,8 +3,9 @@Check here before labeling anything `gap`. Each row names the label to useand where the Origin answer lives today (an anchor in `llms-full.txt` unlessnoted). `reshaped` rows have a documented path, so they get a question if-the team wants the GitHub shape back rather than a card. `not-available`-rows get a question, and a card if they meet the gap bar.+the team wants the GitHub shape back rather than a feedback entry.+`not-available` rows get a question, and a feedback entry if they meet the+bar.Read the source; do not copy this table into the brief.| GitHub call, event, or permission | Label | Where the Origin answer lives |@@ -17,9 +18,9 @@ Read the source; do not copy this table into the brief.| Permissions `<noun>: read\|write` | `reshaped` | `#scopes`; `x-origin-scopes` per operation || Numeric IDs, `/repositories/{id}` | `reshaped` | `#ids`, `#repository-paths` || `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `#pagination` |-| GraphQL | `not-available` | No GraphQL endpoint in the current spec. Decompose into REST calls and count the fan-out; a decomposition that fails the gap bar earns a card about that read. |+| GraphQL | `not-available` | No GraphQL endpoint in the current spec. Decompose into REST calls and count the fan-out; a decomposition that meets the feedback bar earns an entry about that read. || Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | `#check-runs` (check runs with a stable `key`) |-| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `not-available` | No Issues endpoints or events in the current spec. Pull request comments, threads, reviews, and labels cover the pull-request half. Ask what the team needs for the rest; an issue-driven app may earn a card. |+| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `not-available` | No Issues endpoints or events in the current spec. Pull request comments, threads, reviews, and labels cover the pull-request half. Ask what the team needs for the rest; an issue-driven app may earn a feedback entry. || `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `reshaped` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` || Repository webhook CRUD (`/repos/…/hooks`) | `reshaped` | Subscriptions are set per app through Create App / Update App `events` (`#events`). || App-manifest conversion | `reshaped` | App creation form or `CreateApp` (`#installation`, endpoint reference) |