What is Smithers?

Smithers is the constraint-convergence orchestrator for Matrix. It is one vertical built on the Matrix substrate (Matrix is docker-for-actors / npm-for-actors — a typed pub/sub/RPC fabric where every Feed, Service, and Component is an actor on a federated bus; Smithers is a Package that runs on that fabric and uses system.agents, system.inference, and system.factotum rather than re-implementing any of them).

The package's own opening lines in src/index.ts:2-12 say exactly what it does:

Smithers coordinates AI coding agents through a formal protocol where:
Dependers define constraints on the issues they depend on
Constraints are gathered into a single projection before work starts
Sign-off is a forcing function with per-constraint argumentation
Reviews are parallel and barriered (gathered, not piecemeal)
The ratchet accumulates satisfied constraints as invariants
The Projection Principle: The UI, agent prompt, sign-off checklist, and review dispatch are all renderings of the same projection query.

In a sentence: Smithers takes a GitHub issue, gathers everything the rest of the system needs from that issue, dispatches a coding agent that runs until it can argue every constraint is met, then routes the work to parallel reviewers and ratchets what's proven.

The convergence pipeline

SmithersSupervisor (projects/matrix-3/packages/smithers/src/actors/SmithersSupervisor.ts) drives the pipeline. The phases are not informal — they are explicit ConvergencePhase values: gathering, working, sign-off, reviewing, barrier, continuing.

mermaid

sequenceDiagram
    participant User
    participant Supervisor as SmithersSupervisor
    participant Graph as ConstraintGraph
    participant GH as GitHubAdapter
    participant Agent as CodingAgent / SDK Worker
    participant Reviewer as ReviewerAgent

    User->>Supervisor: smithers.start { issueNumber }
    Supervisor->>Graph: graph.constraints-for(N)
    Graph->>GH: github.get-issue(N)
    Graph-->>Supervisor: ConstraintProjection
    Supervisor->>Agent: dispatch with full constraint prompt
    Agent-->>Supervisor: code.event stream
    Agent-->>Supervisor: code.done
    Supervisor->>Supervisor: smithers.sign-off (forced)
    Supervisor->>Reviewer: parallel reviewerAgent.evaluate per constraint
    Reviewer-->>Supervisor: ReviewResult fan-in
    Supervisor->>Supervisor: barrier — all reviews back?
    alt all approve
      Supervisor->>RatchetStore: ratchet.add
      Supervisor-->>User: smithers.converged
    else any reject
      Supervisor->>Agent: restart with rejection feedback
    end

Why the protocol exists

DESIGN.md §1 frames the principle:

Smithers is methodical. Every agent starts knowing exactly what the rest of the system needs from it. Every completion is formally verified. Every review is gathered, not piecemeal. Every satisfied constraint is ratcheted and never regresses.

Concretely, this avoids three failure modes that ad-hoc agent dispatch produces:

Agents that don't know what's expected. Smithers gathers constraints from every depender (and from SYSTEM_CONSTRAINTS, getBootstrapConstraints, and ArchitectureDocWatcher) before the agent ever sees the issue.
Closures without verification. smithers.sign-off is a forcing function — the agent has to argue each constraint. The supervisor inspects the argument before transitioning to review.
Piecemeal review. Every depender reviews simultaneously through ReviewerAgent, against the same evidence; results are gathered behind a barrier, then either ratcheted as RatchetEntry records or fed back as rejection feedback that restarts the agent with the right context.

Top-level supervisor ops

SmithersSupervisor.accepts (SmithersSupervisor.ts:315-353) is the public protocol:

$introspect, $prompt,
workstream.status, workstream.request, workstream.agents,
smithers.start, smithers.stop, smithers.steer,
smithers.status, smithers.graph.status,
smithers.sign-off, smithers.history, smithers.metrics, smithers.review-queue,
smithers.request-service, smithers.request-dispatch,
smithers.request-acknowledge, smithers.request-message, smithers.request-resolve,
smithers.workstream-requests,
smithers.configure, smithers.config,
smithers.health, smithers.timeline, smithers.error-log,
smithers.active-agents, smithers.agents, smithers.containers,
smithers.browser-connect, smithers.browser-disconnect,
smithers.ratchet, smithers.arch-constraints,
smithers.auto, smithers.constraint-approved, smithers.chat-constraints,
workspace.navigate, workspace.set-queue,

Each is a real on* handler. The list is large because Smithers handles its own UI state (workspace.*), its own agent dispatch, and its own workstream-request inbox.

What Smithers does NOT replace

DESIGN.md §2.2:

NOT a project management tool (use GitHub Issues for that).
NOT a CI replacement (CI still runs for human PRs; Smithers subsumes it for agent PRs).
NOT an issue tracker (GitHub is the source of truth).
NOT a code review tool (it automates review dispatch; humans still review the final PR).

Productization status

Per WORKSTREAMS/loose-ends/items/P2.6-smithers-productize.md, Smithers is currently a TODO for full productization. Today's evidence point is local-Vite proof at http://127.0.0.1:3104/apps/smithers/. There is no public HiveCast route yet, no signed-in container-spawning flow, and the worker-isolation audit (P2.5-worker-isolation-audit.md) is the security gate before any public Smithers/Codex/Claude demo.

What is Smithers? ​

The convergence pipeline ​

Why the protocol exists ​

Top-level supervisor ops ​

What Smithers does NOT replace ​

Productization status ​