Architecture

OpenFlows is built on a simple thesis: architecture is the product. AI can generate code against a spec, but it cannot write the spec. OpenFlows encodes the engineering - the architecture, the contracts, the review gates, and the recovery patterns - so that agents produce software, not just code.

Runtime Contract: Coder is the Only Runtime

Coder is the only runtime. OpenFlows is a thin orchestration brain that runs on top of a self-hosted Coder deployment. It does not provision its own VMs, manage its own SSH keys, or host AI agents directly. Instead, it delegates every execution concern to Coder:

• Ephemeral workspaces - Terraform-defined templates, one per worker, created on demand and destroyed after use.
• Control-plane AI agents - Coder Agents live in the Coder control plane, not inside workspaces. They invoke tools by connecting to workspaces over the same secure tunnel used by IDEs.
• Model governance - the Coder AI Gateway centralizes API keys, rate limits, cost tracking, and per-user spend controls.
• Identity - SSO, RBAC, and audit logging are handled by Coder.
• Cost tracking - workspace and LLM usage are attributed per Coder user and group.

Worker workspaces have zero AI software, zero LLM keys, and zero GitHub tokens. The only software they receive is a small openflows-harness binary that talks to Redis with typed, validated schemas. This is a deliberate security boundary: if a workspace is compromised, it contains no long-lived credentials and no model access.

OpenFlows Core

At the center of OpenFlows are three primitives:

• PocketFlow flow graph - a directed graph of nodes that models the engineering lifecycle: triage, planning, implementation, review, CI, merge, and documentation.
• Typed Redis SharedStore contracts - every agent reads and writes through validated schemas, giving the system a single source of truth for state, decisions, and handoffs.
• NEXUS reconcile loop - the controller that polls GitHub, assigns tickets, monitors worker health, retries failures, and escalates when human judgment is required.

OpenFlows uses the Coder Chats API (control plane) for orchestration, not the in-workspace AgentAPI. This means NEXUS asks Coder to run a chat session with a control-plane agent, which then connects to the worker workspace over a secure tunnel. The worker itself never initiates LLM calls or outbound GitHub requests.

Role Topology

Five roles cooperate through the SharedStore:

• nexus - orchestrator / controller. Owns issue polling, ticket assignment, recovery, and escalation.
• forge - builder. Writes code against an agreed contract and opens PRs.
• sentinel - reviewer. Adversarially evaluates every segment for correctness, security, tests, and standards.
• vessel - DevOps. Monitors CI, resolves merge conflicts, and squash-merges green PRs.
• lore - writer. Documents decisions, updates changelogs, and maintains project history.

Extension Point

The primary extension surface is orchestration/agent/registry.json (v2). It declares skills, MCP servers, model assignments, and instance counts per role. Adding a skill, MCP, or model typically requires no Rust code change - only a registry entry and a ./update-binaries.sh run.

Authentication

GitHub authentication is Coder external auth only. There are no personal access tokens stored in OpenFlows or inside workspaces. Each tenant authenticates through Coder's OAuth flow, and every Git operation is performed under that tenant's Coder identity. See the Token Guide for the exact scope requirements.