Coordination Protocol

All inter-agent coordination happens through the openflows-harness CLI and the Redis-backed SharedStore. Workers never access Redis directly - the harness provides typed, validated access to the state machine.

No direct Redis access

The pre_bash_guard.sh hook blocks redis-cli, redis, and any direct Redis commands. All state operations must go through the harness.

Harness Command Reference

Command	Description	Example
`dispatch read`	Read assigned task payload	`openflows-harness dispatch read`
`dispatch status`	Show assignment status	`openflows-harness dispatch status`
`status get`	Read current phase from STATUS.json	`openflows-harness status get`
`status set <phase>`	Update phase (planning/building/testing/review_ready/blocked)	`openflows-harness status set building`
`pr opened --pr N --branch B --title "T"`	Record PR creation	`openflows-harness pr opened --pr 123 --branch forge-1/42 --title "Fix bug"`
`pr merged --pr N`	Record PR merge	`openflows-harness pr merged --pr 123`
`handoff write --contract FILE --notes "..."`	Handoff to next agent	`openflows-harness handoff write --contract changes.md --notes "Done"`
`heartbeat start`	Start 30s heartbeat daemon	`openflows-harness heartbeat start`
`event emit ticket_merged --ticket ID --pr N`	Emit merge event for LORE	`openflows-harness event emit ticket_merged --ticket 42 --pr 123`

Phase Lifecycle

Each ticket progresses through a deterministic sequence of phases. The current phase is tracked in STATUS.json in the worker workspace and mirrored in Redis.

Phase	Agent	Description	Next Phase
`planning`	FORGE	Analyze issue, read repo, write CONTRACT.md	`building`
`building`	FORGE	Implement solution per contract	`testing`
`testing`	FORGE	Run test suite, fix failures	`review_ready`
`review_ready`	SENTINEL	PR opened, awaiting review	`reviewing`
`reviewing`	SENTINEL	Reviewing diff against contract	`approved` \| `changes_requested`
`changes_requested`	FORGE	Address review comments	`review_ready`
`approved`	VESSEL	SENTINEL approved, CI running	`merging`
`merging`	VESSEL	Merge conflict resolution / squash merge	`merged`
`merged`	VESSEL/LORE	PR merged, docs updated	done
`blocked`	Any	Cannot proceed - human escalation	`awaiting_human`
`awaiting_human`	NEXUS	Waiting for human input	`planning` (after unblock)

json

// STATUS.json example
{
  "outcome": "building",
  "phase": "building",
  "ticket": "ISSUE-123",
  "pr_url": null,
  "blocker": null,
  "errors": [],
  "last_updated": "2026-07-20T15:43:21Z"
}

Handoff Protocol

Phase transitions between agents are explicit. The outgoing agent writes a handoff document that the incoming agent reads.

From → To	Artifact	Purpose
FORGE → SENTINEL	`handoff.md` + `CONTRACT.md`	Implementation summary + contract for review
SENTINEL → FORGE	`segment-N-eval.md`	Per-segment approval/rejection
SENTINEL → VESSEL	`final-review.md`	APPROVED unblocks merge
VESSEL → LORE	`ticket_merged` event	Trigger documentation

bash

# FORGE → SENTINEL handoff
openflows-harness handoff write   --contract changes.md   --notes "Implemented rate limiting per CONTRACT.md segments 1-3.
All tests pass. PR #123 opened.
Known: backoff policy uses default exponential (1s base, max 30s).

Heartbeat Protocol

Workers send heartbeats every 30 seconds to Redis. NEXUS monitors these and marks workers as stale after 90 seconds of silence.

bash

# Start heartbeat (runs as background daemon)
openflows-harness heartbeat start

# Heartbeat key in Redis
ns:{"{tenant}"}:heartbeat:forge-1 → 1719000000 (unix timestamp)

# NEXUS reconcile check:
# if (now - last_heartbeat > 90s) → mark worker stale

Event Ring

A ring buffer of the last 1000 events for each tenant. Used by the TUI for real-time dashboard and by operators for debugging.

bash

# Read recent events
redis-cli LRANGE ns:my-team:event_ring 0 99

# Event format (JSON)
{"ts": "2026-07-20T15:43:21Z", "tenant": "my-team", "worker": "forge-1", "level": "INFO", "msg": "segment review APPROVED", "ticket": "ISSUE-123", "segment": 2}

GitHub MCP Integration

All GitHub operations (clone, push, PR creation, review comments, merge) route through the GitHub MCP server. Workers authenticate via Coder external auth - no PATs ever enter the workspace.

GitHub identity

The Coder MCP server resolves the GitHub identity from the Coder external auth token attached to the workspace owner. FORGE acts as the Coder user that owns the tenant's NEXUS workspace.

SharedStore Key Contracts

Key	Type	Schema
`ticket:{id}:status`	String	`open` \| `assigned` \| `working` \| `review_ready` \| `reviewing` \| `approved` \| `merging` \| `merged` \| `blocked` \| `awaiting_human`
`ticket:{id}:dispatch`	JSON	`{ issue, repo, phase, contract_path }`
`ticket:{id}:contract`	String	Full CONTRACT.md content
`ticket:{id}:handoff`	JSON	`{ from_agent, to_agent, contract_changes, notes }`
`worker_slots`	Hash	`forge-1 → {status, workspace_id, last_heartbeat}`