# Multi-Agent Workflows *Patterns that work. Patterns that don't. How to compose Claude, Cursor, Gemini, Copilot, and humans into a team that ships.* ## Why This Exists Every prior page in this module documents a primitive. Collisions, zones, inboxes, knowledge, integrations. Primitives are necessary, and primitives are not sufficient. What the practitioner actually needs is a set of recipes — "if my team looks like X, the coordination shape should be Y." This page is those recipes. It captures the patterns the Aura team and early-adopter customers have converged on over the last year of multi-agent work, along with the anti-patterns that show up whenever someone tries to skip the substrate. > The single biggest determinant of whether a multi-agent team is productive is not which models it uses. It is whether it has a coordination culture. Sentinel gives you the tools to build that culture. The patterns below show what "built" looks like. ## Pattern 1: Claude Plans, Cursor Executes This is the most common and most immediately productive shape. Claude, with its stronger reasoning and its handover tooling, does the multi-file thinking. Cursor, sitting in the editor with the human, does the micro-execution. **Shape:** ```text Human starts feature in Claude Code. Claude calls aura_plan_discover, surfaces gray areas, waits for resolution. Claude calls aura_plan_lock and executes wave 1 (the structural work). Claude sends handoff to "cursor" kind via aura_sentinel_send. Human switches to Cursor; Cursor reads inbox, picks up the handoff. Cursor executes wave 2 (the inline polish, tests, UI wiring). Cursor calls aura_log_intent, commits. Hook verifies. ``` **Why it works:** The two agents play to their strengths. Claude is patient and structural; Cursor is fast and local. The handoff is a structured message with refs, not a prose summary, so Cursor gets exact AST-level context for where to pick up. **Requires:** CLAUDE.md and `.cursorrules` both present and up to date. Inbox notifications visible in Cursor. A human who is willing to switch clients mid-feature. ## Pattern 2: Gemini Expedition, Claude Reviews Send Gemini on a large read-heavy or batch-heavy task. When it returns with a diff, have Claude review it semantically before merge. **Shape:** ```text Gemini takes "migrate src/legacy/** from Flask to FastAPI". Gemini claims zone, runs discovery, produces 40-file diff. Gemini logs aggregated intent, opens a PR. Claude, in a separate session, runs aura_pr_review on the PR branch. Claude posts findings as inbox messages to Gemini's session (or as PR comments if the Gemini session is already closed). Human decides merge. ``` **Why it works:** Gemini's long context is perfect for the expedition. Claude's review instincts are better than Gemini's on large diffs. The two agents never edit the same code; the handoff is fully asynchronous through the PR. **Requires:** Discipline about zone claims on Gemini's side. A Claude session that knows to watch for Gemini PRs. ## Pattern 3: Swarm on a Feature A single feature too large for one session. Split it into disjoint sub-tasks, assign each sub-task to a separate agent session, coordinate through the Sentinel. **Shape:** ```text Human uses aura_plan_discover to produce the plan. Plan is explicitly decomposed into disjoint zones: wave 1 → src/api/** (claude-A) wave 2 → src/ui/** (cursor) wave 3 → tests/** (claude-B) wave 4 → docs/** (gemini) Each agent claims its zone (block mode) and executes its wave. Agents coordinate edge-cases via aura_sentinel_send ("my API change affects your UI call site, see commit X"). ``` **Why it works:** Zone claims make the disjointness enforceable. The shared knowledge base ensures each agent has the context it needs. The inbox handles the inevitable cross-cutting concerns. **Requires:** A plan clean enough that the zones really are disjoint. This is the failure mode — if the zones overlap, the swarm becomes a traffic jam. ## Pattern 4: Human-Plus-Agent Pair Programming The classic. One human, one Claude or Cursor session. The agent is fully in Aura's protocol; the human works normally. The difference from non-Aura pair programming is that the agent's tool calls give the human continuous visibility into what the agent is doing and why. **Shape:** ```text Human opens Claude Code on the repo. Claude, per CLAUDE.md, runs aura_status → aura_live_impacts → aura_memory_read, presents the landscape. Human states goal. Claude runs aura_plan_discover. Plan lock happens in conversation with human. Each edit is preceded by aura_snapshot and followed by a short aura_log_intent call. Human commits; pre-commit hook verifies intent. ``` **Why it works:** The human never has to ask "what are you about to do?" — every tool call is visible. The protocol makes the agent legible. **Requires:** CLAUDE.md configured. Strict mode on. A human willing to read the agent's tool calls instead of just the chat. ## Pattern 5: Continuous PR Review Copilot (or any agent) produces PRs at volume. Aura runs server-side review on every PR and surfaces findings as comments. Humans act on the findings. **Shape:** ```text Copilot opens PR with auto-amended trailers. Aura webhook receives pull_request.opened. Aura runs pr-review, zone-check, intent-verification. Findings posted as a single PR comment. If a BLOCKED zone is crossed, merge gate fails. Human resolves — either dismissing findings, coordinating with zone owner, or pushing a fix. ``` **Why it works:** Even agents that cannot talk to Sentinel benefit from Sentinel's server-side layer. The PR becomes the coordination surface. **Requires:** GitHub App installed. Trailer action in place. Branch protection rules honoring Aura status checks. ## Pattern 6: Nightly Knowledge Harvest A scheduled agent session reviews the day's commits, inbox messages, and impact alerts, and promotes interesting signals to durable knowledge entries. **Shape:** ```text Cron at 02:00: start a Claude session. Claude runs aura_session_summarize for each day-old session. Claude reads the messages log for the past 24h. Claude proposes knowledge entries (not auto-writes) and posts them as an inbox broadcast to "team". Human or senior agent reviews entries in the morning and confirms via aura_memory_write. ``` **Why it works:** Useful knowledge tends to surface in messages ("Oh, right, that function is weird because X"). Without a harvest, it evaporates. With one, the team's memory compounds. **Requires:** Scheduled-agent capability (available via `aura schedule`). A human willing to do the morning review. ## Anti-Patterns The patterns above work. The ones below do not. Each has been seen in real teams and each has a failure mode worth remembering. ### Anti-Pattern: The Zone Grab One agent, usually Claude, claims zone `src/**` in block mode for eight hours on every session. Other agents are permanently locked out. The human on call gets tired of overriding and eventually disables zone enforcement. **Why it fails:** Zones are social contracts. Used as permanent moats, they train the team to ignore them. **Fix:** Node-level claims by default. Path claims only for the duration of a specific wave. TTLs bounded at one to two hours. ### Anti-Pattern: The Silent Fleet Four agents are technically registered. None of them has ever sent an inbox message. No knowledge entries are being written. The team is running four parallel monocultures. **Why it fails:** Coordination without communication is not coordination, it's cohabitation. The 26.86% conflict rate does not drop when the agents merely exist on the same substrate — it drops when they talk. **Fix:** Audit the message log weekly. If an agent session produced zero messages, zero knowledge entries, and zero zone claims, something is wrong with the protocol file. ### Anti-Pattern: The Prose-Only Inbox Agents send each other long prose descriptions instead of structured messages with refs. The inbox becomes a chat log nobody reads. **Why it fails:** Refs are what make messages actionable. A handoff without a commit ref or a node ref is just an email. **Fix:** Protocol files enforce ref attachment. Reject messages without refs at the Sentinel layer (planned for a future release; today the best enforcement is social). ### Anti-Pattern: The Rogue Agent One agent in the fleet does not have Aura wired up correctly. It edits without snapshots, commits without intent, crosses zones silently. Its edits get auto-synced and contaminate the shared state. **Why it fails:** Trust in the substrate is a property of the whole fleet. One rogue agent breaks it for everyone. **Fix:** `aura doctor --fleet` audits every recent commit for protocol compliance. Agents found non-compliant are quarantined (commits blocked at the hook layer) until their protocol file is fixed. ### Anti-Pattern: Ignore the Impact Alerts Cross-branch impact alerts pile up because nobody acknowledges them. Agents continue to edit functions whose contracts have shifted on other branches. Merges become minefields. **Why it fails:** Aura's impact system is a debt tracker. Unacknowledged debt is still debt. **Fix:** Treat the `aura_live_impacts` queue like an incident queue — zero at end of day is the target. Claude, Cursor, and Gemini all have protocol entries instructing them to clear impacts on session start. ### Anti-Pattern: The Planning Skip A team adopts Aura but continues to use Claude for small edits without running `aura_plan_discover`. Features touching eight files get half-implemented because the model never thought about the edges. **Why it fails:** Plan discovery is cheap; the rework when the plan is missing is expensive. **Fix:** CLAUDE.md has a clear threshold (three files) above which plan discovery is mandatory. Honor it. ## Putting It Together A team using Aura well, on a mixed fleet, on a normal day, looks like this: ```text 09:00 Gemini returns from overnight expedition with migration PR. 09:02 Aura posts server-side review on the PR. 09:10 Human reviews, merges, Sentinel records the merge. 09:30 Claude session opens for feature work. Runs status, impacts, knowledge query. Plans a 3-wave feature. 09:45 Claude executes wave 1, logs intent, commits. Auto-sync pushes nodes to Mothership. 10:00 Cursor session opens on a different human's machine. Picks up wave 2 handoff from Claude's message. Edits inline. 10:30 Copilot opens a small PR. Webhook runs review. No collisions. Clean merge. 11:15 Claude notes a gotcha, writes knowledge entry. Cursor queries knowledge later in the day, avoids a mistake. 14:00 Zone claim by Claude for a big refactor. Cursor gets warning, switches to a different task. 17:00 Day-end. All impact alerts cleared. Fleet idle. ``` Nothing dramatic. That's the goal. Coordination that is boring is coordination that works. > The success metric for Sentinel is not how many collisions it caught. It is how few collisions the team had left to catch. ## See Also - [The Sentinel Overview](/docs/lessons/sentinel-overview) — the conceptual foundation. - [Agent Collision Detection](/docs/lessons/agent-collision-detection) — the reactive layer. - [Zone Claims](/docs/lessons/zone-claims) — the preemptive layer. - [Agent Inbox](/docs/lessons/agent-inbox) — the conversation layer. - [Knowledge Sharing](/docs/lessons/knowledge-sharing) — the memory layer. - [Claude Code Integration](/docs/lessons/claude-code-integration), [Cursor Integration](/docs/lessons/cursor-integration), [Gemini CLI Integration](/docs/lessons/gemini-cli-integration), [Copilot Integration](/docs/lessons/copilot-integration) — the client-specific wiring.