Skip to content

Cursor plugin specification and official plugins

TypeScript

Slim the plugin to two skills and one reference; apply eval fixes

Cursor Agent2b2734db1f31
diff --git a/origin-apps/README.md b/origin-apps/README.md
index 4b7027c9..3c0c4b68 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -25,18 +25,9 @@ Both skills fetch the spec at run time and never name an endpoint from memory.
## When to use
-- Writing or reviewing code that calls Origin, mints installation tokens, or
- receives Origin webhooks: `origin-api`.
-- Creating an Origin App and wanting the rules to know up front:
- `origin-api`.
-- 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 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`.
+Ask about the Origin API, or ask to port a GitHub App, and the matching skill
+loads. In Cursor you can also run `/origin-api` or
+`/port-github-app-to-origin`.
## Install in Cursor
@@ -46,30 +37,11 @@ or open Customize, find the plugin, and install it at user or project scope.
## Use outside Cursor
-The skills use only the portable
-[Agent Skills](https://agentskills.io) frontmatter, so they work unchanged in
-other agents.
-
-Claude Code, via the marketplace manifest at this repository's root:
-
-```text
-/plugin marketplace add cursor/plugins
-/plugin install origin-apps@cursor-plugins
-```
-
-Any agent that reads Agent Skills (Claude Code, Codex, and others): copy the
-skill directories into the agent's skills folder. Copy both. The porting
-skill refers to `origin-api` for fundamentals.
-
-```bash
-git clone --depth 1 https://github.com/cursor/plugins.git
-# Claude Code
-mkdir -p .claude/skills && cp -r plugins/origin-apps/skills/* .claude/skills/
-# Codex
-mkdir -p .codex/skills && cp -r plugins/origin-apps/skills/* .codex/skills/
-# Cursor, without the marketplace
-mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/
-```
+The skills use only portable [Agent Skills](https://agentskills.io)
+frontmatter. In Claude Code: `/plugin marketplace add cursor/plugins` then
+`/plugin install origin-apps@cursor-plugins`. Any other agent: copy
+`origin-apps/skills/*` into its skills folder (copy both; the porting skill
+refers to `origin-api`).
## Requirements
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index 5a336b65..e73c478d 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -13,28 +13,17 @@ compatibility: >-
# Origin API
-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.
+The docs are the source of truth. Do not name an endpoint, scope, event slug,
+header, or limit from memory. Where this file and the docs disagree, the docs
+win.
-## Fetch first
-
-Do not name an endpoint, scope, event slug, header, or limit from memory.
-
-The docs live under `https://cursor.com/docs/api/origin/`:
-
-- `llms.txt`: the index. It links every section, endpoint, and webhook
- payload page. Quoted names below ("Scopes", "Events") are section headings;
- find the current link for one in `llms.txt`.
-- `openapi.yaml`: the contract. Its `x-origin-*` extensions are summarized in
- "Endpoint reference".
-- `llms-full.txt`: the whole reference in one file. `changelog`: what moved.
-
-For one question, read `llms.txt`, then fetch only the section that answers
-it. Fetch the whole `llms-full.txt` or `openapi.yaml` for broad work, such as
-a porting brief.
-
-Cite `operationId`s and section names. Where this file and the docs
-disagree, the docs win.
+Under `https://cursor.com/docs/api/origin/`: `llms.txt` is the index and
+links every section, endpoint, and webhook payload; `openapi.yaml` is the
+contract (its `x-origin-*` extensions are summarized in "Endpoint
+reference"); `llms-full.txt` is the whole reference in one file; `changelog`
+says what moved. For one question, read `llms.txt` and fetch only the section
+that answers it. Fetch `llms-full.txt` or `openapi.yaml` whole for broad work
+such as a porting brief. Cite `operationId`s and section names.
## Where to look
@@ -47,9 +36,7 @@ disagree, the docs win.
| 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" |
+| Pagination, errors, request IDs, repository paths, IDs | "Common conventions" |
| Rate limits | "Rate limits" |
| Check-run keys, attempts, stale writes | "Check runs" |
| What is not there yet | "Current limitations" |
@@ -57,21 +44,24 @@ disagree, the docs win.
## Rules to check first
-1. **Native or mirror.** Confirm the target repositories are Origin-native
- 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; a missing subscription is silence, not an error ("Events").
+1. **Native or mirror.** An installation keeps its full scopes only on
+ native repositories and stable outbound mirrors, and some writes are
+ native-only (merging a pull request, changing the default branch); read
+ each operation's description for mirror limits. On a GitHub-sourced
+ mirror, every event except `repository.pushed` still arrives, and every
+ call beyond metadata and contents reads returns `403` ("Mirrored
+ repositories", "Events").
+2. **Subscribe.** Only `installation.*` events arrive without a subscription;
+ a missing subscription is silence, not an error ("Events").
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; do not assume a generic
- verifier passes.
+ step differs from Standard Webhooks; 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 ("Scopes").
5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDs
("Pagination", "IDs").
-Porting an existing GitHub App: the `port-github-app-to-origin` skill in
-this plugin covers how its capabilities map onto Origin.
+Porting an existing GitHub App: use `port-github-app-to-origin` in this
+plugin.
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 1d708574..b177a46b 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -13,68 +13,73 @@ compatibility: >-
# Port a GitHub App to an Origin App
-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.
+Run inside the app's codebase. The output is a porting brief for the team plus
+a Feedback for Cursor section they can send as is (`references/brief.md`).
+This skill plans; it does not write or change code unless the user explicitly
+asks after reading the brief. Follow the `origin-api` skill for the docs and
+the rules to check first. Two rules on top:
-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. Anything you cannot find becomes
- an open question.
+1. **Discover, do not ask.** Read what the app uses out of the code. Anything
+ you cannot find becomes an open question.
2. **Feedback describes use cases, not the team's code.** Team-facing parts of
- the brief may cite 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.
+ the brief may cite `file:line`. Feedback for Cursor names only what the
+ app needs to do and what Origin lacks for it, in Origin terms, with no file
+ paths, module names, framework internals, or repository names.
+
+## What to discover
-## Suggested procedure
+Record a `file:line` for each, and note what you looked for and did not find.
-Adapt the steps to the app. The brief format matters most in its Feedback
-section.
+- Declared permissions and events (manifest or IaC, if checked in; otherwise
+ derive from the calls).
+- Webhook events handled, and every payload field each handler reads,
+ including fields used only for logging.
+- REST and GraphQL call families, with the parameters and filters passed, the
+ response fields read, whether each runs per webhook or in a loop, and the
+ pagination style in use.
+- Authentication: JWT algorithm, how the installation is identified after
+ install, token lifetime handling, any user sign-in and what it is for,
+ whether the app clones or pushes git.
+- Webhook receiver: signature scheme, whether the raw body is available at
+ verification time, how deliveries are deduplicated.
+- Calls a framework or helper library makes on the app's behalf (Probot's
+ receiver, token cache, and config loader; Octokit `App`'s installation and
+ repository listing; app-auth libraries). Read the dependency's docs and
+ list these as rows marked "from `<dependency>`".
-1. **Load the spec.** A brief needs broad coverage, so fetch the full
- `openapi.yaml` and `llms-full.txt` (see `origin-api` for URLs). 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`). 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 calling
- anything a gap, and `references/gap-bar.md` before writing feedback. A
- capability the Origin docs do not mention is not available today and gets
- a question. A behavior the docs neither confirm nor deny becomes a
- question plus a first-run step that observes it, rather than an assumption
- carried over from the app's current platform.
-4. **Write the brief** per `references/brief-template.md`: guidance and a
- default outline, not a form. Every Origin claim names an `operationId`, a
- slug, or a docs section. When there is feedback, also write the
- Feedback section to `ORIGIN-FEEDBACK.md` beside the brief.
-5. **Self-check** before finishing: every Origin claim resolves in the
- fetched files; every gap has a feedback entry that names a tradeoff from
- `gap-bar.md`; the Feedback section and `ORIGIN-FEEDBACK.md` contain nothing
- that reveals the team's internals; the summary names the native-or-mirror
- question.
+## How to map
-## Not in scope
+Fetch `openapi.yaml` and `llms-full.txt` whole; a brief needs broad coverage.
+`rg -B1 -A4 'x-origin-scopes:' openapi.yaml` lists every operation with its
+scope block; `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists every
+event slug with its payload schema. Each endpoint and each payload family has
+a docs section with its fields expanded to dotted paths.
-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.
+- A name match is a candidate, not a result. Confirm by reading the
+ operation's description, parameters, and response fields against what the
+ code passes and reads. A missing parameter or field the code depends on is
+ a workaround or a gap, not a match.
+- GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,
+ `/issues/{n}/labels` on a pull request) live under the pull request
+ endpoints. Used on real issues, see the crib in `references/brief.md`.
+- GraphQL has no counterpart; decompose each document into REST calls and
+ record the fan-out.
+- Scopes are the union of `x-origin-scopes.scopes` over the operations you
+ named, not a translation of the manifest.
+- Each event and action pair maps to at most one slug in "Events"; the action
+ is part of the slug. A pair with no slug is not an event on Origin.
+- For each payload field the code reads, record whether it is present, comes
+ from the envelope (`event.type` carries the action), needs a follow-up read
+ (say which operation and how many calls per event), is derivable, or is
+ absent. Payloads are snapshots; a field on the REST resource that the
+ payload lacks is a follow-up read.
+- A capability the docs do not mention is not available today and gets a
+ question. A behavior the docs neither confirm nor deny gets a question plus
+ a first-run step that observes it, not an assumption carried over from
+ GitHub.
-## Reference files
+## Before finishing
-| File | Read when |
-| --- | --- |
-| `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 capability that maps differently. |
-| `references/gap-bar.md` | Deciding what is feedback for Cursor, and writing the entry. |
-| `references/brief-template.md` | Writing the brief and the feedback file. |
+Every Origin claim resolves in the fetched files. Every gap has a feedback
+entry naming a tradeoff. The feedback contains nothing that reveals the
+team's internals. The summary names the native-or-mirror question.
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
deleted file mode 100644
index 43c0e157..00000000
--- a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# The porting brief
-
-The brief is for the team that owns the app, plus one section they can send
-to Cursor as is. Write it as one Markdown file at the repository root
-(`ORIGIN-PORTING-BRIEF.md` unless the team's docs convention says otherwise)
-and print its path. A small app's brief fits on one screen; parts that have
-nothing to say collapse to a line or disappear. Choose table shapes and
-headings to fit the app.
-
-## What a good brief does
-
-- **Leads with a summary.** Three to five lines: the verdict (ports as is,
- ports with N workarounds, blocked on X), the one question that decides the
- rest (usually native or mirror), and whether there is feedback for Cursor
- and if any of it blocks.
-- **Maps what the app uses to Origin.** Every capability the code relies on,
- with the Origin operation, slug, or docs section it maps to, or a
- note that nothing does. Where a webhook handler reads specific payload
- fields, say per field whether it is present, comes from the envelope, needs
- a follow-up read (and how many per event), is derivable, or is absent.
- Group by facet if the table is long. End with the scopes to request: the
- union of `x-origin-scopes.scopes` over the operations named, minus what
- "Scopes" says is automatic or implied.
-- **Gives an app-specific first-run path when it helps.** The events to
- select by slug, the mirror-state check, the first event that should arrive
- and what it should carry, the first write. Generic setup steps belong to
- "Implementation checklist", not here. Skip for a read-only app
- with one event.
-- **Adds plan notes.** What drives the size of the port (a few bullets, no
- time estimates) and how to roll it out: dual-run or cutover, what a mirror
- trial can and cannot show, what to gate.
-- **Asks only what the team must decide.** Repository set, tolerable event
- volume and follow-up reads, what replaces a flow that has no Origin
- equivalent. Do not restate a row as a question.
-- **Ends with two lines of provenance.** Spec `info.version` and fetch time;
- codebase and commit.
-- **Closes with Feedback for Cursor.** Last section, unnumbered, written to be
- copied verbatim (`gap-bar.md` has the shape). Nothing in it reveals the
- team's internals. When it has at least one entry, also write it to
- `ORIGIN-FEEDBACK.md` beside the brief. When nothing meets the bar, no file;
- one line in the brief saying so.
-
-## What makes it trustworthy
-
-- Every claim about the app cites evidence: `file:line`, or "from
- `<dependency>` (documented behavior)". Team-facing sections only.
-- Every claim about Origin resolves in the fetched `openapi.yaml` or
- `llms-full.txt`: an `operationId`, a slug, or a section. Nothing from
- memory.
-- Behavior the docs do not state is a question plus a first-run step that
- observes it, never an assumption.
-- Feedback for Cursor describes use cases and the API gap in Origin terms,
- with no file paths, module names, framework internals, or repository names.
-
-## Vocabulary, if you want one
-
-Plain notes serve the reader as well as labels. If the table needs a compact
-mark, these four are shared with the other references: `maps` (a documented
-path exists, same or reshaped), `workaround` (same outcome by another route;
-say the tradeoff), `not-available` (nothing in the current spec; carries a
-question), `gap` (no workaround, or one whose tradeoff meets a test in
-`gap-bar.md`; produces a feedback entry). Size marks S/M/L, if used, mean
-adapter change, new code path, product or architecture change.
-
-## Default outline
-
-Adapt or skip parts; the Feedback section is the one to keep exact.
-
-```text
-# Origin porting brief: <app>
-Summary
-1. The app today one paragraph; observed stack; looked for, not found
-2. Capability map table(s); payload fields under webhook events; scopes line
-3. First run app-specific, five steps or fewer (optional)
-4. Plan notes size drivers; rollout (optional)
-5. Questions for the team
-Provenance two lines
-Feedback for Cursor unnumbered, last, copy verbatim; also ORIGIN-FEEDBACK.md
-```
diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief.md b/origin-apps/skills/port-github-app-to-origin/references/brief.md
new file mode 100644
index 00000000..ed6bd09a
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/brief.md
@@ -0,0 +1,115 @@
+# The brief, the feedback, and the crib
+
+## The brief
+
+One Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md` unless
+the team's convention says otherwise); print its path. Budget about 800
+words for a small app and about 2,000 for a large one; parts with nothing to
+say collapse or disappear. Choose table shapes to fit the app. A good brief:
+
+- leads with a summary: the verdict (ports as is, ports with workarounds,
+ blocked on X), the question that decides the rest (usually native or
+ mirror), and whether there is feedback for Cursor and if any of it blocks;
+- lists only the capabilities that do not map straight across, each with
+ the Origin operation, slug, or docs section it maps to or a note that
+ nothing does, and closes the list with one line naming the rest
+ ("maps directly: 14 operations, covered by the scopes line"); shows a
+ payload field only when it is absent or needs a follow-up read; ends with
+ the scopes to request;
+- gives an app-specific first-run path when it helps (events to select, the
+ mirror check, the first event and what it carries, the first write); skips
+ generic setup, which "Implementation checklist" covers;
+- notes what drives the size of the port and how to roll it out (dual-run
+ or cutover), without time estimates;
+- asks only what the team must decide, never restating a row;
+- ends with two lines of provenance (spec `info.version` and fetch time;
+ codebase and commit) and then Feedback for Cursor, last and unnumbered.
+
+Evidence for every app claim (`file:line`, or "from `<dependency>`"); every
+Origin claim resolved against the fetched docs. If you want compact marks:
+`maps` (a documented path exists), `workaround` (say the tradeoff),
+`not-available` (nothing in the current spec; carries a question), `gap`
+(produces a feedback entry).
+
+## Feedback for Cursor
+
+Cursor wants to hear what the team needs. Raise anything that blocks the
+team's core flow, costs them correctness, security, or scale, or that they
+would like Origin to do. The bar sorts items into feedback (a capability
+Origin should add) and questions (decisions the team must make); it does not
+decide whether to speak up.
+
+A workaround reaches the same outcome by another route (a follow-up read, a
+re-keyed identifier, a path change, a client-side filter, a marker the app
+controls) and is often the right answer. It becomes a gap, and a feedback
+entry, when its tradeoff is one of: fan-out that grows with repository or
+activity size at the app's volume; a possibly wrong answer (heuristic own-row
+matching, a pull request inferred from a SHA several versions share, a URL
+whose format is not contractual); a broader scope, longer-lived token, or
+user credential where an installation token should do; a change to what the
+team's users see or can do; or a capability on the hello-world path or the
+team's core flow. A state change the app exists to react to, with no event
+and no other way to observe it, meets the bar. Something the docs never
+mention is not available today and gets a question; it becomes feedback
+only if it blocks the core flow.
+
+Not feedback, only a question or a note: a field or filter the code does not
+use; a convention difference with a mechanical substitute; a documented
+design choice such as token lifetime or no GraphQL.
+
+One entry per gap, in Origin terms, with nothing that reveals the team's
+internals. When there is at least one, also write the section to
+`ORIGIN-FEEDBACK.md` beside the brief; when there is none, no file and one
+line saying so. The file carries no license header, repository name,
+product name, or mention of another forge. A contradiction between the docs
+and observed behavior goes in a short "Docs questions for Cursor" list at
+the end of the feedback, not in the questions for the team. A suggested
+shape:
+
+```markdown
+### Feedback: <capability, in Origin terms>
+- **Use case:** the app needs to <do what, for whom>, <how often or at what volume>.
+- **Origin today:** <what is missing or costly; cite the closest operationId, slug, or section, or "no operation">.
+- **Workaround considered:** <the route and the tradeoff that makes it insufficient, or "none found">.
+- **Blocking?** yes / no, for which flow.
+- **Spec version checked:** <info.version>, <date>.
+```
+
+Describe the capability rather than proposing scope, field, or route names.
+The team sends the feedback, not you; before they do, they strip anything
+that reveals their internals.
+
+## Crib: where GitHub habits land on Origin
+
+Check before calling anything a gap; confirm each in the fetched docs.
+
+Documented path exists: install callback params → "Installation receipt";
+RS256 app JWT → "App JWT"; long-lived installation tokens → "Installation
+access token"; permissions → "Scopes" and `x-origin-scopes`; numeric IDs and
+`/repositories/{id}` → "IDs", "Repository paths"; `Link` pagination and
+totals → "Pagination"; commit statuses → check runs with a stable `key`
+("Check runs"); `/issues/{n}/comments` and `/issues/{n}/labels` on a pull
+request → the pull request endpoints; repository webhook CRUD → per-app
+`events` on Create App / Update App; a single `pull_request` event with an
+`action` field → one slug per action ("Events"); `x-github-*` headers and
+HMAC → "Headers", "Signature verification"; inlined payload data (changed
+files, before-SHA, URLs, profiles) → follow-up reads ("Resource references",
+"Current limitations"); reviews keyed by commit SHA → `pullRequestVersion`;
+finding own rows by actor → check-run `key`, or a marker the app controls;
+writes on a repository mirrored from GitHub → metadata and contents reads
+only, until it is a stable outbound mirror, and merging and default-branch
+changes stay native-only ("Mirrored repositories"); user sign-in and acting
+as a user → "Acting on behalf of users" (user confirmation receipt,
+installation user tokens).
+
+Not available in the current spec (question, and feedback if it blocks the
+core flow): GraphQL (decompose); Issues (pull request comments, threads,
+reviews, and labels cover the pull-request half); OAuth-app token mints;
+arbitrary blob or tree writes (commit-from-files and pushes exist); user,
+email, team, and member directory reads (reviewer identifiers resolve by
+public id, email, or group slug); group membership and effective-permission
+reads. For the last two, the workaround to name is a user token capped to a
+repository and scopes: minting it returns `403` unless the user holds that
+permission, so it doubles as a permission probe.
+
+Crib rows go stale; the fetched docs win.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/discovery.md b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
deleted file mode 100644
index f9c86ab0..00000000
--- a/origin-apps/skills/port-github-app-to-origin/references/discovery.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Discovering what the GitHub App uses, from its codebase
-
-Everything the brief needs about the app is in the repository. Search for it.
-Do not ask for it. Record `file:line` for every fact and list every place you
-looked that turned up nothing. Note the language and libraries as an
-observation. They inform sizes and nothing else.
-
-Seven facets. For each, what to record:
-
-1. **Declared permissions and events.** The manifest or registration snapshot
- if it is checked in (`app.yml`, a manifest JSON, IaC that seeds the app;
- Probot keeps `default_events` and `default_permissions` in `app.yml`). If
- there is none, say so and derive permissions from facet 4. The union of
- what the code calls is what the port needs anyway.
-2. **Webhook events handled.** Each GitHub event and action pair the code
- dispatches on (`app.on("pull_request.opened")`, a switch on
- `x-github-event` plus `payload.action`, SDK parsers), with the handler
- location.
-3. **Payload fields read.** Every property path each handler and its helpers
- dereference from the payload. Include fields used only for logging or
- metrics. Those break dashboards after the port.
-4. **REST and GraphQL calls.** Each distinct call family once (method and path,
- or SDK method) with the parameters and filters the code passes, the
- response fields it reads, whether it runs per webhook or in a loop (this
- decides the fan-out tradeoff), and the pagination style in use. Pagination
- always changes. GraphQL documents count as calls. Mapping decomposes them.
-5. **Authentication and token minting.** The app JWT algorithm. How the code
- identifies the installation after install (callback query, webhook, DB).
- Token lifetime handling. Whether user OAuth exists and what it is for
- (identity, repository discovery, acting for a user). Whether the app clones
- or pushes git as itself.
-6. **Webhook receiver and verification.** The signature scheme. Whether the
- raw body is available at verification time (a framework that parses JSON
- first cannot verify). How the code deduplicates deliveries, if it does.
- Where the public URL is configured.
-7. **Calls the framework makes on the app's behalf.** They are not in the
- app's source, but the port has to make them. List them as rows marked
- "from `<dependency>` (documented behavior)" and read the dependency's docs
- or source, not the app. Common cases:
- - Probot: the built-in receiver and HMAC verification, per-installation
- token minting and caching, `context.repo()` and `context.issue()`,
- `context.isBot`. Companions: `probot-config` reads `.github/<file>.yml`
- and falls back to the owner's `.github` repository; `probot-scheduler`
- lists installations and repositories with the app credential and emits
- `schedule.repository`; `probot-metadata` stores state in issue bodies.
- - Octokit `App`: `webhooks.verifyAndReceive`, `eachInstallation` and
- `eachRepository`, token minting behind `getInstallationOctokit`.
- - `ghinstallation`, `githubkit`, `gidgethub`, `octokit.rb` app auth: JWT
- minting and installation-token exchange.
-
-When something is missing, say so in the inventory ("no manifest found
-(searched: …)", "no signature verification found in the receiver at …").
-Each missing item becomes an up-front question. Do not
-fill it in with what an app of this kind usually does.
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
deleted file mode 100644
index e14f6876..00000000
--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# The feedback bar and the feedback format
-
-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 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 capability whose Origin path is not a straight
- substitution.
-- 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. Noting the workaround 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 tests below. Gaps become feedback entries; when there is
- at least one, the Feedback section is also written to `ORIGIN-FEEDBACK.md`
- beside the brief.
-
-## 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, 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. |
-| Load-bearing | The capability sits on the hello-world path or the team's stated core flow. |
-
-## Usually a workaround or a question
-
-- Anything `origin-isms.md` marks `maps`: a documented path exists.
-- A field or filter the code does not use.
-- 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 today, 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.
-
-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. A suggested
-shape, not a form; keep whatever lines carry information. 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>
-
-- **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>`, <date>.
-```
-
-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/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
deleted file mode 100644
index 160ddd10..00000000
--- a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Origin-isms: GitHub features that map differently on Origin
-
-Check here before calling anything a gap. Each row says whether a documented
-Origin path exists (`maps`) or nothing in the current spec covers it
-(`not-available`), and where the Origin answer lives (a section heading in
-the Origin docs unless noted; find its link in `llms.txt`). A `maps` row is a question only if the team
-wants the old shape back. A `not-available` row is a question, and feedback
-if it meets the bar in `gap-bar.md`. Read the source; do not copy this table
-into the brief.
-
-| What the app uses today | Mark | Where the Origin answer lives |
-| --- | --- | --- |
-| Writes or `push` events on a repository mirrored from GitHub | `maps` | Read-only until the mirror becomes a stable outbound mirror ("Mirrored repositories"); pushes are not delivered for GitHub-sourced mirrors ("Events"). Transitioning is a user-credential operation. First question of every brief. |
-| Install callback query parameters (`installation_id`, `setup_action`) | `maps` | "Installation receipt" |
-| RS256 app JWT | `maps` | "App JWT" |
-| Long-lived installation tokens | `maps` | "Installation access token" |
-| User OAuth, `/user`, `/user/installations`, install-by-user picker | `not-available` | No user-credential flow for apps in the current spec. Repository discovery is through the installation; namespace-wide listing is under "Current limitations". Ask what the flow should do. |
-| Permissions `<noun>: read\|write` | `maps` | "Scopes"; `x-origin-scopes` per operation |
-| Numeric IDs, `/repositories/{id}` | `maps` | "IDs", "Repository paths" |
-| `Link` / `page` / `per_page` pagination, total counts | `maps` | "Pagination" |
-| 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}`) | `maps` | "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 feedback entry. |
-| `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `maps` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |
-| Repository webhook CRUD (`/repos/…/hooks`) | `maps` | Subscriptions are set per app through Create App / Update App `events` ("Events"). |
-| App-manifest conversion | `maps` | App creation form or `CreateApp` ("Installation", endpoint reference) |
-| OAuth-app token mints | `not-available` | Nothing in the current spec. Ask what the flow was for. |
-| Git Data API commit and ref writes | `maps` | Create Commit From Files, Create Git Ref (Git data endpoint reference); "Git HTTPS authentication" for pushes |
-| Git Data API arbitrary blob or tree writes | `not-available` | Not in the current spec. Ask whether commit-from-files or a push covers the use. |
-| Standalone review-thread objects | `maps` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under "Current limitations". |
-| User, email, team, and member lookups | `not-available` | No directory reads in the current spec. Reviewer identifiers resolve by public id, user email, or group slug; `handle` is present when the profile is public ("Resource references"). |
-| Single `pull_request` event with an `action` field, `previous_attributes` | `maps` | "Events", "Event payloads" |
-| `x-github-*` headers, HMAC `x-hub-signature-256` | `maps` | "Headers", "Signature verification" |
-| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `maps` | "Resource references"; the push commit list is under "Current limitations" and may change. Name the follow-up call per field and count the fan-out. |
-| All events delivered after app creation | `maps` | "Events" |
-| Reviews keyed by `commit_id` | `maps` | `pullRequestVersion` on the review schema |
-| Finding own check runs or comments by actor | `maps` | "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 capability that is not on this list and that the Origin docs do not
-mention is not available today; ask the team whether they need it.
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
deleted file mode 100644
index 9683511b..00000000
--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Reading the Origin spec and matching GitHub calls and events to it
-
-Quoted names ("Scopes", "Events") are section headings in the Origin docs;
-find each one's link in `llms.txt`.
-
-Every mapping in the brief comes from the fetched `openapi.yaml`, not from a
-table here. Build the index once. Every later step looks things up in it.
-
-## Extensions the spec carries
-
-| Extension | Where | Use |
-| --- | --- | --- |
-| `x-origin-scopes` | every operation | The scope and credential rules for that operation. "Scopes", "Endpoint reference". |
-| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape; a schema carrying it is a webhook family. "Event payloads". Infer the embedded resource from its `$ref`s; some families have no REST twin. |
-| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | "Preview". Note it in the brief on any capability that touches a badged element. |
-
-## Build the index
-
-1. **Operations and scopes**: `rg -B1 -A4 'x-origin-scopes:' openapi.yaml`
- prints every `operationId` with its scope block. From it, note the union
- of scopes with the operations that need each, and separate
- installation-requestable scopes from ambient and user-only ones
- ("Scopes" explains the difference). The user-only set tells
- you which GitHub flows have no app-side equivalent. Read parameters and
- response components from the spec when a rule below asks for them.
-2. **Webhook events**: `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists
- every slug with its payload schema. Each family has its own section, with
- the fields expanded to dotted paths ("Pull Request Events" and its
- siblings under "Event payloads"; find them in `llms.txt`). In a broad run
- with `llms-full.txt` already fetched, `rg -n '^### Pull Request Events$'
- llms-full.txt` and read to the next `###`. From "Events", note which slugs
- are delivered
- without a subscription and which must be selected.
-3. **Resources**: each endpoint's section lists its "Response Fields" with
- nested objects expanded ("Get Pull Request" under "Pull requests"), for
- "does the Origin object carry this field". Fallback in a broad run:
- `rg -n '^### Get Pull Request$' llms-full.txt`.
-
-## Matching
-
-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 current call answers. A name
-match is a candidate, not a result.
-
-**REST calls**
-
-1. Look for the same resource path under the Origin base path
- ("Repository paths" and "IDs" give the path forms). Most GitHub
- repository, pull request, check, label, branch, and commit paths have a
- direct or near-direct counterpart.
-2. Re-home GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,
- `/issues/{n}/labels` used *on a pull request*) to the pull request
- endpoints. That is a path change, not a gap. When the code uses them on
- real issues, see `origin-isms.md`.
-3. Re-home app and installation calls (`/app`, `/app/installations`,
- access-token minting, `/installation/repositories`) to the Apps and
- installations endpoints and confirm the credential each accepts. `/user`,
- `/user/installations`, `/orgs/…`, `/search/…`, and `/repositories/{id}`
- have no path counterpart. Consult `origin-isms.md` before labeling them.
-4. Compare parameters as well as paths. A matching path that lacks a filter
- the code depends on is a workaround or a gap, not a straight match.
-5. Compare the response fields the code reads. Each missing field gets its
- own line as follow-up call, derivable, or absent. GitHub inlines web URLs,
- nested profiles, and counts that Origin does not.
-
-**GraphQL.** There is no endpoint. Decompose each document into the REST
-reads and writes it stands for, map those, and record the fan-out as the
-row's tradeoff.
-
-**Permissions → scopes.** Do not translate the manifest noun-for-noun. Find
-the operations the code calls and take the union of *their*
-`x-origin-scopes.scopes`. GitHub permissions with no Origin noun
-(`statuses`, `issues`, `members`, `organization_*`, `pages`, `actions`,
-`workflows`, `deployments`) go through `origin-isms.md` first.
-
-**Events → slugs.** Each GitHub `event` + `action` pair maps to at most one
-slug in "Events"; the action is part of the slug. A pair with
-no slug is not an event on Origin. Check whether the state change is
-observable another way before classifying it.
-
-**Payload fields → schema properties.** For each field path a handler reads,
-walk the mapped family's "Payload Fields" list in its docs section and record
-one of five outcomes, matching the brief template's "How" column.
-Present at `<path>`. Present in the envelope (`event.type` carries what
-GitHub puts in `action`). Follow-up read via `<operationId>` with identifiers
-the payload carries. Derivable from present fields, saying how and whether
-the format is contractual. Absent, which goes to the gap bar. A field on the REST
-component that the webhook twin lacks means a follow-up `Get…` on every
-event.
-
-## Out of domain and spec-silent
-
-- A concept neither the spec nor the docs mention is not available
- today and gets a question rather than a gap: there is no Origin answer yet
- to compare against, and the question is how the team tells Cursor they
- need it.
-- A behavior the code depends on that the docs do not state (does an event
- fire for a draft pull request? does `updatedAt` move on a comment?) becomes an open
- question plus a hello-world step that observes it on a native repository.
- Do not settle it from GitHub's behavior.