Orchestrating AI coding agents: the editor owns shape, the shell owns commands

Running an IDE agent and a terminal agent on the same feature feels like having two contractors with one set of blueprints, and the default session collapses into duplicate instructions and clobbered files. The IDE agent wants to edit the codebase in place; the terminal agent wants to run commands, tests, and deploys. When both are told everything, both try to fix the same failing test, and the branch ends up with two competing versions of one function plus a shell that half-rebuilt the dependencies. The remedy is not to use one agent instead of two; it is to decide, out loud, before the session starts, where the ownership line runs, so that orchestrating AI coding agents becomes a ritual instead of a scramble.

The ownership line is easier to draw than it sounds, because the two tools are shaped differently by design. The editor agent lives inside the code: it reads the files, proposes diffs, and knows the syntax tree. The shell agent lives outside the code: it runs the tests, installs the packages, restarts the services, and reads the logs. Say the division to yourself in one sentence: the editor agent owns the code shape, and the shell agent owns the commands, tests, and deploys. When the sentence is spoken before the work starts, every instruction you dictate later has a destination, and the destination is what prevents the two agents from arguing over the same file.

The failure mode that kills this setup is not a deadlock but a drift: you ask the shell agent to fix the test failure, then you ask the editor agent to fix the same failure, and both do, differently. After the third overlap of the morning you stop knowing which version is the branch, which is a much worse state than either agent failing on its own. Keeping the line visible is the trick: write the sentence as the first line of the session note, or say it as the opening of every new task, since a line that is spoken twice a day is a line that gets followed. Orchestrating AI coding agents is mostly the discipline of not crossing your own border mid-session.

Voice is the natural instrument for the split because the instruction carries the owner: you say to the shell agent run the integration tests, and to the editor agent make the missing import a relative one, and the word you choose at the start of the sentence routes the work. With typing, the routing is implicit, and today's agents are cooperative enough to answer the five redundant instructions; with voice, you can narrate the routing while you think, and the narration itself becomes the session log. The session log is the quiet bonus of this workflow, since a spoken division plus its outcomes is a reviewable record of who did what, which is precisely what a two-agent branch needs at merge time.

Set the editor agent's charter in a spoken sentence: you own the imports, the types, the functions, and the file structure, and you do not run builds. Then set the shell agent's charter: you own installing, running, linting, testing, and deploying, and you do not edit source files. The symmetry is the point. Two charters, spoken, take ninety seconds and remove ninety percent of the overlap, because an agent cannot fix a test it is not allowed to run and cannot run a test it is not allowed to read without your explicit handoff instruction. The charter also makes your own behavior repeatable: when a thought arrives, you route it by rule rather than by mood.

The editor agent's domain has edges that matter. Widen the charter to the whole module, or narrow it to the two files the feature touches, and say the boundary so the agent hears it: today you may touch only the billing module. A boundary prevents the confident refactor that reorganizes three neighbors of your feature, which is the editor agent's most beloved and most costly habit. The shell agent's domain needs the same out-loud boundary: run only the billing test file, not the full suite, during the working loop, and run the full suite only when I say. Boundaries are the difference between agents that assist and agents that ambush.

The subtle choreography is in the waiting. The editor agent is editing while the shell agent is running, and the file the editor writes is not the file the shell agent ran, which is the classic stale-run trap. Dictate the handshake rule: the shell agent runs only after the editor agent reports done. Better still, give the shell agent a single command that captures the current state: after you and the editor agent finish a change, re-run the failing test first, then the neighbor tests, then tell me the result. The sequencing spoken aloud once becomes a habit for the whole feature, and the habit is what keeps the two agents from stepping on each other's evidence.

Watch for the second failure mode, which is the agents swapping roles out of helpfulness: the shell agent proposes a code edit to make the test pass, and the editor agent proposes a terminal command to verify something. Encourage neither, and correct both loudly: that edit belongs to the editor agent; that command belongs to the shell agent. The correction is also the training, because after three or four spoken corrections in the first session, both agents start routing their suggestions correctly, and by the end of the week the correction is a rare event rather than a mood. The agents converge on your structure because the structure is the only consistent thing they hear.

A handoff is the moment one agent's work becomes the other agent's input, and the handoff gets wired wrong whenever it is implicit. The shell agent says the test fails on a stale value, and the editor agent, on its own, edits the fixture file to change the value, and both agents now believe they own the fixture. Dictate the handoff explicitly every time: editor agent, the shell agent found that the fixture value is stale; you own the fixture, please update it so the test passes. One sentence, an owner, and a reason. The reason matters because it forces the handoff to be a fact rather than a vibe, and a fact-based handoff is one the other agent can act on without replaying the whole session.

The ownership registry is the operational tool: a short note, which you maintain in plain speech, listing each file in the change and which agent owns it. The registry is the fixture file belongs to the editor agent; the compose file belongs to the shell agent; the migration belongs to both, because the editor writes it and the shell runs it, so the migration gets a rule: write first, run second, and never run while writing. The registry takes a minute to dictate at the start of a session and it is the thing that makes a two-agent day survivable. When you are tired at half past five and two agents are both demanding attention, you read the list instead of the history to decide who is entitled to the file.

The same rule applies to your own voice: when you dictate an instruction, name the agent. Not the shell agent, run the payments test, but editor agent, add the retry; and shell agent, run the payments test afterwards. The naming costs half a second and it routes the instruction through the registry rather than through the agents' own guesswork. After a few days you will notice your instructions arriving pre-routed without effort, and the branch's diff will start looking like a person wrote it: the code changes in one style, the config changes in another, and no file carries the fingerprints of two conflicting attempts.

The handoff record is also the review material. At the end of the feature, open the session log, read the handoffs aloud, and count how many required redoing. One redo per day is normal; three means the registry has a hole, usually a file both agents legitimately touched, and the fix is a new rule rather than a scolding. Say the hole out loud: both agents need the docker-compose file, the editor to add a volume, the shell to rebuild, and the rule is the shell agent waits and never edits. Orchestrating AI coding agents is a loop of finding holes and closing them with a sentence, and the loop is what turns the third session into a quiet one.

At some point the two agents will disagree, and the disagreement is a feature rather than a failure: the editor agent restructures the retry loop into a helper, and the shell agent's test run insists that the helper breaks the integration test because it changed the timing the test asserts. Before you pick a side, make both agents state their case in one sentence each, spoken through you: editor, why the helper; shell, why the test insists. The one-sentence state is the reconciliation instrument, because most agent disagreements dissolve once the two reasons are on the table, and the few that remain are real design choices, which is exactly what a human is supposed to be there for.

Write the disagreement down before you decide, since a disagreement that has been spoken is a decision waiting to be made, while a disagreement that was waved away returns in the merge. Dictate the two positions and the evidence each one has: the editor's helper is tested by the unit suite, the shell's integration test denies the timing assumption. Then decide with your own sentence: the helper stays, and the integration test was asserting an accident of ordering, so the shell agent updates the test to assert the outcome instead. Deciding in spoken language keeps the reasoning attached to the record, and the record is what the third agent, your reviewer next week, will genuinely thank you for.

Sometimes the disagreement signals that the original instruction was ambiguous rather than the agents being wrong, and the correct move is to re-enter the conversation rather than to pick either agent's side. Say it honestly: I asked for a retry with backoff and did not say whether the retry covers the whole chain, which is the root of this fight, and the answer is each step retries independently. Then dictate the resolution to both agents in one message each and confirm the file allocations before either starts. A resolution dictated after the root cause is named is the difference between a patch and a fix, and the difference is visible in the diff within a day.

Learn from the reconciliation by asking the winning agent to record the decision in the code or the notes, not your memory: add a comment saying why the helper is safe despite the timing change, since the comment is the message to the next pair of agents that will argue the same point in three months. Keep a tally of disagreements by type: routing confusion, timing assumptions, and scope ambiguity. The tally is your coaching data, and after a month it will point to sentence in your own dictation that keeps causing the friction, such as the handoff that always lacks an owner or the boundary that always lacks an end time. Naming your own recurring ambiguity out loud is the quiet mastery of the whole arrangement.

The routine is a five-minute spoken opening, and it deserves to be repeated every single session because consistency is what trains the tools to be predictable. Say the three lines: editor agent, you own the code shape, today the billing module; shell agent, you own the commands and tests, the full suite is mine to trigger; both of you, no file edits outside your charters, and handoffs include an owner and a reason. Three lines, one minute, and the session starts with a contract instead of a vibe. The contract is also what your teammates see when they open your session log, and a team that sees contracts starts writing its own.

The middleware of the routine is the session note in plain language, dictated in three bursts: the plan at the start, the handoffs as they happen, and the disagreements as they resolve. The note is the memory that survives your own distraction, since a two-agent session has no single thread you can scroll; it has two threads plus your interruptions in between. When the mail arrives and you have to leave, the note lets you return to exactly the right place, and it lets the next person on the branch do the same without asking. A two-agent branch without a note is a two-agent branch that one person owns, and the owner becomes the bus factor of the week.

Time-box the session like any deep work: forty minutes of running, then a spoken five-minute standup with yourself, where you read the day's handoffs, the red tests, and the unresolved disagreements, and decide which one deserves your next hour. The review-of-the-work session is also the moment to promote a handoff into a permanent rule: we hand off the fixture updates explicitly from now on. Rules promoted from evidence are the ones that stick, whereas rules invented in a planning meeting are the ones that evaporate. The voice is the right medium for the standup because standups are meant to be fast and honest, and speech is faster and more honest than a status document.

After a fortnight the routine becomes invisible, and the measure of the routine is a calm diff rather than a quiet day: the branch has one style per domain, no clobbered files, a log that reads like a story, and tests that pass on the first full run. When a teammate asks how you run two agents without chaos, the answer fits in a sentence: you decide the split out loud, you name the owner in every handoff, and you keep the registry where both can see it. The sentence is the whole article, and it is a sentence you can dictate in the time it takes to say hello, which is exactly how every good engineering workflow ought to behave.