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.jsonnew file mode 100644index 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.jsonindex 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.mdindex 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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++MITdiff --git a/origin-apps/plugin.json b/origin-apps/plugin.jsonnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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))