orchestrate-plan — a Claude Code skill: execute a locked PLAN.md via fresh-context cmux worker pane(s), one phase per /clear, parallel lanes for independent repos

A developer created 'orchestrate-plan', a Claude Code skill that executes a locked PLAN.md by delegating implementation to cmux worker panes one phase at a time, clearing context between phases. The skill supports parallel lanes for independent repos and enforces non-negotiables such as one phase per context window and full context clears.

| name | orchestrate-plan | |---|---| | description | Use when executing a locked PLAN.md e.g. produced by grill-with-docs-codex / codex-review by delegating the implementation to cmux worker pane s ONE PHASE at a time — splitting the plan into context-window-sized phases, fully clearing the worker's context between phases, and when the plan touches INDEPENDENT repos running one worker pane per repo IN PARALLEL with a ~45s monitor/unblock loop. Triggers on "execute the plan", "implement PLAN.md", "orchestrate this implementation", "run the plan with a worker", "split the plan into phases and build it", "build the backend and frontend in parallel panes". Builds on cmux-orchestrate. Not for edits you can finish inline, and not outside a cmux workspace. | You are the orchestrator manager . You do NOT write the implementation yourself. You split a locked plan into context-window-sized phases and drive one or more worker Claudes in separate cmux panes: feed each worker one phase at a time, /clear its context before every phase , verify each phase, then move on — while keeping your own context clean so you can run the whole plan without drowning in tool output. When the plan touches independent repos e.g. a backend api service + a web frontend that both code to a contract the plan already fixes , run one worker pane per repo in parallel and babysit them all with a single ~45s monitor loop. Three non-negotiables: One phase per context window. A phase is a coherent slice of the plan sized to fit one worker context it may be several commits . Split anything bigger; cluster anything trivially small. Fully clear the worker before each phase /clear , never /compact . Every phase starts pristine; the worker re-grounds from disk PLAN.md + the brief + git log . Strictly more deterministic than carrying a lossy summary. Keep the orchestrator's context clean. Never Read worker source files or full scrollback into your window. Verify with git plumbing + narrow greps. Summarize to the human; never paste screens. Prerequisites: a locked PLAN.md exists run grill-with-docs-codex / codex-review first if not . You are inside a cmux workspace — this skill drives cmux panes; the CLI cheat sheet lives in the cmux-orchestrate skill references/cmux-cli.md . Verbatim templates are in references/templates.md . The worker pane runs Claude Code default, launcher x or OpenAI Codex cdx . The user picks. Everything about the orchestration one phase per /clear , verify each phase, keep your context clean, GATE irreversible phases, the === PHASE N DONE === marker, parallel lanes is identical — only the launch command and effort/fast-mode mechanics differ. Claude worker default | Codex worker optional | | |---|---|---| | Launcher | x = claude --dangerously-skip-permissions | = cdx codex --dangerously-bypass-approvals-and-sandbox , YOLO | | Medium effort | /effort medium slash command, re-applied after every Claude reverts effort on clear /clear | launch flag cdx -c model reasoning effort=medium — Codex has no ; the flag is process-level so it /effort commandpersists across . Valid: /clear minimal|low|medium|high|xhigh . | | Fast mode | NEVER — never for a Claude worker or for you, the orchestrator | slash command Codex only . Send once after launch; after /fast /clear , read-screen to confirm it's still ON, re-toggle only if it reverted. | | Clear between phases | /clear | /clear works in Codex too | | Perms prompts | none skip-perms | none YOLO bypass | Effort is ALWAYS medium for implementation. Building against a locked, well-specified plan does NOT need high / xhigh — they are markedly slower for negligible gain here. Fast mode is only ever for a Codex worker — never the orchestrator, never a Claude worker. -n "$CMUX SURFACE ID" && echo "manager surface=$CMUX SURFACE ID" || echo "NOT in cmux — stop" If not in cmux, tell the user and stop the worker-pane model requires it; see Fallback . Resolve inputs: PLAN FILE as an ABSOLUTE path the per-phase prompt hands this path to the worker, so it must be absolute , the target repo dir s , and read PLAN.md and CONTEXT.md /ADRs if present ONCE to derive the phase list — then rely on disk, not memory.Parse PLAN.md into an ordered list of phases, each sized to fit ONE worker context window a coherent slice — usually one feature-area or one repo's slice; may be several commits . Don't over-fragment into one-commit micro-tasks, and don't bundle two unrelated areas into one phase. For each phase record: number + one-line title + which PLAN section s it covers; repo it touches the lane it belongs to ;- a phase description : the concrete scope + an explicit stop point "…and nothing else" so the worker knows where this phase ends; GATED? — true if irreversible/outward-facing deletes code, pushes, deploys, runs migrations, hits staging/prod . Gated phases need explicit human OK before they run;- any watch-items risks to carry forward . Detect parallel lanes. Group phases by repo. If the plan spans multiple repos that can progress independently — each side codes to a contract the plan already pins down e.g. the wire shapes for a new endpoint , with no phase in repo A needing a not-yet-built phase in repo B — mark them as parallel lanes: one worker pane per repo . If phases have cross-repo ordering dependencies B can't start until A's API exists and isn't yet contract-frozen , keep them sequential single lane, or stage the dependent lane to start later . When unsure, default to sequential and tell the human why. Create a todo list. Call TaskCreate once per phase, in execution order, so progress is visible and survives compaction. Within a lane, wire each phase to block the next TaskUpdate addBlockedBy so order is enforced; phases in different parallel lanes are NOT blocked on each other. If a list already exists you were resumed mid-run , reuse it — check TaskList first; never duplicate. Then present the phase breakdown + the lane plan sequential vs N parallel panes to the human and get confirmation before spawning anything human-led planning before fan-out — cmux golden rule 6 . Keep the list in lockstep with reality: mark a phase in progress when you hand it to a worker, and completed only after it's verified — at most one in progress PER LANE. Pick the branch base by topology, NOT by label per repo . The "main branch" label is often wrong; base on the live trunk recent integration commits / the code the plan references : git rev-list --count <labelMain ..<candidate candidate ahead of labelMain? git rev-list --count <candidate ..<labelMain …and behind? A candidate thousands of commits ahead and zero behind IS the trunk regardless of its name. For EACH lane one repo → one pane; a single-repo plan is just one lane : Create the feature branch off the verified base. Never work on main/master; never force-push. Write in that repo template T1 — standing orders the worker re-reads every phase repo+branch, what's done/out-of-scope, conventions, per-phase workflow, stop points, the WORKER-BRIEF.md === PHASE N DONE === marker, watch-items . Keep it untracked. Spawn + name the pane , capture its surface ref $W ai , $W fe , …; one variable per lane : W=$ cmux --json new-split right --focus false | sed -n 's/. "surface ref" : "\ surface: 0-9 \ ". /\1/p' cmux rename-tab --surface "$W" "worker-<repo " Prep the shell + launch the worker Claude default :Confirm boot: cmux send --surface "$W" -- 'cd <repo && <env setup e.g. nvm use \n' cmux send --surface "$W" -- 'x\n' x = claude --dangerously-skip-permissions cmux read-screen --surface "$W" | tail -8 Claude banner + ❯ . Set medium effort: cmux send --surface "$W" -- '/effort medium'; cmux send-key --surface "$W" enter /effort may pop a cache-warning confirm — send-key enter on the highlighted "Yes". Confirm the bottom-right reads ● medium · /effort . Gotcha: /clear reverts effort to the launch default, so re-apply /effort medium after every clear Phase 3 step 2 . For parallel lanes, do steps 1–5 for each pane before starting Phase 3, so all workers are armed. Run this loop for each lane. Lanes run concurrently — drive them round-robin and let the Phase 4 monitor tell you which one needs attention. Confirm idle — read-screen | tail -8 ; no spinner. Fully clear, then re-set effort: cmux send --surface "$W" -- '/clear\n' , read-screen | tail to confirm a fresh transcript if a / palette shows, an extra send-key enter runs /clear . /clear reverts effort — immediately re-apply /effort medium + send-key enter ; confirm ● medium . Send the per-phase prompt template T2 . It carries a the ABSOLUTE path to the full PLAN.md and b this phase's description + stop point , so the worker reads the whole plan from disk but builds ONLY this phase. The prompt also instructs the worker to run the brief, T1, makes this a standing gate . Because it's long, send the text THEN a /ponytail-review and apply reasonable simplifications before finishing separate Enter: cmux send --surface "$W" -- '<phase prompt text, single line, no apostrophes/double-quotes/tabs ' cmux send-key --surface "$W" enter Ghost autocomplete: a greyed Tab-suggestion is NOT typed text — backspace/Esc/Ctrl+U won't clear it; type your prompt over it. Never send it accepts the ghost . \t /Tab Confirm it submitted — read-screen | tail shows the spinner running not the prompt sitting in the box . Wait for idle — single lane: arm the idle watcher snippet W1, run in background: true . Multiple lanes: rely on the Phase 4 multi-pane monitor instead of one watcher per pane. On idle: confirm the phase-done marker. Read the worker's tail read-screen --scrollback --lines 60 | tail -40 and look for the exact line. If present, === PHASE <N DONE === verify independently and lightly snippet V1: git log , git show --stat , narrow grep -n . Do NOT Read source files into your context. Verified → mark the phase completed TaskUpdate , set the lane's next phase in progress , loop to phase N+1 in that lane. No marker / problem → see Phase 4 nudge / correct / escalate . Lane out of phases → that worker is done; leave it idle or close the pane. Every ~45 seconds , walk every active pane cmux --json tree for current refs, then read-screen --surface "$W" | tail -16 per lane and classify each — then act snippet W2 automates the poll . Always read the screen first, then act cmux golden rule : → verify V1 , advance that lane: === PHASE N DONE === + idle /clear → re-apply effort → send next phase prompt. If the lane has no more phases, mark it complete. Error / API failure / crash / "code is done" stall / sitting idle mid-phase → nudge: send a short please continue cmux send --surface "$W" -- 'please continue\n' . If it's clearly lost its task e.g. context got cleared unexpectedly , re-send the phase prompt instead. Worker is asking a question an "ask user"-style prompt, a clarification, or a permission prompt despite bypass → read it. If it's safely answerable from PLAN.md / the brief / obvious convention, pick the most appropriate answer and send it to unblock free-text send , or send-key for a TUI menu — see cmux-orchestrate "Answering agents in workers" . If it's a real decision, a gated step, or otherwise not safely unblockable → escalate to the human cmux notify + pause that lane; keep its phase in progress . Do not guess on irreversible/ambiguous choices. Runaway / wrong direction → cmux send-key --surface "$W" ctrl+c , then redirect. Keep looping until all lanes are complete or a hard escalation. Throughout, keep YOUR context clean tail reads only; never full scrollback . Surface progress to the human in a few lines, optionally via cmux set-progress / cmux notify . - Read screens with | tail -N 8–40 lines . Never dump full scrollback. - Verify with git show --stat , git log --oneline , targeted grep -n — never Read whole source files. - Trust the worker's own gates: the brief requires it to type-check + test + lint, run , and self-report before printing the phase-done marker. You spot-check; you don't re-run everything. /ponytail-review and apply reasonable simplifications - For heavy verification, spawn a throwaway Explore subagent to check a phase and return one-line PASS/FAIL — its file reads stay in its context, not yours. - Summarize to the human; don't relay screens. - You orchestrate; you do not implement. One phase per full reset, never /clear /compact ; each phase prompt is self-contained = absolute PLAN.md path + this phase's description. - The worker ends every phase by printing exactly so you can grep completion. The busy-watcher regex must match ONLY ephemeral spinner text === PHASE <N DONE === 0-9 +s · , esc to interrupt , thinking — NEVER the static status bar or the === PHASE N DONE === marker text matching the marker fires the watcher instantly off the prompt echo . Detect the marker separately, after idle. - Worker effort is always — re-applied after every medium /clear Claude reverts it . Fast mode only ever for a Codex worker. Parallel only for genuinely independent repo lanes. If phases cross-depend, stay sequential. At most one in progress phase PER LANE.- GATE before any irreversible/outward-facing phase — explicit human confirmation. Don't trust branch labels; confirm topology. Don't fake convergence; report real failures. Worker stages only changed files; planning docs PLAN.md, CONTEXT.md, WORKER-BRIEF.md, PLAN-REVIEW-LOG.md stay untracked. - Don't read full files or scrollback into your context "just to be sure" — that defeats the point. - Don't parallelize repos that actually cross-depend; don't let one lane outrun a gated step. - Don't let a worker batch phases or skip its self-verification. - Don't auto-answer a worker's question when it's a real/irreversible decision — escalate instead. The same shape works with the Agent tool: each phase = one fresh general-purpose subagent a new subagent IS a pristine context, satisfying "clear before each phase" , and independent repo lanes = subagents dispatched in parallel. The Agent return value is just a summary keeping your context clean . You lose live pane visibility and mid-phase intervention, so prefer the cmux path when available.