Core Concepts

OpenFlows is not a model, an IDE, or a CI/CD product. It is an orchestration layer that turns a self-hosted Coder deployment into an autonomous engineering team. The concepts in this section explain the ideas that make that possible: why planning beats prompting, why five narrow agents beat one general-purpose agent, how a directed graph and a typed store keep the system coherent, and why security is a property of the runtime rather than a policy document.

If you are a developer or operator trying to decide whether OpenFlows fits your organisation, read these pages first. If you are already running the system, they explain the reasoning behind the configuration files, the registry schema, and the workspace lifecycle you see in production.

Architecture is the product

The central thesis of OpenFlows is that the hard part of software engineering is the architecture, the contract, and the review gate - not the code itself. When agents are cheap and models can write boilerplate in seconds, the value shifts from keystrokes to specification. OpenFlows encodes that shift into a repeatable pipeline.

Concepts at a Glance

Concept	What problem it solves	Read more
Architecture-First	Boilerplate is cheap; correctness is not. Agents write code only after a human-reviewable plan and contract exist.	Details →
Agent Team	Specialised roles with narrow boundaries prevent a single agent from drifting into both authorship and review.	Details →
PocketFlow & SharedStore	A deterministic graph and a typed state bus let the orchestrator reason about progress, not just emit prompts.	Details →
Coder Integration	Coder is the runtime. OpenFlows does not provision VMs, manage SSH keys, or host AI models itself.	Details →
Security Model	Secrets and identity are handled by Coder; workers start empty and are destroyed after merge.	Details →

How the Concepts Fit Together

The five concepts form a stack. At the bottom, Coder provides the runtime: identity, workspaces, model governance, and audit. On top of that runtime, OpenFlows runs a PocketFlow graph whose nodes are the five agents. The agents communicate through a SharedStore with typed contracts, and the whole flow is governed by the architecture-first rule that no implementation begins until a plan has been written and reviewed. Finally, the security model makes those guarantees concrete by ensuring that no worker workspace ever contains secrets, credentials, or long-lived state.

Plan: a GitHub issue is interpreted as a ticket. NEXUS assigns it to FORGE, which writes PLAN.md. SENTINEL writes CONTRACT.md - a reviewable contract, not a guess.
Execute: FORGE implements the plan in segments inside an ephemeral Coder workspace. SENTINEL evaluates each segment and produces segment-N-eval.md.
Merge: after a final review, FORGE opens a PR. VESSEL monitors CI and squash-merges. LORE documents the change, and the workspace is destroyed.
Recover: NEXUS continuously reconciles the SharedStore. If a node crashes, an agent hallucinates, or a workspace disappears, the flow resumes at the correct phase.

Where to Start

🏛️

Architecture-First Development

Why OpenFlows plans before it executes, and why PLAN.md and CONTRACT.md are the real deliverables.

👥

The Agent Team

NEXUS, FORGE, SENTINEL, VESSEL, and LORE - their roles, boundaries, and the issue-to-merge pipeline.

🧠

PocketFlow & SharedStore

The directed flow graph, the Node lifecycle, and typed Redis state contracts that keep the system coherent.

🔗

Coder Integration

How OpenFlows runs as a thin orchestration brain on top of a self-hosted Coder deployment.

🛡️

Security Model

Identity, audit, secrets, ephemeral workspaces, and the no-PAT, no-LLM-keys-in-workspaces policy.

Read these pages before editing registry.json

The orchestration/agent/registry.json file makes a lot more sense once you understand the agent-team model and the Coder integration. If you are tempted to change a model or disable an agent, read the corresponding concept page first.