bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: refocus README on the product, move progress to docs/STATUS.md (#311) 

* docs: refocus README on the product, move progress to docs/STATUS.md

Rework the README around what ReverbCode is and does, drawing the
agent/runtime/tracker framing and the "how it works" flow from the legacy
agent-orchestrator README but stating only what the rewrite's code actually
implements (zellij runtime, GitHub SCM/tracker, 23 verified agent adapters,
port/adapter extensibility surface).

Move progress tracking out of the README: rename docs/status.md to
docs/STATUS.md, reconcile the README's "Status and roadmap" content into it
(SCM observer issue refs, milestone link), correct the adapter count to 23,
and drop the stray trailing markup. Update the README, AGENTS.md, docs/README.md,
and docs/stack.md references accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: format with prettier [skip ci]

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Harshit Singh Bhandari 2026-06-18 15:43:41 +05:30 committed by GitHub
parent b06ea39103
commit dd3faa7357
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 86 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@ -46,7 +46,7 @@ npm run build
- `README.md` — current run/config/test quickstart.
- `docs/README.md` — docs index.
- `docs/architecture.md` — backend mental model, package layout, lifecycle/session/service boundaries, and load-bearing rules.
- `docs/status.md` — what is shipped on `main` today and what is still in flight.
- `docs/STATUS.md` — what is shipped on `main` today and what is still in flight.
- `docs/cli/README.md` — intended CLI shape: thin Cobra client over daemon HTTP, never direct storage/runtime access.
- `docs/agent/README.md` — agent adapter contract and hook behavior.
- `CLAUDE.md` — compatibility pointer for Claude Code; it directs agents back to `AGENTS.md`.

114
README.md
View File

@ -1,36 +1,80 @@
# ReverbCode
A Go-backed agent orchestration daemon for supervising parallel coding-agent
sessions, with an `ao` CLI today and an Electron supervisor planned. The Go
module and packages remain `agent-orchestrator`; "ReverbCode" is the public name.
The orchestration layer for parallel AI coding agents. ReverbCode is a
Go-backed daemon that supervises many coding-agent sessions at once, each in
its own `git worktree`, and routes the feedback they need (CI failures, review
comments, merge conflicts) back to the right agent automatically. It ships with
an `ao` CLI and an Electron supervisor that both drive the same daemon over
loopback.
The Go module and packages remain `agent-orchestrator`; "ReverbCode" is the
public name.
See [`docs/architecture.md`](docs/architecture.md) for the backend mental model
and [`AGENTS.md`](AGENTS.md) for the contributor / worker contract.
and [`AGENTS.md`](AGENTS.md) for the contributor / worker contract. For current
progress (what's shipped vs. in flight) see [`docs/STATUS.md`](docs/STATUS.md).
## What's shipped today
## What it does
- Loopback-only HTTP daemon (`backend/internal/httpd`) controlling projects,
sessions, orchestrators, and hook callbacks over `127.0.0.1`.
- `ao` Cobra CLI (`backend/cmd/ao`) — a thin client over the daemon for daemon
control, project/session/orchestrator management, and worker spawning.
- Worker/orchestrator spawn into isolated `git worktree` workspaces, launched
inside a `zellij` runtime adapter.
- Live per-PR observation via the provider-neutral SCM observer
(`backend/internal/observe/scm/`): polling loop, ETag guards, semantic
diffing, CI/check/review-thread tracking, and lifecycle nudges for CI
failures, review feedback, and merge conflicts.
- A 20+ agent adapter platform under `backend/internal/adapters/agent/`
(`claude-code`, `codex`, `cursor`, `opencode`, `aider`, `amp`, `goose`,
`copilot`, `grok`, `qwen`, `kimi`, `crush`, `cline`, `droid`, and more),
registered through a shared registry with common activity-dispatch / hook
utilities.
- SQLite store (`backend/internal/storage/sqlite/`) with sqlc-generated
queries, DB-triggered change-data-capture into `change_log`, and a CDC
poller/broadcaster (`backend/internal/cdc/`) feeding in-process subscribers
- **Agent-agnostic.** A 23-adapter platform under
`backend/internal/adapters/agent/` (`claude-code`, `codex`, `cursor`,
`opencode`, `aider`, `amp`, `goose`, `copilot`, `grok`, `qwen`, `kimi`,
`crush`, `cline`, `droid`, `devin`, `auggie`, `continue`, `kiro`, `kilocode`,
and more), registered through a shared registry with common
activity-dispatch / hook utilities. The default is set by `AO_AGENT`.
- **Isolated workspaces.** Worker and orchestrator sessions spawn into their own
`git worktree` (`backend/internal/adapters/workspace/gitworktree/`), launched
inside a `zellij` runtime adapter (`backend/internal/adapters/runtime/`) so
every session has its own attachable terminal.
- **Live PR observation.** The provider-neutral SCM observer
(`backend/internal/observe/scm/`) polls each session's PR with ETag guards and
semantic diffing, tracking CI/check runs and review threads, and feeds those
facts into the lifecycle manager, which sends the owning agent nudges for CI
failures, review feedback, and merge conflicts. GitHub is the implemented
provider today.
- **Durable facts, derived status.** The SQLite store
(`backend/internal/storage/sqlite/`) persists a small set of session facts
plus PR/check/comment rows; display status is computed at read time, never
stored. DB triggers append every user-visible change to `change_log`, and a
CDC poller/broadcaster (`backend/internal/cdc/`) feeds in-process subscribers
and an SSE replay endpoint.
- Session lifecycle manager + reaper (`backend/internal/lifecycle/`,
`backend/internal/observe/reaper/`): runtime/activity/PR facts reduced into
the small durable session state, display status derived at read time.
- **Loopback-only daemon.** The HTTP daemon (`backend/internal/httpd`) controls
projects, sessions, orchestrators, and hook callbacks over `127.0.0.1` with no
auth, CORS, or TLS by design.
- **Lifecycle manager + reaper** (`backend/internal/lifecycle/`,
`backend/internal/observe/reaper/`) reduce runtime/activity/PR observations
into the durable session state and reclaim dead sessions.
## How it works
1. Register a local git repo as a project (`ao project add`).
2. Spawn a worker session (`ao spawn`), or an orchestrator that fans work out
across sessions. Each session gets its own `git worktree` and a `zellij`
pane.
3. The agent develops, tests, and opens a PR from inside its worktree.
4. The SCM observer watches that PR and routes feedback back to the agent: a CI
failure, a requested change, or a merge conflict becomes a nudge to the agent
that owns the PR.
5. You inspect, attach a terminal, and merge from the CLI or the Electron app;
human attention is needed only where the loop can't resolve on its own.
## Extensibility
The backend is organized around inbound/outbound port contracts
(`backend/internal/ports/`) with swappable adapters under
`backend/internal/adapters/`:
| Port | Implemented adapters |
| --------- | --------------------------------------------- |
| Agent | 23 harnesses (see above) |
| Runtime | `zellij` |
| Workspace | `git worktree` |
| SCM | GitHub |
| Tracker | GitHub (adapter present; no runtime loop yet) |
| Reviewer | `claude-code` |
| Notifier | port defined; no shipped adapter yet |
See [`docs/STATUS.md`](docs/STATUS.md) for which lanes are live at runtime.
## Quick start
@ -161,20 +205,10 @@ touching the daemon API surface (`npm run sqlc`, `npm run api`).
## Status and roadmap
Current `main` ships the CLI surface above, the SCM observer end-to-end
(issues [#75](https://github.com/aoagents/agent-orchestrator/issues/75),
[#108](https://github.com/aoagents/agent-orchestrator/issues/108),
[#109](https://github.com/aoagents/agent-orchestrator/issues/109)), the agent
adapter platform, and the CDC pipeline with SSE replay. The Tracker observer
([#112](https://github.com/aoagents/agent-orchestrator/issues/112)) and live
`pr_*` event consumers ([#110](https://github.com/aoagents/agent-orchestrator/issues/110))
are in flight. The Electron + React supervisor under `frontend/` is real and
wired to the daemon over the generated typed client (projects/sessions board,
session view, terminal pane, pull-requests page); all daemon logic stays in the
Go backend.
Tracking milestone:
[`rewrite`](https://github.com/aoagents/agent-orchestrator/milestone/1) on GitHub.
Progress tracking lives in [`docs/STATUS.md`](docs/STATUS.md): what is shipped
on `main` today, what is still in flight, and the linked
[`rewrite`](https://github.com/aoagents/agent-orchestrator/milestone/1)
milestone on GitHub.
## Contributing

2
docs/README.md
View File

@ -16,7 +16,7 @@ Start with [architecture.md](architecture.md) for the current backend model and
| [backend-code-structure.md](backend-code-structure.md) | Package ownership rules for the Go backend: domain, services, ports, adapters, storage, HTTP, CLI, and daemon wiring. |
| [cli/README.md](cli/README.md) | CLI commands and daemon control surface. |
| [agent/README.md](agent/README.md) | Agent adapter contract, hook methodology, and session-info derivation. |
| [status.md](status.md) | What is shipped on `main` today and what is still in flight. |
| [STATUS.md](STATUS.md) | What is shipped on `main` today and what is still in flight. |
| [stack.md](stack.md) | Accepted library/runtime choices, pending stack decisions, and dependencies explicitly avoided for V1. |
## Mental model

13
docs/status.md → docs/STATUS.md
View File

@ -5,6 +5,10 @@ Electron/React frontend both drive a live daemon over HTTP/SSE/WebSocket. The
core GitHub flow works end-to-end: add project → spawn session/orchestrator →
attach terminal → observe PR → merge.
This file tracks progress. For what the product _is_ and how to run it, see the
top-level [`README.md`](../README.md); for the backend mental model see
[`architecture.md`](architecture.md).
## Build & test
The local gate is the backend Go build and race-enabled test suite:
@ -39,10 +43,13 @@ surface (`npm run sqlc`, `npm run api`).
- SCM observer (`internal/observe/scm`) wired into the daemon: GitHub provider,
lazy/non-blocking auth, per-PR polling with ETag guards and semantic diffing,
feeding PR facts into lifecycle, which sends agent nudges for CI failures,
review feedback, and merge conflicts.
review feedback, and merge conflicts
([#75](https://github.com/aoagents/agent-orchestrator/issues/75),
[#108](https://github.com/aoagents/agent-orchestrator/issues/108),
[#109](https://github.com/aoagents/agent-orchestrator/issues/109)).
- Terminal mux over WebSocket (`/mux`): per-client `zellij attach` PTY.
- Lifecycle reducer plus reaper (`internal/observe/reaper`).
- Agent adapter platform under `internal/adapters/agent/` (20+ adapters) with a
- Agent adapter platform under `internal/adapters/agent/` (23 adapters) with a
registry and `ao hooks` activity dispatch.
- OpenAPI spec generated from Go DTOs; frontend TS types generated from it and
drift-checked in CI.
@ -76,5 +83,3 @@ surface (`npm run sqlc`, `npm run api`).
Tracking milestone:
[`rewrite`](https://github.com/aoagents/agent-orchestrator/milestone/1).
</content>
</invoke>

2
docs/stack.md
View File

@ -1,7 +1,7 @@
# AO technical stack
This is the source of truth for library and runtime choices in the AO rewrite.
Keep this document about durable technology decisions; use `status.md` for
Keep this document about durable technology decisions; use `STATUS.md` for
implementation progress and `architecture.md` for component behavior and
invariants.