Agent Architecture

OpenFlows uses five specialized agents, each with a distinct role, isolated permissions, and its own lifecycle. They communicate through the Redis-backed SharedStore and are coordinated by NEXUS on every cycle.

Agent Overview

Agent	Role	Plan mode	CLI Module	Workspace Type
NEXUS	Orchestrator	yes	claude-code	Permanent (nexus workspace)
FORGE	Builder	no	claude-code / aider	Ephemeral per ticket
SENTINEL	Reviewer	yes	codex	Ephemeral per review
VESSEL	DevOps	no	codex	Ephemeral per merge
LORE	Documentation	no	aider	Ephemeral per merge

Core Principles

Agent = CLI + Harness - The CLI module (claude-code, codex, aider) executes code; the harness provides state coordination via Redis.
Adversarial by Default - FORGE and SENTINEL use different LLM providers to create natural adversarial review.
Ephemeral Workspaces - Every worker gets a fresh Coder workspace. SENTINEL gets a new workspace per review to eliminate bias.
Control-Plane Coordination - NEXUS runs in the control plane; workers run in workspaces. All LLM calls route through Coder AI Gateway.
GitHub via External Auth - No PATs in workspaces. GitHub identity comes from Coder external auth.

Coordination Protocol

All agents coordinate through the openflows-harness CLI in their workspace. The harness is the only Redis client in a workspace - agents never run redis-cli directly.

bash

# Core harness commands
openflows-harness dispatch read       # Get assigned task
openflows-harness dispatch status     # Show current phase
openflows-harness status get          # Read STATUS.json
openflows-harness status set phase    # Update phase (planning/building/testing/review_ready)
openflows-harness pr opened --pr N --branch B --title "X"
openflows-harness pr merged --pr N
openflows-harness handoff write --contract changes.md --notes "Summary"
openflows-harness heartbeat start     # 30s heartbeat daemon
openflows-harness event emit ticket_merged --ticket 42 --pr 123

Agent Directory

NEXUS - Orchestrator

Rule-based coordinator. Runs the reconcile() loop. Assigns tickets, provisions workspaces, handles recovery.

FORGE - Builder

Implements code against CONTRACT.md. Runs in ephemeral workspace. Hooks enforce policy.

SENTINEL - Reviewer

Adversarial review. Fresh workspace per evaluation. Posts blocking comments on PR.

VESSEL - DevOps

CI monitoring, conflict resolution, squash-merge, workspace teardown.

LORE - Documentation

ADRs, CHANGELOG, post-merge docs. Disabled by default.

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.

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.