The Agent Team

OpenFlows is not one large language model doing everything. It is a team of five specialised agents with narrow roles, clear boundaries, and enforced handoffs. Each agent is a node in the PocketFlow graph, and the SharedStore is the only place they are allowed to coordinate. This design prevents the common failure mode of a single agent that both writes and reviews its own work, drifting into self-justification and hidden bugs.

A worker is defined by a tuple: (role, ticket). When NEXUS assigns a ticket to FORGE, it creates a worker identity such as forge-1 or forge-2, provisions an ephemeral Coder workspace bound to that identity, and records the assignment in the SharedStore. When the ticket is merged, the worker slot is released and the workspace is destroyed. There is no persistent agent personality, no long-lived context, and no accumulated bias.

Roles at a Glance

NEXUS: The Controller, Not a Chat

NEXUS is the orchestrator. It runs on the control plane, not inside a workspace, and it does not engage in open-ended chat. Its job is to keep the pipeline moving and to keep the state consistent. On every poll cycle, NEXUS performs the following actions:

• Discover: poll GitHub for open issues, PRs, and merge statuses; create or update Ticket records in the SharedStore.
• Assign: match open tickets to idle workers using registry.json constraints and current load.
• Provision: create a Coder workspace for the assigned worker and install the configured CLI module.
• Reconcile: detect orphaned tickets, stale workers, unmerged PRs, and completed_without_pr states; resume the flow at the correct phase.
• Escalate: when a ticket is blocked by ambiguity, a security concern, or a failing recovery strategy, mark it AwaitingHuman and stop the worker cleanly.

NEXUS never writes implementation code. It may write STATUS.json when it detects a system-level failure, but it does not edit PLAN.md, CONTRACT.md, or source files. This boundary is what keeps the orchestrator honest: it cannot silently "fix" a bad implementation by patching it itself.

FORGE: The Implementer

FORGE is the primary coding worker. Its lifecycle is the longest of the workers because it owns the planning and implementation phases. In a typical cycle, FORGE:

1. Reads the ticket and the repository context.
2. Writes PLAN.md with a segment breakdown and risk assessment.
3. Waits for SENTINEL to produce an AGREED CONTRACT.md.
4. Implements each segment in turn, committing after each one.
5. Requests SENTINEL evaluation after each segment.
6. Addresses evaluation feedback or rewrites the plan if the direction changes.
7. After final approval, opens a PR via GitHub MCP.
8. Writes a STATUS.json with PR_OPENED and the PR URL.

FORGE is configured with the strongest reasoning model available because the planning phase is where the most expensive decisions happen. It is also the only worker that is typically scaled to multiple parallel instances, each with its own Coder workspace.

SENTINEL: The Adversarial Reviewer

SENTINEL is the quality gate. It reviews plans before implementation, evaluates each segment after it is committed, and performs the final review before a PR is opened. SENTINEL is usually configured with a different model provider than FORGE, creating a natural adversarial review: the reviewer does not share the same training distribution or latent biases as the writer.

SENTINEL is spawned fresh for each evaluation. It does not carry memory of previous reviews, so it cannot develop a grudge or a habit of rubber-stamping. Its workspace is ephemeral and contains only the documents it needs to evaluate: the PLAN.md, the CONTRACT.md, the segment code, and any relevant test output. It has no access to the LLM keys, GitHub tokens, or other secrets used to drive the pipeline.

VESSEL: The Merge Gate

VESSEL is responsible for the final step of the issue-to-merge pipeline. It polls the PR every ten seconds, checks the CI status, and inspects the mergeable field to detect conflicts early. When CI is green and SENTINEL's final-review.md is APPROVED, VESSEL performs a squash merge with a ticket reference in the commit message.

VESSEL does not write code, open PRs, or review plans. Its narrow scope is intentional: it is the only agent allowed to merge, and it only merges after two independent conditions are satisfied. This prevents FORGE from merging its own work and gives NEXUS a clean event to act on after merge.

LORE: The Documentarian

LORE runs after the merge. Its job is to capture the decision in durable documentation: an Architecture Decision Record (ADR) that explains why the change was made, and an update to CHANGELOG.md. LORE uses a lightweight model because its task is summarisation and formatting, not deep reasoning.

Documentation is not an afterthought in OpenFlows; it is a phase of the pipeline. If LORE fails to write the ADR, NEXUS marks the ticket accordingly and may retry or escalate. The repository history is therefore self-describing: every significant change has a design document, a review trail, and a changelog entry.

The Issue-to-Merge Pipeline

Boundaries and Handoffs

Boundaries are enforced by convention, by workspace isolation, and by the SharedStore schema. A worker can only write the documents associated with its role. NEXUS checks the state transitions and refuses to move a ticket to a phase that has not been properly authorised. For example, a ticket cannot move to PR_OPENED unless the SharedStore contains a final-review outcome of APPROVED.

Worker Identity and Scaling

A worker is not a user account. It is a runtime slot created by NEXUS for a specific ticket. The identity is role-instance, such as forge-1 or sentinel-1. Each instance is mapped to a separate Coder workspace, a separate SharedStore slot, and a separate lifecycle.

{
  "agents": {
    "forge": { "instances": 2, "coder_module": "claude-code" },
    "sentinel": { "instances": 1, "coder_module": "codex" },
    "vessel": { "instances": 1, "coder_module": "codex" },
    "lore": { "instances": 1, "coder_module": "aider" }
  }
}

With two FORGE instances, NEXUS can work on two tickets in parallel. Each FORGE worker is isolated, so a crash or a runaway process in one workspace does not affect the other. When a worker finishes, its slot returns to the idle pool and NEXUS assigns the next ticket.

Recommended Model Assignments