# Spec Completion Review Workflow — Cursor Backend

Use when `BACKEND="cursor"`. Prerequisite: Phase 0 backend detection in [workflow-common.md](workflow-common.md) has resolved `BACKEND`, `FLOWCTL`, and `SPEC_ID`.

Cursor shells out to the `cursor-agent` CLI (headless `-p --output-format json`), billed against the user's Cursor subscription. This is the **review backend**, independent of the Cursor-as-primary-host-driver path.

## Step 1: Identify Spec

```bash
# SPEC_ID from arguments (e.g., fn-1, fn-22-53k)
$FLOWCTL show "$SPEC_ID" --json
```

## Step 2: Execute Review

```bash
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/completion-review-receipt.json}"

# Runtime config:
#   --spec <spec>           full spec (cursor:<model>), highest priority
#   FLOW_REVIEW_BACKEND     spec-form ok: cursor:gpt-5.5-high
#   FLOW_CURSOR_MODEL       fills missing model only (default gpt-5.5-high)
#
# Cursor folds reasoning effort INTO the model name, so there is NO effort
# field (no FLOW_CURSOR_EFFORT, no `cursor:<model>:<effort>`).

$FLOWCTL cursor completion-review "$SPEC_ID" --receipt "$RECEIPT_PATH"
```

**Output includes `VERDICT=SHIP|NEEDS_WORK`.**

The runner invokes `cursor-agent -p --output-format json --trust --mode ask` with `cwd=repo_root` (`--mode ask` is read-only — the reviewer never mutates the tree).

## Step 3: Handle Verdict

If `VERDICT=NEEDS_WORK`:
1. Parse issues from output
2. Fix code and run tests
3. Commit fixes
4. Re-run step 2 (receipt enables session continuity when `mode == "cursor"`)
5. Repeat until SHIP

## Step 4: Receipt

Receipt is written automatically by `flowctl cursor completion-review` when `--receipt` provided.
Format: `{"type":"completion_review","id":"<spec-id>","mode":"cursor","verdict":"<verdict>","session_id":"<uuid>","model":"<model>","spec":"cursor:<model>","timestamp":"..."}`

There is **no `effort` key** — effort is not a Cursor field. The `spec` field is the canonical round-trippable form; `model` is the resolved Cursor model string.

Session resume guard: re-review only resumes the cursor session when the existing receipt at `$RECEIPT_PATH` has `mode == "cursor"`. The first call omits `--resume` and captures Cursor's generated `session_id`; continuations pass `--resume <session_id>`. Cross-backend switches start a fresh session.

---

## Anti-patterns (Cursor backend)

- **Direct cursor-agent calls** - Must use `flowctl cursor` wrappers
- **Inventing a `--model` CLI flag** - Use `--spec` for a full `cursor:<model>` value, or the `FLOW_CURSOR_MODEL` env var to fill the model
- **Passing an effort** - Cursor has no effort field; `cursor:<model>:<effort>` is rejected. Pick a model whose name already encodes the effort
- **Fabricating a first-call `--resume` id** - The first call omits `--resume`; persist Cursor's returned `session_id` and resume with that. Session resume uses `--resume=<uuid>` under the hood via `--receipt`
- **Assuming cross-backend session continuity** - Resume only works when prior receipt has `mode == "cursor"`
