diff --git a/AGENTS.md b/AGENTS.md index b7f36fb38..0739c8193 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`. diff --git a/README.md b/README.md index 5fcf05d9d..281cb3767 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.md b/docs/README.md index 43c06876b..073951ec3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/status.md b/docs/STATUS.md similarity index 87% rename from docs/status.md rename to docs/STATUS.md index 70320e07b..13cbbd37b 100644 --- a/docs/status.md +++ b/docs/STATUS.md @@ -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). - - diff --git a/docs/stack.md b/docs/stack.md index afb59855f..a2b0e3e14 100644 --- a/docs/stack.md +++ b/docs/stack.md @@ -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.