Architecture

Agent Hub is a hybrid orchestrator. Deterministic code owns workflow progression; model judgment owns ambiguous interpretation and review quality.

Responsibility Split

Deterministic engine Queue ordering, delivery records, worker state, review gates, reconciliation, deploy stages, repair routing, and watcher persistence.

Supervisor judgment Source completeness, UX/UI evaluation, ambiguous project intent, recovery recommendations, and review sufficiency.

External adapters Codex, Claude Code, terminal behavior, Git, GitHub CLI, deployment tools, notifications, and local operating-system integrations.

The design assumption is that terminal UIs and external tools drift. Their parsing and transient failures should not become the source of truth for workflow semantics.

Durable State

The local runtime stores:

project and worktree metadata
worker sessions
instruction queues
pending delivery and continuation records
structured worker events
handoff and review gates
reconciliation and deployment runs
watcher notification history

Runtime state lives outside Git. Source control owns the engine, prompt, launchers, tests, docs, and install scripts.

Event Authority

Hub-launched workers report structured lifecycle and work-item events. Current-generation structured events can own worker state. Terminal output remains useful for compatibility and diagnostics, but it cannot override valid structured events.

This prevents stale terminal text from reopening old handoffs, treating old output as current progress, or claiming a deploy happened merely because a worker wrote optimistic prose.

Integration Lifecycle

Route an instruction to a project worker.
Preserve the task as a durable work item.
Wait for exact delivery ACK.
Track worker progress and blockers.
Require a structured handoff.
Run Hub review.
Wait for human acceptance when required.
Commit accepted work.
Reconcile into the canonical main worktree.
Deploy from the validated target.
Verify production.
Sync clean sibling worktrees.