{"id":50681402,"url":"https://github.com/binaryphile/agent-orchestration","last_synced_at":"2026-06-08T19:04:57.636Z","repository":{"id":361991435,"uuid":"1256766443","full_name":"binaryphile/agent-orchestration","owner":"binaryphile","description":"Docs-first specification for multi-agent LLM coordination patterns: group lifecycle, scoped broadcast, external observation. Surface-agnostic; tmux-claude is the first surface implementation.","archived":false,"fork":false,"pushed_at":"2026-06-02T04:50:44.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T06:25:27.660Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binaryphile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T04:27:37.000Z","updated_at":"2026-06-02T04:50:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/binaryphile/agent-orchestration","commit_stats":null,"previous_names":["binaryphile/agent-orchestration"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/binaryphile/agent-orchestration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryphile%2Fagent-orchestration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryphile%2Fagent-orchestration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryphile%2Fagent-orchestration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryphile%2Fagent-orchestration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binaryphile","download_url":"https://codeload.github.com/binaryphile/agent-orchestration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryphile%2Fagent-orchestration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34076051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T19:04:57.570Z","updated_at":"2026-06-08T19:04:57.629Z","avatar_url":"https://github.com/binaryphile.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-orchestration\n\nA specification + reference implementation for multi-agent LLM\ncoordination patterns — group lifecycle, scoped broadcast, external\nobservation, and orchestrator-delegate dispatch — independent of the\nsurfaces those agents live in.\n\n## What this is\n\nWhen multiple LLM agents need to coordinate (a \"swarm\" working a\ntask, a pair-programming setup, a reviewer + implementer split, or\nan orchestrator that dispatches isolated delegates to do focused\nwork), the coordination concerns are the same regardless of where\nthe agents live — tmux panes, IDE windows, headless runners, web\ntabs. This project captures those concerns as Cockburn-shaped use\ncases AND ships a reference implementation of the orchestrator-\ndelegate UCs that surface implementations and operators can use\ndirectly.\n\n## What this is NOT\n\n- Not a framework (AutoGen, CrewAI, LangChain are frameworks)\n- Not a transport (era is the transport)\n- Not a surface implementation (tmux-claude is the first surface;\n  this project's `bin/orchestrator` is a reference impl of the\n  orchestrator-delegate UCs, not a surface)\n\nThis is the *contract layer* between surfaces and the agents they\nhost, plus a ready-to-use orchestrator for spawning isolated\ndelegates.\n\n## Vocabulary (inherited where appropriate)\n\n- **Coordination Group** — a named, dynamically-formed collection of\n  agents with a scoped communication channel. (AutoGen-derived shape.)\n- **Member** — an agent currently belonging to a Coordination Group.\n- **Broadcast** — a message published to all current members of a\n  Group; non-members do not receive it.\n- **Orchestrator** — an automated process (typically itself an LLM\n  agent) that forms, modifies, and dissolves Groups dynamically AND\n  may dispatch isolated single-task delegates via UC6-UC8.\n- **Delegate** — a sandboxed, single-task agent invoked by an\n  Orchestrator to perform a unit of work in an isolated worktree;\n  exits when its task is complete (UC6/UC7).\n- **Swarm** — informal: a Coordination Group whose members are\n  collaborating on a focused task.\n\n## Status\n\n- **Use cases**: 10 drafted (UC1-UC5 coordination groups inherited\n  from tmux-claude; UC6-UC8 orchestrator-delegate added in cycle 1;\n  UC12 orchestrator self-monitoring / watchdog added in cycle 2;\n  UC13 operator-relocates-delegate-pane added in cycle 8). UC9-UC11\n  in backlog.\n- **Design**: Part 2 covers the orchestrator-delegate pattern.\n  §1-§7 realize UC6-UC8 (cycle 1: identity model, delegate lifecycle,\n  event schema, inbox subscribe, `claude -p` commit workaround,\n  failure modes, concurrency posture). §8 realizes UC12 with CQRS\n  event-sourcing framing (cycle 2: watchdog and wake handler\n  protocol). Part 1 (coordination groups UC1-UC5) is a heading-only\n  placeholder pending surface-implementation consumption.\n- **Role pattern docs**: `docs/patterns/` houses per-role pattern\n  docs. `orchestrator.md` ships in cycle 2 as the first instance\n  (cycle-driving discipline, delegate dispatch, acceptance review,\n  wake-handler protocol, correction-delegate policy, loopback\n  decision criteria, substitutability framing). `developer.md`\n  ships in cycle 6 (#27125) as the second instance — first\n  delegate-role pattern doc; codified after cycle 5's successful\n  end-to-end delegate dispatch (smoke commit f12691b) per cycle 4\n  R1 grader's \"codify after observing real delegate practice\"\n  framing. `grader.md` ships in cycle A1 (#27838) as the third\n  instance — cross-vendor reviewer role (ChatGPT primary surface\n  via chrome-devtools-mcp; wl-copy + paste fallback); codified\n  after the cycle's own R1 dispatched via the MCP flow. Other\n  roles (operator) get pattern docs as they earn first instance.\n- **Reference implementation**: `bin/orchestrator` ships five\n  subcommands. Cycle 1: `spawn` / `wait` / `topology` (UC6-UC8).\n  Cycle 2: `listen` / `wake-check` (UC12). Cycle 3 fixed the\n  spawn → watcher state-dir handoff race (#26830, design.md Part 2\n  §2 \"State-dir handoff invariant\"). Cycle 5 dropped `dojo --isolate`\n  from the dispatch path (#27332): `bin/orchestrator-watcher` invokes\n  `claude -p` directly in the pre-created worktree on\n  `orch-\u003claunch_token\u003e`; stdout+stderr captured to `delegate.log` via\n  fd-3 redirect; commits persist via standard git. Cycle 5 subsumes\n  cycle 4 (#26887). Cycle 8 adds the **tmux-pane dispatch variant**\n  (#27678): when `$TMUX` is set, `cmd.spawn` dispatches via\n  `tmux split-window -d` so the delegate's live output is visible in\n  a new pane while operator focus stays on the original pane; bare\n  cycle-5 path is the headless fallback (design.md Part 2 §2\n  \"Tmux-pane dispatch variant\"). Subcommand count unchanged (5).\n- **First surface**: tmux-claude consumes coordination-group UCs.\n  Cycle 8's tmux-pane dispatch variant is the orchestrator's own\n  attached-surface integration (independent of tmux-claude's Pane\n  Command Interface, which remains for UC1-UC5 coordination groups).\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryphile%2Fagent-orchestration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinaryphile%2Fagent-orchestration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryphile%2Fagent-orchestration/lists"}