Your agents ask, you rule once, the ruling sticks

3.1 · Your agents ask, you rule once, the ruling sticks 2:06

Narration: a synthetic copy of the narrator's voice · real screens of a demo Foreman with made-up data · Foreman 0.1.0 (main @ a433b56f8) · built 2026-11-02

Script (click a line to play from there)

1. 0:00 An agent has a question. You answer it once, with one click, and every agent after it finds the answer instead of asking you. Here's how.
2. 0:08 This is Foreman, episode three point one. The narration is a synthetic copy of my own voice.
3. 0:15 Every project can keep a Charter: a rulebook in its own repo, in plain Markdown. Titles, chapters that start with a why, and numbered articles.
4. 0:26 Here's acme-web, a made-up shop, and its agents, made up too. Maple builds the checkout. Juniper reviews the work.
5. 0:34 Maple hits a question nobody has ruled on. Does a shopper need an account to pay? It searched the Charter first, and found no answer.
6. 0:43 So instead of stopping to ask you in a chat, Maple files a case. The options, and the one it recommends, with a reason. Then it keeps working.
7. 0:52 Juniper disagrees, and says so as a position, with evidence. Positions are arguments. Nobody counts them as votes.
8. 1:00 Foreman tells you when something waits on you. The pill at the top counts the decisions, on every page.
9. 1:08 Decide mode shows one case per screen. The plain question, each option as a card with its pros and cons, and the rules it touches.
10. 1:16 Pick an option. You get ten seconds to undo it. Then it's written down.
11. 1:22 Foreman adds a dated note under each article the case cites, marks the case decided, and commits both to the project's git.
12. 1:31 Then it types the ruling straight into Maple's terminal. Maple picks it up, and carries on.
13. 1:37 Here's the part that sticks. Later, Birch starts on the phone checkout, and searches the Charter before asking anyone. The answer is already there.
14. 1:46 Open the article's story, and it's all in one place. Who asked, who objected, what you decided, and why. Nobody asks you twice.
15. 1:56 You ruled once. The ruling lives in the repo, with its reason, for every agent that comes after. Next, how to write articles your agents can cite.

When several agents work on one project, they keep running into questions only you can answer. Without somewhere to put the answers, they end up in chat, in handoff notes and in your head, and the next agent asks again. Foreman's Charter gives those answers a home: the project's own rulebook, in its own repo, which agents read before they ask.

This page follows the video. Every screen is a real Foreman, running a made-up shop called acme-web with made-up agents (maple, juniper and birch).

The story in one minute

1. An agent hits a question. It searches the Charter first. Nothing answers it.
2. It files a case instead of stopping to ask you in chat: one plain question, the options, the one it recommends and why. Then it keeps working on something else.
3. Other agents argue. Each can add one position (for or against an option, with evidence). Positions are arguments, not votes.
4. You decide in Decide mode: one case per screen, one click, ten seconds to undo.
5. Foreman writes it down (a dated note under each cited article, the case marked decided, both committed to the project's git) and types the ruling into the asking agent's terminal.
6. The next agent finds it. It searches the Charter before asking, and the answer is there.

A rulebook in the repo

Charter › Rulebook: titles, chapters that open with a Why, numbered articles (§ 1.2.1, § 1.2.2 …).

A project's Charter is plain Markdown in a charter/ folder at the root of its repo: title files (title-1-shop.md), chapters that start with Why:, numbered articles (§ 1.2.2), and one file per case under charter/cases/. You can read and review it without Foreman. Foreman finds a project's Charter when the project is registered (charter-projects.json in Foreman's data folder) or when an agent works in a git repo that has a charter/ folder.

An agent asks: filing a case

Agents › Terminals › Peek: maple searched the Charter, found no answer, filed a case and moved on.

Agents file cases with Foreman's MCP tool charter_file_case (connect Claude Code under Connect › MCP › "Connect Claude Code" so agents have the Charter tools). A good case answers in seconds:

• question: one plain line you can answer with a letter;
• options: one short sentence each, with pros, cons and next (what happens if it is chosen);
• one option recommended, with a one-line reason;
• today: how things are now, shown as the "before";
• cites: the articles it touches.

The case page: options, the agent's context, and juniper's position against A, with evidence.

Other agents add positions with charter_position: for, against or abstain, the option, pros, cons and evidence (a commit, a test, a log line). One position per agent; positions are refused once the case is decided. Foreman shows a tally, labelled "positions", and never decides by counting them.

You rule once: Decide mode

Decide mode: the plain question, each option as a card, and below it the articles the case touches.

When a case waits on you, the "1 decision" pill appears at the top of every dashboard page, and the Charter item in the sidebar carries a badge. Charter › Queue opens straight into Decide mode:

• Press 1 or 2 (or click Choose A) to pick an option; Enter takes the recommended one.
• Add a note first if the agent should know something when it acts on it.
• Not now and Skip leave the case for later.
• After a choice you have ten seconds to Undo; then Foreman writes it.

Only you decide, and only on this Mac's dashboard: there is no MCP tool for deciding, and a remote admin view can read the Charter but not change it.

Written down, and sent back

The article now carries a dated note from the decision, and the commit that wrote it.

A decision does three things:

1. The case gets its decision (who, which option, when, your note) and moves to decided.
2. Every cited article gets one appended line, never edited afterwards: Note (2026-11-02, owner; CASE-0003): Yes: guest checkout, … Reason: …
3. Git: Foreman commits exactly those files (charter: CASE-0003 decided (option A)), leaving any other work in the repo alone.

Then it tells the agent that asked: it types one line into that agent's tmux terminal, found by the Claude session the case was filed from (or the agent's name).

The ruling arrives in maple's terminal as one line, ending "When done, record it with charter_acted."

If the agent that asked can't be found (its session has ended, say), nobody is told, and you can hand the decision to an agent: Foreman starts a new Claude Code session in tmux (charter-<case>) to carry it out. That is episode 3.4.

The ruling sticks

Later, birch searches the Charter before asking, and finds the ruling. (The search on screen is a real query against the demo's Charter.)

Agents search with charter_search and read articles with charter_article; asking that they do this before asking you is itself a rule worth writing (acme-web's § 2.1.1). Under Story, every article tells how it came to be: who wrote it, which cases argued about it, who objected, what you decided and why.

Charter › Story for § 1.2.2: the whole history in one place.

What proves it works

Everything in the video happened for real, in one take, on a fresh demo Foreman (guides/episodes/3.1-rule-once/take.mjs):

• CASE-0003 was filed and argued through the same writes the agents' MCP tools make;
• the click on Choose A in Decide mode produced the commit charter: CASE-0003 decided (option A) in the demo project's git, with the dated notes under § 1.2.1 and § 1.2.2;
• Foreman reported the ruling as delivered to maple's terminal, and the terminal shows the typed line;
• birch's search, run afterwards against the demo's Charter, returned the new note.

Notes on the demo

• The project, agents, cases and dates are made up. maple, juniper and birch are stand-in terminal scripts in the demo, not Claude Code sessions; Foreman treats them exactly as it treats agents.
• The demo is a throwaway Foreman with its own data, off the tailnet, so its Home page shows the router and fleet broker as down. That is expected for a demo and has nothing to do with the Charter.
• Narration: a synthetic copy of the narrator's voice, made on this Mac with Foreman's own voice service.