Skip to content

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.md
index 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 wanting
to 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 goes
The 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.
## License
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index 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-api
description: >-
- 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: MIT
compatibility: >-
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 body
before 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 generic
verifier 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.md
index 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-origin
description: >-
- 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: MIT
compatibility: >-
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.md
index 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 entry
rows 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 the
format is documented. Absent, pointing at the row's label in § 3. Include
fields read only for logging.
@@ -130,16 +129,18 @@ each spec-silent behavior the brief depends on.
## 6. Feedback for Cursor
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."
+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 team
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 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, and
which payload fields are hard requirements?
3. Which flows depend on a user credential today, and what should they do on
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.md
index 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 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 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.md
index 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 confirmed
counterpart. 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**