Skip to content

Cursor plugin specification and official plugins

TypeScript

Retire by-design-absent; relax roadmap absolutes

Cursor Agentdb4e4ee49588
diff --git a/origin-apps/README.md b/origin-apps/README.md
index 52a45a3f..6118ada1 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -12,7 +12,7 @@ reads [Agent Skills](https://agentskills.io).
spec and docs for every fact, gives a table of which docs section answers
which question, and names the four rules to check first (native versus
mirrored repositories, event subscriptions, webhook verification, scopes
-from the spec) plus the GitHub features Origin does not have. Use it for any
+from the spec) plus how GitHub features map onto Origin. Use it for any
Origin work.
`port-github-app-to-origin` builds on `origin-api`. Run it inside your GitHub
@@ -34,8 +34,8 @@ Both skills fetch the spec at run time and never name an endpoint from memory.
- 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 which GitHub features Origin deliberately does not reproduce, and
- what to do instead: either skill.
+- Checking which GitHub features map differently on Origin, and what to use
+ instead: either skill.
In Cursor, ask about the Origin API or ask to port the app, or run
`/origin-api` or `/port-github-app-to-origin`.
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index 258b7f1a..4979deab 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -72,5 +72,5 @@ week.
## Coming from GitHub
-GitHub habits do not carry over. The `port-github-app-to-origin` skill in
-this plugin covers the differences.
+Several GitHub conventions map differently on Origin. The
+`port-github-app-to-origin` skill in this plugin covers the differences.
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 195a09b2..450753d5 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -17,19 +17,19 @@ compatibility: >-
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.
+what changes shape, what is not available today, and what is worth raising
+with Cursor.
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:
+scopes, webhooks, paging, IDs, and errors. 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. 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. It never becomes a gap card.
+2. **Check the documented path first.** Anything in
+ `references/origin-isms.md` has a documented Origin path or a documented
+ limitation. Use the row's label; `not-available` rows still go through
+ the gap bar.
## Procedure
@@ -70,7 +70,8 @@ GitHub. Follow it first. Nothing here repeats it. Two rules on top:
- [ ] Every `gap` row has a card, and the card quotes one of the five
tradeoff tests in `gap-bar.md`.
- [ ] Every `unknown` row has a question in § 7.
- - [ ] No `origin-isms.md` row is labeled `gap`.
+ - [ ] No row `origin-isms.md` labels `reshaped` is labeled `gap`; every
+ `not-available` row has a question.
- [ ] Every event the code handles has a § 4 row for each payload field
it reads, including log-only fields.
- [ ] Calls the framework makes on the app's behalf appear as rows.
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 e2c6b384..71114cfe 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
@@ -19,7 +19,7 @@ card per gap. The team will argue over it in one sitting.
| `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". |
+| `not-available` | Nothing in the current spec covers it (`origin-isms.md` or `#current-limitations`). Names the closest idiom and has a question in § 7; eligible for a card. |
| `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) | The row touches an element badged `x-cursor-visibility: PREVIEW` (`llms-full.txt#preview`). |
@@ -87,7 +87,8 @@ dependency makes on the app's behalf, marked as such.
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.
+`not-available` rows name the closest idiom and their question. `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
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 64eb3f17..94e76c9b 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
@@ -23,9 +23,9 @@ At least one must hold. Quote it on the card.
| 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
+## Not a gap
-- Anything in `origin-isms.md`.
+- Anything `origin-isms.md` labels `reshaped`.
- 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.
@@ -70,6 +70,6 @@ can act without a call.
Do not propose scope, field, or route names. Do not batch unrelated
capabilities. Do not send cards yourself. The team decides what goes out,
through whatever contact route they have with Cursor, quoting the spec
-version and any request ID from failed calls (`llms-full.txt#errors`). "This
-is by design, here is the idiom" is a fine answer. It goes back into the
-brief as `by-design-absent`.
+version and any request ID from failed calls (`llms-full.txt#errors`). "Not
+planned" or "here is the idiom" is a fine answer. Record it in the brief with
+the label it earns.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
index 8a3d7e26..8e01de09 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,37 +1,40 @@
-# Origin-isms: GitHub features Origin departs from on purpose
+# Origin-isms: GitHub features that map differently on Origin
-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
-third column is the `llms-full.txt` anchor where the Origin answer lives.
+Check here before labeling anything `gap`. Each row names the label to use
+and where the Origin answer lives today (an anchor in `llms-full.txt` unless
+noted). `reshaped` rows have a documented path and get no card.
+`not-available` rows get a question, and a card if they fail the gap bar.
Read the source; do not copy this table into the brief.
| GitHub call, event, or permission | Label | Where the Origin answer lives |
| --- | --- | --- |
-| Writes or `push` events on a repository mirrored from GitHub | `by-design-absent` | `#mirrored-repositories`, `#events`. First question of every brief. |
+| Writes or `push` events on a repository mirrored from GitHub | `reshaped` | 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`) | `reshaped` | `#installation-receipt` |
| RS256 app JWT | `reshaped` | `#app-jwt` |
| Long-lived installation tokens | `reshaped` | `#installation-access-token` |
-| User OAuth, `/user`, `/user/installations`, install-by-user picker | `by-design-absent` | `#scopes` (user-credential operations); repository discovery through the installation. Ask what the flow should do. |
+| 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` | `reshaped` | `#scopes`; `x-origin-scopes` per operation |
| Numeric IDs, `/repositories/{id}` | `reshaped` | `#ids`, `#repository-paths` |
| `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `#pagination` |
-| GraphQL | `by-design-absent` | No GraphQL endpoint in the spec. Decompose into REST calls and count the fan-out. |
+| GraphQL | `not-available` | No GraphQL endpoint in the current spec. Decompose into REST calls and count the fan-out; a decomposition that fails the gap bar earns a card about that read. |
| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | `#check-runs` (check runs with a stable `key`) |
-| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `by-design-absent` | No Issues in the spec; conversation is pull request comments, threads, reviews, labels. Ask what the pull-request-scoped behavior should be. |
+| 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 card. |
| `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `reshaped` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |
-| Repository webhook CRUD (`/repos/…/hooks`) | `by-design-absent` | Subscriptions are app settings (`#events`) |
-| App-manifest conversion, OAuth-app token mints | `by-design-absent` | `#installation`, Create App in the endpoint reference |
-| Git Data API tree/blob writes | `by-design-absent` | `#git-https-authentication`; Git data endpoint reference |
-| Standalone review-thread objects | `reshaped` | `#current-limitations`; Pull requests endpoint reference |
-| User, email, team, and member lookups | `by-design-absent` | `#resource-references`; no directory operations in the spec |
+| Repository webhook CRUD (`/repos/…/hooks`) | `reshaped` | Subscriptions are set per app through Create App / Update App `events` (`#events`). |
+| App-manifest conversion | `reshaped` | 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 | `reshaped` | 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 | `reshaped` | 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` | `reshaped` | `#events`, `#event-payloads` |
| `x-github-*` headers, HMAC `x-hub-signature-256` | `reshaped` | `#headers`, `#signature-verification` |
-| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | `#current-limitations`, `#resource-references`. Name the follow-up call per field and count the fan-out. |
+| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | `#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 | `reshaped` | `#events` |
| Reviews keyed by `commit_id` | `reshaped` | `pullRequestVersion` on the review schema |
| Finding own check runs or comments by actor | `reshaped` | `#check-runs` (`key`); comments and reviews by a marker the app controls |
-| Requested-reviewer team pages, `created_via` | `by-design-absent` | Pull requests endpoint reference (reviewers by identifier) |
+| 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 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`.
+with a question.
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 fb5826de..893c3222 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
@@ -85,8 +85,8 @@ event.
- 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. It is never `gap`, because Origin
- has not declined it, and never `by-design-absent`, because only
- `origin-isms.md` rows earn that.
+ has not declined it, and never `not-available` on the strength of this
+ skill alone; 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 pull request? does `updatedAt` move on a comment?) becomes an open
question plus a hello-world step that observes it on a native repository.