--- 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 --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//`. Record `WORKTREE_PATH`. Pass it in every cursor-agent prompt. ``` WORKTREE_PATH: /path/to/.worktrees// 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: 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): " - 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: 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: " ## 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