Cursor plugin specification and official plugins
TypeScript
Frame gap cards and questions as feedback Cursor wants
Cursor Agentecb830457e53
diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 92d10dc3..32866b1b 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -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 in the brief are yours to send through-whatever contact route you have with Cursor.+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.## Licensediff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 897ba919..bce442db 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -47,9 +47,8 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeatsnotes under `#event-payloads`. Name the call for each such field. Then:- Check `origin-isms.md` before writing `gap`. Check `gap-bar.md` beforewriting any card.- - A GitHub feature the Origin docs never mention (Marketplace billing,- merge queues, Actions, Pages) is `unknown` with a question. It is never- `gap`.+ - A GitHub feature the Origin docs do not mention is `unknown` with a+ question. The question is how the team tells Cursor they need it.- A behavior the code depends on that the docs neither confirm nor deny(does event X fire in case Y? does `updatedAt` move on comments?) is aquestion plus a hello-world step that observes it. Never guess it intodiff --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 71114cfe..d50e4408 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 will argue over it in one sitting.+card per gap. The team should be able to review it in one sitting.## Labels@@ -129,8 +129,9 @@ each spec-silent behavior the brief depends on.## 6. Gaps worth raising-Zero or more cards in the `gap-bar.md` shape. If zero, write "No row failed-the gap bar. The workarounds in § 3 carry their tradeoffs." Do not pad.+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.## 7. Questions for the teamdiff --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 94e76c9b..c6828ba2 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,52 +1,59 @@# The gap bar and the escalation card-Most differences are not gaps. A brief that files every difference buries the-two or three that are worth raising. When in doubt, write the row as-`workaround` with the tradeoff and an open question, not as a card.+Cursor wants to hear what the team needs from Origin. Raise anything that+blocks the team's core flow, costs them correctness, security, or scale, or+that 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+ordering: put the asks that block the port ahead of the ones that are+conveniences, so the important ones are read first. When a difference has a+workaround, 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.- 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- fails one of the five tests below. Only gaps become cards.+ meets one of the five tests below. Gaps become cards; everything else the+ team wants to raise becomes a question in § 7.## Nontrivial tradeoff-At least one must hold. Quote it on the card.+At least one should hold for a card. Quote it on the card.| Tradeoff | Test || --- | --- |-| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files, or a full list scan to find one row), and the app's volume makes that budget-relevant. One bounded extra read per event is trivial. |+| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files, or a full list scan to find one row), and the app's volume makes that budget-relevant. One bounded extra read per event is a workaround. || Correctness risk | The workaround can return a wrong answer, not only a slower one. Heuristic "my own row" matching. Inferring a pull request from a SHA several versions share. Assembling a URL whose format is not contractual. || Security posture | The workaround needs a broader scope, a longer-lived token, or a user credential where an installation token should do. || 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. |-## Not a gap+## Usually a workaround or a question, not a card-- Anything `origin-isms.md` labels `reshaped`.+- 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 thelive spec before writing any card.-- A concept the Origin docs never mention (Marketplace billing, merge queues,- Actions, Projects). That is `unknown` plus a question.+- 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-side- predicate. A sorted list read that stops at a cutoff costs- proportional to the matches, not the collection. If that count fails the- bar, the card is about a filter, never about search.+ predicate. 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.-## One pattern that does clear the bar+## One pattern that does meet the barA 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. Do not write it when the app-only logs or tidies up on that change.+notification). Write the card about the event. When the app only logs or+tidies up on that change, a question is enough.## The card@@ -61,15 +68,17 @@ can act without a call.- **Why:** <what the app does with it, one sentence>.- **Closest Origin operation:** `<operationId>` / `<slug>` / none, and what it lacks.- **Workaround considered:** <it, or "none found">.-- **Tradeoff that fails the bar:** <one of the five, with the number or risk>.+- **Tradeoff that meets the bar:** <one of the five, with the number or risk>.- **Shape that would close it:** <a capability, not a design. "List pull requests whose head is this SHA", not a route or field name.>- **Blocking?** yes / no, for which flow.- **Spec version checked:** `<info.version>` on `<date>`.```-Do not propose scope, field, or route names. Do not batch unrelated-capabilities. Do not send cards yourself. The team decides what goes out,-through whatever contact route they have with Cursor, quoting the spec-version and any request ID from failed calls (`llms-full.txt#errors`). "Not-planned" or "here is the idiom" is a fine answer. Record it in the brief with-the label it earns.+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+through whatever contact route they have, quoting the spec version and any+request ID from failed calls (`llms-full.txt#errors`). A reply of "here is+the idiom" or "not planned" is useful too; record it in the brief with the+label it earns.diff --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 8e01de09..576d2418 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@@ -2,8 +2,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` unless-noted). `reshaped` rows have a documented path and get no card.-`not-available` rows get a question, and a card if they fail the gap bar.+noted). `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.Read the source; do not copy this table into the brief.| GitHub call, event, or permission | Label | Where the Origin answer lives |@@ -35,6 +36,5 @@ Read the source; do not copy this table into the brief.| Finding own check runs or comments by actor | `reshaped` | `#check-runs` (`key`); comments and reviews by a marker the app controls || Requested-reviewer team pages, `created_via` | `not-available` | Groups exist and resolve by slug; there is no group membership read in the current spec. |-A feature that is not on this list and that the Origin docs never mention-(Marketplace billing, merge queues, Actions, Pages, Projects) is `unknown`-with a question.+A feature that is not on this list and that the Origin docs do not mention+is `unknown` with a question.diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.mdindex 16c22e67..fccbe665 100644--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md@@ -85,11 +85,10 @@ event.## Out of domain and spec-silent-- A concept neither the spec nor `llms-full.txt` mentions (Marketplace- billing, merge queues, Actions, Pages, Projects, Discussions, HTML probes)- is `unknown` with an up-front question. It is never `gap`, because Origin- has not declined it, and never `not-available` on the strength of this- skill alone; only `origin-isms.md` rows earn that.+- A concept neither the spec nor `llms-full.txt` mentions is `unknown`+ with an up-front question rather than `gap`: there is no Origin answer yet+ to compare against, and the question is how the team tells Cursor they+ need it. Use `not-available` only for `origin-isms.md` rows.- A behavior the code depends on that the docs do not state (does an eventfire for a draft pull request? does `updatedAt` move on a comment?) becomes an openquestion plus a hello-world step that observes it on a native repository.