Cursor plugin specification and official plugins
TypeScript
Drop the spec indexer; llms-full.txt already expands nested fields
Cursor Agent89b461d5a6cd
diff --git a/origin-apps/README.md b/origin-apps/README.mdindex 6118ada1..92d10dc3 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -79,9 +79,6 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/- For the porting skill, read access to the app's source. Producing the briefneeds no Origin credentials. You follow the brief's hello-world pathafterwards.-- Optional: `python3` with PyYAML for the porting skill's- `scripts/index-origin-spec.py`, which prints webhook payload fields with- their references resolved. Without it the skill reads the spec directly.## Where the brief goesdiff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex 4979deab..f0400dc0 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -26,6 +26,11 @@ which rules to check first. It restates nothing you can read there.- `https://cursor.com/docs/api/origin/llms.txt` (index) and`https://cursor.com/docs/api/origin/changelog` (what moved).+Lookup order: for one question, read `llms.txt` to find the section, then+fetch only that section of `llms-full.txt` or the page it links. Fetch the+whole `llms-full.txt` or `openapi.yaml` only when the task needs broad+coverage, such as a porting brief.+Cite `operationId`s and `llms-full.txt` anchors. If this file and the fetcheddocs disagree, the docs win.diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex 450753d5..897ba919 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -9,8 +9,6 @@ description: >-license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.- The optional payload-field script needs python3 with PyYAML; without it,- read the spec directly.---# Port a GitHub App to an Origin App@@ -33,11 +31,11 @@ scopes, webhooks, paging, IDs, and errors. Follow it first. Nothing here repeats## Procedure-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`: two `rg` commands for operations, scopes,- and slugs, and `scripts/index-origin-spec.py openapi.yaml` (needs PyYAML)- for webhook payload fields.+1. **Load the spec** (`origin-api`, "Fetch first"). A brief needs broad+ coverage, so fetch the full `openapi.yaml` and `llms-full.txt`; the+ narrow lookup order in `origin-api` is for later single questions. Record+ `info.version` and the fetch time for the brief's provenance. Build the+ mapping index per `references/spec-mapping.md`.2. **Discover** per `references/discovery.md`. Record a file and line forevery fact, including payload fields read only for logging and calls theframework makes on the app's behalf. Note what you looked for and did not@@ -95,4 +93,3 @@ cards to Cursor. The brief carries them and the team decides.| `references/origin-isms.md` | Labeling a missing GitHub feature. || `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` | Listing webhook payload families with their fields resolved. Optional. |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.mdindex 893c3222..16c22e67 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@@ -21,13 +21,15 @@ table here. Build the index once. Every later step looks things up in it.you which GitHub flows have no app-side equivalent. Read parameters andresponse 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. `scripts/index-origin-spec.py- openapi.yaml` prints each payload family with its fields and `$ref`s- resolved two levels deep; `schema <Name>` does the same for one component.- From `llms-full.txt#events`, note which slugs are delivered without a- subscription and which must be selected.-3. **Resources**: component schemas returned by `Get…`/`List…`, with field- names, for "does the Origin object carry this field".+ every slug with its payload schema. Each family's fields, with nested+ objects expanded to dotted paths, are under its heading in+ `llms-full.txt` (`rg -n '^### Pull Request Events$' llms-full.txt`, then+ read to the next `###`). From `#events`, note which slugs are delivered+ without a subscription and which must be selected.+3. **Resources**: each endpoint's "Response Fields" in `llms-full.txt`+ (`rg -n '^### Get Pull Request$' llms-full.txt`) lists the fields the+ object carries, nested objects expanded, for "does the Origin object carry+ this field".## Matching@@ -73,7 +75,8 @@ no slug is not an event on Origin. Check whether the state change isobservable 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 four outcomes.+walk the mapped family's "Payload Fields" list in `llms-full.txt` and record+one of four outcomes.Present at `<path>`. Follow-up read via `<operationId>` with identifiers thepayload carries. Derivable from present fields, saying how and whether theformat is contractual. Absent, which goes to the gap bar. A field on the RESTdiff --git a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py b/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.pydeleted file mode 100644index b50ab04e..00000000--- a/origin-apps/skills/port-github-app-to-origin/scripts/index-origin-spec.py+++ /dev/null@@ -1,125 +0,0 @@-#!/usr/bin/env python3-"""Print the Origin webhook payload families with their fields resolved.--Usage:- python3 index-origin-spec.py openapi.yaml # every payload family- python3 index-origin-spec.py openapi.yaml schema PullRequest # one component--Fetch the spec first:- curl -sSL https://cursor.com/docs/api/origin/openapi.yaml -o openapi.yaml--Operations and scopes do not need this script. Grep the spec directly:- rg -B1 -A4 'x-origin-scopes:' openapi.yaml- rg -A3 'x-origin-webhook-events:' openapi.yaml--Read-only. Needs PyYAML (`pip install pyyaml`). Everything printed comes from-the spec you pass in; nothing is pinned or embedded here.-"""--import sys--try:- import yaml-except ImportError: # pragma: no cover- sys.stderr.write(- "PyYAML is not installed. Run `pip install pyyaml`, or read the spec "- "directly (search for `x-origin-webhook-events:` and follow the "- "`$ref`s by hand).\n"- )- sys.exit(2)--# Field descriptions are cut to one sentence and this many characters so a-# family fits on one screen.-DESCRIPTION_CHARS = 140-# How many `$ref` levels to expand under a payload. Two reaches the embedded-# resource and its direct children, which is what field mapping needs.-SCHEMA_DEPTH = 2---def ref_name(node):- if not isinstance(node, dict):- return None- if "$ref" in node:- return node["$ref"].rsplit("/", 1)[-1]- if "allOf" in node and node["allOf"] and "$ref" in node["allOf"][0]:- return node["allOf"][0]["$ref"].rsplit("/", 1)[-1]- if node.get("type") == "array":- inner = ref_name(node.get("items", {}))- return f"{inner}[]" if inner else "array"- return None---def first_sentence(text):- return " ".join((text or "").split()).split(". ")[0][:DESCRIPTION_CHARS]---def print_schema(components, name, depth=0, seen=None):- seen = seen or set()- schema = components.get(name)- if not schema:- print(f"{' ' * depth}(no component named {name})")- return- for field, node in (schema.get("properties") or {}).items():- kind = ref_name(node) or node.get("type", "?")- desc = first_sentence(node.get("description"))- print(f"{' ' * depth}{field}: {kind}" + (f" -- {desc}" if desc else ""))- inner = (ref_name(node) or "").rstrip("[]")- if inner and inner in components and depth < SCHEMA_DEPTH and inner not in seen:- seen.add(inner)- print_schema(components, inner, depth + 1, seen)---def print_events(components):- print("== WEBHOOK PAYLOAD FAMILIES (schema | slugs | x-origin-webhook-resource)")- for name, schema in components.items():- slugs = schema.get("x-origin-webhook-events")- if not slugs:- continue- print(f"{name} | {slugs} | resource={schema.get('x-origin-webhook-resource')}")- print_schema(components, name, depth=1)---def load_spec(path):- try:- with open(path, encoding="utf-8") as fh:- spec = yaml.safe_load(fh)- except FileNotFoundError:- sys.stderr.write(f"{path}: not found. Fetch it first (command in --help).\n")- return None- except yaml.YAMLError as err:- sys.stderr.write(f"{path}: not valid YAML ({err}).\n")- return None- if not isinstance(spec, dict) or "components" not in spec or "info" not in spec:- sys.stderr.write(f"{path}: not an OpenAPI document (no `info` or `components`).\n")- return None- components = (spec.get("components") or {}).get("schemas") or {}- if not any("x-origin-webhook-events" in s for s in components.values() if isinstance(s, dict)):- sys.stderr.write(- f"{path}: no schema carries `x-origin-webhook-events`; is this the Origin spec?\n"- )- return None- return spec---def main(argv):- if len(argv) < 2 or argv[1] in ("-h", "--help"):- print(__doc__)- return 1- spec = load_spec(argv[1])- if spec is None:- return 1- components = spec["components"]["schemas"]- schema_mode = len(argv) > 2 and argv[2] == "schema"- if schema_mode and len(argv) < 4:- sys.stderr.write("schema mode needs a component name.\n")- return 1- print(f"# {spec['info'].get('title')} {spec['info'].get('version')}")- if schema_mode:- print_schema(components, argv[3])- else:- print_events(components)- return 0---if __name__ == "__main__":- sys.exit(main(sys.argv))