---
name: cursor-orchestrator
description: >
  Use when executing an implementation plan with cursor-agent as the coding
  engine instead of Claude subagents. Invoke on /cursor-orchestrator, when user
  says "use cursor-agent to implement", or when sdd would apply but the user
  wants cursor to do the heavy coding work.
---

# Cursor Orchestrator

SDD with cursor-agent as implementer. Claude plans, instructs, reviews. cursor-agent
codes and commits. Never the reverse.

**REQUIRED:** Understand `sdd` — wave sequencing and worktree setup carry over.

---

## IRON LAW — active every turn, survives compaction

**Claude does not write, edit, or touch implementation code. Not one line.**

This rule is permanent. It does not reset after compaction, after a long session,
after an advisor call, after a BLOCKED status, or after any other event.

Forbidden — Claude must NEVER:
- Write or edit source files (`.ts`, `.tsx`, `.astro`, `.sql`, configs, etc.)
- Run build or test commands to verify implementation
- Apply a "quick fix" inline to unblock a cursor-agent
- Commit implementation work
- Reason that "it's faster if I just do this myself"

Every one of these is a violation. Dispatch cursor-agent instead — always.

**After compaction:** If you lost context about current wave state, re-read this
skill and check `git log` in the worktree before doing anything else. Do not
reconstruct by writing code.

**If cursor-agent is blocked:** Provide context, re-write the prompt, escalate to
user — never pick up the work yourself.

---

## Your role (Claude = controller only)

- Set up worktree (via `using-git-worktrees`)
- Write cursor-agent prompts with full context + worktree path
- Read output, judge correctness
- Call `advisor()` over all wave commits together
- Dispatch cursor-agent fixers for every finding
- Loop advisor → fixer until advisor returns clean — **no iteration cap**
- **Never write implementation code yourself — see IRON LAW above**

---

## cursor-agent invocation

> SUPERSEDED — original skill kept for reference. Canonical dispatch is
> `~/.claude/skills/cursor-orchestrator/ca.sh` (see SKILL.md). Do NOT rebuild ca.sh from the raw command below.

```bash
# Run via ctx_execute (language: "shell") — output is large, never bare Bash.
# ALWAYS pin --model composer-2.5. NEVER omit it: an unpinned cursor-agent run uses cursor's
# interactive config default (whatever the user last selected), NOT necessarily composer-2.5.
# Prefer ca.sh, which pins the model in one place.
cursor-agent --model composer-2.5 --print --workspace <WORKTREE_PATH> --trust "PROMPT"
```

`--workspace` must point to the worktree, not the main repo root.
cursor-agent has full tool access: reads/writes files, runs shell, runs tests, commits.

---

## Worktree setup

Before first wave, invoke `using-git-worktrees` to create `.worktrees/<branch>/`.
Record `WORKTREE_PATH`. Pass it in every cursor-agent prompt.

```
WORKTREE_PATH: /path/to/.worktrees/<branch>/
All work must happen inside this path.
```

---

## Execution loop

```
Setup worktree → read plan → extract waves → TodoWrite tasks
For each wave (in order):
  → dispatch cursor-agent implementer(s) with WORKTREE_PATH
  → cursor-agent commits its own work inside the worktree
  → verify commits exist: git log in worktree
  → advisor() reviews ALL commits of the wave together
  → if findings → fixer loop (see below) → advisor() again → repeat until clean
  → next wave
After all waves → push / deploy
```

---

## Single-task wave

1. Dispatch cursor-agent implementer (template below) — workspace = WORKTREE_PATH
2. cursor-agent commits its work
3. Verify: `git log --oneline -5` in worktree shows expected commit
4. `advisor()` — reviews full conversation context including all wave commits
5. Clean → next wave
6. Findings → fixer loop (see below)

## Multi-task wave (sequential, no file overlap)

Before dispatching: confirm zero file overlap across tasks.

Run cursor-agent for each task sequentially — each **commits its own work**.

After all tasks committed:
- Verify all commits in worktree git log
- `advisor()` reviews all wave commits together in one call
- Fixer loop if needed (per finding, sequentially)

---

## Fixer loop

```
advisor() has findings?
  ── no ──→ wave done → next wave
  ── yes ─→ dispatch cursor-agent fixer with WORKTREE_PATH + findings verbatim
            fixer commits fix
            advisor() again (all wave commits + fix commits in context)
            repeat until advisor() clean
            no iteration cap — loop until resolved
            if truly stuck (same finding resurfaces 3x) → STOP, escalate to user
```

---

## Implementer prompt template

```
You are implementing [Task N: task name].

## Worktree
WORKTREE_PATH: <path>
All file edits and git operations must happen inside this path.
cd to WORKTREE_PATH before any work.

## Task
[FULL task text from plan — paste it verbatim]

## Context
[Architecture context, dependencies, relevant file paths, existing patterns]

## Codebase conventions
[Key patterns: naming, imports, error handling — grep the worktree if unsure]

## Files to create / modify
[Explicit list from plan]

## Constraints
- Follow existing patterns exactly — read files before writing
- Do not modify files outside the task scope
- Commit your work when done: git commit -m "feat(task-N): <description>"
- If blocked or uncertain: write BLOCKED or NEEDS_CONTEXT at end, explain why

## Report back
STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
COMMIT: [SHA of your commit]
FILES_MODIFIED: [list]
SUMMARY: [what you did]
CONCERNS: [if any]
```

---

## Fixer prompt template

```
You implemented [task/wave description] and the code review found issues.

## Worktree
WORKTREE_PATH: <path>
All edits and git operations inside this path.
cd to WORKTREE_PATH before any work.

## Issues to fix
[Paste advisor() findings verbatim — every finding, no paraphrasing]

## Fix rules
- Fix exactly what is listed — do not refactor unrelated code
- Re-run any tests covering modified files
- Commit the fix: git commit -m "fix: <finding summary>"

## Report back
STATUS: DONE | BLOCKED
COMMIT: [SHA]
FIXED: [what you changed per finding]
```

---

## Handling cursor-agent output

| Output contains | Action |
|-----------------|--------|
| STATUS: DONE | Verify commit SHA in git log, enter advisor review |
| STATUS: DONE_WITH_CONCERNS | Read concerns — correctness issues block advisor; observations proceed |
| STATUS: BLOCKED | Provide missing context, re-dispatch |
| STATUS: NEEDS_CONTEXT | Answer the question, re-dispatch |
| No STATUS line | Treat as DONE_WITH_CONCERNS — scan for blockers |

---

## Red flags — stop immediately

- **Writing, editing, or touching implementation code yourself — IRON LAW violation**
- **"Just this once / quick fix / unblock myself" — still a violation**
- Skipping `advisor()` because "it looks fine"
- Advancing to next wave before advisor() clean on current wave
- Dispatching fixer without quoting specific advisor findings verbatim
- Running cursor-agent against main repo instead of worktree
- Ignoring BLOCKED — never retry without changing something
