{"slug": "orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context", "title": "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", "summary": "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.", "body_md": "| name | orchestrate-plan |\n|---|---|\n| 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. |\n\nYou are the **orchestrator** (manager). You do NOT write the implementation yourself.\nYou split a locked plan into **context-window-sized phases** and drive one or more **worker**\nClaudes in separate cmux panes: feed each worker one phase at a time, ** /clear its context\nbefore every phase**, verify each phase, then move on — while keeping your\n\n*own*context clean so you can run the whole plan without drowning in tool output.\n\nWhen the plan touches **independent repos** (e.g. a backend `api`\n\nservice + a `web`\n\nfrontend that both code to a contract the plan already fixes), run **one worker pane per repo\nin parallel** and babysit them all with a single ~45s monitor loop.\n\nThree non-negotiables:\n\n**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`\n\n, never`/compact`\n\n). Every phase starts pristine; the worker re-grounds from disk (PLAN.md + the brief +`git log`\n\n). 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.\n\n**Prerequisites:** a locked `PLAN.md`\n\nexists (run `grill-with-docs-codex`\n\n/ `codex-review`\n\nfirst if\nnot). You are inside a cmux workspace — this skill drives cmux panes; the CLI cheat sheet lives in\nthe `cmux-orchestrate`\n\nskill (`references/cmux-cli.md`\n\n). Verbatim templates are in `references/templates.md`\n\n.\n\nThe worker pane runs **Claude Code** (default, launcher `x`\n\n) or **OpenAI Codex** (`cdx`\n\n). The user\npicks. Everything about the orchestration (one phase per `/clear`\n\n, verify each phase, keep your\ncontext clean, GATE irreversible phases, the `=== PHASE N DONE ===`\n\nmarker, parallel lanes) is\nidentical — only the launch command and effort/fast-mode mechanics differ.\n\nClaude worker (default) |\nCodex worker (optional) |\n|\n|---|---|---|\n| Launcher | `x` (= `claude --dangerously-skip-permissions` ) |\n(= `cdx` `codex --dangerously-bypass-approvals-and-sandbox` , YOLO) |\n| Medium effort | `/effort medium` slash command, re-applied after every (Claude reverts effort on clear)`/clear` |\nlaunch 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` . |\n| Fast mode | NEVER — never for a Claude worker or for you, the orchestrator |\nslash command (Codex only). Send once after launch; after `/fast` `/clear` , `read-screen` to confirm it's still ON, re-toggle only if it reverted. |\n| Clear between phases | `/clear` |\n`/clear` (works in Codex too) |\n| Perms prompts | none (skip-perms) | none (YOLO bypass) |\n\n**Effort is ALWAYS medium for implementation.** Building against a locked, well-specified plan\ndoes NOT need\n\n`high`\n\n/`xhigh`\n\n— 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\n```\n[ -n \"$CMUX_SURFACE_ID\" ] && echo \"manager surface=$CMUX_SURFACE_ID\" || echo \"NOT in cmux — stop\"\n```\n\nIf not in cmux, tell the user and stop (the worker-pane model requires it; see Fallback).\nResolve inputs: ** PLAN_FILE as an ABSOLUTE path** (the per-phase prompt hands this path to the\nworker, so it must be absolute), the target repo dir(s), and read PLAN.md (and\n\n`CONTEXT.md`\n\n/ADRs if\npresent) 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**\n(a coherent slice — usually one feature-area or one repo's slice; may be several commits). Don't\nover-fragment into one-commit micro-tasks, and don't bundle two unrelated areas into one phase.\nFor each phase record:\n\n**number + one-line title**+ which PLAN section(s) it covers;** repo**it touches (the lane it belongs to);- a\n**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\n**watch-items**(risks to carry forward).\n\n**Detect parallel lanes.** Group phases by repo. If the plan spans **multiple repos that can progress\nindependently** — each side codes to a contract the plan already pins down (e.g. the wire shapes for\na new endpoint), with no phase in repo A needing a not-yet-built phase in repo B — mark them as\n**parallel lanes: one worker pane per repo**. If phases have cross-repo ordering dependencies (B can't\nstart until A's API exists and isn't yet contract-frozen), keep them **sequential** (single lane, or\nstage the dependent lane to start later). When unsure, default to sequential and tell the human why.\n\n**Create a todo list.** Call `TaskCreate`\n\nonce per phase, in execution order, so progress is visible\nand survives compaction. Within a lane, wire each phase to block the next (`TaskUpdate addBlockedBy`\n\n)\nso order is enforced; phases in *different parallel lanes* are NOT blocked on each other. If a list\nalready exists (you were resumed mid-run), reuse it — check `TaskList`\n\nfirst; never duplicate.\n\nThen **present the phase breakdown + the lane plan (sequential vs N parallel panes) to the human and\nget confirmation before spawning anything** (human-led planning before fan-out — cmux golden rule 6).\nKeep the list in lockstep with reality: mark a phase `in_progress`\n\nwhen you hand it to a worker, and\n`completed`\n\nonly after it's verified — at most one `in_progress`\n\nPER LANE.\n\n**Pick the branch base by topology, NOT by label** (per repo). The \"main branch\" label is often wrong;\nbase on the *live trunk* (recent integration commits / the code the plan references):\n\n```\ngit rev-list --count <labelMain>..<candidate>   # candidate ahead of labelMain?\ngit rev-list --count <candidate>..<labelMain>   # …and behind?\n```\n\nA candidate thousands of commits ahead and zero behind IS the trunk regardless of its name.\n\n**For EACH lane** (one repo → one pane; a single-repo plan is just one lane):\n\n**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`\n\n`=== PHASE N DONE ===`\n\nmarker, watch-items). Keep it untracked.**Spawn + name the pane**, capture its surface ref (`$W_ai`\n\n,`$W_fe`\n\n, …; one variable per lane):\n\n```\nW=$(cmux --json new-split right --focus false | sed -n 's/.*\"surface_ref\" : \"\\(surface:[0-9]*\\)\".*/\\1/p')\ncmux rename-tab --surface \"$W\" \"worker-<repo>\"\n```\n\n**Prep the shell + launch the worker**(Claude default):Confirm boot:\n\n```\ncmux send --surface \"$W\" -- 'cd <repo> && <env setup e.g. nvm use>\\n'\ncmux send --surface \"$W\" -- 'x\\n'          # x = claude --dangerously-skip-permissions\n```\n\n`cmux read-screen --surface \"$W\" | tail -8`\n\n(Claude banner +`❯`\n\n).**Set**`medium`\n\neffort:\n\n```\ncmux send --surface \"$W\" -- '/effort medium'; cmux send-key --surface \"$W\" enter\n```\n\n`/effort`\n\nmay pop a cache-warning confirm —`send-key enter`\n\non the highlighted \"Yes\". Confirm the bottom-right reads`● medium · /effort`\n\n.**Gotcha:**`/clear`\n\nreverts effort to the launch default, so re-apply`/effort medium`\n\nafter every clear (Phase 3 step 2).\n\nFor parallel lanes, do steps 1–5 for each pane before starting Phase 3, so all workers are armed.\n\nRun this loop for each lane. Lanes run **concurrently** — drive them round-robin and let the Phase 4\nmonitor tell you which one needs attention.\n\n**Confirm idle**—`read-screen | tail -8`\n\n; no spinner.**Fully clear, then re-set effort:**`cmux send --surface \"$W\" -- '/clear\\n'`\n\n,`read-screen | tail`\n\nto confirm a fresh transcript (if a`/`\n\npalette shows, an extra`send-key enter`\n\nruns`/clear`\n\n).`/clear`\n\nreverts effort — immediately re-apply`/effort medium`\n\n+`send-key enter`\n\n; confirm`● medium`\n\n.**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`\n\nand apply reasonable simplifications before finishing*separate*Enter:\n\n```\ncmux send --surface \"$W\" -- '<phase prompt text, single line, no apostrophes/double-quotes/tabs>'\ncmux send-key --surface \"$W\" enter\n```\n\n**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`\n\n/Tab\n\n**Confirm it submitted**—`read-screen | tail`\n\nshows 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`\n\n). 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`\n\n) and look for the exact line. If present,`=== PHASE <N> DONE ===`\n\n**verify independently and lightly**(snippet V1:`git log`\n\n,`git show --stat`\n\n, narrow`grep -n`\n\n). Do NOT Read source files into your context.**Verified →** mark the phase`completed`\n\n(`TaskUpdate`\n\n), set the lane's next phase`in_progress`\n\n, 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.\n\nEvery **~45 seconds**, walk every active pane (`cmux --json tree`\n\nfor current refs, then\n`read-screen --surface \"$W\" | tail -16`\n\nper lane) and classify each — then act (snippet W2 automates\nthe poll). **Always read the screen first, then act** (cmux golden rule):\n\n→ verify (V1), advance that lane:`=== PHASE N DONE ===`\n\n+ idle`/clear`\n\n→ 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`\n\n(`cmux send --surface \"$W\" -- 'please continue\\n'`\n\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`\n\n, or`send-key`\n\nfor 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`\n\n+ pause that lane; keep its phase`in_progress`\n\n). Do not guess on irreversible/ambiguous choices.**Runaway / wrong direction**→`cmux send-key --surface \"$W\" ctrl+c`\n\n, then redirect.\n\nKeep looping until all lanes are complete or a hard escalation. Throughout, keep YOUR context clean\n(tail reads only; never full scrollback). Surface progress to the human in a few lines, optionally via\n`cmux set-progress`\n\n/ `cmux notify`\n\n.\n\n- Read screens with\n`| tail -N`\n\n(8–40 lines). Never dump full scrollback. - Verify with\n`git show --stat`\n\n,`git log --oneline`\n\n, targeted`grep -n`\n\n— never`Read`\n\nwhole source files. - Trust the worker's own gates: the brief requires it to type-check + test + lint,\n**run**, and self-report before printing the phase-done marker. You spot-check; you don't re-run everything.`/ponytail-review`\n\nand apply reasonable simplifications - For heavy verification, spawn a throwaway\n`Explore`\n\nsubagent 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.\n\n- You orchestrate; you do not implement.\n**One phase per**(full reset, never`/clear`\n\n`/compact`\n\n); each phase prompt is self-contained = absolute PLAN.md path + this phase's description. - The worker ends every phase by printing\n**exactly** so you can grep completion. The busy-watcher regex must match ONLY ephemeral spinner text (`=== PHASE <N> DONE ===`\n\n`[0-9]+s ·`\n\n,`esc to interrupt`\n\n,`thinking`\n\n) —**NEVER** the static status bar or the`=== PHASE N DONE ===`\n\nmarker text (matching the marker fires the watcher instantly off the prompt echo). Detect the marker separately, after idle. - Worker effort is\n**always**— re-applied after every`medium`\n\n`/clear`\n\n(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`\n\nphase 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.\n\n- Don't read full files or scrollback into your context \"just to be sure\" — that defeats the point.\n- Don't parallelize repos that actually cross-depend; don't let one lane outrun a gated step.\n- Don't let a worker batch phases or skip its self-verification.\n- Don't auto-answer a worker's question when it's a real/irreversible decision — escalate instead.\n\nThe same shape works with the `Agent`\n\ntool: each phase = one fresh `general-purpose`\n\nsubagent (a new\nsubagent IS a pristine context, satisfying \"clear before each phase\"), and independent repo lanes =\nsubagents dispatched in parallel. The Agent return value is just a summary (keeping your context clean).\nYou lose live pane visibility and mid-phase intervention, so prefer the cmux path when available.", "url": "https://wpnews.pro/news/orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context", "canonical_source": "https://gist.github.com/EternallLight/091cf67301fde329729a73b70ffd30c3", "published_at": "2026-06-29 12:22:15+00:00", "updated_at": "2026-06-30 11:48:43.451870+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents"], "entities": ["Claude Code", "OpenAI Codex", "cmux"], "alternates": {"html": "https://wpnews.pro/news/orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context", "markdown": "https://wpnews.pro/news/orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context.md", "text": "https://wpnews.pro/news/orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context.txt", "jsonld": "https://wpnews.pro/news/orchestrate-plan-a-claude-code-skill-execute-a-locked-plan-md-via-fresh-context.jsonld"}}