cursor-agent

# Cursor Agent

Cursor Agent CLI runs on the user's Cursor subscription — zero API cost. Always prefer it over inline code generation for any non-trivial coding task.

## Prerequisites

**Required binary: `agent`** (Cursor Agent CLI)

Install from the official site: https://cursor.com/docs/cli/overview — then verify with `agent --version`.
The helper script (`scripts/run.sh`) will exit with an error if `agent` is not found in PATH.

## User Consent Required — MANDATORY

This skill MUST NOT be invoked autonomously. Every invocation requires:

1. **State intent first** — tell the user: the repo, the task, the model, and whether files will be changed
2. **Wait for explicit "yes"** — do not proceed without clear user approval
3. **Default to read-only** — use `run.sh <repo> <task> <model> ask` unless the user explicitly asks for changes
4. **Before writing files** — run in `ask` mode first, show the user the plan, then ask: *"Apply these changes?"*
5. **Before `--cloud`** — explicitly warn: *"This will send repo contents to cursor.com. OK to proceed?"*
6. **Before committing** — show the diff and get confirmation

The helper script (`scripts/run.sh`) defaults to `ask` (read-only). Pass `write` as the mode argument only after the user has confirmed changes should be applied.

## Model Routing

| Task type | Model flag | Mode flag |
|---|---|---|
| Trivial / exploratory | *(omit — `auto`)* | *(omit)* |
| Bug fix / feature / refactor | `--model sonnet-4.6` | *(omit)* |
| Code review / explain (read-only) | `--model sonnet-4.6` | `--mode=ask` |
| Architecture / design planning | `--model opus-4.6-thinking` | `--mode=plan` |
| Long background task | `--model sonnet-4.6` | use `--cloud` instead of `-p` |

## Headless Commands

**Read-only first** — always start with `--mode=ask` to review before applying changes:
```bash
cd <repo> && agent -p "<task>" --model sonnet-4.6 --mode=ask --output-format text --trust
```

**Apply changes** — only after user confirms the plan:
```bash...