Cursor SDK automations

Pipeline driven by CURSOR_API_KEY, running against a checked-out target repo. Independent of automations/claude-sdk/.

Consumer docs: GitHub Actions guide · npm / local guide

Execution model

Each workflow job:

1. Checks out this repo (the platform).
2. Checks out the target repo at target-repo/ via cursor-bootstrap.
3. Sets git committer to Nimble Cursor Bot <[email protected]>.
4. Seeds a per-run support bundle into the target repo:

| Bundle file | Tracked by project? | |---|---| | .cursor/skills/* | No (gitignored per-run) | | .cursor/hooks.json + .cursor/hooks/*.js | No (gitignored per-run) | | .cursor/knowledge/<file>.md | Yes — seeded from knowledge/shared/ only when missing; project commits overrides |

Models per stage

| Stage | Model | |---|---| | triage, implement, fix-pr-comments | claude-sonnet-4-6 | | create_issue_draft, create_issue, create_spec, create_pr_draft, create_pr | default | | review-pr | claude-opus-4-7 |

Environment variables

| Variable | Required | Description | |---|---|---| | CURSOR_API_KEY | yes | Cursor API key | | GH_BOT_TOKEN | recommended | PAT for git push + gh CLI. Falls back to github.token; github.token cannot push under .github/workflows/ | | SHORTCUT_API_TOKEN | no | Routes issues to Shortcut (priority over Linear) | | LINEAR_API_KEY | no | Routes issues to Linear | | LINEAR_TEAM_ID | no | Linear team ID; required when LINEAR_API_KEY is set | | CURSOR_SDK_DEBUG | no | Set to 1 to dump raw Cursor SDK stream events to stderr |

Scripts

| Script | Purpose | |---|---| | run-stage.ts | Stage driver: triage, create_issue_draft, create_issue, create_spec, implement, create_pr_draft, create_pr | | build-implement-matrix.ts | Emits Actions matrix JSON from project marker file detection | | detect-platform.ts | Resolves the platform slug from CURSOR_PLATFORM or marker file scan; sets platform_slug output | | bootstrap-from-ticket.ts | Initialises pipeline state from a GitHub issue, Linear ticket, or Shortcut story URL | | review-pr.ts | PR reviewer; structured verdict + deletions recommended; posts inline comments via gh | | fix-pr-comments.ts | Triages unresolved review threads, applies fixes, posts inline replies, resolves threads | | knowledge.ts | Merges knowledge/shared/ with project .cursor/knowledge/ overrides into the ## Project Knowledge prompt block |

Observability

Cost log: .observability/costs.jsonl (gitignored). Records stage name, duration, and success/failure per run. Token and cost fields are always 0 — Cursor SDK does not expose model pricing. Configured in config/cost-tracker.ts.

Summary: npx cursor-sdk-cost-report

Publishing (maintainers)

Driven by sdk-publish.yml, triggered on a published GitHub Release with a cursor-sdk/vX.Y.Z tag.

One-time setup

• secrets.NPM_TOKEN — npm automation token with publish access to the @nimblehq scope.
• The @nimblehq scope must exist on npm and the publishing user must have developer/owner access.

Procedure

1. Bump version in package.json and add a matching entry to CHANGELOG.md. Merge to main.
2. Run Create GitHub Release → select cursor-sdk. Version is read from package.json — no input needed.

The workflow reads the version from automations/cursor-sdk/package.json, creates the cursor-sdk/vX.Y.Z tag, publishes the release, and triggers sdk-publish.yml to build and push to npm and GitHub Packages. sdk-publish.yml re-checks that the tag matches package.json before publishing.

Diagnostics

| File | Contents | |---|---| | .cursor-pipeline-state.json | Pipeline state passed between stages (also uploaded as an artifact) | | .cursor-pipeline-runs.jsonl | Agent and stage run lifecycle events | | target-repo/.cursor-pipeline-edits.log | Append-only edit audit written by hooks | | .cursor-pipeline-review-raw-<ts>.txt | Raw agent output dumped by review-pr.ts when JSON parsing fails |