Skip to content

Cursor plugin specification and official plugins

TypeScript

Add origin-apps plugin: port a GitHub App to an Origin App

Cursor Agent9a9ea84fb2e1
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 00000000..0af83a86
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,14 @@
+{
+ "name": "cursor-plugins",
+ "owner": {
+ "name": "Cursor",
+ "email": "[email protected]"
+ },
+ "plugins": [
+ {
+ "name": "origin-apps",
+ "source": "./origin-apps",
+ "description": "Plan the port of an existing GitHub App to a Cursor Origin App: discover its GitHub surface, map it onto the live Origin API, write a porting brief."
+ }
+ ]
+}
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index 50f8c271..556d6a14 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -63,6 +63,11 @@
"source": "cursor-sdk",
"description": "Build apps, scripts, and automations with the TypeScript SDK."
},
+ {
+ "name": "origin-apps",
+ "source": "origin-apps",
+ "description": "Plan the port of an existing GitHub App to a Cursor Origin App: discover its GitHub surface, map it onto the live Origin API, write a porting brief."
+ },
{
"name": "orchestrate",
"source": "orchestrate",
diff --git a/README.md b/README.md
index f5e95e01..f29ea65c 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc
| `pr-review-canvas` | [PR Review Canvas](pr-review-canvas/) | Cursor | Developer Tools | Render PR diffs as review canvases grouped by importance. |
| `docs-canvas` | [Docs Canvas](docs-canvas/) | Cursor | Developer Tools | Render documentation as a navigable canvas. |
| `cursor-sdk` | [Cursor SDK](cursor-sdk/) | Cursor | Developer Tools | Build apps, scripts, and automations with the TypeScript SDK. |
+| `origin-apps` | [Origin Apps](origin-apps/) | Cursor | Developer Tools | Plan the port of an existing GitHub App to a Cursor Origin App: discover its GitHub surface, map it onto the live Origin API, write a porting brief. |
| `orchestrate` | [Orchestrate](orchestrate/) | Cursor | Developer Tools | Fan large tasks out across parallel cloud agents with planners, workers, verifiers, and structured handoffs. |
| `pstack` | [pstack](pstack/) | Lauren Tan | Developer Tools | if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. |
| `advisor` | [Advisor](advisor/) | Cursor | Developer Tools | Consult a stronger model before major decisions, when stuck, and before declaring done. |
diff --git a/origin-apps/.claude-plugin/plugin.json b/origin-apps/.claude-plugin/plugin.json
new file mode 100644
index 00000000..9d1cb54b
--- /dev/null
+++ b/origin-apps/.claude-plugin/plugin.json
@@ -0,0 +1,21 @@
+{
+ "name": "origin-apps",
+ "description": "Plan the port of an existing GitHub App to a Cursor Origin App: discover the app's GitHub surface, map it onto the live Origin API, write a porting brief.",
+ "version": "0.1.0",
+ "author": {
+ "name": "Cursor",
+ "email": "[email protected]"
+ },
+ "homepage": "https://cursor.com/docs/api/origin",
+ "repository": "https://github.com/cursor/plugins",
+ "license": "MIT",
+ "keywords": [
+ "origin",
+ "origin-api",
+ "github-app",
+ "webhooks",
+ "integration",
+ "porting"
+ ],
+ "skills": "./skills/"
+}
diff --git a/origin-apps/.cursor-plugin/plugin.json b/origin-apps/.cursor-plugin/plugin.json
new file mode 100644
index 00000000..0d130e52
--- /dev/null
+++ b/origin-apps/.cursor-plugin/plugin.json
@@ -0,0 +1,30 @@
+{
+ "name": "origin-apps",
+ "displayName": "Origin Apps",
+ "version": "0.1.0",
+ "description": "Plan the port of an existing GitHub App to a Cursor Origin App: discover the app's GitHub surface, map it onto the live Origin API, write a porting brief.",
+ "author": {
+ "name": "Cursor",
+ "email": "[email protected]"
+ },
+ "homepage": "https://cursor.com/docs/api/origin",
+ "repository": "https://github.com/cursor/plugins",
+ "license": "MIT",
+ "keywords": [
+ "cursor-plugin",
+ "origin",
+ "origin-api",
+ "github-app",
+ "webhooks",
+ "integration",
+ "porting"
+ ],
+ "category": "developer-tools",
+ "tags": [
+ "origin",
+ "github-app",
+ "integration",
+ "planning"
+ ],
+ "skills": "./skills/"
+}
diff --git a/origin-apps/CHANGELOG.md b/origin-apps/CHANGELOG.md
new file mode 100644
index 00000000..d5d9a2ec
--- /dev/null
+++ b/origin-apps/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this plugin will be documented here.
+
+## 0.1.0 — initial release
+
+- Added the `port-github-app-to-origin` skill: discover a GitHub App's surface
+ from its codebase, map it onto the live Origin API spec, and write a porting
+ brief with a capability table, webhook field map, hello-world path, gap cards,
+ and up-front questions.
diff --git a/origin-apps/LICENSE b/origin-apps/LICENSE
new file mode 100644
index 00000000..ca2bba77
--- /dev/null
+++ b/origin-apps/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/origin-apps/README.md b/origin-apps/README.md
new file mode 100644
index 00000000..8324e10b
--- /dev/null
+++ b/origin-apps/README.md
@@ -0,0 +1,87 @@
+# Origin Apps
+
+Plugin for teams bringing an existing GitHub App to
+[Cursor Origin](https://cursor.com/docs/api/origin), Cursor's code forge.
+Skills only, so it runs in Cursor, Claude Code, Codex, and any agent that
+reads [Agent Skills](https://agentskills.io).
+
+## What it includes
+
+- `port-github-app-to-origin`: run it inside your GitHub App's repository with
+ no other instructions. It discovers the app's GitHub surface from the code
+ (manifest, permissions, events handled, payload fields read, REST and GraphQL
+ calls, token minting, webhook receiver, calls your framework makes for you),
+ fetches the live Origin API 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 to your first real event,
+ gaps worth raising with Cursor, and the questions your team should settle
+ first.
+
+The skill plans; it does not write port code, pick a language or SDK, or
+estimate in time. Mappings come from the Origin OpenAPI spec at run time, so the
+brief tracks the API as published on the day you run it.
+
+## When to use
+
+- You have a GitHub App (Probot, Octokit, go-github, hand-rolled) and want to
+ know what an Origin App version looks like before you start.
+- You are an agent working on such a team's behalf and need a grounded plan.
+- You want to check which GitHub features Origin deliberately does not
+ reproduce, and what the Origin idiom is instead.
+
+In Cursor, open the app's repository and ask to port it to Origin, or run
+`/port-github-app-to-origin`.
+
+## Install in Cursor
+
+Search for **Origin Apps** in the Cursor Marketplace
+([cursor.com/marketplace/origin-apps](https://cursor.com/marketplace/origin-apps)),
+or open **Customize**, find the plugin, and install it at user or project
+scope.
+
+## Use outside Cursor
+
+The plugin ships three manifests for one set of skills: a root `plugin.json`
+([Agent Plugins](https://agent-plugins.org) 1.0), `.cursor-plugin/plugin.json`
+(Cursor Marketplace), and `.claude-plugin/plugin.json` (Claude Code). The
+skill uses only portable frontmatter (`name`, `description`, `license`,
+`compatibility`).
+
+**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 directory into the agent's skills folder.
+
+```bash
+git clone --depth 1 https://github.com/cursor/plugins.git
+# Claude Code
+mkdir -p .claude/skills && cp -r plugins/origin-apps/skills/port-github-app-to-origin .claude/skills/
+# Codex
+mkdir -p .codex/skills && cp -r plugins/origin-apps/skills/port-github-app-to-origin .codex/skills/
+# Cursor, without the marketplace
+mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/port-github-app-to-origin .cursor/skills/
+```
+
+## Requirements
+
+- Network access to `https://cursor.com/docs/api/origin/*` during the run.
+- Read access to the app's source. No Origin credentials are needed to produce
+ the brief; the hello-world path in the brief is what you follow afterwards.
+- Optional: `python3` with PyYAML for `scripts/index-origin-spec.py`, which
+ turns the fetched spec into a grep-friendly index. Without it the skill
+ reads the spec directly.
+
+## Where the brief goes
+
+The skill writes `ORIGIN-PORTING-BRIEF.md` at the repository root and prints
+its path. Gap cards in the brief are yours to send: through your shared Slack
+channel with Cursor if you have one, or to `[email protected]`.
+
+## License
+
+MIT
diff --git a/origin-apps/plugin.json b/origin-apps/plugin.json
new file mode 100644
index 00000000..a0d396b5
--- /dev/null
+++ b/origin-apps/plugin.json
@@ -0,0 +1,21 @@
+{
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+ "name": "origin-apps",
+ "version": "0.1.0",
+ "description": "Plan the port of an existing GitHub App to a Cursor Origin App: discover the app's GitHub surface, map it onto the live Origin API, write a porting brief.",
+ "author": {
+ "name": "Cursor",
+ "email": "[email protected]"
+ },
+ "homepage": "https://cursor.com/docs/api/origin",
+ "repository": "https://github.com/cursor/plugins",
+ "license": "MIT",
+ "keywords": [
+ "origin",
+ "origin-api",
+ "github-app",
+ "webhooks",
+ "integration",
+ "porting"
+ ]
+}
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
new file mode 100644
index 00000000..566f3725
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: port-github-app-to-origin
+description: >-
+ Plan 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 the app's surface onto the live Origin spec and writes a
+ porting brief. No code.
+license: MIT
+compatibility: >-
+ Needs network access to https://cursor.com/docs/api/origin/* at run time.
+ The optional indexing script needs python3 with PyYAML; without it, read the
+ spec directly.
+---
+
+# Port a GitHub App to an Origin App
+
+Run this inside the codebase of an existing GitHub App, with no other
+instructions needed. The output is a **porting brief**
+(`references/brief-template.md`), not an implementation. "The team" below
+means the people who own this app; if you are running this yourself, that is
+you. The team keeps its language, framework, and client strategy; the brief
+tells them what maps, what changes shape, what is absent on purpose, and what
+is worth raising with Cursor.
+
+Three rules shape everything below:
+
+1. **The live Origin docs are the source of truth.** Fetch them at run time
+ and derive every mapping from them. Nothing in this skill pins a version or
+ enumerates endpoints; the `references/` files explain *how to read* the spec
+ and *why* Origin differs, and any concrete example in them is illustrative
+ until you have confirmed it against today's spec.
+2. **Discover, do not ask.** Read the manifest, permission declarations, event
+ handlers, token minting, API calls, and webhook receiver out of the code.
+ Never ask anyone to paste a manifest or list their endpoints. If something
+ is genuinely undiscoverable, record it as an open question in the brief.
+3. **Origin is GitHub-shaped, not GitHub-compatible.** Many differences are
+ decisions, not omissions. Classify them as such and guide the port toward
+ the Origin idiom instead of reproducing the GitHub one.
+
+## Procedure
+
+### 1. Load the live Origin surface
+
+Fetch, in this order, and keep them open for the rest of the run:
+
+- `https://cursor.com/docs/api/origin/llms.txt` (index of everything below)
+- `https://cursor.com/docs/api/origin/openapi.yaml` (the contract; every
+ mapping in the brief cites an `operationId` or a payload schema from it)
+- `https://cursor.com/docs/api/origin/llms-full.txt` (the human reference:
+ installation, authentication, scopes, mirrored repositories, webhooks,
+ conventions, current limitations)
+- `https://cursor.com/docs/api/origin/changelog` (what moved recently)
+
+Record `info.version` and the fetch time in the brief's provenance block. That
+is provenance, not a dependency: the brief describes the API as it is today and
+says so. `references/spec-mapping.md` explains the spec's `x-origin-scopes`,
+`x-origin-webhook-events`, `x-origin-webhook-resource`, and
+`x-cursor-visibility` extensions and how to build the mapping index from them.
+`scripts/index-origin-spec.py <openapi.yaml>` prints that index (operations
+with scopes, parameters, and response fields; webhook slugs with payload
+fields; the scope catalog) so you can grep it instead of paging through 700 KB
+of YAML; it needs python3 with PyYAML and does nothing else.
+
+### 2. Discover the GitHub App's shape
+
+Follow `references/discovery.md`. Produce an inventory with a file and line for
+every fact: declared permissions and events, webhook events handled, payload
+fields the handlers read, REST and GraphQL calls, authentication flow, webhook
+receiver and signature verification, calls made on the app's behalf by its
+framework and helper libraries, and the observed language and client
+libraries (observed, never chosen). Note what you looked for and did not find.
+
+### 3. Map each capability onto Origin
+
+For each inventory row, look up the Origin counterpart in the spec index built
+in step 1 (`references/spec-mapping.md` § Matching rules), then classify it
+with one of the parity labels in `references/brief-template.md`. Before
+labeling anything `gap`, check `references/origin-isms.md`: a GitHub feature
+that Origin deliberately does not reproduce is `by-design-absent` with a
+pointer to the Origin idiom, and the brief must say what to do instead rather
+than raise it. Then apply the bar in `references/gap-bar.md`; only rows that
+clear it become gap cards.
+
+Map webhook payload *fields* the code reads, not just event names. Origin
+payloads are lean row snapshots; a field GitHub inlines is often a follow-up
+REST read on Origin. Say which call, per field.
+
+Two labels are easy to misuse. A GitHub surface with no Origin counterpart
+*and* no mention anywhere in the Origin docs (Marketplace billing, merge
+queues, Actions, Pages) is `unknown` with a question, not a `gap`: Origin has
+not said no, and the team may not 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 also a question, plus a step on the
+hello-world path to observe it; never guess it into `same`.
+
+### 4. Write the brief
+
+Fill `references/brief-template.md` in full. Every table cell that names an
+Origin operation, event, or field links to its anchor in `llms-full.txt` or
+names its `operationId`. Sizes are S/M/L as defined in the template, never
+time. The hello-world path is the sequence Create App → subscribe events →
+install → verify ping signature → first real event on a native repository;
+it is a checklist of things to verify, not code.
+
+### 5. Ask the up-front questions
+
+Close the brief with the questions in the template's final section, pruned to
+what the discovery left open and extended with anything specific you found.
+The first question is always whether the target repositories are Origin-native
+or mirrored from GitHub, because that decides whether the app will receive
+real events at all.
+
+## What this skill does not do
+
+- Write, scaffold, or vibecode port code, adapters, or SDK wrappers.
+- Choose a language, framework, HTTP client, or codegen strategy.
+- Estimate effort in hours, days, or sprints.
+- Pin the spec version, copy endpoint lists into the brief from memory, or
+ claim parity from a name match without reading the operation.
+- Ask for information the codebase already contains.
+- Contact Cursor on the team's behalf; the brief carries the escalation cards
+ and the team decides what to send and where.
+
+## Reference files
+
+| File | Read when |
+| --- | --- |
+| `references/spec-mapping.md` | Building the spec index and matching GitHub calls, events, and payload fields to Origin operations, slugs, and schemas. |
+| `references/discovery.md` | Scanning the codebase for the app's GitHub surface. |
+| `references/origin-isms.md` | Deciding whether a missing GitHub feature is a decision or a gap, and what the Origin idiom is. |
+| `references/gap-bar.md` | Deciding whether a gap is worth raising with Cursor, and writing the card. |
+| `references/brief-template.md` | Writing the output. |
+| `scripts/index-origin-spec.py` | Turning the fetched `openapi.yaml` into a grep-friendly index (operations, webhook families, scopes, one component). Optional; needs PyYAML. |
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
new file mode 100644
index 00000000..7642ca1d
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
@@ -0,0 +1,185 @@
+# Porting brief template
+
+Write the brief as 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; where a section is genuinely empty,
+say so in one line rather than deleting it, so the team can see it was
+considered. Cite spec `operationId`s and `llms-full.txt` anchors; cite the
+team's code by `file:line`.
+
+Keep it light. A table row per capability, a line per follow-up field, a card
+per gap. The team will read this in one sitting and then argue about it; give
+them the shape to argue over, not prose.
+
+## Labels used in the tables
+
+**Parity**
+
+| Label | Meaning |
+| --- | --- |
+| `same` | Same capability, same shape; a path or field rename at most. |
+| `reshaped` | Same capability, different shape: pagination style, identifier form, event granularity, key semantics. The code changes, the behavior does not. |
+| `workaround` | Same outcome reachable with existing surface by a different route (follow-up read, client-side filter, marker). Tradeoff column is mandatory. |
+| `by-design-absent` | GitHub feature Origin deliberately does not reproduce (`origin-isms.md`). Points at the Origin idiom or says "no equivalent; decision needed". |
+| `gap` | No workaround, or a workaround whose tradeoff fails the bar (`gap-bar.md`). Has a card in § Gaps worth raising. |
+| `unknown` | Discovery could not determine the app's use or the spec's answer. Has an up-front question. |
+| `preview` (suffix) | The Origin operation is stamped `x-cursor-visibility: PREVIEW`. Usable; shape may still move. |
+
+**Size** — how much of the team's code changes for this row, by kind of
+change, never by time:
+
+| Size | Meaning |
+| --- | --- |
+| S | Contained in the adapter or client layer: a path, header, identifier, or pagination rewrite; a re-keyed lookup. |
+| M | A new code path: a follow-up read where the payload used to suffice, a handshake step, a new event handler, a data-model change for a new identifier or version concept. |
+| L | A product or architecture change: a flow that depended on user OAuth, a customer-visible behavior, a dependency on the customer's repositories being Origin-native, or a capability with an open gap card. |
+
+---
+
+## Template
+
+```markdown
+# Origin porting brief — <app name>
+
+Planning document. Maps this GitHub App's surface onto the Cursor Origin API
+as published on <date>. Contains no implementation decisions about language,
+framework, or client strategy.
+
+## Provenance
+
+- Origin OpenAPI `info.version`: `<value>`, fetched <timestamp>
+- Docs read: <the four URLs>
+- Codebase: `<repo>` at `<commit>`; scanned <n> files
+- Rows marked `workaround` or `gap` should be re-checked against the changelog before work starts; they are the rows most likely to have moved.
+
+## 1. What the app is today
+
+One paragraph in plain words: what the app does for its users, which GitHub
+events drive it, what it writes back. Then the inventory:
+
+| Facet | Finding | Evidence |
+| --- | --- | --- |
+| Manifest / declared permissions | … or "none checked in; permissions derived from calls" | `file:line` |
+| Declared / handled events | `pull_request.opened`, … | `file:line` |
+| REST call families | <count>, listed in § 3 | |
+| GraphQL | none / <count> documents, decomposed in § 3 | |
+| Auth flow | app JWT (<alg>) → installation token; user OAuth: <yes/no, for what> | `file:line` |
+| Webhook receiver | path, verification scheme, raw-body availability, dedupe | `file:line` |
+| Git as the app | clone / push / none | `file:line` |
+| Observed language and libraries | … (observed only) | |
+| Looked for, not found | … | |
+
+## 2. First decision: which repositories
+
+<State what the code assumes about the repositories it acts on.> On Origin,
+an installation has full scopes only on Origin-native repositories and
+stable outbound mirrors; repositories mirrored from GitHub are read-only to
+apps and do not deliver push events. **Question 1 below must be answered
+before the hello-world path is attempted.**
+
+## 3. Capability table
+
+One row per GitHub capability the code uses. Group rows by facet
+(authentication, installation & discovery, repositories & contents, pull
+requests, reviews & comments, checks, webhooks, git). Follow-up fields go in
+§ 4, not here.
+
+| GitHub thing (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question |
+| --- | --- | --- | --- | --- | --- |
+| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `OriginService_GetPullRequest` | same | S | — | — |
+| … | … | … | … | … | … |
+
+Rules for the table: the Origin column names an `operationId`, an event
+slug, a `llms-full.txt` anchor, or `none`; `workaround` rows always fill
+Tradeoff; `gap` rows link their card; `by-design-absent` rows name the idiom
+in the Tradeoff column; `unknown` rows name their question. Group rows by
+facet with a bold header row (Authentication · Installation & discovery ·
+Configuration · Repositories & contents · Pull requests · Reviews & comments
+· Checks · Webhooks: events · Webhooks: receiver · Git), and include rows
+for calls a dependency makes on the app's behalf, marked as such.
+
+**Scopes to request** (one line under the table): the union of
+`x-origin-scopes.scopes` across every Origin operation named above that an
+installation token can call, minus scopes that are ambient or implied
+(`write` implies `read`; `repository:metadata:read` is automatic). This is
+what the install URL's `scope` parameter carries, so the team can read it
+straight off the brief.
+
+## 4. Webhook payload fields the code reads
+
+For each mapped event, the fields the handlers dereference.
+
+| Event (GitHub → Origin) | GitHub field | Origin | How |
+| --- | --- | --- | --- |
+| `pull_request.synchronize` → `pull_request.head_ref.pushed` | `pull_request.head.sha` | present | `payload.pullRequest.head.sha` |
+| `push` → `repository.pushed` | `commits[].added` | follow-up read | `OriginService_ListComparisonFiles` on `refUpdates[].before..after` — one call per ref update |
+| … | `repository.html_url` | derivable / absent | … |
+
+"How" is one of: present at `<path>`; present in envelope (`event.type` for
+GitHub's `action`); follow-up read via `<operationId>` (state the call count
+per event); derivable (say from what, and whether the format is documented);
+absent (→ § 3's label for that row: `by-design-absent`, `unknown`, or a § 6
+card). Include fields the code reads only for logging; they are the ones
+teams forget until a dashboard breaks.
+
+## 5. Hello-world path
+
+The shortest route to one real event from one native repository. Each step
+is something to verify, not code to write. Link each to `llms-full.txt`.
+Append one step per spec-silent behavior the brief depends on (see the
+questions), stated as the observation to make.
+
+1. **Create the app** in the target namespace's app settings; register the
+ Ed25519 public key only; set the webhook URL and the callback URI.
+2. **Subscribe to events.** Installation lifecycle events arrive regardless;
+ select every repository event from § 3 explicitly. An unselected event is
+ silence, not an error.
+3. **Install** on an Origin-native repository (or a stable outbound mirror).
+ Verify the installation receipt (`kid` → JWKS, `alg`, `typ`, `iss`, `aud`,
+ `exp`, `state`); read the installation ID from `sub`. Never send the
+ receipt as a Bearer token.
+4. **Mint** an app JWT (EdDSA, ~5 min) and exchange it for an installation
+ token; call `/installation/repos` and confirm the repository is listed
+ and its `mirror` state is what § 2 expects.
+5. **Ping** the receiver and verify `v1ed` over the raw body against the
+ JWKS; check timestamp skew handling and `webhook-id` dedupe.
+6. **First real event**: perform the smallest action in § 3 on the native
+ repository (open a PR, push a branch) and confirm the delivery arrives
+ with the expected slug and the payload fields from § 4. If the ping
+ arrived and this did not, re-check steps 2 and 3 before anything else.
+7. **First write back** (if the app writes): the smallest write from § 3
+ (a check run with a stable `key`, a PR comment), confirming the scope
+ from `x-origin-scopes` is in the installation grant.
+
+## 6. Gaps worth raising
+
+Zero or more cards in the `gap-bar.md` shape. If zero, say: "No row failed
+the gap bar; the workarounds in § 3 carry their tradeoffs." Do not pad.
+
+## 7. Questions for the team
+
+Pruned to what discovery left open, plus anything specific found. Always
+starts with the first three.
+
+1. Will the app run against Origin-native repositories (or stable outbound
+ mirrors), or against repositories mirrored from GitHub? (Decides whether
+ the app receives events and can write at all.)
+2. Which of the 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 (user OAuth, install-by-user
+ pickers, acting on behalf of a user), and what should they do on Origin?
+4. Does anything key approvals or reviews by commit SHA rather than by pull
+ request version?
+5. Do you generate clients from OpenAPI? (Then read the changelog for schema
+ renames and check reserved names in your language.)
+6. How do you identify your own check runs / comments / reviews today, and
+ can a key or marker you control replace actor matching?
+7. What is your first success metric: ping received, first real event, or
+ first write back on a native repository?
+8. Anything marked `unknown` in § 1 or § 3.
+
+## 8. Out of scope for this brief
+
+No implementation, no SDK or language choice, no effort estimates in time.
+The brief is a map; the route is the team's.
+```
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
new file mode 100644
index 00000000..fb353213
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
@@ -0,0 +1,147 @@
+# Discovering the GitHub App's shape from the codebase
+
+Everything the brief needs about the existing app is in the repository. Search
+for it; do not ask for it. Record a file and line for every fact so the team
+can check your reading, and record every place you looked that turned up
+nothing so they can point you at the right place if you missed it.
+
+Work through the seven facets below. The searches are starting points across
+the common ecosystems (Node Octokit and Probot, Go `go-github`, Python
+`PyGithub`/`ghapi`/`githubkit`, Java `hub4j`, Ruby `octokit.rb`, .NET
+`Octokit.net`, raw HTTP in any language); extend them when the code uses
+something else. Note the language and libraries you observe as a fact in the
+inventory — they inform sizes in the brief and nothing else.
+
+## 1. Declared permissions and events
+
+The app's manifest or registration snapshot, if it is checked in.
+
+- Files: `app.yml`, `app.yaml`, `.github/app.yml`, `github-app-manifest.json`,
+ `manifest.json`, `app-manifest.*`, Terraform or Pulumi resources for the
+ app, and infrastructure-as-code that seeds a GitHub App.
+- Keys: `default_permissions`, `default_events`, `hook_attributes`,
+ `redirect_url`, `callback_urls`, `setup_url`, `public`,
+ `request_oauth_on_install`, `setup_on_update`.
+- Probot: `app.yml` at the repo root carries `default_events` and
+ `default_permissions`.
+
+When there is no manifest, derive the effective permissions from the calls in
+facet 4 and say the manifest was absent. The union of what the code calls is
+what the port needs anyway.
+
+## 2. Webhook events handled
+
+- Probot / `@octokit/webhooks`: `app.on("<event>.<action>", …)`,
+ `app.on([...])`, `webhooks.on(`, `webhooks.onAny(`, `EmitterWebhookEvent`.
+- Hand-rolled receivers: a `switch` or dispatch on the `x-github-event` header
+ (any casing), on `payload.action`, or on a combined `"<event>.<action>"`
+ string; Go `github.WebHookType(r)` / `github.ParseWebHook`; Python
+ `request.headers["X-GitHub-Event"]`.
+- Framework routes registered for webhook paths: `/webhook`, `/webhooks`,
+ `/github/webhooks`, `/api/github/events`, `createNodeMiddleware`,
+ `createProbot`, smee/ngrok tunnel config in development scripts.
+
+For each handled event record the GitHub event, the action(s) handled, the
+handler location, and — from facet 3 — which payload fields it reads.
+
+## 3. Payload fields read
+
+Inside each handler from facet 2, list every property path dereferenced from
+the payload object: `payload.pull_request.head.sha`, `payload.repository.name`,
+`payload.installation.id`, `payload.sender.login`, `payload.commits[].added`,
+`payload.check_suite.pull_requests`, `payload.before`, `payload.after`, and so
+on. Typed languages make this easy (struct fields accessed); in dynamic
+languages grep the handler body and any helper it passes the payload to.
+Include fields used only for logging or metrics — those are the ones teams
+forget until the port breaks a dashboard.
+
+## 4. REST and GraphQL calls
+
+- Octokit REST: `octokit.rest.<namespace>.<method>(`, `octokit.<namespace>.<method>(`,
+ `octokit.request("<METHOD> /…")`, `octokit.paginate(`, `octokit.graphql(`,
+ `@octokit/graphql`, `.graphql(`.
+- Other SDKs: Go `client.PullRequests.`, `client.Checks.`, `client.Repositories.`,
+ `client.Issues.`, `client.Apps.`; Python `repo.get_pull(`, `gh.rest.`,
+ `githubkit`; Java `GHRepository`, `GHPullRequest`; Ruby `client.pull_request(`.
+- Raw HTTP: `api.github.com`, `/repos/`, `Accept: application/vnd.github`,
+ `X-GitHub-Api-Version`, `uploads.github.com`, `raw.githubusercontent.com`.
+- GraphQL documents: `.graphql` / `.gql` files, template strings starting with
+ `query` or `mutation`, generated client code.
+
+Record each distinct call family once (method + path, or SDK method), with
+the parameters and filters the code passes (state, base, head, per_page,
+sort, since, check_name, app_id, filter…), the response fields it reads, and
+whether it is called in a loop or per webhook (this decides the fan-out
+tradeoff on the brief row). Note pagination style in use (`Link` header,
+`page`/`per_page`, `octokit.paginate`, GraphQL cursors) — it always changes.
+
+## 5. Authentication and token minting
+
+- App identity: `GITHUB_APP_ID`, `APP_ID`, `GITHUB_PRIVATE_KEY`, `PRIVATE_KEY`,
+ `.pem` files, `createAppAuth`, `@octokit/auth-app`, `ghinstallation`
+ (Go), `jwt.encode(... "RS256")`, `App.get_installation(`.
+- Installation tokens: `/app/installations/{id}/access_tokens`,
+ `installationId`, `installation_id`, `app.auth(`, `getInstallationOctokit(`,
+ `ghs_` prefixes in tests or fixtures, token caches keyed by installation.
+- User OAuth: `/login/oauth/authorize`, `/login/oauth/access_token`,
+ `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `@octokit/auth-oauth-*`,
+ `/user`, `/user/installations`, `/user/repos`, "setup URL" handlers reading
+ `installation_id` and `setup_action` from the callback query string.
+- Git over HTTPS as the app: `x-access-token:` in clone URLs, credential
+ helpers, `GIT_ASKPASS`.
+
+Record the flows present: app JWT algorithm, how the installation is
+identified after install (callback query, webhook, or DB), token lifetime
+handling, whether user OAuth exists and what it is used for (identity,
+repo discovery, acting on behalf of a user), and whether the app pushes or
+clones git.
+
+## 6. Webhook receiver and verification
+
+- Signature: `x-hub-signature-256`, `x-hub-signature`, `verify(`,
+ `verifyAndReceive(`, `WEBHOOK_SECRET`, HMAC-SHA256 helpers,
+ `github.ValidatePayload`.
+- Delivery handling: use of `x-github-delivery` for idempotency, queueing
+ before or after responding, retry handling, redelivery tooling against
+ `/app/hook/deliveries`.
+- Transport: the public URL and how it is configured (manifest
+ `hook_attributes.url`, env var, tunnel in dev).
+
+Record the verification scheme, whether the raw body is available at
+verification time (frameworks that parse JSON first cannot verify), and how
+deliveries are deduplicated, if at all.
+
+## 7. Calls the framework makes on the app's behalf
+
+Some of the app's GitHub surface is not in its own source: it is what the
+framework or a helper library does for it, and the port has to do it too.
+When the code uses one of these, list the calls the dependency makes as rows
+in their own right, marked "from `<dependency>` (documented behavior)" so the
+team knows they were inferred, not read. `node_modules` is usually not
+checked in, so read the dependency's README or its source on its own
+repository, not the app.
+
+- **Probot**: the built-in receiver (`POST /`, `@octokit/webhooks` HMAC
+ verification, `x-github-event` routing), per-installation token minting
+ and caching, `context.repo()` / `context.issue()` helpers,
+ `context.isBot` (`payload.sender.type`). Common companions:
+ `probot-config` (reads `.github/<file>.yml`, falling back to the owner's
+ `.github` repository), `probot-scheduler` (lists installations and their
+ repositories with the app credential, then emits `schedule.repository` on
+ an interval), `probot-metadata` (stores state in issue bodies).
+- **Octokit `App` / `@octokit/app`**: `app.webhooks.verifyAndReceive`,
+ `app.eachInstallation` / `app.eachRepository` (installation + repository
+ listing), automatic installation-token minting behind
+ `app.getInstallationOctokit`.
+- **Go `ghinstallation`, Python `githubkit`/`gidgethub`, Ruby `octokit`
+ app auth**: JWT minting and installation-token exchange.
+- **Frameworks' webhook middleware** in any language: which header names
+ they read and whether they verify against the raw body.
+
+## When something is missing
+
+Say so in the inventory: "no manifest found (searched: …)", "no signature
+verification found in the receiver at …", "GraphQL client present but no
+query documents found". Each missing item becomes either a row with an
+`unknown` label or an up-front question in the brief. Do not fill gaps with
+assumptions about 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
new file mode 100644
index 00000000..1e0d3290
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
@@ -0,0 +1,143 @@
+# The gap bar and the escalation card
+
+Most differences between GitHub and Origin are not gaps. A brief that files
+every difference trains the team to ignore it and buries the two or three
+things Cursor actually needs to hear. Use this bar, and when in doubt, write
+the row as `workaround` with an honest tradeoff and an open question rather
+than as a gap card.
+
+## Definitions
+
+- A **difference** is any row whose parity label is not `same`.
+- A **workaround** is a way to get the same outcome with the surface that
+ exists today: a follow-up read, a re-keyed identifier, a path change, a
+ client-side filter, a marker the app controls.
+- A **gap** is a difference with **no workaround**, or a workaround whose
+ tradeoff is **nontrivial**. Only gaps become escalation cards.
+
+## What makes a tradeoff nontrivial
+
+A workaround's tradeoff is nontrivial when at least one of these holds. Quote
+the one that applies on the card.
+
+| Tradeoff | Test |
+| --- | --- |
+| **Fan-out at scale** | The workaround multiplies calls per event by a factor that grows with repository or activity size (N commits × M files per push; a full list scan to find one row), and the app's event volume makes that budget-relevant. One extra bounded read per event is trivial. |
+| **Correctness risk** | The workaround can produce a wrong answer, not just a slower one: identifying "my own row" by a heuristic; inferring a pull request from a SHA that 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. |
+| **Product behavior visible to the team's customers** | The workaround changes what their users see or can do (no team link in a comment, no user-scoped repository picker), not just how the code is organized. |
+| **Load-bearing for the port** | The capability sits on the hello-world path or on the team's stated core flow, so its tradeoff decides whether the port ships. |
+
+If none apply, the row is `workaround`, sized honestly, with the tradeoff in
+the tradeoff column and no card.
+
+## What is never a gap
+
+- Anything on the `origin-isms.md` list. Those rows are `by-design-absent`
+ or `reshaped`, and the brief points at the idiom. Filing them wastes the
+ team's and Cursor's time; the decisions are recorded.
+- A field or filter the code does not actually use. Map what the code reads,
+ not what the SDK exposes.
+- A difference that exists only because the code uses a GitHub convenience
+ (`Link` pagination, numeric IDs, `html_url`) in a place where the Origin
+ convention is a mechanical substitution.
+- Something the changelog says shipped or the spec already carries. Re-check
+ the live spec before writing any card; the rows most likely to be stale are
+ the ones you are about to escalate.
+- A concept the Origin docs never mention at all (Marketplace billing, merge
+ queues, Actions, Projects). That is `unknown` plus a question
+ (`spec-mapping.md` § Out-of-domain surfaces); a card asks Origin to build
+ something the team may not want.
+- A GitHub search query. Origin has no search endpoint by design for the
+ surfaces it exposes; a list operation with `sortBy`/`state`/filters plus a
+ client-side predicate is the idiom. Count the fan-out honestly (a sorted
+ list read that stops at a cutoff is proportional to the matches, not the
+ collection), and only if that count fails the bar does it become a card
+ about a *filter*, never about search.
+
+## One pattern that does clear the bar
+
+A state change the app reacts to that has **no event**, when the app's
+purpose is to react to exactly that change and the state is otherwise
+invisible until an unrelated event arrives. Reading the state off the next
+event's snapshot is the workaround; it fails on correctness and
+customer-visible behavior when the app is a gate (a check, a block, a
+notification) and the lag is the whole failure mode. Write the card about the
+event; do not write it when the app merely logs or tidies up on that change.
+
+## The escalation card
+
+One card per gap, in the brief's "Gaps worth raising" section, in this shape.
+It is written so Cursor can act on it without a call.
+
+```markdown
+### Gap: <one line naming the capability, in Origin terms>
+
+- **GitHub surface the app uses:** `<METHOD /path>` or `<event.action>` or `<permission>`, at `<file:line>`.
+- **What the app needs from it:** <the data or effect, one sentence>.
+- **Why:** <what the app does with it, one sentence>.
+- **Closest Origin surface today:** `<operationId>` / `<event slug>` / none, and what it lacks.
+- **Workaround considered:** <the workaround, or "none found">.
+- **Tradeoff that fails the bar:** <one of the five, quoted, with the number or risk>.
+- **Shape that would close it:** <a field, a filter, an event, an operation — described as a capability, not a design: "list pull requests whose head is this SHA", not a proto sketch>.
+- **Blocking?** yes / no, and for which flow.
+- **Spec version checked:** `<info.version>` on `<date>`.
+```
+
+Keep the card to those lines. Do not propose scope names, field names, or
+route templates; Cursor owns the shape and applies design conventions the
+card cannot see. Do not batch unrelated capabilities into one card.
+
+## Where the card goes
+
+The brief is written for the team. The cards are theirs to send, in their own
+words if they prefer. Two routes exist today:
+
+- **A shared Slack channel with Cursor**, if the team has one from working
+ with Cursor on the integration. Post the card there; it reaches the people
+ who own the API.
+- **`[email protected]`**, the feedback address the Origin documentation names.
+ Put "Origin API" and the app name in the subject and paste the card.
+
+Either way, quote the spec version the card was checked against and any
+`X-Request-ID` values from failed calls (every Origin error response carries
+one; the API reference asks for it when you contact Cursor). A card that
+states the capability and the tradeoff cleanly is the fastest path to an
+answer, including a "this is by design, here is the idiom" answer, which is a
+fine outcome and belongs back in the brief as a `by-design-absent` row.
+
+Do not send cards yourself. Write them, put them in the brief, and let the
+team decide what goes out.
+
+## Calibration examples
+
+Illustrations of where the bar falls. Each is written as a pattern, because
+the specific surface may have moved since this file was written; confirm
+against the live spec before reusing the verdict.
+
+- **A list operation lacks a filter the code relies on to find its own row**
+ (for example, finding the app's own check run for a commit by name or key).
+ Workaround: page the whole list and match client-side. Trivial when the
+ list is small and bounded; **gap** when the list grows with activity and the
+ lookup runs per event (fan-out) or when the match is heuristic
+ (correctness). State which.
+- **A web URL the app posts in comments is not in the payload or resource.**
+ Workaround: assemble it from slug and number. Correctness risk only if the
+ URL format is not contractual — check the docs; if the format is documented,
+ it is `derivable`, not a gap. If it is not documented, write a card that
+ asks for the URL field rather than guessing.
+- **A membership roster the app uses to attribute approvals to a team** has
+ no read on Origin and no workaround (identity is a TypeID; there is no
+ directory). Correctness plus product behavior: **gap**, with a card that
+ names the capability ("who is in group X, for a repository this
+ installation can read") and leaves the oracle analysis to Cursor.
+- **Push payload lacks the changed-file list.** Workaround: compare or list
+ commit files on receipt. One bounded read per push is `workaround`; if the
+ app fans out per commit and per file on high-volume repositories, quote the
+ multiplier and let the team decide — and note that the lean payload is the
+ documented design (`origin-isms.md` § Webhooks), so the card, if any, is
+ about a compare endpoint's shape, not about fattening the payload.
+- **The app uses GitHub Issues.** Never a card. `by-design-absent`; the
+ up-front question is what the PR-scoped behavior should be.
+- **The app uses commit statuses.** Never a card. `reshaped` onto check runs
+ with a stable key.
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
new file mode 100644
index 00000000..d81f7226
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
@@ -0,0 +1,169 @@
+# Origin-isms: where Origin departs from GitHub on purpose
+
+Origin uses GitHub's nouns and general shape and deliberately not its wire
+format. When a GitHub feature has no counterpart in the spec, check this list
+before calling it a gap: a row here is `by-design-absent` (or `reshaped`) in
+the brief, and the brief's job is to point the team at the Origin idiom. Each
+entry gives the departure, the idiom, and the reason in one line, so you can
+explain it to a team that has only ever seen GitHub. Confirm the current
+wording in `llms-full.txt`; this file explains intent, the docs state the
+contract.
+
+## Which repositories an app can act on
+
+- **Apps act on Origin-native repositories (and stable outbound mirrors).** A
+ repository mirrored *from* GitHub is read-only to an installation — metadata
+ and contents reads, clone/fetch/pull — and rejects pull requests, reviews,
+ comments, checks, rulesets, and every write with `403`. Why: a write on a
+ mirror would have to act on GitHub as Cursor's GitHub App, with risk Origin
+ cannot bound; and GitHub already sends its own webhooks for those repos.
+- **`repository.pushed` is not delivered for GitHub-mirrored repos.** Why:
+ GitHub owns those pushes and already notifies the app; Origin would
+ duplicate them. Consequence for the port: a ping works on a mirror and then
+ nothing else does. The first up-front question in every brief is
+ native-or-mirror for exactly this reason.
+- **`mirror.status` does not tell you whether writes are allowed.** Treat the
+ `403` as authoritative.
+
+## Identity and authentication
+
+- **No OAuth-app token exchange as the install path.** Install is a consent
+ redirect that returns a signed **installation receipt** JWT (`sub` = the
+ installation ID, `state` echoed) instead of `installation_id` and
+ `setup_action` query parameters. Why: the receipt proves the approval came
+ from Origin; a bare query string cannot. The receipt is never a Bearer
+ token.
+- **App JWT is EdDSA over Ed25519, not RS256.** Register only the public key;
+ up to ten active keys. `kid` and `iss` are the app ID; `aud` is fixed.
+- **Installation tokens are `oit_…`, short-lived, minted just in time**, and
+ can be attenuated to fewer scopes or to specific `repositoryIds` (IDs, not
+ slugs — resolve the ID first). Git over HTTPS uses Basic auth with username
+ `x-access-token` and the token as password; Bearer belongs to REST only.
+- **User-scoped calls (`/user`, `/user/installations`, install-by-user) have
+ no app-side counterpart.** Repository discovery is through the
+ installation (`/installation/repos`), and app creation, adding
+ repositories to an installation, and mirror transitions are admin actions
+ carried by a Cursor user credential, not app calls. Read the live
+ Authentication section for the current user-credential story before
+ labeling anything here; do not assume a GitHub-OAuth analog exists.
+- **Scopes, not permissions.** `repository:<noun>[:<sub>]:<read|write>`;
+ `write` implies `read`; `repository:metadata:read` is automatic; the
+ installation can only narrow what the admin approved. Look each called
+ operation's requirement up in `x-origin-scopes` rather than translating the
+ manifest noun-for-noun.
+
+## Wire conventions
+
+- **Opaque TypeIDs, never integers**: `app_…`, `i_…`, `ns_…`, `repo_…`,
+ `user_…`, `cmt_…`, `evt_…`. Why: sequential IDs are enumerable; opaque IDs
+ are the stable handle to cache. A repository is addressable by ID as
+ `/repos/_/{repoId}`, which survives renames; there is no
+ `/repositories/{id}` route and no numeric ID anywhere.
+- **camelCase JSON; 64-bit integers (PR numbers, version numbers) are JSON
+ strings; RFC 3339 timestamps.**
+- **Defaults are present, not omitted.** `false`, `0`, `""`, `[]` appear in
+ bodies; only fields documented as optional are absent when unset. Do not
+ treat a missing key as the default and do not treat a present `false` as
+ "unset".
+- **Pagination is `pageSize` / `pageToken` / `nextPageToken`.** Tokens are
+ opaque, bound to the resource and filters, and there is no `Link` header,
+ no `page`, no total count. Why: keyset cursors do not skip or duplicate
+ under concurrent writes; offsets do. Restart when filters change.
+- **Errors are one envelope**: `google.rpc.Status` `{code, message, details}`
+ with typed `details` (`BadRequest` field violations, `RequestInfo` request
+ id on every error; further typed detail types such as machine-readable
+ `ErrorInfo` reasons may be added, so read the live Errors section and
+ tolerate unknown detail types). `X-Request-ID` is on every error. **`404`
+ never distinguishes not-found from no-access.** Why: anti-enumeration.
+ Branch on status and `code`; quote the request id when escalating.
+- **No GraphQL.** REST only; decompose queries.
+- **Rate limits are a per-principal point budget**, `X-RateLimit-*` plus
+ `Retry-After` on `429`; Git HTTPS meters separately (`X-RateLimit-Resource:
+ git`). Cursor can raise per-app budgets on request.
+- **Public terminology is "pull request"** throughout; do not expect
+ "change" or "changeset" on the wire.
+
+## Resources GitHub has that Origin does not reproduce
+
+- **No commit statuses.** Check runs are the only status primitive:
+ `PostCheckRun` upserts on a caller-stable `key` (with `externalId` /
+ `externalUpdatedAt` for retries and ordering), and rulesets bind on check
+ keys. Why: one status model, idempotent by construction. A `statuses`
+ permission or `POST /statuses/{sha}` maps to checks, not to a gap.
+- **No Issues.** Origin's conversation surfaces are pull requests, pull
+ request comments and threads, reviews, and labels on pull requests. An
+ `issues`-only GitHub App has no Origin equivalent for that part; say so
+ and ask what the team wants the PR-scoped behavior to be. GitHub's
+ `/issues/{n}/comments` used *on a PR* is just a path change.
+- **No repository-level webhook CRUD** (`/repos/…/hooks`). Subscriptions are
+ an app-settings concern; there are no per-repo hook objects.
+- **No app-manifest conversion endpoint and no OAuth-app token mints.**
+ Legacy GitHub mechanisms Origin does not reproduce. App creation is a
+ form (which accepts prefill query parameters) or the user-credential
+ `CreateApp` operation.
+- **No REST git-object writes beyond the documented ones.** Commits are
+ pushed over Git HTTPS with an installation token (or created through the
+ documented commit-from-files and ref operations); do not expect a GitHub
+ Git Data API for arbitrary tree/blob writes.
+- **No standalone threads API.** Comments are the only content write
+ surface; a thread materializes from its first diff-anchored comment and is
+ addressable for resolve/reopen. Why: one write surface, no dual bookkeeping.
+- **No user/email directory.** Actors carry a TypeID (and a handle where the
+ contract exposes it); there is no lookup from email to user and no team
+ or member pages to link to. Why: an email or membership oracle.
+
+## Webhooks
+
+- **One message serves REST and webhooks.** A payload snapshots the one
+ object that changed exactly as its `Get…` returns it, plus compact
+ references (`repository`, `pullRequest`) for its containers. Why: consumers
+ reuse their REST decoders and never see a partially hydrated shape.
+- **Webhooks notify; the API answers.** Payloads are lean by design: no
+ changed-file lists on pushes, no before-SHA on PR events, no web URLs, no
+ inlined user profiles. Follow-up reads (`GetCommit`, `CompareCommits`,
+ `ListComparisonFiles`, `GetRepo`, `GetPullRequest`) are the intended
+ pattern. Why: no emit-time joins, no size blowups, no staleness races.
+ Map fields the code reads to specific follow-up calls and count the
+ fan-out honestly; that count is the tradeoff, not a defect.
+- **Slugs are `<resource>[.<sub>].<past-tense-action>`** and the action lives
+ in the slug (`pull_request.created`, `pull_request.review.submitted`,
+ `repository.check_run.completed`), never in a payload `action` field, and
+ there is no `previous_attributes` delta. Why: granular event types over
+ payload flags; one shape per event. GitHub's `pull_request` +
+ `action: synchronize` becomes `pull_request.head_ref.pushed`, and so on —
+ confirm each in `x-origin-webhook-events`.
+- **Envelope**: `{deliveryId, appId, installationId, event: {id, type,
+ eventTime, payload}}`. `deliveryId` is stable across retries and is the
+ idempotency key; `event.id` identifies the domain event. Routing headers
+ are `webhook-id`, `webhook-timestamp`, `webhook-signature`,
+ `webhook-event-type`, `webhook-app-id`, `webhook-installation-id` (not
+ `x-github-*`); after verification the body is authoritative.
+- **Signature is Ed25519 over a SHA-256 digest, scheme `v1ed`**, keys from
+ Origin's JWKS (rotated weekly, cache per `Cache-Control`), not an HMAC
+ shared secret. It tracks the Standard Webhooks spec except that it signs a
+ digest instead of the raw string, so off-the-shelf Standard Webhooks
+ verifiers do not validate it as-is. Verify the raw body before parsing;
+ reject timestamps more than five minutes off.
+- **Installation lifecycle events are always delivered; every other event
+ must be selected in app settings.** Creating the app subscribes to nothing
+ else. Why: opt-in exposure. This is the second most common first-week
+ stall after mirror-vs-native.
+- **Delivery is at-least-once with retries and a seven-day recovery window**
+ (`ListWebhookDeliveries`, `BatchRedeliverWebhookDeliveries`); persistent
+ failure pauses the app's delivery.
+
+## Checks, reviews, comments
+
+- **Check runs upsert on `key`**, live under a check suite keyed the same
+ way, and can be flagged re-requestable; a re-request arrives as an event
+ to the owning app. Annotations are appended, not replaced.
+- **Reviews anchor to a pull request *version*, not a commit SHA.** Why: a
+ SHA can match several versions after a rebase or retarget. Code that keys
+ approvals by `commit_id` re-keys by version number.
+- **Requested reviewers are addressed by identifier** (users, groups), and
+ Origin is deliberately careful about existence oracles on that surface. Do
+ not expect `created_via` or team pages on the read side.
+- **Find your own writes by a key you control.** Check runs are found by
+ their `key`; for reviews and comments, carry a marker the app owns (a body
+ prefix, a stable key) rather than relying on actor identity alone, and
+ confirm in the spec which author filters the list operations offer.
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
new file mode 100644
index 00000000..d0dcf83f
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
@@ -0,0 +1,185 @@
+# Reading the Origin spec and matching GitHub surface to it
+
+The mapping in the brief is derived from the live `openapi.yaml`, not from a
+table in this skill. This file explains what the spec carries and how to match
+against it. Build the index once at the start of the run; every later step
+looks things up in it.
+
+## What the spec carries
+
+`https://cursor.com/docs/api/origin/openapi.yaml` is OpenAPI 3.1 generated from
+Origin's protobuf contract. Beyond the standard fields, four extensions matter
+for porting:
+
+| Extension | Where | Meaning |
+| --- | --- | --- |
+| `x-origin-scopes` | every operation | `scopes`: the scope strings the operation requires. `tokenTypes`: which credentials it accepts (`app` JWT, `installation` token, `user`). `ambient: true`: the scopes come with the credential itself, so an app has nothing to request for it. |
+| `x-origin-webhook-events` | payload schemas under `components.schemas` | The event slugs that deliver this payload shape. A schema carrying it is a webhook payload family; the slugs are the only authoritative list of subscribable events. |
+| `x-origin-webhook-resource` | payload schemas, when present | Points at the REST component the payload embeds (the object a `Get…` operation returns). When absent, infer the embedded resource from the payload's `$ref` properties. Do not assume every payload has a REST twin; pushes, deletions, and reviewer requests are event-native. |
+| `x-cursor-visibility: PREVIEW` | some operations | Published but badged preview. Carry the badge into the brief; a preview operation is usable, but tell the team the shape may still move. |
+
+Everything else you need is standard: `paths` with `operationId`,
+`description`, `parameters`, request and response schemas, and `example`
+blocks; `components.schemas` with field descriptions that are the contract
+text itself.
+
+`llms-full.txt` adds what the spec cannot: the installation flow, the receipt
+and app JWT, installation tokens and Git HTTPS, the scopes table, the mirrored
+repositories rule, webhook headers, signature verification, the delivery
+envelope, retries and recovery, pagination and error conventions, and the
+current limitations list. Read those sections before mapping; several rows in
+the brief (auth, receiver, pagination) map onto them rather than onto an
+operation.
+
+## Build the index
+
+Parse the YAML and produce four lookups. Keep them in a scratch file; the
+brief cites from them.
+
+1. **Operations**: for each path and method, record `operationId`, method,
+ path template, first sentence of `description`, `x-origin-scopes`
+ (`scopes`, `tokenTypes`, `ambient`), `x-cursor-visibility` if any, path and
+ query parameter names, request body top-level fields, and the response
+ component name.
+2. **Webhook events**: for each schema with `x-origin-webhook-events`, record
+ each slug → schema name → the properties and their `$ref`s (or the
+ `x-origin-webhook-resource` target). Also read the Events table in
+ `llms-full.txt` § Webhooks reference for each slug's trigger sentence and
+ for which events are app-lifecycle (always delivered) versus repository
+ subscriptions (must be selected in app settings).
+3. **Scopes**: the union of every `scopes` value seen in `x-origin-scopes`,
+ annotated with which operations require it, plus the Scopes table in
+ `llms-full.txt` for the human description and the `write` ⊃ `read` rule.
+ Separate the scopes an installation can request from those that are
+ ambient or user-credential-only; the latter tell you which GitHub flows
+ have no app-side equivalent by construction (for example, app creation and
+ installation-repository changes are admin actions on Origin, not app
+ calls).
+4. **Resources**: component schemas returned by `Get…`/`List…` operations,
+ with their field names. Used to answer "which fields does the Origin object
+ carry" when mapping payload fields and response fields the code reads.
+
+## Matching rules
+
+Match in this order and stop at the first rule that yields a confirmed
+counterpart. "Confirmed" means you read the Origin operation's description and
+parameters and they answer the same question the GitHub call answers. A name
+match is a candidate, never a result.
+
+### REST calls
+
+1. **Normalize the GitHub path** and look for the same shape under
+ `/v1/origin`: `/repos/{owner}/{repo}` → `/v1/origin/repos/{ownerSlug}/{repoName}`;
+ `{pull_number}` → `{pullNumber}`; `{ref}`/`{sha}` stay; GitHub's
+ `check-runs`, `check-suites`, `compare/{basehead}`, `contents`, `git/…`,
+ `pulls/{n}/{files,commits,reviews,comments,requested_reviewers,merge}`,
+ `labels`, `branches`, `commits` all have direct or near-direct shapes.
+ Custom-verb operations on Origin use a `:verb` suffix
+ (`…/contents:batchGet`, `…/check-runs:batchUpsert`, `…:grep`).
+2. **Re-home GitHub's issue-flavored PR calls.** GitHub puts PR conversation
+ comments under `/issues/{n}/comments` and labels under `/issues/{n}/labels`;
+ on Origin those live under `/pulls/{n}/…`. This is a path change, not a
+ gap, when the code only ever uses them on pull requests. When the code
+ uses them on real issues, see `origin-isms.md` (issues are not an Origin
+ surface).
+3. **Re-home app and installation calls.** GitHub's `/app`,
+ `/app/installations`, `/app/installations/{id}/access_tokens`,
+ `/installation/repositories` have Origin counterparts under `/v1/origin/app…`
+ and `/v1/origin/installation/repos`; check `tokenTypes` to confirm which
+ credential each takes. GitHub's `/user`, `/user/installations`,
+ `/orgs/{org}/…`, `/search/…`, and `/repositories/{id}` have no path
+ counterpart; consult `origin-isms.md` and the Authentication section
+ before deciding whether they are absent by design, covered by a different
+ idiom, or a gap.
+4. **Compare parameters, not just paths.** A matching path with a missing
+ filter the code depends on (for example a list the code narrows by a field
+ Origin does not accept) is `workaround` or `gap`, not `same`. Read the
+ `parameters` block.
+5. **Compare response fields the code reads.** Trace which response
+ properties the handlers dereference and check them against the Origin
+ component. Missing fields are common where GitHub inlines convenience data
+ (web URLs, nested user profiles, aggregate counts). Each missing field gets
+ its own line under the row: follow-up call, derivable, or absent.
+
+### GraphQL
+
+There is no GraphQL endpoint. Decompose each query or mutation into the REST
+reads and writes it stands for, then map those individually. Note the fan-out
+(one query → N calls) as the tradeoff on the row. If the query exists to
+avoid REST pagination or to fetch a cross-repository view, say so; that is
+the tradeoff the team weighs.
+
+### Permissions → scopes
+
+GitHub permissions are `<noun>: read|write`; Origin scopes are
+`repository:<noun>[:<subnoun>]:<read|write>` with `write` implying `read`
+and `repository:metadata:read` granted automatically. Match the noun, then
+verify by finding the operations the code actually calls in the Operations
+lookup and reading *their* `x-origin-scopes` — the scope set in the brief is
+the union of what the called operations require, not a translation of the
+manifest. GitHub permissions with no Origin noun (`statuses`, `issues`,
+`members`, `organization_*`, `pages`, `actions`, `workflows`, `secrets`,
+`deployments`, `environments`) go through `origin-isms.md` before they can be
+called gaps.
+
+### Webhook events → slugs
+
+Origin slugs are `<resource>[.<sub-resource>].<past-tense-action>` with the
+action in the slug, never in the payload: GitHub's single `pull_request` event
+with an `action` field is several Origin events. Translate each
+`event.action` pair the code handles into a candidate slug, then confirm the
+slug appears in the Webhook events lookup. Candidates that do not appear are
+not events on Origin; check whether the state change is observable another
+way (an event on a related resource, or a REST read on receipt of one) before
+classifying. Installation lifecycle events are always delivered to the app;
+everything else must be subscribed explicitly, which the brief's hello-world
+path calls out.
+
+### Payload fields → schema properties
+
+For each field path a handler reads off a GitHub payload
+(`payload.pull_request.head.sha`, `payload.repository.full_name`,
+`payload.sender.login`, `payload.commits[].added`), find the Origin payload
+schema for the mapped slug and walk its properties. Record one of:
+
+- **present** at `<origin.path>`;
+- **follow-up read**: not in the payload, available from `<operationId>` using
+ identifiers the payload does carry;
+- **derivable**: assembled from present fields (say how, and note whether the
+ format is contractual);
+- **absent**: no payload field and no read that yields it (this row goes to
+ the gap bar).
+
+The payload carries references (`repository`, `pullRequest`) around the
+snapshot of the one object that changed. Expect a lean shape and plan the
+follow-up reads; that is the Origin design, not a defect
+(`origin-isms.md` § Webhooks). Compare the webhook snapshot's schema with
+the REST resource it mirrors: a field on the REST component that the webhook
+twin lacks (for example a list the resource carries but the snapshot omits)
+is a follow-up read via the matching `Get…`, and the code that reads it off
+the GitHub payload today needs that read on every event.
+
+### Out-of-domain surfaces and spec-silent behavior
+
+Some of what a GitHub App touches is not source control at all: Marketplace
+billing and plan lookups, merge queues, Actions, Pages, Projects,
+Milestones, Discussions, `github.com` HTML probes. When neither the spec nor
+`llms-full.txt` mentions the concept, the row is `unknown` with an up-front
+question about what the team wants on Origin, never `gap` (Origin has not
+declined it; the team may not need it) and never `by-design-absent` (only
+`origin-isms.md` rows earn that).
+
+When the code depends on a behavior the docs do not state (does an event
+fire for a pull request opened as a draft? does `updatedAt` move on a
+comment? what does a remove return when nothing was there?), do not resolve
+it from GitHub's behavior. Record the dependency in the row's Open question
+column and add a step to the hello-world path that observes it on a native
+repository.
+
+## Provenance in the brief
+
+Write the spec's `info.version`, the fetch timestamp, and the four URLs into
+the brief's provenance block. State plainly that the brief reflects the
+surface on that date and that the team should re-read the changelog before
+acting on any row marked `workaround` or `gap`, because those are the rows
+most likely to have moved.
diff --git a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py
new file mode 100644
index 00000000..2bb1aa2a
--- /dev/null
+++ b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Print a grep-friendly index of the Origin OpenAPI spec.
+
+Usage:
+ python3 index-origin-spec.py openapi.yaml # everything
+ python3 index-origin-spec.py openapi.yaml ops # operations only
+ python3 index-origin-spec.py openapi.yaml events # webhook payload families
+ python3 index-origin-spec.py openapi.yaml scopes # scope catalog
+ python3 index-origin-spec.py openapi.yaml schema PullRequest # one component
+
+Fetch the spec first:
+ curl -sSL https://cursor.com/docs/api/origin/openapi.yaml -o openapi.yaml
+
+Read-only. Needs PyYAML (`pip install pyyaml`). Everything printed comes from
+the spec you pass in; nothing is pinned or embedded here.
+"""
+
+import sys
+
+try:
+ import yaml
+except ImportError: # pragma: no cover
+ sys.stderr.write(
+ "PyYAML is not installed. Run `pip install pyyaml`, or read the spec "
+ "directly (search for `operationId:`, `x-origin-scopes:`, and "
+ "`x-origin-webhook-events:`).\n"
+ )
+ sys.exit(2)
+
+METHODS = ("get", "post", "put", "patch", "delete")
+
+
+def ref_name(node):
+ if not isinstance(node, dict):
+ return None
+ if "$ref" in node:
+ return node["$ref"].rsplit("/", 1)[-1]
+ if "allOf" in node and node["allOf"] and "$ref" in node["allOf"][0]:
+ return node["allOf"][0]["$ref"].rsplit("/", 1)[-1]
+ if node.get("type") == "array":
+ inner = ref_name(node.get("items", {}))
+ return f"{inner}[]" if inner else "array"
+ return None
+
+
+def first_sentence(text):
+ return " ".join((text or "").split()).split(". ")[0][:140]
+
+
+def print_schema(components, name, depth=0, seen=None, max_depth=2):
+ seen = seen or set()
+ schema = components.get(name)
+ if not schema:
+ print(f"{' ' * depth}(no component named {name})")
+ return
+ for field, node in (schema.get("properties") or {}).items():
+ kind = ref_name(node) or node.get("type", "?")
+ desc = first_sentence(node.get("description"))
+ print(f"{' ' * depth}{field}: {kind}" + (f" -- {desc}" if desc else ""))
+ inner = (ref_name(node) or "").rstrip("[]")
+ if inner and inner in components and depth < max_depth and inner not in seen:
+ seen.add(inner)
+ print_schema(components, inner, depth + 1, seen, max_depth)
+
+
+def print_ops(spec):
+ print("== OPERATIONS (operationId | METHOD path | scopes | tokenTypes | ambient | visibility)")
+ for path, methods in spec["paths"].items():
+ for method, op in methods.items():
+ if method not in METHODS:
+ continue
+ xs = op.get("x-origin-scopes") or {}
+ params = [p["name"] for p in op.get("parameters", [])]
+ body = None
+ rb = op.get("requestBody")
+ if rb:
+ schema = rb["content"]["application/json"]["schema"]
+ body = ref_name(schema) or list((schema.get("properties") or {}).keys())
+ resp = (
+ op.get("responses", {})
+ .get("200", {})
+ .get("content", {})
+ .get("application/json", {})
+ .get("schema", {})
+ )
+ print(
+ f"{op.get('operationId')} | {method.upper()} {path} | "
+ f"scopes={xs.get('scopes')} tokenTypes={xs.get('tokenTypes')} "
+ f"ambient={xs.get('ambient')} visibility={op.get('x-cursor-visibility')}"
+ )
+ print(f" params={params} body={body} -> {ref_name(resp) or '(empty)'}")
+ print(f" {first_sentence(op.get('description'))}")
+
+
+def print_events(spec):
+ components = spec["components"]["schemas"]
+ print("== WEBHOOK PAYLOAD FAMILIES (schema | slugs | x-origin-webhook-resource)")
+ for name, schema in components.items():
+ slugs = schema.get("x-origin-webhook-events")
+ if not slugs:
+ continue
+ print(f"{name} | {slugs} | resource={schema.get('x-origin-webhook-resource')}")
+ print_schema(components, name, depth=1, max_depth=2)
+
+
+def print_scopes(spec):
+ print("== SCOPES (scope | tokenTypes seen | operations)")
+ table = {}
+ for path, methods in spec["paths"].items():
+ for method, op in methods.items():
+ if method not in METHODS:
+ continue
+ xs = op.get("x-origin-scopes") or {}
+ for scope in xs.get("scopes") or []:
+ entry = table.setdefault(scope, {"tokens": set(), "ops": [], "ambient": False})
+ entry["tokens"].update(xs.get("tokenTypes") or [])
+ entry["ops"].append(op.get("operationId"))
+ entry["ambient"] = entry["ambient"] or bool(xs.get("ambient"))
+ for scope in sorted(table):
+ e = table[scope]
+ print(f"{scope} | tokenTypes={sorted(e['tokens'])} ambient={e['ambient']} | {e['ops']}")
+
+
+def main(argv):
+ if len(argv) < 2:
+ print(__doc__)
+ return 1
+ with open(argv[1], encoding="utf-8") as fh:
+ spec = yaml.safe_load(fh)
+ mode = argv[2] if len(argv) > 2 else "all"
+ print(f"# {spec['info'].get('title')} {spec['info'].get('version')}")
+ if mode == "schema":
+ print_schema(spec["components"]["schemas"], argv[3])
+ return 0
+ if mode in ("ops", "all"):
+ print_ops(spec)
+ if mode in ("events", "all"):
+ print_events(spec)
+ if mode in ("scopes", "all"):
+ print_scopes(spec)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))