FORGE - Builder Agent

FORGE is the primary code generation agent. It writes implementation code against a CONTRACT.md that defines the acceptance criteria, security requirements, and test expectations. FORGE runs inside an ephemeral Coder workspace with its own isolated Git worktree and branch.

Architecture

┌─────────────────────────────────────────────────────────────┐
│ FORGE Workspace (ephemeral Coder workspace)                  │
│                                                              │
│  ┌────────────────┐     ┌──────────────────────────────────┐│
│  │ Coder Agent    │────▶│ openflows-harness                ││
│  │ (LLM Session)  │     │ - dispatch read (get task)       ││
│  └────────────────┘     │ - status get/set (track phase)   ││
│                          │ - pr opened (record PR)          ││
│                          │ - heartbeat start (alive signal) ││
│                          │ - handoff write (to Sentinel)    ││
│                          └──────────────────────────────────┘│
│                                      │                        │
│                                      ▼                        │
│                              ┌─────────────┐                 │
│                              │    Redis    │                 │
│                              │ SharedStore │                 │
│                              └─────────────┘                 │
└─────────────────────────────────────────────────────────────┘

Workflow Phases

Phase	Status Value	Description
Planning	`planning`	Analyze task, read repository, create `CONTRACT.md`
Building	`building`	Implement solution per contract
Testing	`testing`	Run test suite, verify all pass
Review Ready	`review_ready`	PR opened, awaiting SENTINEL review
Revising	`revising`	Addressing SENTINEL review comments
Blocked	`blocked`	Cannot proceed - human escalation needed

Hook System (Claude Code)

FORGE uses a comprehensive hook system for policy enforcement and quality:

Hook	Trigger	Purpose
`session_start.sh`	Session starts	Provides dispatch context, workflow guide, contract path
`pre_bash_guard.sh`	Before any bash	Blocks direct Redis access, destructive commands, git push --force
`post_write_lint.sh`	After file write	Auto-formats code (rustfmt, prettier, gofmt)
`stop_require_artifact.sh`	On stop attempt	Refuses to stop unless PR is created or blocked
`pre_task_guard.sh`	Before subagent	Validates task scope, prevents scope creep
`post_task_guard.sh`	After subagent	Verifies subagent completed expected work

Coordination via Harness

FORGE uses the following harness commands to coordinate with NEXUS and SENTINEL:

openflows-harness dispatch read — Reads task assignment from NEXUS
openflows-harness status set building — Updates progress to building phase
openflows-harness pr opened — Records PR creation
openflows-harness heartbeat start — Starts heartbeat daemon for liveness signal
openflows-harness handoff write — Hands off to SENTINEL for review

CONTRACT.md Format

The contract is the agreement between FORGE and SENTINEL. FORGE writes it during planning; SENTINEL reviews against it during code review.

The CONTRACT.md is a markdown document that specifies the goal, acceptance criteria, security requirements, files to be modified, and risks. It serves as the specification that FORGE implements against and SENTINEL reviews.

Configuration

Configure FORGE in registry.json under the agents section with plan_mode: false.

plan_mode: false

FORGE runs with plan_mode: false because it executes implementation, not planning. SENTINEL uses plan_mode: true for adversarial review.

Workspace Template

The openflows-forge template includes:

Repository clone
openflows-harness binary
Claude Code CLI with hook scripts
Rust toolchain, Node.js, Go (as needed per workspace)
Git configuration for FORGE user identity

Security Controls

No direct Redis - All access via openflows-harness
No GitHub tokens - Identity via Coder external auth
No LLM keys - All calls route through Coder AI Gateway
Hook guards - Prevent redis-cli, git push --force, destructive ops
Ephemeral workspace - Destroyed after PR merge