| name | boss |
| description | Use ONLY when the user explicitly asks to orchestrate parallel external agents (Codex or Claude Code) in tmux sessions via tp (tmux-pilot). Or when a user tells you that you're the boss or orchestrator. You can also use this if you are an operclaw agent. NEVER auto-invoke for a generic "do this in parallel" request. For in-process subagents, use superpowers:dispatching-parallel-agents instead. |
| argument-hint | "review" | "status" | "kill" [INFO] |
boss: orchestrate multiple agents in the ai-gene-review repo
Overview
Use this skill when the user wants you to orchestrate one or more gene review jobs, in such a way the user has observability via the tmux wrapper tp
Ground rules:
- bosses are knowledgeable about GO annotation review but delegate all work involving editing
- bosses will answer questions in response to a user, and may do extensive research, but if it turns into something bigger, should be delegated to an agent
Example user invocations:
/boss review human SDHA
- user intent: create a new tp session to review a gene's annotations
/boss review ECOLI secA BACSU ftsZ DROME jar
- user intent: batch-review multiple genes in parallel
/boss status
- user intent: I want to know the status of all sessions in this repo
- are they active?
- is there a PR?
- is the PR passing?
- has the PR been reviewed? If so, was it approved?
- is the PR in conflict?
About
Turn the main session into an orchestrator of external agents running in tmux. Each worker is a Codex or Claude Code process inside its own tmux session, on its own branch, in its own git worktree. Boss observes and steers via tp (tmux-pilot) — never via raw tmux send-keys. Boss does not write code itself.
Core principle: one worker = one task = one branch = one worktree.
Typical ai-gene-review tasks
- Gene review: review GO annotations for a gene (the primary task). One gene = one PR.
- Rule review: review UniProt annotation rules (ARBA/UniRule). One rule = one PR.
- Prediction review: review computational predictions for a gene. Can be bundled with gene review.
When NOT to use
- The user did not explicitly invoke boss / tp / tmux-pilot / "external agents". A bare "do these in parallel" is not a boss invocation — use
superpowers:dispatching-parallel-agents (in-process subagents) instead.
- Single-task or strictly sequential work — just do it directly.
- Tasks have cross-dependencies. Boss assumes embarrassingly parallel work (in this repo: one PR per gene). Serialize dependent work yourself.
Hard rules
- One task, one session, one branch, one worktree. Never reuse a session for a second task.
- Every worker gets its own isolated worktree under
~/worktrees/ (tp's default). Multiple boss-managed agents run in parallel on different branches — they cannot share a worktree (git only permits one worktree per branch), cannot reuse the orchestrator's checkout, and must never be placed inside the repo (.worktrees/, .claude/worktrees/, workdirs/, etc.). Isolation is the whole point of the parallel-agents model: one agent per ~/worktrees/<slug>/, period.
- Use
tp exclusively for agent control — tp new, tp send, tp peek, tp status, tp ls, tp set, tp kill, tp clean. Never use raw tmux send-keys or tmux capture-pane for agent interaction. Read-only tmux list-sessions is acceptable if tp cannot cover it, but prefer tp ls --json.
- Default profile is
codex. Use --profile claude only when the user says so or the task is reasoning/review-heavy rather than mechanical.
- Issue linkage:
- Multi-commit work:
--issue N is required. tp pulls the issue title into @desc and derives a branch like fix/N-<slug>.
- Single-commit chore:
--issue optional; -d "description" is enough and you pick the slug.
- Every
tp send after session creation uses --wait. Agents are not always at a sendable prompt; --wait blocks until they are.
- If
tp has friction, talk to Chris and/or file an issue at cmungall/tmux-pilot. Do not fall back to raw tmux send-keys without explicit permission.
Workflow
Generally the orchestrator should be run as an agent from an up to date main branch; not from a worktree
plan → dispatch → monitor → steer → complete → clean
1. Plan
Use TodoWrite. One item per task. For each, note:
- Slug (session name): short (< 20 chars), lowercase, hyphens. Do NOT prefix with the repo name.
tp prepends the repo basename to the worktree path automatically, so a aigr- prefix produces a doubled path like ~/worktrees/ai-gene-review-aigr-review-sdha (cmungall/tmux-pilot#23). Use review-sdha, not aigr-review-sdha.
- GH issue number (if multi-commit — required per rule 5)
- Profile (default
codex)
- One-sentence description (->
@desc)
- Initial prompt (one line, terse — see step 2.3 below)
Confirm the plan with the user before dispatching if there are more than ~3 tasks or if issue linkage is ambiguous.
2. Dispatch — ordered sequence, do not skip steps
tp new bundles worktree creation, branch creation, session start, agent launch, and prompt delivery into one call. Several of those silently fail or drift in known ways. Always verify each step.
2.1 Confirm or create the GH issue (multi-commit only)
Per rule 5, multi-commit work requires --issue N. If no existing issue covers the task, file one:
gh issue create --repo ai4curation/ai-gene-review \
--title "Review GO annotations: SDHA" \
--body "..."
For a single-commit chore, skip this and use -d "description" in the next step.
2.2 Run tp new
tp new review-sdha --profile codex \
--repo ~/repos/ai-gene-review \
--issue 260 \
--branch feat/review-sdha \
--prompt "/review human SDHA"
tp new fix-typo --profile codex \
--repo ~/repos/ai-gene-review \
--branch fix/typo-readme \
-d "Fix typo in README" \
--prompt "fix the typo in README.md and open a PR"
What tp new does, atomically in one call:
- creates an isolated worktree at
~/worktrees/<repo>-<slug>/
- creates the branch (override auto-derived name with
--branch to match convention: feat/review-<gene> for gene reviews)
- starts a detached tmux session
- launches the agent (codex / claude) inside the worktree
- attempts to type the
--prompt as the first user turn
Expect tp new to exit non-zero with Timed out waiting for session to become ready. This is cmungall/tmux-pilot#22 — tp new --prompt races agent startup and frequently drops the prompt. A timeout exit does not mean the dispatch failed; it means readiness detection gave up before the agent's TUI finished rendering. Always verify with the next steps. Empirically, --prompt lands successfully on roughly 1 in 5 first attempts, so plan for step 2.4 (redeliver) to run on most dispatches.
Parallel-dispatch cancellation gotcha. If you fire multiple tp new calls in a single parallel batch (e.g., multiple Bash tool uses in one message), a timeout exit in one call can cancel the sibling calls mid-flight. The cancelled calls' tmux sessions may still have been partially created by tp before cancellation (session creation is front-loaded; readiness detection is the slow part), so after a parallel batch always run tp ls to inventory which expected slugs actually exist and re-dispatch only the missing ones sequentially. For batches of 2-4, sequential dispatch is more predictable and the serial overhead is small. For larger batches, dispatch in parallel but budget for retries and verify every slug individually.
Keep --prompt terse. The worker launches inside the worktree and inherits everything: CLAUDE.md, all project skills (review, aigr-pr-review, bioreason-predictions, ...), the just targets, and the validation stack. Do not restate SOPs, validation steps, or skill names in the prompt — the worker finds and invokes them on its own. A one-line directive ("/review human SDHA", "fix the bug in Y") is almost always enough. Over-instructing wastes tokens, crowds out the worker's own planning, and risks contradicting project guidance.
2.3 Verify the worktree path (parallelism invariant)
tp status review-sdha | grep ^Dir:
The worktree path must:
- live under
~/worktrees/
- have exactly one
ai-gene-review- prefix (not ai-gene-review-aigr-...)
- not be inside the repo (
.worktrees/, .claude/worktrees/, workdirs/)
If any of those is wrong, abort and redispatch — do not try to patch it live:
tp clean review-sdha --force
Isolation of every agent under ~/worktrees/ is the whole basis of the parallel-agents model. Don't compromise it "just this once".
2.4 Verify the prompt landed
tp peek review-sdha -n 15
If the pane shows only the codex TUI header (model name, directory, Tip: ...) with no task line after the > input prompt, --prompt was dropped. Redeliver manually:
tp send --wait review-sdha "/review human SDHA"
--wait is required — the agent may not be at a sendable prompt yet.
2.5 Mark bookkeeping
tp set review-sdha status active
Now the session is dispatched, verified, and tracked. Move on to Monitor (step 3).
3. Monitor
Be proactive. Check sessions every few minutes during active dispatch. Don't wait to be asked.
tp ls --json
tp ls --status active
tp peek review-sdha -n 40
tp status review-sdha
Two state dimensions — do not confuse them:
| Dimension | Source | Vocabulary | Read with |
|---|
tp agent state (transient, observed) | agent transcript + pane | idle running completed interrupted error unknown | tp status <name> |
boss @status (curated, your bookkeeping) | you set it | active idle waiting-human blocked done-ish | tp get <name> status |
4. Steer
Send follow-ups only when sendable. Always --wait:
tp send --wait review-sdha "Also check the deep research file for additional references."
tp send --wait --timeout 120 review-sdha "continue"
5. Stuck-agent protocol
Symptoms: tp status shows error, interrupted, or stuck on running/unknown for too long; tp peek shows a Codex trust prompt, repeated failure, or confusion. Note: brand-new repos and worktrees in Codex often pause at a trust prompt; sometimes Codex needs an extra Enter to advance.
Playbook:
- Nudge once with
tp send --wait <name> "<clarifying instruction>". For trust prompts, often "yes" or another Enter is enough.
- If still stuck after one nudge:
tp set <name> status waiting-human, then report to the user with the session name, the symptom, and a proposed next step. Do not rescue the same session more than twice — escalate.
6. PR follow-through (this is the actual completion loop)
A PR being opened is NOT completion. In this repo an automatic claude-code-review job runs on every PR and acts as the reviewer. A task is only "done" when the PR has been approved by claude-code-review AND all CI checks pass. Until then the worker's job isn't finished.
After the worker reports "PR opened, validation passes" and goes idle, boss's standard SOP is to prod the worker to watch its own PR through to approval. Boss does not run gh pr view / gh pr checks itself — boss delegates that to the worker.
Standard prod sequence:
- Worker reports PR opened, goes idle.
- Boss sends:
tp send --wait <name> "check the PR — wait for the claude-review comment, address any feedback, fix any failing CI checks"
- Worker polls
gh pr view / gh pr checks, reads the claude-code-review bot's comment, and addresses issues in new commits (re-pushes automatically; PR updates in place).
- Boss peeks periodically. If the worker reports approval + all checks green, that is the real completion signal:
tp set <name> status done-ish
- If the worker says it can't address the review feedback, a check is failing in a way it doesn't understand, or it loops more than twice without convergence:
tp set <name> status waiting-human
then report to the user with the PR URL, the specific failing check or review comment, and what the worker tried.
Never mark done-ish on PR-opened alone. "I opened a PR" is a milestone, not a finish line. If you mark it done-ish and walk away, you've left an un-reviewed draft sitting in the queue.
Tear down only after done-ish:
tp kill review-sdha
tp ls --status done-ish
tp clean --status done-ish --dry-run
tp clean --status done-ish --force
Command cheatsheet
| Intent | Command |
|---|
| Dispatch Codex on a GH issue | tp new <name> --profile codex --repo <path> --issue <N> --prompt "..." |
| Dispatch Claude on an ad-hoc branch | tp new <name> --profile claude --repo <path> --branch <br> --prompt "..." |
| List everything (machine-readable) | tp ls --json |
| Recent output | tp peek <name> -n 40 |
| Detailed state | tp status <name> |
| Send follow-up | tp send --wait <name> "..." |
| Long follow-up | tp send --wait --timeout 120 <name> "..." |
| Set boss status | tp set <name> status <active|waiting-human|done-ish> |
| Tear down one | tp kill <name> |
| Clean batch | tp clean --status done-ish --force |
Run tp <command> --help for full flag lists.
Red flags — STOP
| Thought | Reality |
|---|
"I'll just use tmux send-keys once" | No. Talk to Chris or file an issue at cmungall/tmux-pilot. |
| "Let me reuse this session for a second task" | One task = one session. Spin a new one. |
| "I'll have task A pipe its branch into task B" | Boss is for embarrassingly parallel work. Serialize dependent work yourself. |
"I'll skip --wait, it's faster" | You'll race the prompt and lose input. Every send uses --wait. |
| "PR is open, I'll mark it done-ish" | No. PR-opened is a milestone, not completion. Prod the worker to watch its own PR through claude-code-review approval + green CI. Only then done-ish. |
"I'll run gh pr view / gh pr checks myself" | No — delegate. tp send --wait <name> "check the PR, address review feedback, fix failing checks". Boss orchestrates, worker executes. |
| "The user said 'in parallel', activate boss" | Only if they named boss / tp / tmux / external agents. Otherwise use dispatching-parallel-agents. |
| "Worktree inside the repo is fine just this once" | No. Every agent needs an isolated worktree under ~/worktrees/. Parallelism requires isolation — git only allows one worktree per branch, and agents step on each other if they share a checkout. |
| "Two agents can share a worktree if they work on different files" | No. Shared worktree = shared git index, shared dirty state, shared branch. One agent per worktree. |
"Firing 5 tp new calls in parallel is faster" | Beware the parallel-cancellation gotcha — a timeout in one call can cancel sibling calls mid-flight, leaving a mix of created, partially-created, and missing sessions. After any parallel dispatch, run tp ls and re-dispatch the missing slugs sequentially. |
| "I should remind the worker about CLAUDE.md rules / validation / the right skill to use" | No. The worker inherits CLAUDE.md and all project skills automatically. One-line prompts only. |
Related skills
superpowers:dispatching-parallel-agents — in-process subagents via the Agent tool. Use when work is read-only, stateless, or fits in one Claude context. Boss is the external-process counterpart for stateful, observable, multi-hour code work.superpowers:using-git-worktrees — worktree hygiene. Mostly redundant under boss because tp creates worktrees for you; useful for any manual recovery.
