cursor-agent-supervisor

Agent Supervisor

You can start subagents (e.g. to work on a specific JJ revision) with:

# Create a conversation with a sub-agent:
cursor-agent --print --model <model-name> create-chat  # Prints a conversation uuid

# Give a task to the sub-agent: (command will finish when sub-agent is done)
cursor-agent --print --resume <conversation-uuid> "...description of the subagent's task..."

Model Selection

cursor-agent --print --model unknown-model will print an error that will list available models. Unless you know which model is best for the task, just use sonnet-4.5 by default.

Invocation

Important: Sub-agent tasks can take several minutes. Always use a longer timeout:

# In your Shell tool call, set timeout to 10 minutes
timeout: 600000

The --print flag makes the sub-agent run on its own, and reply only once it is done.

Setting Things up for the Sub-agent

Prepare things up so the agent can focus on its task (eg. if using JJ, don't ask them to run jj commands unless really necessary. Notably run jj edit yourself first to get into the revision where the work should be done). Ideally, the sub-agent should only have to read your instructions, hack on code, run build/tests, hack on code, etc. until your instructions are implemented, and then reply with a final answer. YOU are in charge of bookkeeping, not them. YOU have the big picture, they don't.

Giving Good Instructions

Give the subagent the instructions they will need to complete the task, but do not overwhelm them.

Do:

• Provide a clear, specific goal
• List key files to read/modify
• Specify what "done" looks like
• Include relevant patterns to follow or reference implementations
• Tell them which skills to load if needed

Don't:

• Dump or link to entire skills when they only need a subset
• Include irrelevant context
• Leave success criteria ambiguous

Task Description Template

Work on [specific task] in [repo/directory].

**Setup:**
- Skills to load or files to read IN FULL
- Summarized instructions from skills or files, tailored to the task

**Goal:**
[Clear description of what to implement/fix]

**Key files:**
- path/to/main/file.ts - [why it matters]
- path/to/reference.ts - [pattern to follow]

**Requirements:**
- [Specific requirement 1]
- [Specific requirement 2]

**Done when:**
- [Testable criterion 1]
- [Testable criterion 2]
- [e.g., "pnpm -F @pkg lint passes"]

After Sub-agent Completes

Always verify the sub-agent's work:

1. Check what changed: check the commit/revision diff, and adequation with the task
2. Review the actual code if the changes are non-trivial
3. Run verification commands (tests, type-check, lint)
4. Update task status based on results (if using jj-todo-workflow)

When Things Go Wrong

If the sub-agent:

• Fails or errors out: Read the output, fix any blocking issues, retry with more context
• Produces incomplete work: Continue the work yourself or spawn another sub-agent with clarified instructions
• Goes off track: Review what happened, potentially revert changes, retry with tighter constraints
• Gets stuck on tooling: May need to provide explicit commands or paths