Multi-Agent Orchestration for AI Coding Agents

A coding agent orchestration workflow is useful when a feature crosses files, interfaces, and review steps that one session cannot safely hold at once. Imagine Claude Code implementing a saved-search API, Cursor building the screen, and Codex checking the integration. The useful question is not how many agents are running. It is whether each has a bounded assignment, the same current contract, a way to surface a blocked dependency, and a named human who decides when the feature is complete. This is an illustrative workflow, not a customer case study or a measured speed claim.

For the general meaning of agent orchestration, start with that overview. This guide follows one coding feature across three clients. The client connection guide covers setup in more detail; the steps here focus on what to hand off after each client connects.

First decide whether to split the work

Use one agent when the change is small, the same files must be edited in every step, or a single test gives quick feedback. A second agent adds briefs, branch integration, and another place for an assumption to drift. For a saved-search feature, splitting starts to help when API, screen, and verification can be described as separate outputs. If the API shape is still unknown, resolve that interface before asking the screen agent to implement against a guess. Parallelize independent work; sequence dependent work.

Claude Code documents subagents with their own context and permissions within a session. They can handle a bounded side task, but that alone does not establish a shared project record across Claude Code, Cursor, and Codex. The Claude Code subagents guide explains when that in-session delegation is enough. Cursor's project rules can keep repo instructions in version-controlled .cursor/rules; rules tell an agent how to work, while the feature ticket records what is currently agreed. This distinction matters after a session restarts or the API contract changes.

Put the shared brief in one place

For this example, the human lead writes one feature brief: a signed-in user can save a search, list saved searches, and delete one they own. Define the accepted result: the saved list survives a reload; a second user cannot see or delete the first user's entries; an unauthorized request fails; and the screen handles loading and errors. The lead names three deliverables: backend route plus tests, UI plus a real interaction check, and integration review. This is the shared contract, not an invitation for three agents to each redesign the feature.

AppHandoff's current MCP endpoint is https://api.apphandoff.com/mcp. The current connection guide explains setup; its current server catalogue has bootstrap, get, find, read_skill, ticket, plan, message, project, and decide_lifecycle_proposal. The last is a signed-in human approval action and may be absent from a client's tool list without approval-card support. The MCP server page is the product entry point. Read the connected server's tool help and rules before writing; examples here describe a workflow, not a frozen tool schema.

Claude Code: claude mcp add --transport http apphandoff https://api.apphandoff.com/mcp
Codex:      codex mcp add apphandoff --url https://api.apphandoff.com/mcp
Cursor:     .cursor/mcp.json -> {"mcpServers":{"apphandoff":{"url":"https://api.apphandoff.com/mcp"}}}

Each client authenticates with its own account and resolves the intended project. Start with bootstrap; if the account can access several projects, confirm which one the human meant. Then use get for the full feature ticket and find to see nearby work. A find card is a summary, so read the ticket body, tasks, decisions, and contract before editing. The live server rules, reachable through get on $rules, determine the allowed write and required fields. This order is documented in the repo's MCP getting-started guide.

Name ownership before opening editors

The lead gives Claude Code the API route, authorization checks, and route tests. Cursor gets the screen and its interaction test. Codex gets the integration review and any named regression it can add without rewriting the other two lanes. A brief lists expected files or directories, its acceptance checks, the commit or branch it starts from, and what evidence to return. Paths are an early conflict check: AppHandoff's find supports a paths filter for overlapping open work, and a ticket claim records a live lease. A lease flags ticket ownership; it is not a filesystem lock or a guarantee of conflict-free merges.

Concurrent writers get separate Git worktrees and branches. Git's worktree documentation describes linked working trees attached to one repository. Each agent can run its own checks and produce a reviewable diff without overwriting another agent's uncommitted files. The lead still needs to compare changes against the current base, resolve conflicts, and test the integrated result. A worktree separates files on disk; it does not reconcile two incompatible API assumptions.

Publish the API boundary before the screen depends on it

The backend brief gives the contract a concrete shape: POST /saved-searches accepts a search query and returns an ID plus its normalized query; GET /saved-searches returns the signed-in user's entries; DELETE /saved-searches/:id returns a defined success response. The exact paths are illustrative. The lead also names error cases, such as missing authentication, invalid query, and deleting an entry owned by another user. Record the chosen fields and error behavior on the feature ticket through the supported contract action after checking the live tool help.

Now Claude Code can implement the backend lane. It claims its ticket, checks for overlapping paths, and builds only its assigned route and tests. It returns the changed files, test command and result, commit or diff reference, and any deviation from the agreed contract. If it discovers that the database shape cannot support the request safely, it records the blocker and stops at the boundary. The lead decides whether to amend the contract and re-brief the UI lane. A confident status sentence without a test result or a specific blocker is not useful handoff evidence.

Cursor can start independent screen layout work while the backend tests run, provided its brief explicitly says which assumptions are provisional. Before wiring network behavior, it re-reads the ticket's published contract rather than relying on an earlier chat summary. If the backend changes query to searchText, the backend owner updates the shared contract and names the affected UI task. Cursor acknowledges the new shape, changes its request code, and records what it tested. A ticket message can carry the question and answer; direct cross-client messaging is not required for this asynchronous handoff.

A handoff from this saved-search example should be short enough for the next lane to check. The following specimen is illustrative, including its test line; replace placeholders with the actual revision, command, result, and changed artifact before anyone uses it as proof.

Saved-search API → screen handoff (illustrative)
Scope: backend POST, GET, DELETE /saved-searches; UI owner owns the screen
Contract revision: [ticket contract revision/link]; query field and auth errors
Changed artifact: [backend commit or diff + route/test links]
Check: [exact command] → [observed pass/fail and environment]
Blocker: [none observed, or failing case and owner]; UI must not infer unknown fields
Next owner: Cursor screen lane; re-read contract, wire request, test save/reload
Integration owner: Codex; verify cross-account denial after both lanes land

Sequence verification after both sides exist

Codex starts the integration lane against the merged candidate or another explicitly identified integration branch. Its brief asks for a narrow check of three things: the UI sends the published request, the API returns the published response, and authorization prevents another account's data from appearing. It reports the exact command, environment, observed result, and any unverified step. If the observed behavior differs from the contract, it files a reproducible blocker with the expected and actual shapes, then routes it to the owner of the broken boundary. It does not silently rewrite both lanes to make one test green.

A unit test that proves the route's authorization rule, a component test that proves the screen's error state, and a real interaction check that saves and reloads a search answer different questions. A passing unit suite alone does not prove the whole flow. The lead chooses the smallest checks that can disprove each acceptance condition and keeps the evidence attached to the work. In a Claude Code lane, Claude Code hooks can record bounded tool events as supporting evidence, though a log is not itself verification. The MCP-coordinated team example offers a broader process view; this example is deliberately limited to one feature.

Recover from stalls and stale state

If an agent stops mid-task, first inspect its diff and the ticket state. AppHandoff's ticket claims use time-limited leases and expose other live holders through the board. A new agent should re-read the latest ticket, contract, and working branch before continuing; it should not infer that a lease timeout means the partial code is safe to discard. Release or reassign ownership through the current rules, preserve the partial work, and give the replacement a brief naming what is complete, what failed, and the next proof needed.

If a write returns a stale revision, re-read the card and decide whether the intended change still applies. If a write timed out after being sent, retry with the same idempotency key rather than creating a duplicate. If the contract changed after Cursor built against it, stop integration until the backend and UI owners agree on one version. These are bounded recovery steps from AppHandoff's current write contract; they are more reliable than telling an agent to retry until it works.

Review and record the completion decision

The lead reviews the integrated diff and checks evidence against the acceptance conditions before recording completion. A PR body line such as Closes HO-123 parks that ticket in validation when the merge is recorded; the platform moves it to live after a deploy is recorded, or after the merge is confirmed on the default branch for a repo that reports no deploys. A bare ticket mention only links the merge. If proof is uncertain, leave the ticket in validation for a person to confirm or return for work. A signed-in human handles any lifecycle approval card; the agent cannot approve its own proposal. These are workflow rules, not a claim that this illustrative saved-search feature was merged or deployed.

This division gives each agent a useful job without pretending the agents share one context window. The ticket carries the current brief and evidence, the worktrees isolate concurrent edits, the contract orders dependent work, and the lead integrates the result. If one agent can carry the feature with less coordination, use one. If the handoffs matter, keep them explicit enough that a fresh session could continue from the ticket and the code without asking the previous agent what happened.