🧪 Skills
Cursor Dispatch
Orchestrate Cursor Agent CLI for coding tasks with concurrency control, timeout recovery, and multi-task coordination. Use when: (1) dispatching coding tasks...
v1.1.0
Description
name: cursor-dispatch description: "Orchestrate Cursor Agent CLI for coding tasks with concurrency control, timeout recovery, and multi-task coordination. Use when: (1) dispatching coding tasks to cursor agent via CLI, (2) analyzing code before modifying (plan mode), (3) running parallel batch coding tasks with concurrency limits, (4) coordinating multi-step code changes with review gates, (5) recovering from stuck/timeout cursor processes. Triggers: cursor dispatch, plan then execute, code analysis pipeline, batch coding tasks, cursor agent orchestration, parallel coding, concurrent tasks."
Cursor Agent CLI Dispatch
Orchestrate cursor agent CLI with concurrency control, timeout recovery, and retry.
Hard Constraints (from testing)
| Constraint | Value | Source |
|---|---|---|
| PTY required | pty: true mandatory |
No output without PTY |
| Max safe concurrency | 6 parallel tasks | Tested 8 OK, 6 is safe margin |
| Plan timeout (single file) | 60-120s | Tested on .gd files |
| Plan timeout (multi-file) | >180s, WILL timeout | Don't attempt |
| Execute timeout | 60-90s typical | Up to 180s for complex |
--output-format json |
BROKEN in PTY | Use text format only |
| Empty output = failure | Check output size > 20 bytes | Retry if empty |
Command Template
exec(
command: "cd <project> && cursor agent -p --trust [FLAGS] --model auto --workspace . '<prompt>'",
pty: true,
timeout: <seconds>
)
| Mode | Flags | Timeout | Use |
|---|---|---|---|
| Plan | --plan |
180s | Read-only analysis |
| Execute | --yolo |
180s | Auto-approve changes |
| Ask | --mode ask |
120s | Q&A, no changes |
Concurrency Control Protocol
State Tracking
Before launching cursor tasks, track them via process(action=list). Each running exec session with cursor agent counts toward the limit.
Launch Rules
1. Check: process(action=list) → count sessions with "cursor agent" in command
2. If count >= MAX_CONCURRENT (default 4, max 6): WAIT or QUEUE
3. Launch: exec(command=..., pty=true, timeout=T, background=true)
4. Record: sessionId + taskId + startTime
5. Poll: process(action=poll, sessionId=X, timeout=T*1000)
Concurrency Limits by Task Type
| Scenario | Max Concurrent | Why |
|---|---|---|
| Plan-only (read) | 6 | No file conflicts |
| Execute (write) | 3 | Avoid git/file conflicts |
| Mixed plan+execute | 4 | Balance safety and speed |
| Same-file tasks | 1 (serial only) | NEVER parallel on same file |
Timeout & Recovery Protocol
Detection
A task is stuck when:
process(action=poll, timeout=T)returns with process still running after timeout- Exit code 143 (SIGTERM) or 137 (SIGKILL) = was killed by timeout
- Output is empty (< 20 bytes) after completion = silent failure
Recovery Steps
1. DETECT: poll returns "still running" or exit 143/137 or empty output
2. KILL: process(action=kill, sessionId=X)
3. WAIT: 3 seconds cooldown (avoid API rate limits)
4. SIMPLIFY: reduce prompt scope (fewer files, simpler question)
5. RETRY: relaunch with simplified prompt, same or higher timeout
6. MAX RETRIES: 2 attempts total. After 2 failures → report to user
Simplification Strategy
When a task times out, simplify before retrying:
| Original | Simplified |
|---|---|
| "Scan all dungeon scripts for bugs" | "Scan dungeon_manager.gd for null refs" |
| "Fix 5 issues in this file" | "Fix issue #1 and #2 only" |
| "Analyze architecture of combat system" | "List all functions in arpg_monster.gd" |
Cleanup Protocol
When to Clean Up
- Before starting a new batch of tasks
- After any task failure
- On session start (check for orphans)
How to Clean Up
1. process(action=list) → find all cursor-related sessions
2. For each: check if still running
3. If running > 10 minutes: process(action=kill, sessionId=X)
4. Verify: ps aux | grep "cursor agent -p" | grep -v grep
5. Nuclear option: pkill -f "cursor agent -p" (kills ALL cursor CLI agents)
Orphan Detection
Cursor agent processes that outlive their exec session become orphans:
# Find orphan cursor agent processes
ps aux | grep "cursor agent -p" | grep -v grep
# Kill specific orphan
kill <PID>
Four Dispatch Chains
Chain A: Direct Execute
For simple tasks (1-3 files, clear logic). Single exec call.
exec(
command: "cd <project> && cursor agent -p --trust --yolo --model auto --workspace . '<task>'",
pty: true, timeout: 180
)
→ poll → verify output not empty → done
Chain B: Plan → Review → Execute ⭐
For complex tasks. Most reliable chain.
Step 1 — PLAN (pty:true, timeout:180):
"检查 <file> 中会导致运行时崩溃的问题。重点：<specific concerns>。只列会崩溃的。"
Step 2 — REVIEW (agent decides):
Parse output → grade 🔴🟠🟡🟢 → select fixes for this round
Step 3 — EXECUTE (pty:true, timeout:180):
"修复 <file> 中 N 个问题：[paste selected items with line numbers and fix code]。
修复后运行：<verify command>。确认无错误后 git commit。"
Step 4 — VERIFY:
Run headless build/test to confirm
Chain C: Parallel Batch
For independent tasks across different files. Use background exec.
# Launch (respect concurrency limit)
exec(cmd="cursor agent ... task1", pty:true, background:true) → session1
exec(cmd="cursor agent ... task2", pty:true, background:true) → session2
exec(cmd="cursor agent ... task3", pty:true, background:true) → session3
# Monitor
process(action=poll, sessionId=session1, timeout=180000)
process(action=poll, sessionId=session2, timeout=180000)
process(action=poll, sessionId=session3, timeout=180000)
# Verify all
Run headless build/test
Rules:
- Max 4 parallel execute tasks (6 for plan-only)
- NEVER parallel on same file
- Check for git conflicts after all complete
- If any fails: kill remaining → fix conflict → retry failed ones
Chain D: Plan Global → Serial Execute
For large refactors with dependencies.
1. Plan pass on each file (can parallel, up to 6)
2. Collect all findings → sort by dependency
3. Execute in dependency order (serial)
4. Verify after each execute before next
5. If verify fails: stop, fix, re-plan remaining
Prompt Engineering for Cursor Agent
Plan Prompts (what works)
Good: "检查 scripts/dungeon/dungeon_manager.gd 中所有可能返回 null 的函数调用，以及调用方是否有 null 检查"
Good: "列出
Execute Prompts (what works)
Good: Include exact line numbers + expected code change + verify command + git commit Bad: Vague "fix the bugs" without specifics
Template
Plan: "检查 <file> 中 <specific concern>。只列会崩溃/卡死的问题，给出行号和修复方案。"
Execute: "修复 <file> 中 N 个问题：
1. 第 X 行：<current code> → <fixed code>
2. 第 Y 行：<current code> → <fixed code>
修复后运行：<verify command>
确认无错误后 git commit -m '<message>'。"
Model Selection
| Task | Model | Timeout |
|---|---|---|
| Default | auto |
— |
| Simple edits | auto |
120s |
| Complex analysis | auto + --plan |
180s |
| Code review | auto + --mode ask |
120s |
auto routes to best available model (typically opus-4.6-thinking). Don't override unless needed.
Session Resume
cursor agent ls # List past sessions
cursor agent -p --trust --continue "..." # Continue last
cursor agent -p --trust --resume <id> "..." # Resume specific
Timing Benchmarks
v2.6.12 (tested 2026-03-06 evening, cursor 2.6.12)
| Task Type | Time | Concurrency Tested |
|---|---|---|
| List functions (small file <50 lines) | 8-14s | 6/6 parallel ✅ |
| List functions (medium file ~600 lines) | 17s | single ✅ |
| List functions (large file ~1000 lines) | 40s | single ✅ |
| Simple execute (add comment, 1 file) | 16-19s | 3/3 parallel ✅ |
| Ask mode (simple Q&A) | 8s | single ✅ |
| Complex analysis (null-check scan, 660 lines) | 84s | single ✅ |
| Long complex prompt (3+ concerns, multi-file ref) | >180s | TIMEOUT ⚠️ |
| Execute with broad prompt (3 bugs, multi-concern) | >180s | TIMEOUT ⚠️ |
Key Findings (v2.6.12)
- Simple tasks (list/comment/ask) are MUCH faster than v2026.02.27 (8-40s vs 55-120s)
- Complex analysis still takes 60-120s — similar to old version
- Broad prompts (3+ separate concerns) STILL timeout — must split into 1-concern-per-task
- Silent failures (empty output) reduced but still occur on timeout
- 6 parallel plan = all pass in ~53s wall clock (individual 8-14s each)
- 3 parallel execute = all pass in ~25s wall clock (individual 16-19s each)
Failure Mode: Prompt Complexity (NOT concurrency)
Timeouts correlate with prompt complexity, not concurrency:
- 6 simple tasks parallel → all pass in <20s each
- 1 complex task with 3+ concerns → timeout at 180s
- Solution: ALWAYS split multi-concern prompts. One concern per cursor task.
Previous version (v2026.02.27, tested 2026-03-06 morning)
| Task Type | Time | Concurrency Tested |
|---|---|---|
| List functions (1 file) | 15s | 8/8 passed |
| Null-check scan (1 file) | 80-120s | 4/4 parallel ✅ |
| Execute fix (1 file, 1-4 issues) | 55-90s | 3/3 parallel ✅ |
| Multi-file analysis | >180s | TIMEOUT |
Validated Workflows
Workflow 1: Parallel Plan → Review → Parallel Execute (2026-03-06)
Round 1 (Chain B serial): 3 files × plan→execute = 9 fixes, 3 commits
Round 2 (Chain C parallel): 4 files × plan (parallel) → review → 3 files × execute (parallel) = 3 fixes, 3 commits
Total: 12 runtime crash risks fixed, 6 commits, Godot headless zero errors
Workflow 2: Skip Plan, Direct Execute (2026-03-06 evening)
When you already know exactly what to change, skip Plan and go straight to Execute:
3 parallel Execute (different files) = all pass, 16-19s each
Pre-requisite: dispatcher already analyzed the code and wrote precise prompts
Key insight: Plan can always be parallelized (read-only). Execute can be parallelized only when tasks touch different files. Review is always serial (agent decides). Critical: Keep prompts focused — 1 file, 1 concern, specific line numbers.
For model list and CLI parameters, see references/models-and-params.md.
Reviews (0)
Sign in to write a review.
No reviews yet. Be the first to review!
Comments (0)
No comments yet. Be the first to share your thoughts!