https://github.com/binaryphile/agent-orchestration

Docs-first specification for multi-agent LLM coordination patterns: group lifecycle, scoped broadcast, external observation. Surface-agnostic; tmux-claude is the first surface implementation.
https://github.com/binaryphile/agent-orchestration

Last synced: 13 days ago
JSON representation

Docs-first specification for multi-agent LLM coordination patterns: group lifecycle, scoped broadcast, external observation. Surface-agnostic; tmux-claude is the first surface implementation.

• Host: GitHub
• URL: https://github.com/binaryphile/agent-orchestration
• Owner: binaryphile
• License: mit
• Created: 2026-06-02T04:27:37.000Z (20 days ago)
• Default Branch: main
• Last Pushed: 2026-06-02T04:50:44.000Z (20 days ago)
• Last Synced: 2026-06-02T06:25:27.660Z (20 days ago)
• Language: Shell
• Size: 14.6 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# agent-orchestration

A specification + reference implementation for multi-agent LLM

coordination patterns — group lifecycle, scoped broadcast, external

observation, and orchestrator-delegate dispatch — independent of the

surfaces those agents live in.

## What this is

When multiple LLM agents need to coordinate (a "swarm" working a

task, a pair-programming setup, a reviewer + implementer split, or

an orchestrator that dispatches isolated delegates to do focused

work), the coordination concerns are the same regardless of where

the agents live — tmux panes, IDE windows, headless runners, web

tabs. This project captures those concerns as Cockburn-shaped use

cases AND ships a reference implementation of the orchestrator-

delegate UCs that surface implementations and operators can use

directly.

## What this is NOT

- Not a framework (AutoGen, CrewAI, LangChain are frameworks)

- Not a transport (era is the transport)

- Not a surface implementation (tmux-claude is the first surface;

  this project's `bin/orchestrator` is a reference impl of the

  orchestrator-delegate UCs, not a surface)

This is the *contract layer* between surfaces and the agents they

host, plus a ready-to-use orchestrator for spawning isolated

delegates.

## Vocabulary (inherited where appropriate)

- **Coordination Group** — a named, dynamically-formed collection of

  agents with a scoped communication channel. (AutoGen-derived shape.)

- **Member** — an agent currently belonging to a Coordination Group.

- **Broadcast** — a message published to all current members of a

  Group; non-members do not receive it.

- **Orchestrator** — an automated process (typically itself an LLM

  agent) that forms, modifies, and dissolves Groups dynamically AND

  may dispatch isolated single-task delegates via UC6-UC8.

- **Delegate** — a sandboxed, single-task agent invoked by an

  Orchestrator to perform a unit of work in an isolated worktree;

  exits when its task is complete (UC6/UC7).

- **Swarm** — informal: a Coordination Group whose members are

  collaborating on a focused task.

## Status

- **Use cases**: 10 drafted (UC1-UC5 coordination groups inherited

  from tmux-claude; UC6-UC8 orchestrator-delegate added in cycle 1;

  UC12 orchestrator self-monitoring / watchdog added in cycle 2;

  UC13 operator-relocates-delegate-pane added in cycle 8). UC9-UC11

  in backlog.

- **Design**: Part 2 covers the orchestrator-delegate pattern.

  §1-§7 realize UC6-UC8 (cycle 1: identity model, delegate lifecycle,

  event schema, inbox subscribe, `claude -p` commit workaround,

  failure modes, concurrency posture). §8 realizes UC12 with CQRS

  event-sourcing framing (cycle 2: watchdog and wake handler

  protocol). Part 1 (coordination groups UC1-UC5) is a heading-only

  placeholder pending surface-implementation consumption.

- **Role pattern docs**: `docs/patterns/` houses per-role pattern

  docs. `orchestrator.md` ships in cycle 2 as the first instance

  (cycle-driving discipline, delegate dispatch, acceptance review,

  wake-handler protocol, correction-delegate policy, loopback

  decision criteria, substitutability framing). `developer.md`

  ships in cycle 6 (#27125) as the second instance — first

  delegate-role pattern doc; codified after cycle 5's successful

  end-to-end delegate dispatch (smoke commit f12691b) per cycle 4

  R1 grader's "codify after observing real delegate practice"

  framing. `grader.md` ships in cycle A1 (#27838) as the third

  instance — cross-vendor reviewer role (ChatGPT primary surface

  via chrome-devtools-mcp; wl-copy + paste fallback); codified

  after the cycle's own R1 dispatched via the MCP flow. Other

  roles (operator) get pattern docs as they earn first instance.

- **Reference implementation**: `bin/orchestrator` ships five

  subcommands. Cycle 1: `spawn` / `wait` / `topology` (UC6-UC8).

  Cycle 2: `listen` / `wake-check` (UC12). Cycle 3 fixed the

  spawn → watcher state-dir handoff race (#26830, design.md Part 2

  §2 "State-dir handoff invariant"). Cycle 5 dropped `dojo --isolate`

  from the dispatch path (#27332): `bin/orchestrator-watcher` invokes

  `claude -p` directly in the pre-created worktree on

  `orch-`; stdout+stderr captured to `delegate.log` via

  fd-3 redirect; commits persist via standard git. Cycle 5 subsumes

  cycle 4 (#26887). Cycle 8 adds the **tmux-pane dispatch variant**

  (#27678): when `$TMUX` is set, `cmd.spawn` dispatches via

  `tmux split-window -d` so the delegate's live output is visible in

  a new pane while operator focus stays on the original pane; bare

  cycle-5 path is the headless fallback (design.md Part 2 §2

  "Tmux-pane dispatch variant"). Subcommand count unchanged (5).

- **First surface**: tmux-claude consumes coordination-group UCs.

  Cycle 8's tmux-pane dispatch variant is the orchestrator's own

  attached-surface integration (independent of tmux-claude's Pane

  Command Interface, which remains for UC1-UC5 coordination groups).

## License

MIT.