1. Problem Background: Why a Single-Model Loop Falls Short

When a coding agent moves from answering questions to editing code, running tests, and opening pull requests, the first hard limit it hits is not the model’s capability ceiling but context capacity. A real engineering task often involves several rounds of log searches, reading through a dozen files, and repeated build-and-failure iterations. If the raw output of any single step is dumped back into the main conversation in full, the context window fills up fast—followed by instruction forgetting, drift in early constraints, and a higher error rate in tool-call parameters.

The more mainstream industry solution is to split execution into two layers: a coordinator that understands intent, decomposes tasks, dispatches work, and synthesizes results; and several workers that complete research, implementation, and verification in their own independent contexts. The two communicate through structured messages—the coordinator receives only compressed conclusions, not raw noise. The value of this design comes down to three things: the main context stays clean, subtasks can run in parallel, and a failure can be retried locally without polluting global state.

Whether this architecture works depends roughly 80% on how well the coordinator prompt is written. The sections below break down a publicly visible coordinator-layer prompt and explain the design intent of each part.

2. The Overall Skeleton: A Prompt Is Not a Character Card but a Set of Decision Constraints

The structural layering of this prompt is almost the standard skeleton for a “production-grade agent system prompt”:

1. A one-line definition of system identity and collaboration partners
2. Role responsibilities (what to do / what not to do)
3. Tool inventory and their semantic boundaries
4. Communication protocol (who can read what)
5. Execution policy (when to delegate, how to judge progress, how to terminate)

It is worth stressing the ordering between the second and third layers: declare responsibilities first, then declare tools. Many teams do the reverse and pile tool descriptions at the front. The result is that the model reads “available tools” as “tools that must be used,” so it spins up a worker even for a question it should answer directly—wasting one dispatch and a full round of latency.

The opening self-positioning is just one sentence, yet it does three things: it states that the identity is a coordinator, that the collaboration partners are multiple workers, and that the domain is software engineering tasks. No extra adjectives, no information-free role packaging like “you are a world-class expert.” In long-running tasks, every sentence of decision-irrelevant rhetoric dilutes the constraints the model actually needs to follow.

3. Role Definition: Writing “Delegation” as a Conditional Action

The responsibility section lists four items: help the user achieve their goal; direct workers to do research, implementation, and verification; synthesize results and communicate with the user; and answer directly when possible.

The first three are routine division of labor; the fourth is the key part. It states an explicit anti-delegation principle—anything you can do yourself without using tools, don’t delegate. The engineering meaning is that the coordinator is itself a full conversational model, capable of answering conceptual questions, explaining what an error means, and comparing solution options. Without this explicit constraint, the model tends to handle every request in a way that “looks more diligent”: it spins up a worker no matter how large or small the question. The cost is doubled latency, conclusions diluted by the worker’s intermediate narration, and simple questions over-engineered.

Two accompanying constraints in the communication protocol are equally counterintuitive but extremely necessary:

• Every message the coordinator outputs is for the user. This makes the output channel singular. The model no longer has the illusion that “this line is just internal thinking,” so it naturally keeps its phrasing complete, its conclusions clear, and its output readable for a reader.
• Worker return values and system notifications are internal signals, not conversation partners—do not thank or acknowledge them. This targets one of the most common degradation behaviors in multi-agent systems: agents start exchanging pleasantries. A typical symptom is the coordinator replying “Thanks for the excellent work, I’ve taken your results into account” after receiving a subtask result—wasting tokens and making the user think a stranger joined the conversation. The prompt also gives the correct alternative action: when new information arrives, summarize it for the user. Redirecting “reply to the subprocess” into “report to the human” solves three problems at once—courtesy replies, context bloat, and user-perception confusion.

4. Worker Capabilities: Template Injection Instead of Multi-Branch Prompts

One of the most reusable engineering details in this prompt is that the worker capability description is made a runtime variable rather than hardcoded:

${workerCapabilities} = configuration A ? "Workers can use terminal commands, file read/edit tools, and tools provided by services connected via the external tool protocol."
                                    :  "Workers can use the standard tool set, tools provided by external tool services, and predefined project capabilities accessed through the skill mechanism. Delegate skill invocations (such as submission flows and verification flows) to workers."

The two branches correspond to two product forms: one is a lean mode with only a minimal tool set, for low-cost or restricted environments; the other is a full mode that additionally exposes reusable in-project flows (team-defined commit conventions, verification pipelines, and so on). The trade-off logic here is worth copying:

• Capability descriptions are injected by configuration, not written as if-else in the prompt. Runtime code selects the branch; the model only sees one definite block of text, reducing the ambiguity from conditional reasoning.
• Capability descriptions are precise to tool granularity, not a vague “you have many capabilities.” The coordinator needs to judge “can this be delegated” based on them, so the precision of the capability list directly determines the accuracy of dispatch decisions.
• Invocations of reusable flows are clearly assigned to workers. These flows usually contain multi-step operations and state changes. If the coordinator were allowed to run them directly, the main context would be flooded by process output. Handing execution to workers and returning only results is the necessary design for keeping the main context clean.

5. The Tool Set: Every Tool Needs a “When Not to Use It”

The coordinator usually holds only four kinds of tools: create a worker, send a follow-up message to an existing worker, stop a running worker, and subscribe to external events. The small number is deliberate—the coordinator’s job is decision and synthesis, not execution. The prompt gives each tool a semantic boundary:

• Create worker: start a new independent task with no shared context. Suited for work that needs a clean context, like “build a new module” or “investigate another lead.”
• Send follow-up message: continue an existing worker through targeted delivery via its agent identifier. Suited for “add a constraint” or “fix the edge case from just now”—continuing rather than restarting lets the worker reuse the context it has already built and avoid redundant work.
• Stop worker: terminate tasks that have drifted from the goal, gotten stuck in a loop, or been superseded by a new approach. This one is often overlooked, but without it a single misdispatch keeps burning compute until it ends on its own.
• Subscribe to external events: listen for asynchronous signals such as pull request comments, review feedback, and build results from the code hosting platform. This lets the coordinator keep following external feedback after a task is delivered, forming a closed loop instead of ending once the submission is done.

6. Execution Policy: Goal Confirmation, Phase Division, and Progress Judgment

The execution methodology shown in the body of this prompt can be distilled into four steps.

Confirm the goal first. Align on the goal before dispatching: does the user want to “fix this error” or “refactor the whole module,” what is the acceptance criterion, and are there files that must not be touched? In a multi-agent architecture, a single dispatch is expensive (a full round of worker startup and context building), and the rework cost of a goal mismatch is far higher than asking a few more questions before starting. So goal confirmation is an investment, not a delay.

Phases are fixed as research → implement → verify. The order of the three phases cannot be swapped. The research phase produces facts (relevant files, call chains, constraints), the implementation phase produces changes, and the verification phase produces evidence (build passes, tests pass, behavior matches expectations). Writing it as fixed phases keeps the model from skipping straight to editing code, and from declaring completion the moment it finishes editing.

Progress is judged by outputs, not narration. The reliable signals for whether a worker is progressing normally are four: whether it has produced phase-level facts or file changes; whether it has given reproducible verification commands and results; whether there is substantive progress within message intervals (rather than repeating the same conclusion); and whether it has clearly reported blockers and the decisions needed. Narration like “working hard on the analysis” cannot count as evidence of progress.

Report blockers rather than guess. When a worker hits an ambiguity that requires a user decision (conflicting requirements, destructive changes, missing permissions or credentials), the correct action is to hand the problem back to the coordinator along with the options, and let the coordinator ask the user. This is far cheaper than letting a subprocess push hundreds of lines of code forward on a wrong assumption.

7. Context and Cost Engineering

Beyond behavioral constraints, these prompts usually come with supporting cost-control measures, which apply equally well when building your own:

• Summarize results: workers return only conclusions, key file paths, and verification evidence—not the full reasoning trace or raw logs.
• Truncate tool output: large file reads and long command outputs are truncated to a limit before returning, with the omission noted, to keep a single tool call from breaking through the window.
• Local retry of subtask failures: retries happen inside the worker; the coordinator only sees the final result, so intermediate failures do not repeatedly occupy the main context.
• Batch external events: high-frequency events (a run of consecutive review comments) are merged into a single wake-up rather than triggered one by one.

8. A Self-Build Checklist and Common Anti-Patterns

If you want to write a similar coordinator-layer prompt for your own agent system, build it in this order:

1. Write your identity, collaboration partners, and domain in one line, with no rhetoric.
2. List responsibilities, and explicitly state “do not delegate what you can answer directly.”
3. Declare that “every one of your outputs is for the user,” and that “subprocess output is an internal signal—do not respond to it, summarize for the user instead.”
4. Inject the worker capability list via a template variable, at the granularity of specific tools and reusable flows.
5. Add a “when not to use it” line for each coordinator tool.
6. Write research → implement → verify as fixed phases, and define the acceptance output for each.
7. Define progress criteria (outputs, verification evidence, blocker reporting), and make clear that narration does not count as progress.
8. Define termination conditions (completed, blocked and needs a decision, over budget, superseded by a new approach).

The anti-patterns to watch for are equally clear: putting the tool list before responsibilities, which causes over-dispatch; lacking a stop mechanism, so misdispatches cannot be reclaimed; not distinguishing internal signals from user-visible output, which makes agents exchange pleasantries and the context bloat fast; writing worker capabilities as a vague “you have strong capabilities,” which throws off dispatch decisions; and letting subprocesses directly run multi-step reusable flows, which dumps process noise back into the main context.

9. Conclusion

The value of this coordinator-layer prompt is not in its wording but in how it pre-solves, at the prompt level, the three things most likely to go wrong in a multi-agent system: when to do it yourself and when to hand it off (the anti-delegation principle and the capability list), where information flows (output directed only at the user, subprocess results treated as internal signals), and how to tell whether things are moving forward (fixed phase division and output-based criteria). Architecture sets the capability ceiling; the prompt determines whether that architecture can perform reliably—and the latter is often the part that gets the least investment for the highest return.