The Orchestra Now Asks Before Building

🎻 What Orchestra Actually Is

Orchestra is the protocol you reach for when a task is too big for one Claude session to hold in its head: migrations, audits, multi-phase builds with research, design, code, tests, and visual checks all stacked on top of each other.

The way it works is unusual. The Claude session you talk to is just a narrator, it doesn’t do any of the actual thinking.

Instead, it runs a small command-line program (the “runner”) that lives in the background. That runner is the thing that spawns brand-new Claude sessions to do every piece of real work.

That setup gives you two things at once. The narrator session stays small (no memory bloat across phases), and every specialist gets a full clean working memory of about a million tokens to focus on its one job.

🚧 The Gap We Hit

The user typed something like this:

/one-shot-orchestra plan let’s finish the migration from
render to cloudflare pages...

The word plan there matters. It’s how you tell our other protocol, /one-shot-scripts, that you want to see and approve a written plan before any code gets touched. The user expected orchestra to behave the same way.

It didn’t. Orchestra responded that plan mode wasn’t supported and suggested falling back to /one-shot.

Reasonable enough as a fallback. But the user wanted the real thing: orchestra’s heavy-duty multi-phase machinery, with a chance to read the plan and shape it before the runner started spending hours on workers.

🔁 Why The Easy Fix Was Wrong

In /one-shot-scripts, plan mode is simple. After the research phase, the same Claude session writes the plan, hands it to Claude Code’s built-in “approve plan” popup, and the user sees it inline.

That works because in one-shot-scripts, the same session does everything. The session that did the research is the session that writes the plan, so the plan comes straight out of its own working memory.

Orchestra is built around the opposite rule: the narrator session never does any thinking work.

So if we asked the narrator to “just write the plan,” we’d be putting planning logic right back where we’d spent the whole architecture trying to avoid it.

📐 The Shape Of The Fix

The plan had to be written by a brand-new Claude session that the runner spawns specifically to write it. So we added a new role to orchestra’s lineup: the Planner.

The Planner is what we call a “decision worker.” That’s a session whose job is to make a decision and write a document, not to build anything.

We already had a few of these: the Conductor decides how to split work into parallel jobs, the Merger combines results, the Loop-Judge decides whether the run needs another pass. The Planner slots in next to them.

It fires exactly once per run, in one specific spot:

This is the only spot in an orchestra run where it stops and waits for a human. Everything else is autonomous from start to finish.

📝 What The Plan Actually Looks Like

The Planner’s brief tells it to write a plan with eight specific sections. We pinned the structure down so the user always knows what they’re reading.

The Planner writes this whole document to a file called work/plan.md. The narrator’s job at the gate is to open that file and show it to the user word-for-word, not summarized.

The user needs to see exactly what they’re saying yes or no to.

🎛️ Two New Buttons For The Narrator

Once the plan is on screen, the user replies in normal English. The narrator then picks one of two new commands to run.

If the user’s reply is ambiguous (“hmm, maybe”), the narrator is told not to guess. It asks again.

🔁 The Revision Loop

Revisions have no cap. The user can ask for changes once, three times, or ten times.

We don’t want a tool that gives up on you because you’re still figuring out the shape.

The trick is what happens on each revision. We don’t want the Planner to write a “v2 changes” section tacked onto the bottom.

We want the new plan to read as if the Planner had written it correctly the first time, with the user’s feedback baked in.

Because the Planner is always a brand-new session, there’s no memory of the old plan getting in the way. It reads the prior plan as a document, reads the feedback as a document, and writes a new clean plan from those inputs.

🔀 The State Machine Got Three New Stops

Orchestra runs by cycling through “states” (named stages like routing, phase_running, scoring_pending). Plan mode added three new ones, plus a permanent flag.

planner_pending  →  planner_running  →  plan_pending_approval
                                                  ↓
                                          ( approve )  vs  ( revise )
                                                  ↓
                                              routing       plan_revising
                                            (Builder)            ↓
                                                          planner_running
                                                          (loops back)

Once the user approves, the plan_approved flag flips to true and stays true for the rest of the run.

Even if the Loop-Judge later decides to re-run an earlier phase to fix a quality issue, the plan gate doesn’t fire again. One approval, one run.

🧪 How We Tested It Without Burning Tokens

We didn’t want to spawn real Claude sessions for every test (each one costs real money and takes minutes). So we built an offline test that fakes the worker outputs and just verifies the plumbing.

The test script lives at runner/test-plan-mode.sh. It runs six checks. All six pass.

The one thing the test deliberately doesn’t do is launch a real Planner terminal. That path is one line in the spawn code, and we verify it by hand on real runs.

⚖️ Two Skills, Same Word, Different Implementations

This was the second skill we’ve added plan mode to. The other one, /one-shot-scripts, did it in a much simpler way, and the contrast shows why the orchestra version had to be different.

🎁 What You Get

If you already have one-shot-orchestra, the plan-mode upgrade is part of the latest release. Type plan after the skill name and the gate fires automatically.

For huge tasks (migrations, audits, multi-day builds), the gate pays for itself the first time it catches a misread requirement before the runner spends an hour building the wrong thing.