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