Skip to content

Cursor plugin specification and official plugins

TypeScript

Unslop pass over skills, references, README, and manifests

Cursor Agente97c83e73109
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 505ac1ad..8d18083d 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -8,7 +8,7 @@
{
"name": "origin-apps",
"source": "./origin-apps",
- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App."
+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App."
}
]
}
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index 484fedf2..bf0d0b7a 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -66,7 +66,7 @@
{
"name": "origin-apps",
"source": "origin-apps",
- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App."
+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App."
},
{
"name": "orchestrate",
diff --git a/README.md b/README.md
index a6418fb7..59acad9d 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +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 | Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App. |
+| `origin-apps` | [Origin Apps](origin-apps/) | Cursor | Developer Tools | Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App. |
| `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
index b09982da..dde7dcf6 100644
--- a/origin-apps/.claude-plugin/plugin.json
+++ b/origin-apps/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "origin-apps",
- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",
+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.",
"version": "0.1.0",
"author": {
"name": "Cursor",
diff --git a/origin-apps/.cursor-plugin/plugin.json b/origin-apps/.cursor-plugin/plugin.json
index edd88eed..cefa3aa4 100644
--- a/origin-apps/.cursor-plugin/plugin.json
+++ b/origin-apps/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
"name": "origin-apps",
"displayName": "Origin Apps",
"version": "0.1.0",
- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",
+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.",
"author": {
"name": "Cursor",
"email": "[email protected]"
diff --git a/origin-apps/CHANGELOG.md b/origin-apps/CHANGELOG.md
index f7285b41..38ba40c9 100644
--- a/origin-apps/CHANGELOG.md
+++ b/origin-apps/CHANGELOG.md
@@ -2,14 +2,14 @@
All notable changes to this plugin will be documented here.
-## 0.1.0 — initial release
+## 0.1.0, initial release
-- Added the `origin-api` skill: fetch the live Origin docs and OpenAPI spec
- first, then apply the practices that hold across spec versions (credentials
- and token minting, minimal scopes, webhook verification and idempotency,
- opaque page tokens, TypeIDs, the error envelope, rate limits, and the
- deliberate differences from GitHub).
-- Added the `port-github-app-to-origin` skill, built on `origin-api`: 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.
+- Added the `origin-api` skill. It lists the live Origin docs and OpenAPI spec
+ to fetch first, then the Origin rules that GitHub habits get wrong:
+ credentials and token minting, minimal scopes, webhook verification and
+ idempotency, opaque page tokens, TypeIDs, the error envelope, rate limits,
+ and the differences from GitHub that are decisions rather than gaps.
+- Added the `port-github-app-to-origin` skill, built on `origin-api`. It reads
+ what a GitHub App uses from GitHub out of its codebase, maps that onto the
+ live Origin spec, and writes a porting brief with a capability table, a
+ webhook field map, a hello-world path, gap cards, and up-front questions.
diff --git a/origin-apps/README.md b/origin-apps/README.md
index c6e4f05f..785328a9 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -1,70 +1,70 @@
# Origin Apps
-Plugin for building on [Cursor Origin](https://cursor.com/docs/api/origin),
-Cursor's code forge: creating an Origin App, calling the API, receiving
-webhooks, or bringing an existing GitHub App across. Skills only, so it runs
-in Cursor, Claude Code, Codex, and any agent that reads
-[Agent Skills](https://agentskills.io).
+Two skills for building on [Cursor Origin](https://cursor.com/docs/api/origin),
+Cursor's code forge. They cover creating an Origin App, calling the API,
+receiving webhooks, and bringing an existing GitHub App across. The plugin is
+skills only, so it runs in Cursor, Claude Code, Codex, and any agent that
+reads [Agent Skills](https://agentskills.io).
## What it includes
-- `origin-api`: the general skill. Fetch-first sources (the live OpenAPI spec
- and docs are the only source for endpoints, scopes, and event slugs) plus a
- checklist of the Origin gotchas GitHub instinct gets wrong: native vs
- mirrored repositories, opt-in webhook events, `v1ed` signatures, `deliveryId`
- idempotency, lean payloads, credential kinds and token minting, scopes from
- `x-origin-scopes`, opaque page tokens, TypeIDs, `404` semantics, rate
- limits, and the deliberate differences from GitHub. Use it for any Origin
- work.
-- `port-github-app-to-origin`: builds on `origin-api`. Run it inside your
- GitHub App's repository. It discovers the app's GitHub surface from the code,
- maps it onto the live spec, and writes a porting brief: capability table,
- webhook fields your handlers read and where each comes from on Origin,
- scopes to request, hello-world path, gaps worth raising with Cursor, and the
- questions to settle first. It plans; it writes no code and estimates no
- time.
-
-Both fetch the spec at run time and never name an endpoint from memory.
+`origin-api` is the general skill. It lists the sources to fetch first (the
+live OpenAPI spec and docs are the only source for endpoints, scopes, and
+event slugs) and then the Origin rules that GitHub habits get wrong. Native
+versus mirrored repositories. Opt-in webhook events. `v1ed` signatures.
+`deliveryId` idempotency. Lean payloads. Credential kinds and token minting.
+Scopes from `x-origin-scopes`. Opaque page tokens. TypeIDs. `404` semantics.
+Rate limits. The differences from GitHub that are decisions, not gaps. Use it
+for any Origin work.
+
+`port-github-app-to-origin` builds on `origin-api`. Run it inside your GitHub
+App's repository. It reads what the app uses from GitHub out of the code, maps
+that onto the live spec, and writes a porting brief with a capability table,
+the webhook fields your handlers read and where each comes from on Origin,
+the scopes to request, a hello-world path, the gaps worth raising with Cursor,
+and the questions to settle first. It plans. It writes no code and estimates
+no time.
+
+Both skills fetch the spec at run time and never name an endpoint from memory.
## When to use
-- You are writing or reviewing code that calls Origin, mints installation
- tokens, or receives Origin webhooks: `origin-api`.
-- You are creating an Origin App and want the hello-world path and the
- first-week traps up front: `origin-api`.
-- 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:
+- Writing or reviewing code that calls Origin, mints installation tokens, or
+ receives Origin webhooks: `origin-api`.
+- Creating an Origin App and wanting the first-week traps up front:
+ `origin-api`.
+- Holding a GitHub App (Probot, Octokit, go-github, hand-rolled) and wanting
+ to know what an Origin App version looks like before starting:
`port-github-app-to-origin`.
-- You want to check which GitHub features Origin deliberately does not
- reproduce, and what the Origin idiom is instead: either.
+- Checking which GitHub features Origin deliberately does not reproduce, and
+ what to do instead: either skill.
-In Cursor, ask about the Origin API or ask to port the app; or run
+In Cursor, ask about the Origin API or ask to port the app, or run
`/origin-api` or `/port-github-app-to-origin`.
## Install in Cursor
-Search for **Origin Apps** in the Cursor Marketplace
+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.
+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`
+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
skills use only portable frontmatter (`name`, `description`, `license`,
`compatibility`).
-**Claude Code**, via the marketplace manifest at this repository's root:
+Claude Code, via the marketplace manifest at this repository's root:
```text
/plugin marketplace add cursor/plugins
/plugin install origin-apps@cursor-plugins
```
-**Any agent that reads Agent Skills** (Claude Code, Codex, and others): copy
-the skill directories into the agent's skills folder. Copy both; the porting
+Any agent that reads Agent Skills (Claude Code, Codex, and others): copy the
+skill directories into the agent's skills folder. Copy both. The porting
skill refers to `origin-api` for fundamentals.
```bash
@@ -80,9 +80,9 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/
## Requirements
- Network access to `https://cursor.com/docs/api/origin/*` during the run.
-- For the porting skill: 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.
+- For the porting skill, read access to the app's source. Producing the brief
+ needs no Origin credentials. You follow the brief's hello-world path
+ afterwards.
- Optional: `python3` with PyYAML for the porting skill's
`scripts/index-origin-spec.py`, which turns the fetched spec into a
grep-friendly index. Without it the skill reads the spec directly.
@@ -90,8 +90,8 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/
## Where the brief goes
The porting skill writes `ORIGIN-PORTING-BRIEF.md` at the repository root and
-prints its path. Gap cards in the brief are yours to send: through your shared
-Slack channel with Cursor if you have one, or to `[email protected]`.
+prints its path. The 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
diff --git a/origin-apps/plugin.json b/origin-apps/plugin.json
index 61a2f288..75ab6a38 100644
--- a/origin-apps/plugin.json
+++ b/origin-apps/plugin.json
@@ -2,7 +2,7 @@
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "origin-apps",
"version": "0.1.0",
- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",
+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.",
"author": {
"name": "Cursor",
"email": "[email protected]"
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index d670dc84..eb6e1ae5 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -1,11 +1,11 @@
---
name: origin-api
description: >-
- Build on the Cursor Origin API: create an Origin App, authenticate as it,
+ Build on the Cursor Origin API. Create an Origin App, authenticate as it,
call the REST API, receive webhooks. Use whenever code or a plan touches
Origin endpoints, installation tokens, scopes, webhook subscriptions or
- signatures, page tokens, or an Origin App manifest. Fetch-first sources plus
- the gotchas GitHub instinct gets wrong.
+ signatures, page tokens, or an Origin App manifest. Lists the sources to
+ fetch first and the Origin rules that GitHub habits get wrong.
license: MIT
compatibility: >-
Needs network access to https://cursor.com/docs/api/origin/* at run time.
@@ -13,68 +13,73 @@ compatibility: >-
# Build on the Origin API
-## Fetch first; never name an endpoint, scope, slug, or header from memory
+## Fetch first. Never name an endpoint, scope, slug, or header from memory.
-- `https://cursor.com/docs/api/origin/openapi.yaml` — the contract. Every
- operation carries `x-origin-scopes` (`scopes`, `tokenTypes`, `ambient`);
- every webhook payload schema carries `x-origin-webhook-events`, the only
+- `https://cursor.com/docs/api/origin/openapi.yaml` is the contract. Every
+ operation carries `x-origin-scopes` (`scopes`, `tokenTypes`, `ambient`).
+ Every webhook payload schema carries `x-origin-webhook-events`, the only
authoritative list of subscribable slugs.
-- `https://cursor.com/docs/api/origin/llms-full.txt` — installation flow,
- authentication, scopes table, mirrored repositories, webhook headers and
- verification, delivery envelope, retries, pagination, errors, limitations.
-- `https://cursor.com/docs/api/origin/llms.txt` (index) and
- `https://cursor.com/docs/api/origin/changelog` (what moved).
+- `https://cursor.com/docs/api/origin/llms-full.txt` covers the installation
+ flow, authentication, the scopes table, mirrored repositories, webhook
+ headers and verification, the delivery envelope, retries, pagination,
+ errors, and current limitations.
+- `https://cursor.com/docs/api/origin/llms.txt` is the index.
+ `https://cursor.com/docs/api/origin/changelog` says what moved.
-Cite `operationId`s and `llms-full.txt` anchors. Where this file and the
-fetched docs disagree, the docs win.
+Cite `operationId`s and `llms-full.txt` anchors. If this file and the fetched
+docs disagree, the docs win.
-## Gotchas
+## Rules GitHub habits get wrong
-- **Native or mirror, first.** Apps get full scopes only on Origin-native
- repositories. A repository mirrored from GitHub returns `403` on every write
- and never delivers `repository.pushed`; the ping succeeds and then nothing
- else arrives.
+- **Check native or mirror before anything else.** Apps get full scopes only
+ on Origin-native repositories. A repository mirrored from GitHub returns
+ `403` on every write and never delivers `repository.pushed`. The ping
+ succeeds and then nothing else arrives.
- **Only installation lifecycle events are delivered by default.** Select
- every other event in app settings; an unselected event is silence, not an
+ every other event in app settings. An unselected event is silence, not an
error.
-- **Signature `v1ed` is Ed25519 over a SHA-256 digest of the raw body**, keys
- from Origin's JWKS. It is Standard Webhooks except for the digest, so
- off-the-shelf verifiers fail unmodified. Verify the raw body before parsing;
- reject `webhook-timestamp` more than five minutes off. Headers are
- `webhook-*`, not `x-github-*`; after verification the body is authoritative.
-- **`deliveryId` is the idempotency key** (stable across retries);
- `event.id` is the domain event. Return `2xx` after verification and process
- asynchronously: persistent failure pauses delivery for the app.
-- **Payloads are lean snapshots** of the one object that changed plus
- container references: no changed-file lists, before-SHAs, web URLs, or
- inlined profiles. Follow up with the `Get…` for the object; count the
- fan-out. The action is in the slug (`pull_request.review.submitted`); there
+- **Signature `v1ed` is Ed25519 over a SHA-256 digest of the raw body**, with
+ keys from Origin's JWKS. It matches Standard Webhooks except for the digest,
+ so off-the-shelf verifiers fail unmodified. Verify the raw body before
+ parsing. Reject `webhook-timestamp` more than five minutes off. Headers are
+ `webhook-*`, not `x-github-*`. After verification the body is authoritative.
+- **`deliveryId` is the idempotency key.** It is stable across retries.
+ `event.id` identifies the domain event. Return `2xx` after verification and
+ process asynchronously, because persistent failure pauses delivery for the
+ app.
+- **Payloads are lean snapshots** of the one object that changed, plus
+ references to its containers. No changed-file lists, before-SHAs, web URLs,
+ or inlined profiles. Follow up with the `Get…` for the object and count the
+ fan-out. The action is in the slug (`pull_request.review.submitted`). There
is no `action` field.
-- **The installation receipt JWT is proof of consent, never a Bearer token.**
+- **The installation receipt JWT proves consent. It is never a Bearer token.**
Its `sub` is the installation ID.
-- **App JWT is EdDSA over Ed25519, not RS256.** Register only the public key.
-- **Installation tokens are short-lived; mint just in time** from the app JWT
- and attenuate to the scopes and `repositoryIds` the job needs (IDs, not
- slugs). Git over HTTPS is Basic auth, user `x-access-token`, token as
- password; Bearer is REST only.
-- **Scopes come from the operations you call**: request the union of their
- `x-origin-scopes.scopes`. `write` implies `read`; `repository:metadata:read`
- is automatic; `ambient: true` needs no request. Operations whose
+- **The app JWT is EdDSA over Ed25519, not RS256.** Register only the public
+ key.
+- **Installation tokens are short-lived. Mint them just in time** from the
+ app JWT and attenuate to the scopes and `repositoryIds` the job needs (IDs,
+ not slugs). Git over HTTPS uses Basic auth with user `x-access-token` and
+ the token as password. Bearer is REST only.
+- **Scopes come from the operations you call.** Request the union of their
+ `x-origin-scopes.scopes`. `write` implies `read`. `repository:metadata:read`
+ is automatic. `ambient: true` needs no request. Operations whose
`tokenTypes` is user-only (create app, add repositories to an installation,
- mirror transitions) have no app-side path; there is no `/user` analog.
+ mirror transitions) have no app-side path, and there is no `/user` analog.
- **Page tokens are opaque and bound to the resource and filters.** Never
- construct, parse, or reuse across filter changes. Send `pageSize` on every
- request, including continuations. No `Link` header, no total.
+ construct, parse, or reuse one across filter changes. Send `pageSize` on
+ every request, including continuations. There is no `Link` header and no
+ total.
- **IDs are TypeIDs** (`repo_…`, `i_…`, `cmt_…`), never integers. Cache IDs,
- not slugs; `/repos/_/{repoId}` survives renames. 64-bit integers (PR
+ not slugs. `/repos/_/{repoId}` survives renames. 64-bit integers (PR
numbers, versions) are JSON strings. Defaults are present (`false`, `0`,
`[]`), so a present `false` is a value.
-- **`404` is not-found *or* no-access.** Branch on status and `code`, never
- message text. Quote `X-Request-ID` when escalating.
-- **Rate limit is a per-principal point budget**; honor `Retry-After` on
- `429`. Git HTTPS is metered separately. Per-app raises exist; ask.
-- **Deliberate differences, not gaps:** no commit statuses (check runs upsert
- on a caller-stable `key`); no Issues (conversation is PR comments, threads,
- reviews, labels); no GraphQL; no per-repository webhook CRUD; no user or
- email directory; reviews anchor to a pull request *version*, not a SHA; a
+- **`404` means not found or no access.** Branch on status and `code`, never
+ on message text. Quote `X-Request-ID` when escalating.
+- **The rate limit is a per-principal point budget.** Honor `Retry-After` on
+ `429`. Git HTTPS is metered separately. Cursor raises per-app budgets on
+ request.
+- **These are decisions, not gaps.** No commit statuses (check runs upsert on
+ a caller-stable `key`). No Issues (conversation is PR comments, threads,
+ reviews, and labels). No GraphQL. No per-repository webhook CRUD. No user or
+ email directory. Reviews anchor to a pull request version, not a SHA. A
thread materializes from its first diff-anchored comment.
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
index dbccfa72..0f17e23e 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -4,8 +4,8 @@ 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.
+ the Origin API. Maps what the app uses from GitHub 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.
@@ -15,53 +15,58 @@ compatibility: >-
# Port a GitHub App to an Origin App
-Run inside the GitHub App's codebase. Output is a **porting brief**
-(`references/brief-template.md`), not an implementation: what maps, what
-changes shape, what is absent on purpose, what is worth raising with Cursor.
+Run inside the GitHub App's codebase. The output is a porting brief
+(`references/brief-template.md`), not an implementation. It says what maps,
+what changes shape, what is absent on purpose, and what is worth raising with
+Cursor.
-Fundamentals (which docs to fetch, credentials, scopes, webhooks, paging,
-IDs, errors, deliberate differences) are the `origin-api` skill in this
-plugin. Follow it first; nothing here repeats it. Two rules on top:
+The `origin-api` skill in this plugin covers which docs to fetch, credentials,
+scopes, webhooks, paging, IDs, errors, and the deliberate differences from
+GitHub. Follow it first. Nothing here repeats it. Two rules on top:
1. **Discover, do not ask.** Read permissions, events, handlers, calls, token
minting, and the receiver out of the code. Never ask for a manifest or an
- endpoint list. What is genuinely undiscoverable becomes an open question.
+ endpoint list. Anything you cannot find becomes an open question.
2. **Departures are decisions, not omissions.** Anything in
- `references/origin-isms.md` is `by-design-absent` or `reshaped` with a
- pointer to the idiom, never a gap card.
+ `references/origin-isms.md` is `by-design-absent` or `reshaped`, with a
+ pointer to the idiom. It never becomes a gap card.
## Procedure
-1. **Load the spec** (`origin-api` § Fetch first). Record `info.version` and
+1. **Load the spec** (`origin-api`, "Fetch first"). Record `info.version` and
the fetch time for the brief's provenance. Build the mapping index per
- `references/spec-mapping.md`; `scripts/index-origin-spec.py openapi.yaml`
- prints it (needs PyYAML).
-2. **Discover** per `references/discovery.md`: a file and line for every fact,
- including payload fields read only for logging and calls the framework
- makes on the app's behalf. Note what you looked for and did not find.
-3. **Map** each inventory row (`references/spec-mapping.md` § Matching) and
- label it with the parity labels in the brief template. Map webhook payload
- *fields* the code reads, not just event names; a field GitHub inlines is
- often a follow-up read on Origin, so name the call per field. Then:
- - `origin-isms.md` before `gap`; `gap-bar.md` before any card.
- - A GitHub surface the Origin docs never mention (Marketplace billing,
- merge queues, Actions, Pages) is `unknown` with a question, never `gap`.
+ `references/spec-mapping.md`. `scripts/index-origin-spec.py openapi.yaml`
+ prints it and needs PyYAML.
+2. **Discover** per `references/discovery.md`. Record a file and line for
+ every fact, including payload fields read only for logging and calls the
+ framework makes on the app's behalf. Note what you looked for and did not
+ find.
+3. **Map** each inventory row (`references/spec-mapping.md`, "Matching") and
+ label it with the parity labels in the brief template. Map the webhook
+ payload fields the code reads, not only the event names. A field GitHub
+ inlines is often a follow-up read on Origin, so name the call for each
+ field. Then:
+ - Check `origin-isms.md` before writing `gap`. Check `gap-bar.md` before
+ writing any card.
+ - A GitHub feature the Origin docs never mention (Marketplace billing,
+ merge queues, Actions, Pages) is `unknown` with a question. It is never
+ `gap`.
- A behavior the code depends on that the docs neither confirm nor deny
(does event X fire in case Y? does `updatedAt` move on comments?) is a
- question plus a hello-world step that observes it; never guess it into
+ question plus a hello-world step that observes it. Never guess it into
`same` from GitHub behavior.
4. **Write the brief** from the template in full. Every Origin cell names an
- `operationId`, slug, or `llms-full.txt` anchor. Sizes are S/M/L, never
- time.
+ `operationId`, a slug, or an `llms-full.txt` anchor. Sizes are S, M, or L,
+ never time.
5. **Close with the questions**, pruned to what discovery left open. The
- first is always native-or-mirror: it decides whether the app receives
- events at all.
+ first is always native or mirror, because it decides whether the app
+ receives events at all.
## Not in scope
-Writing port code or adapters; choosing a language, framework, or client;
-estimating in time; asking for anything the codebase contains; sending gap
-cards to Cursor (the brief carries them; the team decides).
+Writing port code or adapters. Choosing a language, framework, or client.
+Estimating in time. Asking for anything the codebase contains. Sending gap
+cards to Cursor. The brief carries them and the team decides.
## Reference files
@@ -69,8 +74,8 @@ cards to Cursor (the brief carries them; the team decides).
| --- | --- |
| `../origin-api/SKILL.md` | First. Sources and fundamentals. |
| `references/discovery.md` | Scanning the codebase. |
-| `references/spec-mapping.md` | Building the index; matching calls, events, and fields. |
+| `references/spec-mapping.md` | Building the index. Matching calls, events, and fields. |
| `references/origin-isms.md` | Labeling a missing GitHub feature. |
-| `references/gap-bar.md` | Deciding whether a difference earns a card; writing it. |
+| `references/gap-bar.md` | Deciding whether a difference earns a card, and writing it. |
| `references/brief-template.md` | Writing the output. |
| `scripts/index-origin-spec.py` | Turning `openapi.yaml` into a grep-friendly index. Optional. |
diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
index f20b5ae3..04c9e23f 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
@@ -1,11 +1,11 @@
# Porting brief template
-One Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md` unless the
-team's docs convention says otherwise); print its path. Fill every section; an
-empty section says so in one line rather than disappearing. Cite spec
-`operationId`s and `llms-full.txt` anchors; cite the team's code by
-`file:line`. A table row per capability, a line per follow-up field, a card
-per gap; the team will argue over it in one sitting.
+Write one Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md`
+unless the team's docs convention says otherwise) and print its path. Fill
+every section. An empty section says so in one line rather than disappearing.
+Cite spec `operationId`s and `llms-full.txt` anchors. Cite the team's code by
+`file:line`. One table row per capability, one line per follow-up field, one
+card per gap. The team will argue over it in one sitting.
## Labels
@@ -13,29 +13,30 @@ per gap; the team will argue over it in one sitting.
| Label | Meaning |
| --- | --- |
-| `same` | Same capability, same shape; a path or field rename at most. |
-| `reshaped` | Same capability, different shape (pagination, identifier form, event granularity, key semantics). Code changes, behavior does not. |
-| `workaround` | Same outcome by a different route (follow-up read, client-side filter, marker). Tradeoff column mandatory. |
+| `same` | Same capability, same shape. A path or field rename at most. |
+| `reshaped` | Same capability, different shape (pagination, identifier form, event granularity, key semantics). The code changes, the behavior does not. |
+| `workaround` | Same outcome by a different route (follow-up read, client-side filter, marker). The Tradeoff column is mandatory. |
| `by-design-absent` | Origin deliberately does not reproduce it (`origin-isms.md`). Names the idiom or "no equivalent; decision needed". |
| `gap` | No workaround, or one that fails `gap-bar.md`. Has a card in § 6. |
| `unknown` | Discovery or the spec could not answer. Has a question in § 7. |
-| `preview` (suffix) | Origin operation is `x-cursor-visibility: PREVIEW`. Usable; shape may move. |
+| `preview` (suffix) | The Origin operation is `x-cursor-visibility: PREVIEW`. Usable. The shape may move. |
**Size** (kind of change, never time)
| Size | Meaning |
| --- | --- |
-| S | Adapter or client layer: path, header, identifier, or pagination rewrite; re-keyed lookup. |
-| M | New code path: a follow-up read where the payload sufficed, a handshake step, a new handler, a data-model change for a new identifier or version concept. |
-| L | Product or architecture change: a flow that depended on user OAuth, a customer-visible behavior, a dependency on native repositories, an open gap card. |
+| S | Adapter or client layer. A path, header, identifier, or pagination rewrite, or a re-keyed lookup. |
+| M | A new code path. A follow-up read where the payload used to suffice, a handshake step, a new 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 native repositories, an open gap card. |
## Template
```markdown
-# Origin porting brief — <app name>
+# Origin porting brief for <app name>
-Planning document. Maps this GitHub App's surface onto the Cursor Origin API
-as published on <date>. No decisions about language, framework, or client.
+Planning document. Maps what this GitHub App uses from GitHub onto the Cursor
+Origin API as published on <date>. It makes no decisions about language,
+framework, or client.
## Provenance
@@ -43,12 +44,12 @@ as published on <date>. No decisions about language, framework, or client.
- Docs read: <the URLs>
- Codebase: `<repo>` at `<commit>`
- Re-check `workaround` and `gap` rows against the changelog before work
- starts; they move most.
+ starts. They are the rows most likely to have moved.
## 1. What the app is today
-One paragraph: what it does for its users, which events drive it, what it
-writes back. Then:
+One paragraph on what it does for its users, which events drive it, and what
+it writes back. Then:
| Facet | Finding | Evidence |
| --- | --- | --- |
@@ -65,9 +66,9 @@ writes back. Then:
## 2. First decision: which repositories
<What the code assumes about the repositories it acts on.> Apps have full
-scopes only on Origin-native repositories and stable outbound mirrors;
-repositories mirrored from GitHub are read-only to apps and deliver no push
-events. **Question 1 must be answered before § 5 is attempted.**
+scopes only on Origin-native repositories and stable outbound mirrors.
+Repositories mirrored from GitHub are read-only to apps and deliver no push
+events. **Answer question 1 before attempting § 5.**
## 3. Capability table
@@ -79,16 +80,16 @@ dependency makes on the app's behalf, marked as such.
| GitHub thing (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question |
| --- | --- | --- | --- | --- | --- |
-| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | — | — |
+| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | none | none |
The Origin column names an `operationId`, a slug, a `llms-full.txt` anchor,
-or `none`. `workaround` rows fill Tradeoff; `gap` rows link their card;
-`by-design-absent` rows name the idiom; `unknown` rows name their question.
+or `none`. `workaround` rows fill Tradeoff. `gap` rows link their card.
+`by-design-absent` rows name the idiom. `unknown` rows name their question.
**Scopes to request:** the union of `x-origin-scopes.scopes` across every
Origin operation above that an installation token can call, minus ambient
-and implied scopes (`write` implies `read`; `repository:metadata:read` is
-automatic). This is what the install URL's `scope` parameter carries.
+and implied scopes (`write` implies `read`, and `repository:metadata:read` is
+automatic). The install URL's `scope` parameter carries this list.
## 4. Webhook payload fields the code reads
@@ -97,39 +98,41 @@ automatic). This is what the install URL's `scope` parameter carries.
| `pull_request.synchronize` → `<slug>` | `pull_request.head.sha` | present | `payload.pullRequest.head.sha` |
| `push` → `<slug>` | `commits[].added` | follow-up read | `<operationId>`, one call per ref update |
-"How" is one of: present at `<path>`; present in envelope (`event.type` for
-GitHub's `action`); follow-up read via `<operationId>` with the call count
-per event; derivable (from what; is the format documented); absent (→ § 3's
-label). Include fields read only for logging.
+"How" is one of five values. Present at `<path>`. Present in the envelope
+(`event.type` for GitHub's `action`). Follow-up read via `<operationId>`,
+with the call count per event. Derivable, saying from what and whether the
+format is documented. Absent, pointing at the row's label in § 3. Include
+fields read only for logging.
## 5. Hello-world path
-Shortest route to one real event from one native repository. Each step is a
-verification, linked to `llms-full.txt`; append one step per spec-silent
-behavior the brief depends on, stated as the observation to make.
+The shortest route to one real event from one native repository. Each step
+is a verification, linked to `llms-full.txt`. Append one step for each
+spec-silent behavior the brief depends on, stated as the observation to make.
-1. Create the app; register the Ed25519 public key; set webhook URL and
- callback.
+1. Create the app, register the Ed25519 public key, and set the webhook URL
+ and callback.
2. Select every repository event from § 3 in app settings.
-3. Install on an Origin-native repository; verify the receipt JWT and read
+3. Install on an Origin-native repository. Verify the receipt JWT and read
the installation ID from `sub`.
-4. Mint an app JWT, exchange for an installation token, confirm the
- repository is listed and its mirror state matches § 2.
+4. Mint an app JWT, exchange it for an installation token, and confirm the
+ repository is listed with the mirror state § 2 expects.
5. Verify the ping (`v1ed` over the raw body, timestamp skew, `deliveryId`
dedupe).
6. Perform the smallest action in § 3 and confirm the slug and the § 4
- fields arrive. Ping but no event: re-check steps 2 and 3 first.
+ fields arrive. If the ping arrived and this did not, re-check steps 2 and
+ 3 first.
7. Smallest write from § 3 (check run with a stable `key`, PR comment),
confirming its scope is in the grant.
## 6. Gaps worth raising
-Zero or more cards in the `gap-bar.md` shape. If zero: "No row failed the gap
-bar; the workarounds in § 3 carry their tradeoffs." Do not pad.
+Zero or more cards in the `gap-bar.md` shape. If zero, write "No row failed
+the gap bar. The workarounds in § 3 carry their tradeoffs." Do not pad.
## 7. Questions for the team
-Always the first three; then what discovery left open.
+Always the first three, then what discovery left open.
1. Native repositories (or stable outbound mirrors), or repositories mirrored
from GitHub? Decides whether the app receives events and can write.
@@ -139,12 +142,12 @@ Always the first three; then what discovery left open.
Origin?
4. Does anything key approvals or reviews by commit SHA rather than PR
version?
-5. How do you identify your own check runs / comments / reviews today; can a
- key or marker you control replace actor matching?
+5. How do you identify your own check runs, comments, and reviews today? Can
+ a key or marker you control replace actor matching?
6. Do you generate clients from OpenAPI? (Read the changelog for renames.)
## 8. Out of scope
No implementation, no SDK or language choice, no time estimates. The brief is
-a map; the route is the team's.
+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
index a6258c3b..bc408bc8 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/discovery.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
@@ -1,56 +1,54 @@
-# Discovering the GitHub App's shape from the codebase
+# Discovering what the GitHub App uses, from its codebase
-Everything the brief needs about the app is in the repository. Search; do not
-ask. Record `file:line` for every fact and list every place you looked that
-turned up nothing. Note the language and libraries as an observation; they
-inform sizes and nothing else.
+Everything the brief needs about the app is in the repository. Search for it.
+Do not ask for it. Record `file:line` for every fact and list every place you
+looked that turned up nothing. Note the language and libraries as an
+observation. They inform sizes and nothing else.
Seven facets. For each, what to record:
1. **Declared permissions and events.** The manifest or registration snapshot
- if checked in (`app.yml`, manifest JSON, IaC that seeds the app; Probot
- keeps `default_events` / `default_permissions` in `app.yml`). If absent,
- say so and derive permissions from facet 4; the union of what the code
- calls is what the port needs anyway.
+ if it is checked in (`app.yml`, a manifest JSON, IaC that seeds the app;
+ Probot keeps `default_events` and `default_permissions` in `app.yml`). If
+ there is none, say so and derive permissions from facet 4. The union of
+ what the code calls is what the port needs anyway.
2. **Webhook events handled.** Each GitHub event and action pair the code
dispatches on (`app.on("pull_request.opened")`, a switch on
- `x-github-event` + `payload.action`, SDK parsers), with the handler
+ `x-github-event` plus `payload.action`, SDK parsers), with the handler
location.
-3. **Payload fields read.** Every property path dereferenced from the payload
- inside each handler and the helpers it passes the payload to. Include
- fields used only for logging or metrics; those break dashboards after the
- port.
-4. **REST and GraphQL calls.** Each distinct call family once (method + path
- or SDK method) with the parameters and filters passed, the response fields
- read, whether it runs per webhook or in a loop (decides the fan-out
- tradeoff), and the pagination style in use (it always changes). GraphQL
- documents count as calls; they are decomposed during mapping.
-5. **Authentication and token minting.** App JWT algorithm; how the
- installation is identified after install (callback query, webhook, DB);
- token lifetime handling; whether user OAuth exists and for what (identity,
- repository discovery, acting for a user); whether the app clones or pushes
- git as itself.
-6. **Webhook receiver and verification.** Signature scheme; whether the raw
- body is available at verification time (frameworks that parse JSON first
- cannot verify); how deliveries are deduplicated, if at all; where the
- public URL is configured.
-7. **Calls the framework makes on the app's behalf.** Not in the app's
- source, but the port has to do them. List them as rows marked "from
- `<dependency>` (documented behavior)" and read the dependency's docs or
- source, not the app. Common cases:
- - **Probot**: built-in receiver and HMAC verification, per-installation
- token minting and caching, `context.repo()` / `context.issue()`,
- `context.isBot`; companions `probot-config` (reads `.github/<file>.yml`,
- falling back to the owner's `.github` repository), `probot-scheduler`
- (lists installations and repositories with the app credential, emits
- `schedule.repository`), `probot-metadata` (state in issue bodies).
- - **Octokit `App`**: `webhooks.verifyAndReceive`, `eachInstallation` /
- `eachRepository`, automatic token minting behind
- `getInstallationOctokit`.
- - **`ghinstallation`, `githubkit`, `gidgethub`, `octokit.rb` app auth**:
- JWT minting and installation-token exchange.
+3. **Payload fields read.** Every property path each handler and its helpers
+ dereference from the payload. Include fields used only for logging or
+ metrics. Those break dashboards after the port.
+4. **REST and GraphQL calls.** Each distinct call family once (method and path,
+ or SDK method) with the parameters and filters the code passes, the
+ response fields it reads, whether it runs per webhook or in a loop (this
+ decides the fan-out tradeoff), and the pagination style in use. Pagination
+ always changes. GraphQL documents count as calls. Mapping decomposes them.
+5. **Authentication and token minting.** The app JWT algorithm. How the code
+ identifies the installation after install (callback query, webhook, DB).
+ Token lifetime handling. Whether user OAuth exists and what it is for
+ (identity, repository discovery, acting for a user). Whether the app clones
+ or pushes git as itself.
+6. **Webhook receiver and verification.** The signature scheme. Whether the
+ raw body is available at verification time (a framework that parses JSON
+ first cannot verify). How the code deduplicates deliveries, if it does.
+ Where the public URL is configured.
+7. **Calls the framework makes on the app's behalf.** They are not in the
+ app's source, but the port has to make them. List them as rows marked
+ "from `<dependency>` (documented behavior)" and read the dependency's docs
+ or source, not the app. Common cases:
+ - Probot: the built-in receiver and HMAC verification, per-installation
+ token minting and caching, `context.repo()` and `context.issue()`,
+ `context.isBot`. Companions: `probot-config` reads `.github/<file>.yml`
+ and falls back to the owner's `.github` repository; `probot-scheduler`
+ lists installations and repositories with the app credential and emits
+ `schedule.repository`; `probot-metadata` stores state in issue bodies.
+ - Octokit `App`: `webhooks.verifyAndReceive`, `eachInstallation` and
+ `eachRepository`, token minting behind `getInstallationOctokit`.
+ - `ghinstallation`, `githubkit`, `gidgethub`, `octokit.rb` app auth: JWT
+ minting and installation-token exchange.
When something is missing, say so in the inventory ("no manifest found
(searched: …)", "no signature verification found in the receiver at …").
Each missing item becomes an `unknown` row or an up-front question. Do not
-fill gaps with what an app of this kind usually does.
+fill it in with what an app of this kind usually does.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
index fd732713..60ee0d17 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
@@ -1,74 +1,75 @@
# The gap bar and the escalation card
-Most differences are not gaps. A brief that files every difference buries
-the two or three things Cursor needs to hear. When in doubt, write the row as
-`workaround` with an honest tradeoff and an open question, not as a card.
+Most differences are not gaps. A brief that files every difference buries the
+two or three things Cursor needs to hear. When in doubt, write the row as
+`workaround` with the tradeoff and an open question, not as a card.
-- A **difference** is any row whose parity label is not `same`.
-- A **workaround** reaches the same outcome with today's surface: 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 cards.
+- A difference is any row whose parity label is not `same`.
+- A workaround reaches the same outcome with today's API by another route. A
+ follow-up read, a re-keyed identifier, a path change, a client-side filter,
+ a marker the app controls.
+- A gap is a difference with no workaround, or a workaround whose tradeoff
+ fails one of the five tests below. Only gaps become cards.
## Nontrivial tradeoff
-At least one must hold; quote it on the card.
+At least one must hold. Quote it on the card.
| Tradeoff | Test |
| --- | --- |
-| **Fan-out at scale** | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files; a full list scan to find one row) and the app's volume makes that budget-relevant. One bounded extra read per event is trivial. |
-| **Correctness risk** | The workaround can be wrong, not just slower: heuristic "my own row" matching, inferring a PR from a SHA several versions share, assembling a URL whose format is not contractual. |
-| **Security posture** | Needs a broader scope, a longer-lived token, or a user credential where an installation token should do. |
-| **Customer-visible behavior** | Changes what the team's users see or can do, not how the code is organized. |
-| **Load-bearing** | Sits on the hello-world path or the team's stated core flow. |
+| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files, or a full list scan to find one row), and the app's volume makes that budget-relevant. One bounded extra read per event is trivial. |
+| Correctness risk | The workaround can return a wrong answer, not only a slower one. Heuristic "my own row" matching. Inferring a PR from a SHA several versions share. Assembling a URL whose format is not contractual. |
+| Security posture | The workaround needs a broader scope, a longer-lived token, or a user credential where an installation token should do. |
+| Customer-visible behavior | The workaround changes what the team's users see or can do, not how the code is organized. |
+| Load-bearing | The capability sits on the hello-world path or the team's stated core flow. |
## Never a gap
- Anything in `origin-isms.md`.
-- A field or filter the code does not actually use.
+- A field or filter the code does not use.
- A GitHub convenience (`Link` pagination, numeric IDs, `html_url`) where the
Origin convention is a mechanical substitution.
-- Something the changelog says shipped or the spec already carries. Re-check
- the live spec before writing any card.
+- Anything the changelog says shipped or the spec already carries. Re-read the
+ live spec before writing any card.
- A concept the Origin docs never mention (Marketplace billing, merge queues,
- Actions, Projects): `unknown` plus a question.
-- A GitHub Search query. The idiom is a list operation with its filters plus
- a client-side predicate; a sorted list read that stops at a cutoff is
- proportional to the matches, not the collection. Only if that count fails
- the bar does it become a card about a *filter*, never about search.
+ Actions, Projects). That is `unknown` plus a question.
+- A GitHub Search query. The idiom is a list operation with its filters plus a
+ client-side predicate. A sorted list read that stops at a cutoff costs
+ proportional to the matches, not the collection. If that count fails the
+ bar, the card is 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 reacting to
-exactly that change is the app's purpose and the state is invisible until an
-unrelated event arrives. Reading it off the next snapshot fails on
-correctness and customer-visible behavior when the app is a gate (a check, a
-block, a notification). Write the card about the event; not when the app
-merely logs or tidies up on that change.
+A state change the app reacts to that has no event, when reacting to exactly
+that change is the app's purpose and the state is invisible until an
+unrelated event arrives. Reading it off the next snapshot fails on correctness
+and customer-visible behavior when the app is a gate (a check, a block, a
+notification). Write the card about the event. Do not write it when the app
+only logs or tidies up on that change.
## The card
-One per gap, in the brief's "Gaps worth raising" section, written so Cursor
-can act without a call:
+One per gap, in the brief's "Gaps worth raising" section. Write it so Cursor
+can act without a call.
```markdown
### Gap: <capability, in Origin terms>
-- **GitHub surface the app uses:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.
+- **GitHub call, event, or permission:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.
- **What the app needs from it:** <data or effect, one sentence>.
- **Why:** <what the app does with it, one sentence>.
-- **Closest Origin surface today:** `<operationId>` / `<slug>` / none, and what it lacks.
+- **Closest Origin operation today:** `<operationId>` / `<slug>` / none, and what it lacks.
- **Workaround considered:** <it, or "none found">.
- **Tradeoff that fails the bar:** <one of the five, with the number or risk>.
-- **Shape that would close it:** <a capability, not a design: "list pull requests whose head is this SHA", not a route or field name>.
+- **Shape that would close it:** <a capability, not a design. "List pull requests whose head is this SHA", not a route or field name.>
- **Blocking?** yes / no, for which flow.
- **Spec version checked:** `<info.version>` on `<date>`.
```
-Do not propose scope, field, or route names; Cursor owns the shape. Do not
-batch unrelated capabilities. Do not send cards yourself; the team decides
-what goes out (their shared Slack channel with Cursor, or `[email protected]`
-with "Origin API" and the app name in the subject), quoting the spec version
-and any `X-Request-ID` from failed calls. "This is by design, here is the
-idiom" is a fine answer and goes back into the brief as `by-design-absent`.
+Do not propose scope, field, or route names. Cursor owns the shape. Do not
+batch unrelated capabilities. Do not send cards yourself. The team decides
+what goes out, through their shared Slack channel with Cursor or to
+`[email protected]` with "Origin API" and the app name in the subject, quoting the
+spec version and any `X-Request-ID` from failed calls. "This is by design,
+here is the idiom" is a fine answer. It goes back into the brief as
+`by-design-absent`.
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
index db4f021a..c4ca2326 100644
--- 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
@@ -1,11 +1,11 @@
-# Origin-isms: GitHub surfaces Origin departs from on purpose
+# Origin-isms: GitHub features Origin departs from on purpose
Check here before labeling anything `gap`. A row below is `by-design-absent`
-or `reshaped`; the brief points at the idiom and never files a card. The
-reasoning behind each lives in the `origin-api` skill; this table carries only
-what the classifier needs. Confirm current wording in `llms-full.txt`.
+or `reshaped`. The brief points at the idiom and never files a card. The
+`origin-api` skill carries the reasoning. This table carries only the label
+and the idiom. Confirm current wording in `llms-full.txt`.
-| GitHub surface the app uses | Label | Origin idiom |
+| GitHub call, event, or permission | Label | Origin idiom |
| --- | --- | --- |
| Acting on a repository mirrored *from* GitHub (writes, `push` events) | `by-design-absent` | Install on Origin-native repositories or stable outbound mirrors. Mirrors are read-only to apps and deliver no `repository.pushed`. First question of every brief. |
| Install callback with `installation_id` + `setup_action` query params | `reshaped` | Signed installation receipt JWT; `sub` is the installation ID. Not a Bearer. |
@@ -26,12 +26,12 @@ what the classifier needs. Confirm current wording in `llms-full.txt`.
| User, email, team, and member lookups | `by-design-absent` | Actors are TypeIDs (plus a handle where exposed). No directory. |
| Single `pull_request` event with `action` field, `previous_attributes` | `reshaped` | One slug per action (`pull_request.head_ref.pushed`); no `action` field, no delta. Confirm each slug in `x-origin-webhook-events`. |
| `x-github-*` headers, HMAC `x-hub-signature-256` | `reshaped` | `webhook-*` headers; `v1ed` Ed25519 over a SHA-256 digest, JWKS keys. |
-| Payload inlines: changed files on push, before-SHA, `html_url`, `sender` profile | `reshaped` | Follow-up `Get…` / `CompareCommits` / `ListComparisonFiles` with identifiers the payload carries. Name the call per field; count the fan-out. |
+| Fields GitHub inlines in payloads (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | Follow-up `Get…`, `CompareCommits`, or `ListComparisonFiles` with identifiers the payload carries. Name the call for each field and count the fan-out. |
| Default delivery of all events after app creation | `reshaped` | Only installation lifecycle is default; select the rest. |
| Reviews keyed by `commit_id` | `reshaped` | Reviews anchor to a pull request version. |
| Finding own check runs / comments by actor | `reshaped` | Check runs by `key`; comments and reviews by a marker the app controls. |
| Requested-reviewer team pages, `created_via` | `by-design-absent` | Reviewers addressed by identifier only. |
-Not on this list, and not mentioned anywhere in the Origin docs (Marketplace
-billing, merge queues, Actions, Pages, Projects): `unknown` with a question,
-never `by-design-absent`.
+A feature that is not on this list and that the Origin docs never mention
+(Marketplace billing, merge queues, Actions, Pages, Projects) is `unknown`
+with a question, never `by-design-absent`.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
index 0a788ba5..a3928bfd 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
@@ -1,30 +1,29 @@
-# Reading the Origin spec and matching GitHub surface to it
+# Reading the Origin spec and matching GitHub calls and events to it
-Every mapping in the brief is derived from the fetched `openapi.yaml`, not
-from a table here. Build the index once; every later step looks things up in
-it.
+Every mapping in the brief comes from the fetched `openapi.yaml`, not from a
+table here. Build the index once. Every later step looks things up in it.
## Extensions the spec carries
| Extension | Where | Meaning |
| --- | --- | --- |
-| `x-origin-scopes` | every operation | `scopes` required; `tokenTypes` accepted (`app`, `installation`, `user`); `ambient: true` means nothing to request. |
-| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape. A schema carrying it is a webhook family; these slugs are the only authoritative event list. |
-| `x-origin-webhook-resource` | some payload schemas | The REST component the payload embeds. When absent, infer from `$ref`s; pushes, deletions, and reviewer requests are event-native with no REST twin. |
-| `x-cursor-visibility: PREVIEW` | some operations | Usable, shape may move. Carry the badge into the brief as a `preview` suffix. |
+| `x-origin-scopes` | every operation | `scopes` the operation requires. `tokenTypes` it accepts (`app`, `installation`, `user`). `ambient: true` means there is nothing to request. |
+| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape. A schema carrying it is a webhook family. These slugs are the only authoritative event list. |
+| `x-origin-webhook-resource` | some payload schemas | The REST component the payload embeds. When absent, infer it from `$ref`s. Pushes, deletions, and reviewer requests are event-native with no REST twin. |
+| `x-cursor-visibility: PREVIEW` | some operations | Usable. The shape may move. Carry the badge into the brief as a `preview` suffix. |
## Build the index
1. **Operations**: `operationId`, method, path, `x-origin-scopes`,
- visibility, parameter names, request top-level fields, response component.
+ visibility, parameter names, top-level request fields, response component.
2. **Webhook events**: slug → schema → properties and `$ref`s (or the
`x-origin-webhook-resource` target). From `llms-full.txt` § Webhooks,
which slugs are app-lifecycle (always delivered) versus repository events
(must be selected).
-3. **Scopes**: union of every `scopes` value, annotated with the operations
- that need it; separate installation-requestable scopes from ambient and
- user-only ones (the latter tell you which GitHub flows have no app-side
- equivalent by construction).
+3. **Scopes**: the union of every `scopes` value, annotated with the
+ operations that need it. Separate installation-requestable scopes from
+ ambient and user-only ones. The user-only set tells you which GitHub flows
+ have no app-side equivalent.
4. **Resources**: component schemas returned by `Get…`/`List…`, with field
names, for "does the Origin object carry this field".
@@ -33,10 +32,10 @@ prints all four.
## Matching
-Match in this order; stop at the first rule that yields a *confirmed*
+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 it answers the same question. A name match is a candidate,
-never a result.
+parameters and it answers the same question the GitHub call answers. A name
+match is a candidate, never a result.
**REST calls**
@@ -46,21 +45,22 @@ never a result.
`…/contents:batchGet`).
2. Re-home GitHub's issue-flavored PR calls: `/issues/{n}/comments` and
`/issues/{n}/labels` used *on a pull request* live under `/pulls/{n}/…`.
- Path change, not a gap. Used on real issues: `origin-isms.md`.
+ That is a path change, not a gap. When the code uses them on real issues,
+ see `origin-isms.md`.
3. Re-home `/app`, `/app/installations`, access-token minting, and
`/installation/repositories` under `/v1/origin/app…` and
`/v1/origin/installation/repos`; confirm `tokenTypes`. `/user`,
- `/user/installations`, `/orgs/…`, `/search/…`, `/repositories/{id}` have
- no path counterpart: consult `origin-isms.md` before labeling.
-4. Compare parameters, not just paths. A matching path missing a filter the
- code depends on is `workaround` or `gap`, not `same`.
-5. Compare response fields the code reads. Each missing field gets its own
- line: follow-up call, derivable, or absent. GitHub inlines convenience
- data (web URLs, nested profiles, counts) that Origin does not.
-
-**GraphQL.** No endpoint. Decompose each document into the REST reads and
-writes it stands for, map those, and record the fan-out as the row's
-tradeoff.
+ `/user/installations`, `/orgs/…`, `/search/…`, and `/repositories/{id}`
+ have no path counterpart. Consult `origin-isms.md` before labeling them.
+4. Compare parameters as well as paths. A matching path that lacks a filter
+ the code depends on is `workaround` or `gap`, not `same`.
+5. Compare the response fields the code reads. Each missing field gets its
+ own line as follow-up call, derivable, or absent. GitHub inlines web URLs,
+ nested profiles, and counts that Origin does not.
+
+**GraphQL.** There is no endpoint. Decompose each document into the REST
+reads and writes it stands for, map those, and record the fan-out as the
+row's tradeoff.
**Permissions → scopes.** Do not translate the manifest noun-for-noun. Find
the operations the code calls and take the union of *their*
@@ -69,26 +69,27 @@ the operations the code calls and take the union of *their*
`workflows`, `deployments`) go through `origin-isms.md` first.
**Events → slugs.** Each GitHub `event` + `action` pair becomes a candidate
-slug (`pull_request` + `synchronize` → `pull_request.head_ref.pushed`);
-confirm it exists in the webhook index. A candidate that does not exist is
-not an event on Origin; check whether the state change is observable another
-way before classifying.
+slug (`pull_request` plus `synchronize` becomes `pull_request.head_ref.pushed`).
+Confirm it exists in the webhook index. A candidate that does not exist is
+not an event on Origin. Check whether the state change is observable another
+way before classifying it.
**Payload fields → schema properties.** For each field path a handler reads,
-walk the mapped slug's payload schema and record one of: **present** at
-`<path>`; **follow-up read** via `<operationId>` with identifiers the payload
-carries; **derivable** from present fields (say how, and whether the format
-is contractual); **absent** (goes to the gap bar). A field on the REST
-component that the webhook twin lacks is a follow-up `Get…` on every event.
+walk the mapped slug's payload schema and record one of four outcomes.
+Present at `<path>`. Follow-up read via `<operationId>` with identifiers the
+payload carries. Derivable from present fields, saying how and whether the
+format is contractual. Absent, which goes to the gap bar. A field on the REST
+component that the webhook twin lacks means a follow-up `Get…` on every
+event.
## Out of domain and spec-silent
- A concept neither the spec nor `llms-full.txt` mentions (Marketplace
billing, merge queues, Actions, Pages, Projects, Discussions, HTML probes)
- is `unknown` with an up-front question. Never `gap` (Origin has not
- declined it) and never `by-design-absent` (only `origin-isms.md` rows earn
- that).
+ is `unknown` with an up-front question. It is never `gap`, because Origin
+ has not declined it, and never `by-design-absent`, because only
+ `origin-isms.md` rows earn that.
- A behavior the code depends on that the docs do not state (does an event
- fire for a draft PR? does `updatedAt` move on a comment?) is an open
+ fire for a draft PR? does `updatedAt` move on a comment?) becomes an open
question plus a hello-world step that observes it on a native repository.
- Do not resolve it from GitHub's behavior.
+ Do not settle it from GitHub's behavior.