Your first story

This page walks one story from an empty project to a merged pull request, for someone who has installed Foreman and wants to see it work once before leaving it to run. It covers /foreman:init, the story file, /foreman:story for one story by hand, the stages a story goes through, /foreman:run for a run that picks stories by itself, and what the dashboard shows meanwhile. Every command is on Every command.

Run /foreman:init

In Claude Code, in the project, run /foreman:init. It asks one question at a time, offers what it detected as the default, never asks for a key’s value in the chat, and never names or opens an env file. It does six things, in order.

1. Detect. It runs foreman init detect, which prints one JSON line: suggested, a starting config, and found, what it saw. It reads package.json (a check script becomes the check npm run check, else a test script becomes npm test; a package-lock.json, pnpm-lock.yaml or yarn.lock becomes the install command npm ci, pnpm install --frozen-lockfile or yarn install --frozen-lockfile, run when that file changes or node_modules is missing), pyproject.toml (uv run pytest and uv sync with a uv.lock, else pytest and pip install -e .), a Makefile with a test: target (make test), the job names in .github/workflows (the CI jobs a release waits for), a stories or docs/stories folder holding a file with id: in its frontmatter, CLAUDE.md and the git remote. A pack may claim the project: sfdx-project.json makes it a Salesforce project, and its findings are shown as plain lines. If foreman.config.json already exists, init says so and never replaces it.
2. A pack’s questions. For a Salesforce project the Set up page has no screen for the pack’s block, so /foreman:init asks the pack’s questions in the chat first (the sandboxes, the branches, the release stages and path) and writes the config itself. See Salesforce set-up. The Salesforce pack is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org.
3. Hand-off. It starts foreman setup in the background and gives you the address of the Set up page, which walks every step, keys included. Then it asks one question: did the page open, or does this machine have no browser? On a project with no config yet, the page’s first step is a form: the project’s name, where the stories come from (story files or Jira), the story folder or the Jira site and filter, the check command with a button that runs it once, and the CI jobs to wait for. Save writes foreman.config.json. The Set up tab has every step.
4. No browser. Init asks the same form’s fields in the chat and pipes the answers to foreman init write --answers, which writes the same file the page would. Then it runs foreman setup next, gives you its lines one at a time, and loops until it prints “All set”. When a step needs a key, you run foreman keys set NAME in a terminal of your own and paste the value; it reads it without showing it.
5. What the write does. foreman init write refuses a config that would not load, a stories block its source refuses, and a story folder outside the project, and writes nothing then. Otherwise it writes foreman.config.json (an existing file needs --force), turns the plugin on for the project in .claude/settings.json, adds the state folder (.foreman/, or stateDir) to .gitignore unless a line already covers it, and, for markdown stories, creates the story folder with one example story, S-1.md, unless the folder already has story files (--no-example skips it). It prints one line for each.
6. Doctor. It ends with foreman doctor and explains each FAIL in plain words from its fix line; warnings get a mention. Then it tells you how to start: /foreman:story <id> for one story by hand, or /foreman:run to let Foreman work through the stories on its own.

The example story it writes is a good first one, because it changes one file and nothing else:

---
id: S-1
title: Try Foreman on a small change
status: todo
depends_on: []
---

## What

Add one line to the README saying this project is built with Foreman.

## Done when

The README has the line and the project's checks pass.

## Progress notes

_Newest first._

Write or pick a story

Stories are markdown files with frontmatter (id, title, status, depends_on), one per file in the story folder (stories.dir). A file without an id: is not a story. The body says what to build and, under a “Done when” heading, how anyone can tell it is finished; the architect turns that line into a check someone can run, and the tester checks it against the running code. status is one of todo, in-progress, blocked, done or retired, and depends_on lists the ids that must be done first: a story is offered only when every one of them is. For stories kept inside the repo, Foreman records progress in .foreman/, and the story’s own pull request is what marks it done: the commit that ships it also marks the story file done, so the base branch reads done exactly when the pull request merges. Every field, groups, progress notes and follow-ups are on Story files.

Stories can also come from Jira, where each issue a JQL filter finds is a story; see Stories from Jira. On a Salesforce project they can come from Cases; see Stories from Salesforce. A story that is yours to do, not Foreman’s, is an owner task and is never picked; see Owner tasks.

To write your own, keep the first one small, say what changes in a sentence or two, and write the Done when as something that can be checked rather than a feeling. When several stories are ready, Foreman picks a story already in progress first, then the earliest group, then the lowest id, skipping any whose dependencies are not done; see How Foreman picks.

Build one story with /foreman:story

/foreman:story S-1 builds and ships one story in the Claude session you run it from. A run uses the same skill: the supervisor starts a fresh, unattended session for each story and runs it there. By hand it is the way to watch one story end to end.

The session is the foreman for exactly one story. It does not build or review the story itself and never overrules a stage that rejected it; it moves the story between the agents, releases it and keeps the story’s record true. It reads the config once (foreman config show) for baseBranch, remote, branchPrefix, stateDir and generated. The story’s branch is <branchPrefix><id in lower case>: story/s-1 with the defaults.

1. Before it starts. If HALT is in the state folder, a release failed earlier and only you can clear it: the session reports what the file says and stops with halted. Changes to generated paths are discarded one by one. Uncommitted changes on the story’s own branch are its work in progress and are kept; changes anywhere else belong to someone and stop the session with halted, saying exactly what is there. It starts nothing itself: the slot’s environment is the supervisor’s job, and a check that fails because something is not running is a finding, not a reason to start it.
2. Pick. foreman story next --id S-1 --strict offers the story only when every story in depends_on is done. Then foreman story start S-1 marks it in progress and tells the command centre. A story with history is looked at first: a pull request already merged is closed after foreman health --site says the live site answers; a branch holding the story’s commit with no uncommitted work goes straight to the release; a branch with work in progress carries on from it. Otherwise the branch is cut fresh from origin/main.
3. The pipeline. foreman workflow-args S-1 prints the workflow’s arguments, and the session runs the foreman:pipeline workflow with them. It comes back passed, blocked (the architect found it cannot be built now), deferred (the design needs files or exclusive resources this slot does not hold: the session claims them and runs again) or failed (still rejected after every round). The next section says what happens inside.
4. Commit. foreman checks --changed --reuse --start and foreman checks --wait <id> run the project’s checks, reusing the tester’s run when the tree is exactly the one it recorded; a story is never committed without a passing full-suite result for its exact tree. A failing check gets one fix round, then a second failure fails the story. Each generated entry’s regenerate command runs, foreman story finalize S-1 --note "<what now works>" marks the story file done for stories kept in the repo, and one commit holds the whole story, message S-1 <title>, with no attribution lines. A story that changed no file still gets an empty commit, because the release refuses a branch with none.
5. Release. foreman ship --story S-1 waits for the ship lock (one release at a time), then runs the project’s ship steps: bring in the base, push, open the pull request, wait for CI and whatever the project configures after that (merge, migrate, deploy, verify). The release is automatic: a story that passes every stage and CI is merged without asking. Exit 0 is shipped. Exit 2 is CI or the checks failing, 6 a conflict with the base, 10 Salesforce deletes waiting on your approval, and 4 or 5 a failure after the point of no return, which writes HALT: nothing is retried or repaired until you say “I’ve fixed it”. See How a story ships.
6. Close. foreman story done S-1 --note "<note>" says what now works, how it was verified and the pull request, then foreman story end records the outcome, the findings left open and the builder, so Foreman can learn from them. The reply ends with one line the supervisor reads: FACTORY_RESULT: shipped S-1, or blocked, failed, halted, deferred, held, ready-to-promote or empty.

Anything you must decide goes to you through foreman decide add and shows on Waiting on you; your answers come back through foreman decide pending at the start of the next session. The architect’s plan is kept in <stateDir>/plans/S-1.json, so a story started again after a stop does not pay for a second design. Three mode words change the path: after-halt closes or fails a story whose halt you fixed, fresh throws the old work away and builds from the base again, and group-summary writes a finished group’s summary. More on Story sessions.

What each stage does

The pipeline has four phases, Architect, Build, Test and Review, run by five agents. Each reads the project’s CLAUDE.md first, follows the project traits you give its role, and uses the skills Foreman learned (see Agents and traits). A Salesforce project swaps in the pack’s agents (sf-architect, sf-admin, sf-developer, sf-agentforce, sf-tester and sf-code-reviewer).

Name	What it does	Tools
architect	Reads the story and the code around it and decides whether it can be built now. It is blocked when it needs something only you can supply, builds on a story that is not done, contradicts the code, or its Done when already holds (“Nothing to build”). When you must choose between options it names, it asks you the question with a recommendation. When ready, it picks the builder by each builder’s use line and writes the design: every file the story will create, change or delete, the exclusive resources it needs, what changes file by file, the test plan and the Done when as a check. It never edits a file and never runs the checks.	Read, Grep, Glob, Bash
builder	Builds the story from the design, tests first: writes the tests in the test plan and sees them fail for the right reason, then implements until they pass, nothing beyond the story. Runs the quick checks (foreman checks --changed --quick) while it builds and before handing over, and keeps the project’s docs true where CLAUDE.md asks. In a fix round it fixes each finding and says what it changed. It never writes foreman.config.json, the settings or the key files.	Read, Write, Edit, Grep, Glob, Bash
tester	Decides whether the story works, trusting nothing it has not checked. Runs every check itself (foreman checks --changed, never --reuse), checks the Done when against the running code and looks for the cases the builder missed. A failing or skipped check is a blocker. Approves or rejects; does not fix.	Read, Grep, Glob, Bash
compliance-reviewer	Runs beside the security reviewer once the tester approves. Checks the change does what the story and its design say and no more, that each CLAUDE.md rule it touches holds, that no test, lint rule, type check or CI step was weakened to get it through, and that no dependency was added beyond what the rules allow. Cites file:line for every finding.	Read, Grep, Glob, Bash
security-reviewer	Runs beside the compliance reviewer. Reviews the change for access checks on every new entry point, input validation, injection, secrets or personal data in code or logs, internal detail leaking in errors, unsafe deserialisation and the holes the project’s CLAUDE.md names. Cites file:line.	Read, Grep, Glob, Bash

The two reviewers run in parallel, and only after the tester approves: reviewing code the tester has just rejected is wasted work. A reviewer set to run through another CLI (roles.reviewers[i].engine) is handed to the review-relay agent, and when that engine is missing, out of time or gives no verdict, the reviewer’s own agent runs instead.

Every finding has a severity: blocker, major or minor. A round is one pass of tester and reviewers over a build. Blocker and major findings send the story back to the builder for a fix round, which the next round tests and reviews again; minor ones pass through, stay on the story’s record and can become a follow-up story later. A story gets rounds build attempts in all (the first build plus the fix rounds; the default is 3, from 1 to 10), and one still rejected after the last is failed and goes to you. A stage that returns nothing counts as a blocker. Each role runs on the model its role is set to (roles.<role>.model), or the session’s model when unset. Then the story goes to commit and release as above. The command centre’s lane shows the stages as Design, Build, Test, Review, Commit and Release.

Start a run with /foreman:run

A run is foreman run, which starts the supervisor: it builds up to slots stories at once, each in a fresh unattended Claude session inside its own slot (w1, w2 and so on: a git worktree under .foreman/worktrees/ with the project’s env file linked in and its own environment), and releases them one at a time. In Claude Code, /foreman:run starts, watches, steers and stops a run in words. Before it starts one it checks that no run is going (foreman run refuses a second and names the pid), whether foreman status says paused (the run would start paused), whether HALT is there (the run would start held), that git status --porcelain is empty, pulls the base branch, and names any open items from foreman decide list. Then it runs foreman run <N> --workers <W>, reads the end of the log after about 30 seconds, and tells you what started.

Name	What it does	Default
N	How many new stories to start. With no number the run lasts until foreman stop: when nothing is buildable it waits on standby and starts new stories as they come.	until stopped
--workers W	How many slots build at once, 1 to slots. foreman workers W and the Workers control change it while the run goes; a change applies at the next pick.	the workers setting (1)
--exit-when-idle	Stops instead of standing by, with “Nothing left to build.”	off
--foreground	Stays attached: Ctrl-C, kill and a closed terminal are passed to the supervisor, and the command returns its exit code.	off: the run is detached
--dry-run	Prints what each slot would start and changes nothing. It may run beside a live run.	off

foreman run starts the factory in its own session, so closing the terminal or the Claude session that started it does not stop it; its output goes to .foreman/logs/supervisor.out. It prints the supervisor’s pid, the dashboard’s address (port console.port, 4317 by default) and the log, then returns; a supervisor that stops before writing its pid is reported with the end of its log. To keep it going after a crash or a reboot, run foreman service install in the project. That hands it to launchd on a Mac, or to systemd --user on Linux, which start it each time you log in and again after a crash. With the service installed, a plain foreman run starts the service, which runs until stopped and takes no story or worker count; for a count, run foreman run --foreground N in your own terminal. foreman stop finishes the stories in progress and stops the run until your next foreman run, and foreman doctor says whether it runs as a service. foreman doctor also counts stray Foreman processes (supervisors, hook runs, foreman learn or notify runs) that tests or manual checks left running, and foreman doctor --end-strays ends them. Pause, resume, stop and the slot actions are on Run, pause, stop.

With two or more stories running at once, two of them never change the same file. Each design lists the files its story will change, and the story claims them before it is built. A story whose design names a file another running story is changing waits until that story ends (it ships, or stops for another reason), then starts by itself; the board’s recent list shows it as deferred, with the reason. A story whose earlier design named files or resources that a running story holds is not started again until they are free. A deferred story also waits while any running story’s design names one of the files it needs, even before that story has claimed them, and foreman status names that story. One that was deferred twice on the same story waits until that story ends. foreman status lists each waiting story under “Waiting on running stories” (“ACME-2 waits for ACME-1: src/a.mjs”). A “build next” request for a waiting story stays first in line and starts it as soon as they are free. A file a story lets go of is kept for up to 30 minutes for the highest-priority story waiting on it, until that story claims its files or its session ends; another story whose design names it waits for that one. A lower-priority story whose earlier design names a file a higher-priority story waits on is not started meanwhile. Waiting on you and foreman status name the top waiting story and the story holding its file (“FYI: The highest-priority story waiting on files: ACME-2 waits for ACME-1: src/a.mjs”). Files every story touches are never claimed: fileLocks.ignore in foreman.config.json (globs, ["CHANGELOG.md"] by default; your list replaces it) and every generated path. See Slots.

On a Mac, features.keepAwake (on by default) keeps the computer from idle sleep while a run is going, and from sleeping at all while it is on mains power. macOS may still sleep when the lid is closed and no external display is attached. After such a sleep the run logs a late wake and asks Jira again before it holds picking.

On Vercel, add {"git":{"deploymentEnabled":{"story/*":false}}} to vercel.json, or each story spends two deployments (a preview and the release) and a small plan runs out; foreman doctor warns when it is missing.

What the dashboard shows while it builds

The dashboard opens on the Command centre. Under Now building there is one lane per slot, and each lane shows its story, its state (Building, Waiting to ship, Held, Parked, Down or Idle), the stage pipeline from Design to Release with the current stage marked, and a card per agent that says in plain words what the agent is doing, its stage, run time, steps and model, with Show command for the raw command and View conversation for its conversation as it happens. Beside the lanes, the Waiting on you panel carries the same headline as the tab and counts what needs you now and what can wait. The run details card has five tabs: Live feed, the run’s events as they happen; Up next, the stories in line, with Taken by you under it for the ones you took over; Finished, the stories that ended, with Ready to promote for releases that wait on a click elsewhere; Progress; and Tokens, token use per agent once a story finishes. Controls hold Pause and Resume, I’ve fixed it when a halt waits, the Workers picker, Build this story next, and Stop, which asks first. Readout counts the agents online and the run’s numbers. A tour of every tab is on The dashboard.