Writing

Designing an AI Coding Agent Orchestration Plan

2026-09-18

AI coding agents are now table stakes, but multi-agent setups mostly fail in the same boring ways: unclear goals, no responsibility boundaries, and no checkpoints. You get more output, not more progress.

This tutorial walks through a concrete way to design an AI coding agent orchestration plan for a new project before you spin up a single session. It’s a companion to the broader piece, AI coding agent orchestration: the complete guide for multi-agent development (read that for the theory; use this for the how).

Prerequisites

Before you start, you should already:

Use at least one coding agent daily (Claude, Cursor, Copilot, etc.).
Be comfortable running agents from the terminal or IDE.
Have a rough product requirement for a new feature or service.

You’ll need:

A git repo (or a new one) for the project.
Your preferred coding agents installed.
A text file in the repo where you’ll keep the orchestration plan, e.g. AGENTS.md or orchestration-plan.md.

If you’re already juggling several sessions, a manager like Maxxwell (agent-of-agents) gives you fleet visibility and a single orchestrator seat, but the planning steps here still apply if you’re orchestrating by hand with tmux.

Step 1: Translate product requirements into agent-friendly goals

Start from the product requirement, not from “let’s use three agents”. You want goals that a non-human collaborator can follow.

1.1 Write a constraints-aware requirement

Take the product spec and compress it into:

Goal: what outcome matters.
Context: what exists already.
Constraints: what cannot break.
Done when: what observable condition means “ship”.

Example requirement for a new feature:

Feature: API for project-level todos

Goal:
  Provide a REST API that lets users create, list, update, and delete
  todos scoped to a project.

Context:
  - Monolith: Django 5 app with DRF.
  - Auth: JWT-based, existing decorator `@require_auth`.
  - Existing models: User, Project.

Constraints:
  - Must not break existing /api/user/* endpoints.
  - Response times <= 200ms P95 under current traffic.
  - Tests required for all new endpoints.

Done when:
  - New /api/projects/:id/todos/ endpoints implemented.
  - Tests passing in CI.
  - Basic OpenAPI docs generated.

This matches OpenAI’s Goal/Context/Constraints/Done pattern and gives any agent a stable north star.

1.2 Break into coherent agent goals

Now slice that into 2-4 independent goals suitable for separate agents. Each job should be:

Narrow enough for a single plan.
Testable.
Runnable in parallel without excessive coupling.

Continuing the example:

G1: Design and stub the /api/projects/:id/todos/ schema and routes.
G2: Implement Django models + serializers + views for project todos.
G3: Add integration and performance tests around todo endpoints.
G4: Generate and validate OpenAPI documentation.

These are your high-level agent goals.

Write them at the top of AGENTS.md.

Step 2: Define agent roles and responsibilities

Anthropic, Microsoft, and OpenAI all say the same thing in different words: only add agents where separation of concerns helps. That means defining roles like a real team.

2.1 Create an agent responsibility matrix

In AGENTS.md, draft a simple table mapping goals → roles → responsibilities → outputs.

Example template:

## Agent responsibility matrix

| Role ID | Name                | Primary goals | Responsibilities                                      | Must produce                    |
|--------|---------------------|---------------|-------------------------------------------------------|---------------------------------|
| A1     | API Architect Agent | G1            | Design routes, request/response schema, error model  | ADR, route stubs               |
| A2     | Backend Dev Agent   | G2            | Implement models, views, serializers, migrations     | Code, migrations, unit tests    |
| A3     | Test Engineer Agent | G3            | Integration tests, perf baseline, regression checks  | Test suite, perf report         |
| A4     | Docs Agent          | G4            | Generate OpenAPI, ensure examples, doc review points | OpenAPI spec, README section    |

This is your agent responsibility matrix template. Copy/paste it per feature and adjust roles instead of improvising in the moment.

2.2 Choose the smallest viable team

Anthropic reports that multi-agent systems often burn 3-10× more tokens than single-agent setups. So default to fewer roles:

Merge roles when the cost of coordination outweighs specialization.
Split roles when the outputs are clearly different artifacts (e.g. tests vs docs).

In a small project you might only keep A1-A3 and fold docs into A1.

2.3 Write per-role prompts and boundaries

For each role, add a short, pinned brief that can be reused across sessions.

Example for A2 Backend Dev Agent:

### A2 Backend Dev Agent brief

You are the Backend Dev Agent for the project.

Scope:
- Implement Django models, serializers, views, and migrations for todos.
- Follow direction from A1's API design document.
- Coordinate with A3 by providing fixtures and test hooks.

Out of scope:
- Changing the overall API contract without A1.
- Modifying auth beyond using `@require_auth`.
- Editing CI workflows.

Definition of done:
- New code passes `pytest` and `mypy`.
- New endpoints behave as described in A1's ADR.

This becomes the system prompt or initial context you feed to your coding agent when you spin up the session.

Step 3: Plan the workflow and checkpoints before code

DORA’s 2025 research is blunt: AI amplifies the quality of your workflow. If you don’t define checkpoints, agents happily run off a cliff.

3.1 Define lifecycle stages and gates

Write down the stages work will pass through, with hard gates where a human or orchestrator must sign off.

Simple multi-agent lifecycle template:

Stage 0: Plan
  - A1 drafts API design ADR + endpoint list.
  - Orchestrator reviews and approves.

Stage 1: Implement
  - A2 implements models/views per ADR.
  - A3 starts basic integration tests in parallel.

Stage 2: Validate
  - A3 expands tests, runs perf checks.
  - A4 generates OpenAPI spec.

Stage 3: Review
  - Orchestrator reviews code, tests, docs.
  - Only then merge to main.

This gives you explicit agent orchestration checkpoints and handoffs.

3.2 Mark human-in-the-loop checkpoints

OpenAI’s guardrails docs distinguish automatic runs from human approval steps. Do the same:

Checkpoints:

C1 (human): Approve A1 API design ADR before any implementation.
C2 (human): Approve A2 PR to feature branch before perf tests.
C3 (human): Approve A3 test coverage + perf report before merge.
C4 (human): Approve A4 docs before public release.

Anything not explicitly gated can run concurrently.

3.3 Decide what orchestrator vs workers handle

OpenAI’s orchestration guidance separates manager-in-control vs specialist-takes-over. For coding agents:

Orchestrator (manager) handles:
- Task slicing.
- Assigning goals.
- Comparing outputs across agents.
- Reporting what landed vs what is waiting on you.
Worker agents (specialists) handle:
- Implementing within their role.
- Asking for clarification at checkpoints.

If you’re using Maxxwell, the orchestrator is itself a real coding-agent session with this brief, and each worker is a normal agent session attached to your existing tools. Controls draft instructions to workers into a composer instead of firing them automatically, so you stay the one who presses enter.

Step 4: Specify session statuses and drift detection signals

With multiple agents, the next failure mode is “I can’t tell which is stuck, which is idle, and which is building the wrong thing”. Most vendors now explicitly recommend surfacing status.

4.1 Define a status vocabulary

Even if you’re doing this by hand, agree with yourself on a small set of states.

A practical set:

not_started
working
idle
waiting_on_you
blocked
needs_sign_in
done
dead
not_heard_from

You can also add a “possibly_stalled” overlay when you haven’t seen output for N minutes.

In Maxxwell, this is baked in as per-session labels in one window; in tmux you can simulate it with suffixes in pane titles or comments in AGENTS.md.

4.2 Define drift indicators

You don’t want automatic corrections (they’re brittle), but you do want clear, observable signs something is off:

Agent editing files outside its declared scope.
Plans or ADRs that add new goals not in the requirement.
Repeated errors (e.g. failing tests, 500s) with no adaptation.
Long runs (>10-15 minutes) with no human-visible artifacts.

Write drift rules as simple checks:

Drift checks:
- File paths modified must match agent's scope.
- API routes must match G1 ADR.
- Any new cross-cutting concerns (caching, auth changes) require C1 review.

This is manual drift detection. Some orchestration platforms promise automatic drift correction; this guide assumes you’re the one making course corrections.

4.3 Add context-pressure expectations

Anthropic calls out context management as the core constraint. For each agent, define what happens when context gets too big:

When to summarize.
When to truncate logs.
When to start a new session.

If you use Maxxwell, you get a live context pressure readout with tiered warnings and a one-click compact operation, but it still waits for you to decide when to compact or restart.

Step 5: Build a reusable multi-agent workflow template

At this point you’ve got goals, roles, checkpoints, and statuses. Now turn that into a template you can drop into new repos.

5.1 Orchestration template skeleton

Here’s a practical AGENTS.md template you can adapt.

# AI Agent Orchestration Plan

## 1. Feature / Project

- Name: <short name>
- Goal: <single-sentence outcome>
- Context:
  - Tech stack:
  - Existing systems:
  - Constraints:
- Done when:
  - [ ] Condition 1
  - [ ] Condition 2

## 2. Agent Goals

- G1: ...
- G2: ...
- G3: ...

## 3. Roles and Responsibilities

| Role ID | Name      | Primary goals | Responsibilities             | Must produce           |
|--------|-----------|---------------|------------------------------|------------------------|
| A1     |           |               |                              |                        |
| A2     |           |               |                              |                        |

### 3.1 Role Briefs

#### A1 <Role name>

Scope:
- ...

Out of scope:
- ...

Definition of done:
- ...

#### A2 <Role name>

...

## 4. Workflow and Checkpoints

Stages:

Stage 0: Plan
- ...

Stage 1: Implement
- ...

Checkpoints:
- C1 (human): ...
- C2 (human): ...

## 5. Status and Drift Rules

Status states:
- not_started, working, idle, waiting_on_you, blocked,
  needs_sign_in, done, dead, not_heard_from

Drift checks:
- ...

Context rules:
- Summarize when conversation > N tokens.
- Start new session when ...

## 6. Orchestrator Notes

- Orchestrator role: <who/what>
- Tools: <Maxxwell / tmux / IDE>
- Reporting:
  - What landed:
  - What is waiting on you:

Drop this file into each new project. Over time you’ll tweak it to match your team’s patterns.

5.2 Align with repo-level guidance

OpenAI recommends an AGENTS.md plus PLANS.md per complex feature. You can either:

Put the orchestration template in AGENTS.md and link to feature-specific plans.
Or create per-feature docs/feature-X-agents.md that follow the same structure.

The important part is that your agent orchestration plan lives in the repo alongside code, not in somebody’s head.

Step 6: Connect the plan to real sessions

The plan only matters if it drives how you actually run agents.

6.1 Spin up sessions per role

For each role in the matrix, create a real agent session and feed it the relevant brief.

Example using a generic CLI agent:

# API Architect Agent
ai-agent --session A1-api-architect \
  --system "You are A1 API Architect Agent. Use AGENTS.md and ADR-001 as truth." \
  --context AGENTS.md ADR-001.md

# Backend Dev Agent
ai-agent --session A2-backend-dev \
  --system "You are A2 Backend Dev Agent. Only change backend code under backend/." \
  --context AGENTS.md

Name sessions by role ID to align with the plan.

In Maxxwell, you’d:

Start an orchestrator seat from the feature brief.
Add worker seats for each role, pointing at your existing Claude/Codex/Cursor sessions.
Use the orchestrator to draft commands/instructions for workers, then hit enter when you agree.

6.2 Track status in one place

You need a single place where you can see which agents are:

Working.
Idle.
Waiting on you.
Blocked.

If you’re DIY:

Update AGENTS.md statuses manually.
Or add a simple status script that prints a small table from a YAML/JSON file.

If you’re using Maxxwell:

Each session shows status (working, idle, waiting on you, etc.) in one window.
Quitting the app detaches from sessions instead of killing them, so long-running jobs outlive the UI.

Either way, the goal is that you can answer in under 10 seconds: “Which sessions are stuck, which are progressing, and which need my decision?”

6.3 Run return reports

At the end of a work block, have the orchestrator (or yourself) write a short return report:

## Return report - 2026-09-01

What landed:
- A2: Implemented project todo models and views; tests green.
- A3: Added basic integration tests; perf baseline at 180ms P95.

Waiting on you:
- C1: Approve A1 ADR changes to error model.
- C3: Decide on cache strategy for /todos endpoints.

Risks:
- Context nearing window for A2; consider summarizing.
- A3 flagged flaky test on CI; needs attention.

This separates “done” from “needs approval” and avoids the classic failure where a background agent quietly builds the wrong thing for 20 minutes.

FAQ: Designing AI coding agent orchestration

How many agents should I start with on a new project?

Start with one agent plus a human orchestrator. Only add more when you hit a real bottleneck like context pollution or long-running background tasks. Anthropic’s guidance and data show multi-agent systems often cost 3-10× more tokens; you want that overhead only when it buys real throughput.

How do I prevent agents from building the wrong thing?

Use explicit goals and checkpoints:

Pin a short, stable Goal/Context/Constraints/Done spec.
Require a design artifact (ADR, plan) before implementation.
Add human checkpoints (C1/C2/C3) where changes cross boundaries.
Define drift rules so you can spot when an agent edits outside its scope.

This is simpler and more reliable than trying to auto-correct drift in code.

Do I need a dedicated “orchestrator” agent, or can I orchestrate manually?

You can orchestrate manually if you’re running 1-2 sessions. Past that, you become the bottleneck. A dedicated orchestrator agent (or a manager like Maxxwell’s orchestrator seat) helps by:

Tracking goals and checkpoints.
Drafting instructions for workers.
Summarizing what landed vs what needs your call.

But the orchestrator still reports to you. It drafts; you press enter.

How do I adapt this plan for an existing codebase?

Same steps, but:

Add more context about legacy systems and constraints.
Use the agent roles to wrap dangerous areas (e.g. DB migrations) in extra checkpoints.
Add drift rules specific to fragile modules.

You’re not changing the planning process, just feeding more context and more constraints into the same template.

Where should the orchestration plan live in my repo?

Put AGENTS.md at the repo root or inside docs/. Link to it from README.md. The plan should:

Version with code.
Be reviewed like code.
Be close enough that new contributors can find it in 1-2 clicks.

This is now part of your project’s architecture, not an optional side note.