programmatic-agent-runs

name	programmatic-agent-runs
description	Govern Cursor SDK local, cloud, self-hosted, and subagent coding runs before they create branches or PRs.

Programmatic Agent Runs

Use this skill before launching a coding agent through the Cursor SDK, Cursor cloud agents, self-hosted workers, or subagents.

When to use

• A task starts from code, CI, a backend service, a kanban automation, or any unattended workflow
• The run can edit files, push a branch, create a PR, publish a package, deploy, or call shell tools
• The run delegates work to subagents with different prompts, models, or scopes

Launch checklist

1. Recall lessons with search_lessons for the repo, branch, files, and intended action.
2. Check active gates with prevention_rules before enabling writes or autoCreatePR.
3. Use the narrowest runtime: local for developer-in-the-loop work, cloud for isolated async work, self-hosted for private network/data requirements.
4. Give each subagent a bounded file or responsibility scope.
5. Persist run metadata: runtime, repo URL, starting ref, run id, agent id, branch, PR URL, and linked ThumbGate evidence.
6. Require verification output before merge, publish, deploy, or customer-facing claims.

Cursor SDK guardrails

• Attach ThumbGate MCP through the run environment so the agent can retrieve lessons and gates.
• Prefer a clean starting ref and a disposable branch for cloud VM runs.
• Do not set autoCreatePR for destructive, billing, release, or production tasks unless the gate check is clean.
• If a cloud run finishes while the developer is offline, inspect the run transcript and PR diff before treating the result as accepted.
• Capture thumbs_down feedback when a run violates scope, skips proof, repeats a known mistake, or opens a noisy PR.

Output

For each governed run, report:

• Runtime: local, cloud, or self-hosted
• Scope: files, modules, or workflow the agent may touch
• Gates checked and result
• Verification evidence
• Branch or PR URL
• Any feedback captured for future prevention