@revisium/orchestrator 0.1.0-alpha.8 → 0.1.0

package/README.md

@@ -1,168 +1,188 @@
-# agent-orchestrator
+<div align="center">
 
-Local orchestrator for software-development tasks driven by short-lived AI agents (architect → developer →
-reviewer → integrator), hosted in **NestJS**. **DBOS** owns durable progress — execution is crash-safe and resumes
-from the first unfinished step — while **Revisium** owns meaning: roles, policy, inbox, events. Workflow-as-data is
-a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overview.md).
+# @revisium/orchestrator
 
-> 🚧 **Early alpha.** The end-to-end MVP works — create a run → plan gate → implement → review → PR → merge
-> gate — see [`docs/roadmap.md`](./docs/roadmap.md).
+Local-first orchestration for software-development work driven by short-lived agents.
 
-## Start here
+**Turn a task into a playbook-driven state machine.**
 
-- Repo context for agents: [`AGENTS.md`](./AGENTS.md)
-- Vision: [`docs/vision.md`](./docs/vision.md)
-- Architecture & invariants: [`docs/architecture-overview.md`](./docs/architecture-overview.md)
-- Docs index & roadmap: [`docs/README.md`](./docs/README.md) · [`docs/roadmap.md`](./docs/roadmap.md)
+[![License](https://img.shields.io/github/license/revisium/orchestrator?color=blue)](LICENSE)
+[![CI](https://github.com/revisium/orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/revisium/orchestrator/actions/workflows/ci.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=revisium_agent-orchestrator&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=revisium_agent-orchestrator)
+[![npm](https://img.shields.io/npm/v/@revisium/orchestrator?color=red)](https://www.npmjs.com/package/@revisium/orchestrator)
 
-## Local Development
+Part of the [Revisium](https://github.com/revisium/revisium) ecosystem.
 
-`revo` is one daemonized product. **`revo start`** brings up the whole stack — the standalone
-Revisium daemon plus the Revo host daemon that owns DBOS and serves the GraphQL + MCP front doors —
-and bootstraps the control-plane so it is ready to use. The CLI is lifecycle-only
-(`start` / `stop` / `status` / `restart` / `doctor` / `logs`); orchestration (runs, inbox, …) is
-reached over **MCP** (agents) or **GraphQL** (UI/scripts), both served by the daemon.
+</div>
 
-Run a source checkout alongside an installed package without collisions via a named **profile**
-(`--profile dev`, or `REVO_PROFILE=dev`): the `dev` profile shifts the whole port band off the
-`default` profile, so the two never share a port, data dir, or `dbos` database.
+```mermaid
+flowchart LR
+  task[Task]
+  playbook[Playbook]
+  machine[State machine]
+  outcome[Outcome]
 
-```sh
-pnpm install
-pnpm run revo -- start --profile dev    # standalone + host daemon, bootstrapped & ready
-pnpm run revo -- status --profile dev   # stack health summary
-pnpm run revo -- doctor --profile dev   # diagnose process / port / profile issues
-pnpm run revo -- logs --profile dev     # tail host + standalone logs; add -f to follow
-pnpm run revo -- restart --profile dev  # stop, then start
-pnpm run revo -- stop --profile dev
+  task --> playbook --> machine --> outcome
+
+  subgraph nodes[State machine nodes]
+    agent[Agent step] --> script[Script step] --> gate[Human gate] --> branch{Branch}
+    branch --> loop((Loop))
+    loop -. retry .-> agent
+    loop -. reroute .-> script
+  end
+
+  machine -. expands into .-> nodes
+  outcome --> pr[Pull request]
+  outcome --> evidence[Evidence]
+  outcome --> decisions[Decisions]
+  outcome --> history[Run history]
 ```
 
-| Knob | `default` (installed package) | `dev` (source checkout) |
-| --- | --- | --- |
-| data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
-| standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
-| Revo GraphQL | `19223` | `19623` |
-| DBOS database | `dbos` | `dbos_dev` |
+> Revo is in active development. The package is suitable for evaluation and local experimentation; do not treat
+> the public contract as stable yet.
+
+## Overview
 
-Any single knob can be overridden explicitly — `REVO_DATA_DIR` / `REVO_PORT` / `REVO_PG_PORT` /
-`REVO_GRAPHQL_PORT` / `REVO_DBOS_DB` — and an explicit env var always wins over the profile band.
+Revo is a local control plane for agentic work. A caller creates a run, Revo selects a playbook, and the playbook
+executes as a state machine made of agent steps, script steps, human gates, branches, and loops.
 
-Connect an agent over MCP (a thin stdio bridge that forwards to the running daemon):
+The goal is not to replace coding agents. Revo coordinates them: it keeps state, records evidence, enforces gates,
+and gives humans a stable place to approve plans, resolve questions, inspect feedback, and decide when work is ready
+to ship.
+
+## How It Works
+
+- **Playbooks define flow.** Roles, scripts, gates, verdicts, branches, and loop limits are data, not hidden prompt
+  convention.
+- **Agent steps are short-lived.** Each agent process receives current state and exits after one step.
+- **Script steps do deterministic work.** Automation such as integration, polling, and response actions stays outside
+  agent prompts.
+- **Human gates are state changes.** A plan approval, question answer, or merge approval resolves an inbox item and
+  resumes the run.
+- **Outputs are traceable.** Artifacts, evidence, decisions, attempts, cost, and run history are recorded for later
+  inspection.
+
+## Concepts
+
+| Term | Meaning |
+| --- | --- |
+| **Revo** | The local orchestrator and control plane for software-development runs. |
+| **Playbook** | A versioned bundle of roles, pipelines, policies, and routing rules. |
+| **Pipeline** | A state-machine template that defines the steps, gates, branches, loops, and terminal outcomes. |
+| **Role** | A named agent definition: prompt, model level, scope, runner, and allowed behavior. |
+| **Agent step** | A pipeline node that starts a short-lived coding agent through a role. |
+| **Script step** | A deterministic automation node used for integration, polling, readiness, or response actions. |
+| **Human gate** | A required decision or answer; the run parks until an inbox item is resolved. |
+| **Run** | One task moving through a selected playbook and pipeline. |
+| **Attempt** | One execution of one step; the unit for logs, verdicts, tokens, and cost. |
+| **MCP** | The local agent-facing tool bridge exposed by `revo mcp`. |
+| **GraphQL API** | The local API surface for UI and script integrations. |
+
+## Alpha Install
+
+The `@alpha` package is a prerelease for evaluating Revo locally. It uses the `default` profile:
 
 ```sh
-claude mcp add revo -- pnpm --dir "$PWD" run revo -- mcp
+npm install -g @revisium/orchestrator@alpha
+revo start
+revo status
+revo doctor
+revo logs
+revo stop
 ```
 
-Run the local verification gates:
+Connect an MCP-capable agent to the installed binary:
 
 ```sh
-pnpm run typecheck
-pnpm run lint:ci
-pnpm run test:cov
-pnpm run verify
+codex mcp add revo -- revo mcp
+claude mcp add revo -- revo mcp
 ```
 
-The smoke scripts are guarded: they require a non-default `REVO_DATA_DIR`,
-`REVO_PORT`, `REVO_PG_PORT`, and `REVO_DBOS_DB`; GraphQL smoke paths also require
-`REVO_GRAPHQL_PORT`.
+Default local ports:
+
+| Service | Port |
+| --- | --- |
+| Revisium standalone HTTP | `19222` |
+| embedded Postgres | `15440` |
+| Revo GraphQL | `19223` |
+
+GraphQL is available at `http://127.0.0.1:19223/graphql` in the default profile. The target contract is documented in
+[docs/specs/graphql-admin-api-v1.spec.md](./docs/specs/graphql-admin-api-v1.spec.md), and the committed SDL is
+[src/api/graphql-api/schema.graphql](./src/api/graphql-api/schema.graphql).
+
+## Roadmap
+
+Revo is in active development. The public roadmap lives in GitHub Milestones and umbrella issues; this README only points to the current tracks.
+
+| Track | Start here |
+| --- | --- |
+| Default playbook stabilization | [Milestone #1](https://github.com/revisium/orchestrator/milestone/1), [umbrella #146](https://github.com/revisium/orchestrator/issues/146) |
+| GraphQL admin API v1 migration | [Milestone #4](https://github.com/revisium/orchestrator/milestone/4), [umbrella #167](https://github.com/revisium/orchestrator/issues/167) |
+| Execution profiles and runner/model binding | [Milestone #5](https://github.com/revisium/orchestrator/milestone/5), [umbrella #168](https://github.com/revisium/orchestrator/issues/168) |
+| Loop engineering layer | [Milestone #2](https://github.com/revisium/orchestrator/milestone/2), [umbrella #148](https://github.com/revisium/orchestrator/issues/148) |
+| Role and pipeline authoring | [Milestone #3](https://github.com/revisium/orchestrator/milestone/3), [umbrella #157](https://github.com/revisium/orchestrator/issues/157) |
+
+Use umbrella issues for initiative context and child issues for reviewable delivery slices. Work orders do not live in docs.
+
+## Local Development
+
+Use the `dev` profile when running a source checkout next to an installed package. The profile has isolated ports,
+data directory, and DBOS database.
 
 ```sh
-pnpm run smoke:control-plane
-pnpm run smoke:create-run
-pnpm run smoke:inspect-run
+pnpm install
+pnpm run revo -- start --profile dev
+pnpm run revo -- status --profile dev
+pnpm run revo -- doctor --profile dev
+pnpm run revo -- logs --profile dev
+pnpm run revo -- stop --profile dev
 ```
 
-### Live Run Observability Smoke
+| Knob | `default` | `dev` |
+| --- | --- | --- |
+| data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
+| standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
+| Revo GraphQL | `19223` | `19623` |
+| DBOS database | `dbos` | `dbos_dev` |
+
+Explicit environment variables override the profile: `REVO_DATA_DIR`, `REVO_PORT`, `REVO_PG_PORT`,
+`REVO_GRAPHQL_PORT`, and `REVO_DBOS_DB`.
 
-This smoke runs a real agent. It can call provider CLIs and incur cost. Use it
-only when that is intentional.
+## Front Doors
+
+`revo mcp` is the agent front door. It is a local stdio bridge to the daemon and exposes product-level tools for
+runs, gates, repository diagnostics, method discovery, and PR readiness.
 
 ```sh
-export REVO_SMOKE_REPO=/path/to/local/sandbox-repo
-pnpm run revo -- start --profile dev   # standalone + host daemon (serves GraphQL + MCP), ready
+codex mcp add --env REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
+claude mcp add -e REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
 ```
 
-Drive and observe a run through the daemon's front doors — there are no `run`/`serve` CLI commands.
-From an agent, use the MCP tools (`create_run`, `start_run`, then `get_agent_activity` /
-`get_agent_log`). From a UI or script, use the GraphQL front door the daemon already serves at
-`http://127.0.0.1:$REVO_GRAPHQL_PORT/graphql` — create a run:
-
-```graphql
-mutation Create($data: CreateRunInput!) {
-  createRun(data: $data) {
-    runId
-  }
-}
-```
+For the `dev` profile, GraphQL is available at `http://127.0.0.1:19623/graphql`.
 
-Then observe it over the same endpoint:
-
-```graphql
-query Activity($runId: ID!) {
-  runAgentActivity(runId: $runId) {
-    runId
-    aggregateStatus
-    latestOutputAt
-    attempts {
-      attemptId
-      runner
-      status
-      stdoutBytes
-      stderrBytes
-      artifactRef
-    }
-  }
-}
-
-query Log($data: GetAgentLogInput!) {
-  runAgentLog(data: $data) {
-    runId
-    attemptId
-    stream
-    offsetBytes
-    nextOffsetBytes
-    totalBytes
-    truncated
-    content
-  }
-}
-```
+## Verification
 
-For MCP, configure the MCP client to launch this checkout's local binary with the
-same environment. The MCP tools do not accept per-call profile arguments; the
-profile comes from the process environment.
-
-```json
-{
-  "mcpServers": {
-    "revo-dev": {
-      "command": "/path/to/agent-orchestrator/bin/revo.js",
-      "args": ["mcp"],
-      "env": {
-        "REVO_DATA_DIR": "/path/to/.revisium-orchestrator-dev",
-        "REVO_PORT": "19622",
-        "REVO_PG_PORT": "15840",
-        "REVO_GRAPHQL_PORT": "19623",
-        "REVO_DBOS_DB": "dbos_dev"
-      }
-    }
-  }
-}
+```sh
+pnpm run typecheck
+pnpm run lint:ci
+pnpm run test:cov
+pnpm run verify
 ```
 
-Useful MCP observability tools for the same run:
+Smoke and e2e scripts that start local daemons may need an unsandboxed terminal and isolated non-default ports.
 
-- `get_agent_activity`
-- `get_agent_attempts`
-- `get_agent_log`
-- `read_agent_output_events`
-- `tail_agent_log`
+## Documentation
 
-If running from a sandboxed automation environment, local server checks may fail
-with `listen EPERM` or a misleading `No free port found from <port>`. Re-run the
-daemon, GraphQL, and MCP smoke commands from a normal terminal or an approved
-unsandboxed execution context.
+| Start here | Purpose |
+| --- | --- |
+| [docs/README.md](./docs/README.md) | Documentation map and ownership rules |
+| [docs/vision.md](./docs/vision.md) | Product direction, glossary, and capability map |
+| [docs/architecture-overview.md](./docs/architecture-overview.md) | Runtime layers, invariants, and lifecycle |
+| [docs/developer-guide.md](./docs/developer-guide.md) | Source map and contributor onboarding |
+| [docs/specs/](./docs/specs/) | Exact product contracts |
+| [docs/adr/](./docs/adr/) | Durable architecture decisions |
+| [AGENTS.md](./AGENTS.md) | Repo-local instructions for coding agents |
 
 ## License
 
-See [LICENSE](./LICENSE).
+MIT - see [LICENSE](./LICENSE).