Cursor plugin specification and official plugins
TypeScript
Final pass: partner audience, use-case feedback, guidance not procedure
Cursor Agent32bbb4e20c3a
diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 22061a26..8794cd71 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -8,20 +8,18 @@ reads [Agent Skills](https://agentskills.io).## What it includes-`origin-api` is the general skill. It sends the agent to the live OpenAPI-spec and docs for every fact, gives a table of which docs section answers-which question, and names the four rules to check first (native versus-mirrored repositories, event subscriptions, webhook verification, scopes-from the spec) plus how GitHub features map onto Origin. Use it for any-Origin work.--`port-github-app-to-origin` builds on `origin-api`. Run it inside your GitHub-App's repository. It reads what the app uses from GitHub out of the code, maps-that 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, feedback for Cursor,-and the questions to settle first. It plans. It writes no code and estimates-no time.+`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.++`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 hello-world path, feedback for Cursor, and+the questions your team should settle first. It plans; it writes no code+unless you ask.Both skills fetch the spec at run time and never name an endpoint from memory.@@ -34,8 +32,8 @@ Both skills fetch the spec at run time and never name an endpoint from memory.- Holding a GitHub App (Probot, Octokit, go-github, hand-rolled) and wantingto know what an Origin App version looks like before starting:`port-github-app-to-origin`.-- Checking which GitHub features map differently on Origin, and what to use- instead: either skill.+- Checking how a capability your app relies on today maps onto Origin:+ `port-github-app-to-origin`.In Cursor, ask about the Origin API or ask to port the app, or run`/origin-api` or `/port-github-app-to-origin`.@@ -83,8 +81,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 feedback entries 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 for Cursor section is written to be sent as is;+the rest of the brief is for your team.## Licensediff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex f0400dc0..f45fa68e 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -1,23 +1,24 @@---name: origin-apidescription: >-- Guides building on the Cursor Origin API: creating an Origin App,- authenticating as it, calling the REST API, receiving webhooks. Use whenever- code or a plan touches Origin endpoints, installation tokens, scopes, webhook- subscriptions or signatures, page tokens, or an Origin App manifest. Points- at the docs section that answers each question and names the few rules that- GitHub habits get wrong.+ Routes questions about the Cursor Origin API to the right section of the+ Origin docs and names the few rules to check first. Use when a task mentions+ Origin, the Origin API, Origin Apps, or Origin webhooks, including creating+ an Origin App, authenticating as one, calling Origin endpoints, or handling+ Origin webhook deliveries.license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.----# Build on the Origin API+# Origin API-The docs are the only source of truth. This skill tells you where to look and-which rules to check first. It restates nothing you can read there.+The docs are the source of truth. This skill says where to look and which+rules to check first; it does not restate the docs.-## Fetch first. Never name an endpoint, scope, slug, header, or limit from memory.+## Fetch first++Do not name an endpoint, scope, event slug, header, or limit from memory.- `https://cursor.com/docs/api/origin/openapi.yaml`: the contract. Its`x-origin-*` extensions are summarized under `#endpoint-reference`.@@ -26,56 +27,49 @@ which rules to check first. It restates nothing you can read there.- `https://cursor.com/docs/api/origin/llms.txt` (index) and`https://cursor.com/docs/api/origin/changelog` (what moved).-Lookup order: for one question, read `llms.txt` to find the section, then-fetch only that section of `llms-full.txt` or the page it links. Fetch the-whole `llms-full.txt` or `openapi.yaml` only when the task needs broad-coverage, such as a porting brief.+For one question, use `llms.txt` to find the section, then read only that+section. Fetch the whole `llms-full.txt` or `openapi.yaml` when the task+needs broad coverage, such as a porting brief.-Cite `operationId`s and `llms-full.txt` anchors. If this file and the fetched-docs disagree, the docs win.+Cite `operationId`s and `llms-full.txt` anchors. Where this file and the docs+disagree, the docs win.## Where to look| Question | Section of `llms-full.txt` || --- | --- |-| Which credential for which call; how to mint and how long it lives | `#authentication` through `#git-https-authentication` |+| Which credential for which call; minting and lifetime | `#authentication` through `#git-https-authentication` || Install flow and the callback receipt | `#installation`, `#installation-receipt` |-| Which scope an operation needs | `x-origin-scopes` on the operation; `#scopes` for the table and the rules |+| 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` and its subsections |-| Which events exist and which are delivered without subscribing | `#events` |-| Payload shapes and the `x-origin-webhook-events` extension | `#event-payloads` |+| Webhook headers, signature, envelope, retries, pausing, recovery | `#webhooks` |+| Which events exist and which arrive without subscribing | `#events` |+| Payload shapes | `#event-payloads` || Pagination, errors, request IDs, repository paths | `#common-conventions` || ID form and stability | `#ids` || What a `PREVIEW` badge means | `#preview` |-| Rate limits and headers | `#rate-limits` |+| Rate limits | `#rate-limits` || Check-run keys, attempts, stale writes | `#check-runs` || What is not there yet | `#current-limitations` || A checklist to build against | `#implementation-checklist` |## Rules to check first-In priority order. Each is one line in the docs; getting it wrong costs a-week.-1. **Native or mirror.** Confirm the target repositories are Origin-native- or stable outbound mirrors before anything else. On any other mirror- state an installation can only read, and pushes are not delivered- (`#mirrored-repositories`, `#events`).+ or stable outbound mirrors. On any other mirror state an installation can+ only read, and pushes are not delivered (`#mirrored-repositories`,+ `#events`).2. **Subscribe.** Only the `installation.*` events arrive without a- subscription. `#events` says what else delivery needs; a missing- subscription is silence, not an error.+ subscription; a missing subscription is 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 the Standard Webhooks spec, so do not assume a generic+ step differs from the Standard Webhooks spec; do not assume a genericverifier passes.4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`- over the operations the app calls, and nothing else (`#scopes`).-5. **Opaque tokens and IDs.** Page tokens and IDs are not yours to build or- parse (`#pagination`, `#ids`).--## Coming from GitHub+ over the operations the app calls (`#scopes`).+5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDs+ (`#pagination`, `#ids`).-Several GitHub conventions map differently on Origin. The-`port-github-app-to-origin` skill in this plugin covers the differences.+Porting an existing GitHub App: the `port-github-app-to-origin` skill in+this plugin covers how its capabilities map onto Origin.diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 5a1a44c9..5467e11e 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -1,11 +1,11 @@---name: port-github-app-to-origindescription: >-- Plans the port of an existing GitHub App to a Cursor Origin App. Use when a- repo is a GitHub App (manifest, Probot, Octokit or another GitHub SDK, webhook- signature handlers) and the task is to bring it to Origin or compare it with- the Origin API. Maps what the app uses from GitHub onto the live Origin spec- and writes a porting brief. No code.+ Plans the port of an existing GitHub App to a Cursor Origin App. Use when the+ task is to bring a GitHub App to Origin or compare what it uses against the+ Origin API. Reads the app's needs out of its code, maps them onto the live+ Origin spec, and writes a porting brief with feedback for Cursor. Planning+ only.license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.@@ -13,82 +13,67 @@ compatibility: >-# Port a GitHub App to an Origin App-Run inside the GitHub App's codebase. The output is a porting brief-(`references/brief-template.md`), not an implementation. It says what maps,-what changes shape, what is not available today, and what is worth raising-with Cursor.+Run inside the app's codebase. The output is a porting brief+(`references/brief-template.md`): what maps, what changes shape, what is not+available today, and what to tell Cursor. This skill plans; it does not write+or change code unless the user explicitly asks for that after reading the+brief.-The `origin-api` skill in this plugin covers which docs to fetch, credentials,-scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeats it. Two rules on top:+The `origin-api` skill in this plugin covers the docs and the rules to check+first; follow it. Two rules on top:1. **Discover, do not ask.** Read permissions, events, handlers, calls, token- minting, and the receiver out of the code. Never ask for a manifest or an- endpoint list. Anything you cannot find becomes an open question.-2. **Check the documented path first.** Anything in- `references/origin-isms.md` has a documented Origin path or a documented- limitation. Use the row's label; `not-available` rows still go through- the gap bar.+ minting, and the receiver 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 files and lines. The Feedback for Cursor section 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.-## Procedure+## Suggested procedure-1. **Load the spec** (`origin-api`, "Fetch first"). A brief needs broad- coverage, so fetch the full `openapi.yaml` and `llms-full.txt`; the- narrow lookup order in `origin-api` is for later single questions. Record- `info.version` and the fetch time for the brief's provenance. Build the- mapping index per `references/spec-mapping.md`.-2. **Discover** per `references/discovery.md`. Record a file and line for- every fact, including payload fields read only for logging and calls the- framework makes on the app's behalf. Note what you looked for and did not- find.-3. **Map** each inventory row (`references/spec-mapping.md`, "Matching") and- label it with the parity labels in the brief template. Map the webhook- payload fields the code reads, not only the event names. If a payload- lacks a field the REST resource has, read the resource; see the per-field- notes 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 feedback entry.- - 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 a- question plus a hello-world step that observes it. Never guess it into- `same` from GitHub behavior.-4. **Write the brief** from the template in full. Every Origin cell names an- `operationId`, a slug, or an `llms-full.txt` anchor. Sizes are S, M, or L,- never time.-5. **Close with the questions**, pruned to what discovery left open. The- first is always native or mirror, because it decides whether the app- receives events at all.-6. **Check the brief and fix.** Copy this list, tick each line, fix what- fails, and repeat until a pass changes nothing.+Adapt the steps to the app. The brief format matters most in its Feedback+section.- - [ ] Every Origin cell names an `operationId`, slug, or anchor that- exists in the files fetched in step 1.- - [ ] Every `gap` row has a feedback entry, and the entry quotes one of the five- tradeoff tests in `gap-bar.md`.- - [ ] Every `unknown` row has a question in § 7.- - [ ] No row `origin-isms.md` labels `reshaped` is labeled `gap`; every- `not-available` row has a question.- - [ ] Every event the code handles has a § 4 row for each payload field- it reads, including log-only fields.- - [ ] Calls the framework makes on the app's behalf appear as rows.- - [ ] The scopes line equals the union of `x-origin-scopes.scopes` over- the § 3 operations.- - [ ] Question 1 is native or mirror.+1. **Load the spec.** A brief needs broad coverage, so fetch the full+ `openapi.yaml` and `llms-full.txt`. Record `info.version` and the fetch+ time for provenance. Build the index per `references/spec-mapping.md`.+2. **Discover** per `references/discovery.md`, including payload fields read+ only for logging and calls the framework makes on the app's behalf. Note+ what you looked for and did not find.+3. **Map** each capability (`references/spec-mapping.md`) and label it with+ the parity labels in the brief template. Map the payload fields the code+ reads, not only the event names; if a payload lacks a field the REST+ resource has, a follow-up read is the usual answer (`#event-payloads`).+ Check `references/origin-isms.md` before labeling `gap`, and+ `references/gap-bar.md` before writing feedback. A capability the Origin+ docs do not mention is `unknown` with a question. A behavior the docs+ neither confirm nor deny becomes a question plus a hello-world step that+ observes it, rather than an assumption carried over from the app's+ current platform.+4. **Write the brief** from the template. Every Origin cell names an+ `operationId`, a slug, or an `llms-full.txt` anchor. Sizes are S, M, or L,+ not time.+5. **Self-check** before finishing: every Origin cell resolves in the fetched+ files; every `gap` row has a feedback entry that names a tradeoff from+ `gap-bar.md`; every `not-available` and `unknown` row has a question; the+ Feedback section contains nothing that reveals the team's internals; the+ first question is native or mirror.## Not in scope-Writing port code or adapters. Choosing a language, framework, or client.-Estimating in time. Asking for anything the codebase contains. Sending gap-feedback to Cursor yourself; the brief carries it and the team sends it.+Writing or changing code without the user's explicit ask. Choosing a+language, framework, or client. Estimating in time. Sending feedback to+Cursor yourself; the brief carries it and the team sends it.## Reference files| File | Read when || --- | --- |-| `origin-api` skill (install both) | First. Sources and fundamentals. |+| `origin-api` skill (install both) | First. Docs pointers and the rules to check. || `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 is feedback for Cursor, and writing the entry. |+| `references/origin-isms.md` | Labeling a capability that maps differently. |+| `references/gap-bar.md` | Deciding what 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 a5ac56f5..d17796ac 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@@ -3,12 +3,12 @@Contents: [Labels](#labels) (parity, size) and [Template](#template)(provenance, §§ 1-8).-Write one Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md`-unless the team's docs convention says otherwise) and print its path. Fill-every 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-feedback entry per gap. The team should be able to review it in one sitting.+A default shape; adapt it to the app. Write one Markdown file at the+repository root (`ORIGIN-PORTING-BRIEF.md` unless the team's docs convention+says otherwise) and print its path. Cite spec `operationId`s and+`llms-full.txt` anchors. Sections 1 to 5 and 7 are for the team and may cite+their code by `file:line`. Section 6 is for Cursor and must not reveal the+team's internals; its format is the part to keep exact.## Labels@@ -20,11 +20,11 @@ feedback entry per gap. The team should be able to review it in one sitting.| `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 feedback entry. |-| `gap` | No workaround, or one whose tradeoff meets the bar in `gap-bar.md`. Has a feedback entry in § 6. |+| `gap` | No workaround, or one whose tradeoff meets a test 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`). |-**Size** (kind of change, never time)+**Size** (kind of change, not time)| Size | Meaning || --- | --- |@@ -37,9 +37,9 @@ feedback entry per gap. The team should be able to review it in one sitting.```markdown# Origin porting brief for <app name>-Planning document. Maps what this GitHub App uses from GitHub onto the Cursor-Origin API as published on <date>. It makes no decisions about language,-framework, or client.+Planning document. Maps what this app uses today onto the Cursor Origin API+as published on <date>. It makes no decisions about language, framework, or+client.## Provenance@@ -68,20 +68,20 @@ it writes back. Then:## 2. First decision: which repositories-<What the code assumes about the repositories it acts on.> Apps have full-scopes only on Origin-native repositories and stable outbound mirrors.-Repositories mirrored from GitHub are read-only to apps and deliver no push-events. **Answer question 1 before attempting § 5.**+<What the code assumes about the repositories it acts on.> What an+installation can do on a mirrored repository is defined in+`llms-full.txt#mirrored-repositories` and `#events`. Answer question 1 before+attempting § 5.## 3. Capability table-One row per GitHub capability the code uses, grouped by facet with a bold-header row (Authentication · Installation & discovery · Configuration ·-Repositories & contents · Pull requests · Reviews & comments · Checks ·-Webhooks: events · Webhooks: receiver · Git). Include rows for calls a-dependency makes on the app's behalf, marked as such.+One row per capability the code uses today, grouped by facet (authentication,+installation and discovery, configuration, repositories and contents, pull+requests, reviews and comments, checks, webhook events, webhook receiver,+git). Include rows for calls a dependency makes on the app's behalf, marked as+such.-| GitHub thing (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question |+| Capability today (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question || --- | --- | --- | --- | --- | --- || `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | none | none |@@ -91,19 +91,18 @@ or `none`. `workaround` rows fill Tradeoff. `gap` rows link their feedback entryrows name their question.**Scopes to request:** the union of `x-origin-scopes.scopes` across every-Origin operation above that an installation token can call, minus ambient-and implied scopes (`write` implies `read`, and `repository:metadata:read` is-automatic). The install URL's `scope` parameter carries this list.+Origin operation above that an installation token can call, minus the scopes+`llms-full.txt#scopes` says are automatic or implied.## 4. Webhook payload fields the code reads-| Event (GitHub → Origin) | GitHub field | Origin | How |+| Event (today → Origin) | Field read today | Origin | How || --- | --- | --- | --- |-| `pull_request.synchronize` → `<slug>` | `pull_request.head.sha` | present | `payload.pullRequest.head.sha` |-| `push` → `<slug>` | `commits[].added` | follow-up read | `<operationId>`, one call per ref update |+| `<event.action>` → `<slug>` | `<field path>` | present | `payload.pullRequest.head.sha` |+| `<event>` → `<slug>` | `<field path>` | follow-up read | `<operationId>`, one call per ref update |"How" is one of five values. Present at `<path>`. Present in the envelope-(`event.type` for GitHub's `action`). Follow-up read via `<operationId>`,+(`event.type` carries the action). Follow-up read via `<operationId>`,with the call count per event. Derivable, saying from what and whether theformat is documented. Absent, pointing at the row's label in § 3. Includefields read only for logging.@@ -130,16 +129,18 @@ each spec-silent behavior the brief depends on.## 6. Feedback for CursorCapabilities 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."+format: use case and API gap, in Origin terms, with nothing that reveals the+team's internals. If none, write "No row met the feedback bar; the+workarounds in § 3 carry their tradeoffs."## 7. Questions for the teamDecisions the team must make before the port, not asks of Cursor. Always thefirst three, then what discovery left open.-1. Native repositories (or stable outbound mirrors), or repositories mirrored- from GitHub? Decides whether the app receives events and can write.+1. Native repositories (or stable outbound mirrors), or repositories in+ another mirror state? Decides whether the app receives events and can+ write.2. Which follow-up reads in § 4 are acceptable at your event volume, andwhich payload fields are hard requirements?3. Which flows depend on a user credential today, and what should they do ondiff --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 0b56fc54..16c0d7b2 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@@ -2,86 +2,71 @@Cursor wants to hear what the team needs from Origin. Raise anything thatblocks 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 feedback for Cursor or a question for the team, 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 feedback entry adds the tradeoff analysis Cursor-needs to prioritize it.+that they would like Origin to do. The bar below sorts items into feedback+for Cursor (a capability Origin should add) and questions for the team+(decisions the team must make); it does not decide whether to speak up. It+also orders feedback so the items that block the port are read first.- A difference is any row whose parity label is not `same`.-- A workaround reaches the same outcome with the current API by another route. A- follow-up read, a re-keyed identifier, a path change, a client-side filter,- a marker the app controls.+- A workaround reaches the same outcome with the current API by another+ route: a follow-up read, a re-keyed identifier, a path change, a+ client-side filter, a marker the app controls. A `workaround` row with its+ tradeoff is often the right answer.- A gap is a difference with no workaround, or a workaround whose tradeoff- 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.+ meets one of the tests below. Gaps become feedback entries.-## Nontrivial tradeoff--At least one should hold for a feedback entry. Quote it in the entry.+## Tradeoffs that make a workaround insufficient| 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 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. |+| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size, 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 matching of the app's own rows, 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. |+| Customer-visible behavior | The workaround changes what the team's users see or can do. || Load-bearing | The capability sits on the hello-world path or the team's stated core flow. |-## Usually a workaround or a question, not feedback+## Usually a workaround or a question- 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 the- Origin convention is a mechanical substitution.-- Anything the changelog says shipped or the spec already carries. Re-read the- 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 that- resource. 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 meets the bar, the feedback- is usually about a filter rather than search.--## One pattern that does meet the bar+- A convention difference (pagination style, identifier form, URL fields)+ where the Origin convention is a mechanical substitution.+- Anything the changelog says shipped or the spec already carries. Re-read+ the live spec before writing feedback.+- A capability the Origin docs do not mention: `not-available` or `unknown`+ with a question. The team should still ask if they need it.+- A query the app runs against a search API, when the spec has no search+ operation for that resource. A list operation with its filters plus a+ client-side predicate is the idiom; if that fails the fan-out test, the+ feedback is usually about a filter.-A state change the app reacts to that has no event, when reacting to exactly-that change is the app's purpose and the state is invisible until an-unrelated event arrives. Reading it off the next snapshot fails on correctness-and customer-visible behavior when the app is a gate (a check, a block, a-notification). Write the feedback entry about the event. When the app only logs or-tidies up on that change, a question is enough.+One pattern that does meet the bar: a state change the app reacts to that+has no event, when reacting to that change is the app's purpose and the+state is invisible until an unrelated event arrives. That fails correctness+and customer-visible behavior when the app is a gate. Write the feedback+about the event.## The feedback format-One entry per gap, in the brief's "Feedback for Cursor" section. Write it-so Cursor can act without a call.+One entry per gap, in the brief's "Feedback for Cursor" section. Describe the+use case and the API gap relative to it, in Origin terms. No file paths,+module names, framework internals, code structure, or repository names; those+belong in the team-facing sections of the brief.```markdown### 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>.-- **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 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.>+- **Use case:** the app needs to <do what, for whom>, <how often or at what volume>.+- **Origin today:** <what is missing or costly for that use case; cite the closest `operationId`, slug, or anchor, or "no operation">.+- **Workaround considered:** <the route and the tradeoff that makes it insufficient, or "none found">.- **Blocking?** yes / no, for which flow.-- **Spec version checked:** `<info.version>` on `<date>`.+- **Spec version checked:** `<info.version>`, <date>.```-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 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 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.+Describe the capability rather than proposing scope, field, or route names,+so Cursor can fit it to the API's conventions. One capability per entry.++The team sends the feedback, not you. Before they forward it, they should+strip anything that reveals their internals. 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/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.mdindex 016f16ae..f043a6c7 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@@ -33,10 +33,10 @@ table here. Build the index once. Every later step looks things up in it.## Matching-Match in this order and stop at the first rule that yields a confirmed+Try these in order and stop at the first rule that yields a confirmedcounterpart. Confirmed means you read the Origin operation's description and-parameters and it answers the same question the GitHub call answers. A name-match is a candidate, never a result.+parameters and it answers the same question the current call answers. A name+match is a candidate, not a result.**REST calls**