Foremandocumentation
← Back to the app

How Foreman works

GhostFactory is the brand. Foreman is the process and the runtime — nine steps that cannot be skipped or reordered, only configured. Three stations are inside GF, Span Chain is independent.

This page holds the explanation. The app keeps only names and controls; every “?” next to a setting links here, to the relevant section.

Nine steps

01CAPTURE
02TRIAGE
03PLAN
04CONTAIN
05RUN
06GATE
07RECORD
08COMMIT
09LEARN

Foreman is not a bot. The steps are deterministic — decisions are made by the agents above them, writes are made by git. The order is load-bearing: what has to happen before the write cannot be postponed until after it.

COMMIT and LEARN. The single source of truth about what happened is git and Linear. After the commit, the difference between the plan and reality is written back to K-B. A discovery run always ends with a recorded decision, not just code.

rule

K-B is read by Step 0 and written by LEARN. Nothing in between touches memory.

Step 0 — what is read before TRIAGE

Reads K-B
The GF-1000 monorepo — verified facts about the code, not recollections.
Reads the Linear issue
Exit criteria and labels decide the run type.
Mechanical Step 0
Facts are verified against the disk, not against the context. Without that you get fake precision.
Automatic TRIAGE
Foreman determines the run type itself (fix / feature / discovery). Otherwise it asks.

Switchyard · PLAN

Switchyard decides what fits into a run. It knows nothing about the content of the code, only about its scope. It assembles a sealed manifest and hashes it — once sealed, it does not change; a second attempt is a new manifest, not an edit of the old one.

The station is still design — Foreman assembles the plan according to its rules.

Shroud · GATE — when it waits

The gate cannot be turned off per run. The chip in the composer only presets what is checked on a new run. Automatic gates always run; judge and human are added according to risk.

Public HTTP behavior
A new endpoint, a different status code or a header in the response.
Database migration
Anything in priv/repo/migrations.
New dependency
Including transitive bumps in the lockfile.
Open finding
A lens set to blocks always holds the run — this condition also covers reports.
File deletion
Deleting or moving files outside the diff of a single module.
Large diff
A human wants to read a manifest of more than 12 files.
Runtime config change
Configuration that changes without a deploy.
who confirms

A bot cannot confirm a gate it raised itself. Confirmation is up to the project's owner or maintainer.

Security lenses over the diff

Lenses get only the manifest's diff, not the repo. Impact outside the diff is reported as unverified — that is why a finding carries its provenance: the source, the lens, and what could not be verified.

Hash chain and ledger
Append-only, no span overwrites, hash continuity.
OTP supervision
Restart strategies, links, processes that die silently.
HTTP boundary
Status codes, headers, RFC 9110.
Secret redaction
API keys and tokens in a log, an error message or a span.
Dependencies and CVEs
New deps checked against the advisory database.

Each lens has three states: blocks, reports, off. A blocking finding holds the run even without a human gate.

Murmur · RUN

Murmur runs inside Shroud — CONTAIN is its boundary, not its setting. A run sees only the worktree: no remote, no secrets, no network beyond the registry.

Span Chain · RECORD

Span Chain is the only live station live and it is independent — it runs on spanchain.dev with its own credentials. Projects neither inherit nor override this config; the other stations are extracted from its records.

Verify level
How many layers of the chain are verified after the commit. L3 is the whole run history.
What gets recorded
L0 is the run input. “Every step” means a span for each of the nine steps.
Span retention
After expiry the hashes remain and the payloads disappear.
Append-only
Overwriting a run creates a new span. The old one stays readable.

Export. The ledger dump is JSON with spans, hashes and timestamps — without payloads.

Settings

Configuration does not sit in the rail next to the work. It is a separate page, as in Linear or Vercel: it opens from Settings at the bottom of the rail or with the shortcut ⌘,, the rail is swapped for a sidebar with pages, and Esc takes you back. Projects, environment chips and the agent dock are not here — settings are not work.

General
Appearance — material effects and mode.
Process
Nine steps, Switchyard, Shroud (gate and security lenses), Murmur and Span Chain. The pages match the stations and layers of the process.
Agents
Agent builder, review lenses, teams and skills.
Tools
Harnesses and rigs, Model routing.
Workspace
Projects and their overrides, demo data reset.

Scope global / project exists only on the process and agent layer pages. Span Chain is independent, appearance is local to the browser, and agents, harnesses and routing keep their own record. Search in the sidebar goes through row names, the descriptions behind “?” and the values; clicking a result opens the page and briefly highlights the row. Agent builder and Harnesses open a list first; the detail is one click further.

Projects and inheritance

A project inherits the global GF config. An override is created only once you switch something on the project — and it can be discarded by clicking the own label.

What a project cannot override: Foreman's nine steps (the process is the same for every project), Span Chain (an independent station with its own config) and the append-only ledger.

Agent layer

Agents are a commodity — what matters is what they may do and what is kept out of their hands. Foreman's nine steps are the frame; an agent picks its place within it.

In the builder you set for an agent: who it is, in which steps it may step in, what it reads and what is kept out of its hands. An agent does not hold a model — it inherits it from the step it runs in (see Model routing).

Review lenses and skills

Claude
Implementation and review. Writes the run and reads other reviews; on its own diff it does not have the last word.
Gemini
Architecture. Reads ADRs and decisions — looks for what was decided without evidence.
Grok
Counterargument. Gets the same input and has to look for a reason why it is wrong.

In parallel, everyone gets the same input; in serial, each sees the previous answer.

boundary

Review is advisory. Only the gate in Shroud can block a run — a lens on its own stops nothing.

Teams and skills. Fourteen teams, twenty-nine skills. Skills are versioned in the monorepo and a team takes them according to the run type; a skill may change the run's prompt, otherwise skills are only documentation. A run labeled Type Discovery does not finish without a recorded decision.

Model routing

Which model does which step. Providers are interchangeable — the process rules are not. Routing is the only place where the run's model is chosen. In a free session you choose the model yourself; the boundary between the two is described in Sessions and runs.

Sessions and runs

A session is what you sit at. A run is what goes through the nine steps. They are not two names for the same thing, and they do not follow the same rules.

A session carries a project, a harness and an environment. It is free work — you ask, read, try things. Nothing is recorded, because without a manifest there is nothing to record. You choose the model yourself.

A run comes into being only when a manifest comes out of a session. From that moment on, the nine steps and the gate before the commit apply. You no longer choose the model — it is inherited from routing per step and locked in the dock.

why it works this way

Choosing the model in a run would bypass the evidence. The gate rests on being able to say afterwards what produced the diff — and “a human switched it along the way” is not an answer the ledger could carry. A free session has no such commitment, so there it would only get in the way.

You can tell a session with a run by its header carrying the run number and by the model picker being locked to @route:run.

Harness design

A harness is the CLI or app that actually drives the agent — Claude Code, Codex, OMP, Pi, prime-agent, opencode2. It carries both the session and the run: free chat runs under a harness, and when a run comes out of a session, the same harness pulls the RUN step in Murmur.

The harness is interchangeable, the process is not. The nine steps, the manifest gate and the append-only ledger do not know which harness ran under them — and are not supposed to. A harness is the same as a provider: a replaceable part.

Reach
Each harness supports a different set of providers. The models offered in a session are the intersection of what the harness can reach and what is enabled in routing — not a list by who made the model. That is why Claude Code also offers a model from OpenAI.
Subagents
Some harnesses support them, others do not. Where they do not, delegation is not offered at all — it is more honest to say so than to offer a button that does nothing.
TUI and GUI
The harness records whether it has a text interface, a graphical one, or both. On mobile a TUI is unusable, so a session under a harness without a GUI is not offered on the phone.
Switching
Changing the harness of a session can take away the model's reach. The model then falls back to the default and this is said out loud — a silent override would mean that something other than what is on the screen is running.

Harness kit and rigs design

What a harness can do — TUI, subagents, reach — is an observation and is not configured. What you put into it is the kit: what it is for, workflows and skill agents. Both are on the Harnesses screen.

What it is for
A label and a sentence. It is a note for you, not a rule: the process does not change, the nine steps and the gate apply the same way under every harness.
Skill agents
The same agents as in Agent builder, including their skills — there is no second list. They are put into a harness, not into a rig, so where an agent sits is recorded once. Foreman and Chain are not put in: Foreman is the process above every harness, Chain the ledger outside it.
Workflow
The order of agents and the role that holds each step. A workflow with several agents delegates, so it cannot be put into a harness without subagents, and it says why. When a workflow wants an agent that is not in the harness, a gap is shown — the agent is not added quietly.
Rig
Several harnesses under one purpose. One leads and must support subagents — a rig is delegation, just across a tool boundary. The others write or review. A workflow step goes to the member with the same role; when no such role exists, the one who leads does it.
What a rig gives
Reach is the union of the members' reach — Codex alone reaches only OpenAI, in a rig further too. The environment is their intersection: that is where the whole rig runs. When no environment has all the members, each runs somewhere else and tailscale connects them.
what is planned

Sessions on a whole rig and custom workflows. Today a session opens on a single harness and workflows are put in from a fixed catalog; the rig holds how the work would be split.

Environments design

Local, cloud and phone are the same entity — they differ only in what they are and how they are reached. An environment holds which harnesses are installed on it and how much work it can carry. It is operational state, not a setting, so it lives as the Environments tab in Fleet.

why tailscale and not SSH

Nothing is open to the internet, and no keys to someone else's machine are kept anywhere. An environment is reachable because it is on the same network — not because it has a public port. A port that does not exist cannot be misconfigured.

Panels, Fleet and TUI design

Working with several agents at once has two modes: an overview of everything, and a few sessions side by side where the actual work happens.

Fleet is the overview — a grid of all sessions with their last lines of output. It is not a work surface; it is for picking what deserves a panel.

Split panels are the work. The surface holds four sessions side by side, each with its own dock, its own harness and its own model. One session is the same as four, just with one panel — the default state is not a different mode, it is a special case of the same thing.

Focus
Only one panel takes the keys, and its frame shows it. ⌥1–⌥4 switch between panels; ⌘1–⌘3 stay with projects, so they do not get in each other's way.
Fifth panel
You cannot go beyond four. Pinning a fifth replaces the one you are currently on, and says so — silently dropping a panel would be worse than refusing.
Draft text
Re-rendering a panel must not eat what is typed in another one. Draft messages survive every re-render; otherwise one delivered message would erase the work next to it.

TUI

The GUI/TUI switch changes how the same session is read, not how it runs. The same messages, just without bubbles: prompt, text, time, full mono.

why not green on black

A terminal aesthetic would break the whole material system and add nothing. Mono on its own already says it is machine output — and a transcript is read, so it belongs on paper, not on glass. What a harness cannot do is not offered: Pi has no TUI, so that button is disabled.

Sync across devices planned

A message sent from mobile should be on the desktop before you manage to switch windows. That is the whole brief.

A message carries where it came from. Without that, sync can only be claimed, not shown — and a claim about speed that cannot be seen on the screen is marketing. That is why a message from the phone has the device printed on it, not just the time.

The chip in the top bar holds the latency and the list of devices with when each last checked in. It is an observation, not a setting — there is nothing to switch there, because on the client side there is nothing to switch.

status

Sync is still planned. The app shows the state it would carry, so that you can judge whether it is the right thing — not to make it look finished.

Control plane

What is happening right now — attempts, budgets and rejections across all projects. It is the state of the control plane, not history.

Queue. The bar on a row is the nine steps; its position says where the run stands. A row selects the run for the Attempt and Gate Zero sections.

Dispatch paused. Runs already in progress finish, nothing new is started and gates cannot be confirmed.

Gate Zero

The order is load-bearing. Gate Zero is deterministic and fail-closed — the first rejection stops the rest, so green tests below it mean nothing.

Stations and drain

Writes go in one direction: manifest → sandbox → diff → gate → ledger. Nothing is rewritten backwards.

Murmur drain finishes what is running and takes nothing new. The queue is not cleared.

Run history

The station column says where the run ended — for a finished run it is LEARN, for a stopped one the station that holds it. The findings column is the number of lens findings in the manifest, not the number of bugs in the code.

Crew

Crew is the same runtime for non-technical teams. The agent holds the phase; what it may not decide on its own, it hands to a human as a task — including the reason. People can be on several teams, and a task always carries the agent that handed it off.

A decision carries where it came from. A budget gets approved on the road, not at a desk — that is why a task has the device printed on it from which the human decided, and a message carries a delivery mark. Here the device is a property of the human, not of an environment: the marketing team does not run on tailscale, so it is not the same entity as the machines in Sync.

What Crew deliberately does not show. Harness, model choice, split view or TUI. Delegation here goes agent → human, not agent → agent, so whoever picks banners in the creative team does not care whether Codex or opencode2 runs underneath. It would be a demo of the plumbing, not of a feature.

Appearance

Material effects are local — they are kept in the browser, not in the GF config. Turning everything off leaves the plain material without light; useful for screenshots and slow machines.