Glossary

The words Foreman uses, each in two or three sentences, with a link to the page that explains it. Read it when a status line, an email or a dashboard card uses a word you do not know. The Salesforce terms describe a pack that is a preview: its release paths pass their own tests, but no story has yet shipped through them on a live org, and the Gearset path has not run against a live Gearset pipeline.

Terms

Architect. The first agent in the pipeline. It reads one story and the code around it, decides whether the story can be built now, picks the builder by its use line and writes the design and test plan, including the files the story will change. It writes no code. See Agents and traits.

Auto-pause. The pause Foreman makes itself when three stories in a row miss, so a broken set-up does not burn through the backlog. Only a ship or a ready-to-promote clears the count; a story waiting on you, a deferral or an environment ending neither counts nor clears it. foreman resume starts the run again and counts afresh. See Run, pause, stop.

Baseline. The Salesforce pack’s record of what an org already fails before any story touches it: its failing local Apex tests and its org-wide coverage, kept per org under the state folder until foreman sf baseline --refresh. A deploy whose only failures are in the baseline is an inherited failure and is never blamed on the story. See Build orgs.

Brief. The text of a story the agents build from: the body of a markdown story file, a Jira issue’s description or a Salesforce Case’s Description. It says what to build and ends with the “Done when” line. See Story files.

Builder. The agent that builds a story from the architect’s design, tests first, and fixes what the tester or a reviewer found. A project can have several builders under roles.builders, each with a use line the architect picks by; the default is one named developer. See Agents and traits.

Check. One of the project’s test or lint commands listed in checks in foreman.config.json, each with a when: always for the full suite, or a glob for a check that runs only when matching files changed. Agents run them through foreman checks, which records each run so a check runs once per tree and its result is shared. See How a story ships.

Claim. The record that a slot is building a story, or that you have taken it, kept as a small file under the state folder. A story also claims every file its design names before it is built, so two stories never change the same file at once. See Slots.

Decision. A question Foreman leaves for you on Waiting on you, with options such as “Retry with a note to the architect”, “I’ll take it” or “Drop”. Answer it on the dashboard or with foreman decide answer; Foreman applies the answer on its next loop. See Waiting on you.

Deferred. A story that was picked but cannot start because its design names a file or an exclusive resource another running story holds. It waits until those are free, then starts by itself; foreman status names the story it waits for. See How Foreman picks.

Dev Hub. The Salesforce org that creates scratch orgs, named in salesforce.build.scratch.devHub. It may be the production org, within the production block; it is never a build org or a stage. See Build orgs.

Done when. The line or heading in a story that says how the tester knows the story is finished. The tester verifies it against the running code before it approves. See Story files.

Exclusive resource. Something only one story may touch at a time, such as the database schema, named in resources in foreman.config.json with the paths it covers. A slot takes the resource’s lock before building a story whose design touches it, and a story that needs a held resource is deferred. See Slots.

Feature switch. An on or off setting under features, such as followUps or notifications. foreman features off <name> turns one off for this machine; --team writes it to foreman.config.json. See Settings and switches.

Follow-up. A new story foreman learn proposes to fix the minor findings a shipped story left behind. You create or ignore it on Waiting on you, or features.autoCreateFollowUps creates it at once with an Undo. See How Foreman learns.

FYI. An item on Waiting on you that tells you something Foreman already did, such as a learned change or a dependency it added, and that you can undo or acknowledge. FYIs are never counted as things waiting on you. See Waiting on you.

Halt. The state after a release failed past the point of no return or after a deploy went wrong: Foreman writes a HALT file in the state folder and starts no release until you clear it. Press I’ve fixed it or run foreman fixed; foreman health checks the problem is gone first. See When things go wrong.

Learned skill. A Claude Code skill Foreman writes by itself from a lesson, at most 6 KB, copied into each slot as .claude/skills/foreman-learned-<slug>/. It is on trial like a learned trait and can be undone with foreman learning undo. See How Foreman learns.

Learned trait. A rule of at most 400 characters Foreman adds to one role, or to every role, from a lesson. The agents read it after your own traits, under a heading that says CLAUDE.md and your traits win, and it is tagged [L-n] so a finding can name it. See How Foreman learns.

Lesson. A problem that keeps coming back, found in the last 60 stories: findings that repeat in meaning, a failed story, a fix that did not fix, your retry note, or a repeated tool error. The learner proposes what each lesson should become. See How Foreman learns.

Local setting. A setting value kept in settings.json in the state folder, for this machine only. It wins over the team value; foreman settings set <name> <value> without --team writes one. See Settings.

Miss. A story that did not ship because of something the pipeline did: a rejection, a crash or a watchdog stop. Three in a row cause an auto-pause. An ending the environment caused, a block, a wait or a deferral is not a miss. See Run, pause, stop.

Notifier. The adapter that sends you notifications, named by notify.adapter: none writes them to the outbox, email-resend emails them through Resend. With features.notifications off, every notifier is the outbox. See Notifications.

Outbox. The outbox/ folder in the state folder, where the none notifier writes each notification as a JSON file instead of sending it. The Jira and Salesforce story sources have outboxes of their own for a write the service did not take. See Notifications.

Owner task. A story that is yours to do, such as a Jira issue with the owner label or a Case with the owner value. Foreman never picks it; its card on Waiting on you shows what you need, the steps, how long it takes and when it is done. See Owner tasks.

Pack. A bundle of defaults, agents, ship steps, doctor checks and environments for one kind of project, chosen with pack in foreman.config.json. The one pack today is salesforce. See Salesforce overview.

Park. A slot or a release set aside. A slot is parked when its story crashed twice or hit the watchdog’s hard limit, and waits for you to unpark, skip or take it over; a release is parked when a step cannot finish now, such as a promotion someone clicks later. See Parked releases.

Production block. The Salesforce pack’s rule that no deploy reaches production, enforced in Foreman’s sf wrapper and in the Bash guard however the org is named. An org marked "production": true in salesforce.orgs takes only an allow-list of commands: queries, record changes, describes, retrieves and scratch org creation. See Production stays yours.

Quick check. The faster command a check may carry as quick, for a change in progress. The builder runs it while building; the tester runs the full suite. A quick run is never reused. See How a story ships.

Ready to promote. The status of a story whose release parked: every check passed, its slot is free, and the release finishes later. foreman release watch, which the run does every 5 minutes, checks whether it finished and moves the story to done. See Parked releases.

Release. What happens after a story is committed: foreman ship runs the ship steps in order and merges the pull request. Releases run one at a time, through a ship lock, and a halt freezes them all. See How a story ships.

Reviewer. An agent that reviews a story’s changes once the tester approves, and reports without fixing. The defaults are a compliance reviewer and a security reviewer; a reviewer can also run through another CLI with engine. See Agents and traits.

Round. One pass of build, test and review. When the tester or a reviewer rejects, the builder gets a fix round; rounds (default 3) caps how many before the story fails. See How a story ships.

Run record. One JSON file per story session under runs/ in the state folder: the result, cost, turns, minutes per stage, rounds, serious findings and the tokens each agent used. foreman report reads them; features.costMetrics turns them off. See Costs and reports.

Runner. The machine that runs Foreman unattended in the cloud: a container built from the Foreman runner image, or a GitHub Actions job. It clones the project, builds, pushes the state branch and waits. See Run in the cloud.

Sandbox pool. The Salesforce slot environment where salesforce.build lists several sandboxes and each slot builds in its own. Before a story starts, Foreman checks the org is the sandbox it expects and undoes the last unmerged story’s changes there. See Build orgs.

Scratch org. A Salesforce org made from the Dev Hub for one story and deleted once the story closes, when salesforce.build is { "scratch": ... }. A sweep deletes the org of any story that has been in no slot for 5 minutes. See Build orgs.

Ship step. One step of a release, named in ship.steps: merge-main, push, pr, ci, merge, deploy-github, smoke, watch and the Salesforce pack’s own. Each can fail with its own exit code and some write a halt. See How a story ships.

Slot. One copy of the repository, a git worktree under worktrees/ in the state folder, named w1, w2 and so on, where one story builds. slots (1 to 8) sets how many exist; a change takes effect at the next restart. See Slots.

Stage (pipeline). Where a story is in its session: architect, build, test and review, then commit and release. The story session records them with foreman stage and the command centre shows them. See How a story ships.

Stage (Salesforce release). One of up to four orgs a story is deployed to in order after it merges, each { name, org, branch? } in salesforce.stages. stopAt names the last stage a story reaches, QA or UAT and never production. See Stages and release paths.

Standby. What a run does when nothing is left to build: it stays up, lets go of keep-awake, and picks up a new story, an unblocked one or an answered decision by itself. --exit-when-idle stops the run instead. See Run, pause, stop.

State branch. With state.store: "branch", an orphan git branch (foreman-state by default) checked out as the state folder, so a laptop and a runner share one copy of the run state. Logs, slot worktrees and caches stay on each machine. See Run state on a branch.

State folder. .foreman/ unless stateDir says otherwise: everything Foreman writes about a run, such as claims, locks, decisions, run records, logs, the learned items and the local settings. It is kept out of git. See Files Foreman writes.

Story. One unit of work Foreman builds end to end: a markdown file in stories/, a Jira issue the JQL filter finds, or a Salesforce Case. It has an id, a title, a brief and a “Done when”, and its own branch and pull request. See Story files.

Taken by you. A story you took over with “I’ll take it”: Foreman claims it for you, blocks it with “Taken by the owner” and leaves its branch and draft pull request alone. Hand it back with foreman handback when the run should carry on. See Waiting on you.

Team setting. A setting value written into foreman.config.json, so everyone who runs the project gets it. foreman settings set <name> <value> --team or Save for the team writes one; a local setting on a machine wins over it. See Settings.

Tester. The agent that runs after the builder: it re-runs every check itself, verifies the “Done when” against the running code and looks for the cases the builder missed. It approves or rejects, and never fixes. See Agents and traits.

Tick. One unit of background work. foreman learning tick runs the learner after a story and evaluates the items on trial; foreman cloud tick is one GitHub Actions job’s worth of work: pull the state branch, build at most one story, learn, push. See How Foreman learns and Run in the cloud.

Trait. A short rule added to a role’s prompt without replacing the agent, from .claude/foreman/traits/all.md, .claude/foreman/traits/<role>.md or roles.<role>.traits. A pack’s traits come first, so yours win. See Agents and traits.

Trial. The watch Foreman keeps on a new or changed learned item: the next learning.window stories that use it (5 by default), or 14 days, compared with the 10 stories before. It rolls the item back at once when a finding names it or two trial stories fail, and at the end keeps, retires or rolls it back. See How Foreman learns.

Waiting on you. The dashboard tab, and the same list in foreman status and foreman decide list, of everything the run waits on, ranked by what each answer frees, in sections Needs you now, Your tasks, Quick decisions, Later and FYI. Only what you can act on now is counted. See Waiting on you.

Watchdog. The timers that stop a stuck session: watchdog.quietMinutes (30) when it prints nothing, watchdog.buildMinutes (120) when the story makes no progress, and a hard limit at 4 times the build limit, after which the slot is parked. A release gets 15 minutes of grace past both. See When things go wrong.

Worker. How many stories build at the same time, set by workers (1 by default) and never more than slots. When you lower it while more stories run, the run drains: those stories finish, and no new one starts until fewer than the new limit are running. See Slots.