Playbook · session path

How to use the API now

Use Cloud Agents for GitHub pull requests in the background. Keep pi and OpenCode for local chat and debug.

1Scratch pad
2ve-work
3Landings
PRYou merge
API check scope the key GitHub fix 471 repos CLI cursor-agent First PR scratch pad
Recent path on this machine: check the key, open GitHub App access, wire the CLI, ship one real PR.

How to read it. Accent on the right is the proof step. Grey boxes are setup. Skip left boxes once they are done; live work starts at launch.

Setup

Once

Five steps. Do them in order the first time. After that, skip straight to launch.

  1. Load the key: source ~/.agentcookie/secrets/cursor/secrets.env (or open a new shell after the zsh bus loads cursor).
  2. Check the seat: cursor-agent me — expect cli-cursor and the API email.
  3. Confirm the repo is linked: cursor-agent repos ve-work. Empty means fix the Cursor GitHub App, not the CLI.
  4. Launch: cursor-agent launch --pr owner/repo "clear task". Prefer one repo and one outcome per job.
  5. Open the PR URL from status. Read the diff. Merge or close. Never auto-merge from the agent.

Plan limit: only a few Cloud Agents can run at once. Stop or delete finished runs before you start more. Concurrent launches return a plan upgrade error.

Top 3 use cases

From your history

These three targets came from your recent sessions: Cursor wiring, the multi-profile job agent, and landing or directory polish.

Each block has when to use it, which repo, why history points there, and a full prompt you can paste into cursor-agent launch --pr.

Use case 1 · safest

Design-safe HTML on ve-agent-scratch

When: you want a small HTML page. You do not want to touch a product repo yet.

Repo: collectivewinca/ve-agent-scratch

Why it fits history: default Cloud Agent repo with design rules and a working PR path.

Follow AGENTS.md and design-tokens.css.

Add one self-contained file reports/session-radar.html.

Content:
- Title: "Agent session radar"
- Short intro: background GitHub jobs versus local chat agents
- A table with 3 rows: local pi/OpenCode, Cursor Cloud Agent, IDE chat
- Columns: surface, best for, not for
- Light theme only. Use CSS variables from design-tokens.css.
- No raw hex outside tokens.
- Keep the file under 200 lines.

Open a pull request when done. Do not edit AGENTS.md.

Use case 2 · product

Small ve-work improvement

When: docs, copy, a small UI fix, or a README step. Clear PR shape.

Repo: collectivewinca/ve-work

Why it fits history: active multi-profile job agent. Heavy local debug stays in pi. The agent ships the boring PR.

Repo: ve-work (multi-profile job-application agent).

Task:
1) Find the user-facing docs or README section that explains how a new profile gets a dashboard login.
2) Add a short "Operator smoke check" subsection with 5 bullet steps a human can run after onboard.
3) Keep tone plain. Short sentences. No marketing words.
4) Do not change auth code, secrets, or deploy scripts.
5) Open a PR. In the PR body, list every file you touched.

If you cannot find the right doc file, stop and say which paths you searched.
Do not invent a new app route.

Use case 3 · growth surface

Landing polish (miny-directory / yugawatt)

When: copy, accessibility, or one section needs a clean PR. Not a full redesign.

Repo: collectivewinca/miny-directory or collectivewinca/yugawatt (one per run)

Why it fits history: many sessions ship or review landings. Agents handle bounded UI text. You keep brand calls.

Repo: miny-directory (music industry entity directory).

Task:
1) Locate the main public landing or home page component.
2) Add a concise "What you can find here" section with 4 bullets:
   artists, labels, venues, festivals.
3) Match existing components, spacing, and typography.
4) Do not add new dependencies.
5) Do not change PocketBase schemas, auth, or scrape jobs.
6) Open a PR. Describe UI states in the PR body.

If the home page is generated, edit the source template that generates it,
not dist/ only.

What not to send

Keep local

Not every task is a Cloud Agent job. If the work needs live secrets, SSH, or open-ended debug, keep it in pi or OpenCode.

pi / OpenCode
  • OAuth debug
  • Live server SSH and cron
  • Secret rotation and .env edits
  • Wide explore with no PR shape
Review rule
  • Agent opens the PR
  • You merge
  • No auto-merge
  • No deploy from the agent