Agent Roles

OpenFlows uses five specialized agents, each with a distinct role, isolated permissions, and its own Coder workspace. They communicate through the SharedStore - a Redis-backed state machine - and are coordinated by NEXUS on every cycle. Each agent's CLI code agent is installed by a Coder Registry module (e.g. claude-code, codex, aider), and GitHub identity comes from Coder external auth - no personal access tokens.

Quick Reference

Agent	Role	Plan mode	What it does
NEXUS	Orchestrator	yes	Assigns issues, coordinates the team, owns `reconcile()` failure recovery, notifies you when needed
FORGE	Builder	no	Writes code against an agreed `CONTRACT.md`, creates branches, opens PRs
SENTINEL	Reviewer	yes	Adversarially reviews code for security, quality, and test coverage against the contract
VESSEL	DevOps	no	Monitors CI, handles merge conflicts, squash-merges green PRs, tears down workspaces on merge
LORE	Writer	no	Documents decisions, updates changelogs, maintains project history (disabled by default - enable in registry)

Agent = CLI (muscle) + Harness (brain)

FORGE and NEXUS can use the same CLI but are different agents because they have different architectures - different personas, skills, hooks, and permissions. The system is extensible in two independent dimensions: swap the CLI module to change the code agent, or swap the harness to change the agent's behavior.

NEXUS - Orchestrator

The brain of the pipeline. NEXUS supervises every phase of the flow and recovers broken states automatically via reconcile(). It runs on every cycle and halts gracefully when there is no more work. NEXUS does not run inside a Coder workspace - it is the control plane that provisions and manages them.

Polls GitHub for open issues and syncs them as typed tickets (T-001, T-002…)
Assigns tickets to idle FORGE workers, respecting CI readiness and flow recovery state
Provisions an ephemeral Coder workspace for each FORGE worker via the Coder API
Detects orphaned tickets, unmerged PRs, and stale workers - resumes at the correct phase
Manages the CommandGate: approves or rejects dangerous bash commands from FORGE
Enforces CI-first rule: ensures CI setup tickets are completed before feature work begins
Escalates unrecoverable states to AwaitingHuman - suspends the worker and stores the reason in SharedStore for TUI visibility

FORGE - Builder

The senior engineer. FORGE runs inside an ephemeral Coder workspace with its own isolated Git worktree and branch. A Coder Registry module (claude-code, codex, or aider) installs the CLI code agent into the workspace. FORGE implements code segment by segment and never pushes directly - all PRs go through GitHub MCP under the Coder user's identity.

Runs inside an ephemeral Coder workspace (branch: forge-1/T-001)
Writes PLAN.md with a segment breakdown - SENTINEL reviews it before any code is written
Implements each segment, commits, updates WORKLOG.md, and waits for SENTINEL eval
Scans and redacts secrets before every push
Opens pull requests via GitHub MCP after SENTINEL's final-review.md is APPROVED
Writes STATUS.json with status: "BLOCKED" and a specific question when blocked

SENTINEL - Reviewer

The security auditor. SENTINEL is ephemeral - spawned fresh in its own Coder workspace for each evaluation, which eliminates accumulated bias. It is read-only and cannot modify code. It evaluates against 5 criteria: correctness, security, test coverage, standards compliance, and no regressions. Using a different LLM provider than FORGE creates adversarial review - the reviewer's blind spots differ from the writer's.

Reviews PLAN.md → writes CONTRACT.md (AGREED or CHANGES_REQUESTED)
Evaluates each committed segment → writes segment-N-eval.md
Performs final holistic review → writes final-review.md
Only after APPROVED does FORGE proceed to open the pull request
Read-only permissions - cannot write or commit to the worktree
Workspace torn down after each evaluation - fresh slate every time

VESSEL - DevOps Engineer

The merge gatekeeper. VESSEL is the only agent authorized to push to the main branch. It polls CI, detects conflicts early, attempts automated resolution, and squash-merges green PRs. If a conflict can't be resolved automatically, VESSEL re-routes the ticket back to the same FORGE worker - no new branch, no context loss.

Polls GitHub check runs at 10-second intervals (configurable timeout, default 30 min)
Detects merge conflicts via GitHub's mergeable field before CI completes
Attempts automated resolution via GitHub update-branch or local rebase inside the workspace
Writes CONFLICT_RESOLUTION.md and re-routes to the same FORGE worker
Squash-merges approved PRs with ticket references; emits ticket_merged for LORE

LORE - Documenter

The technical writer. LORE activates after every successful merge and never interrupts active development. It generates Architecture Decision Records, updates CHANGELOG.md, and commits documentation changes via GitHub MCP under the Coder user's identity.

Triggered by VESSEL's ticket_merged event - never blocks the development pipeline
Generates structured ADRs from the merged work's technical decisions
Appends deployment summaries to CHANGELOG.md with PR references and ticket IDs
Commits and pushes documentation changes via GitHub MCP
Read-only access to application code - cannot modify source files

Per-Agent Configuration

Each agent's LLM provider, model, Coder Registry module (CLI), and worker count are configured in orchestration/agent/registry.json. Different agents can use different CLI modules - FORGE on claude-code while LORE uses aider. See the Agent Setup Guide for details.

Ephemeral workspace lifecycle

When NEXUS assigns a ticket to a FORGE worker, it provisions a fresh Coder workspace from your template. The coder_module installs the CLI code agent into that workspace. After the PR is merged, the workspace is torn down - no lingering state, no stale credentials. SENTINEL gets its own workspace per evaluation, also torn down after use. Each parallel FORGE instance gets its own workspace.