Waiting on you

Waiting on you is the one list of everything the run needs from you: the questions the agents asked, your owner tasks, a halt, a release that waits on a click, a slot that needs a decision, and notes about what Foreman did by itself. It is a tab on the dashboard, the Waiting on you panel on the Command centre, the “Waiting on you” count in foreman status, and the words of foreman decide list. This page is for whoever answers: what each card means, what every button does, and what happens next.

How the list is ranked

Each item has a kind: a decision (a question with options, or one answered in words), an owner task (a story only you can do), the halt (a failed release froze the release line), a release ready to promote, a slot that is parked or down, a run item (why the run is idle or needs you) or a learned change Foreman made itself. Each one also says what it blocks (the stories that cannot be built until it is dealt with) and what it frees (the stories that become buildable the moment it is).

Items fall into three groups. Now is anything you can act on today. Later is an owner task whose own blockers are still open; its card reads “Can start after ACME-12” and lists them. FYI is there to read, and never counts. The tab’s badge and the count in foreman status count only the now items, with a bundle of quick decisions counted once.

The now items are ordered by what unblocks most: the halt first, because it stops every slot; then a pause the run made itself, because nothing new starts until it is resumed; then the run being stuck; then urgent decisions (an agent asked with --urgent); then parked or down slots; then the item that frees the most stories; then the one that blocks the most; then the newest; then the id. Later items follow, fewest open blockers first, and FYI items last in the order they were made.

Above the cards the headline says where the run stands, and Go to it takes you to the one card to do first. The first state that fits wins: halted; paused (by you, for Jira with the time it went unreachable, or by the run itself with the reason); running but stuck; standby (“Standby: nothing to build. 3 stories wait on your tasks. Picks up new stories automatically.”); running, with what it builds and how many things need you; else idle, with how many stories wait on you and what the best item frees. The same words head the Command centre. When the run reaches standby with things waiting, it also emails you once, as Run, pause and stop describes.

foreman decide list prints the open items in the same groups (Needs you now, Quick decisions with the command that answers each bundle whole, FYI, then Answered, not yet applied); foreman decide list --all prints every item flat, answered and applied ones too.

Needs you now

A card says what to do, with one button per action and the full text folded under Details. A decision card also carries the agent’s explanation in plain words: What this story is for, What happened, Is anything damaged? (only when the run touched something outside the story), each option’s hint, and a Recommendation, whose option comes first.

Action	What it does	What happens next
An option button on a decision	Saves that option as your answer, with the note you typed if any.	The run picks the answer up at its next step, within seconds for most kinds (below). Until it is applied you can change it under Answered.
Send answer	Saves your words as the answer to a question with no options, or to a task the agent asked you for (a key, an account, a sign-off).	The story goes back to todo with your answer in a note for the architect, so the next pick takes it.
I fixed it (the halt)	Runs foreman health.	Only if its checks pass does the halt clear and the held stories ship, oldest first. Otherwise the run stays halted and shows what still fails.
Check now (a release ready to promote)	Runs foreman release watch now instead of waiting for the next 5-minute check.	The page shows the result shortly; the story moves to Done when its release finishes. See Parked releases.
Resume (the run paused itself)	Clears the pause.	The run picks the next story at its next check, for every free slot.
A slot button	One of the slot actions.	The slot moves as the table there says.

Some now items have no button because only a change outside the page can clear them: the config turned invalid under the run (“config invalid since HH:MM: <reason>; running on the last good config”), the run is not making progress (“Not building for N minutes”, from the progress watchdog), a “build next” request that cannot start after 3 tries, and Jira unreachable for more than 30 minutes (for its first 30 minutes it is an FYI, because a sleeping computer or a dropped network causes most of those and the refresher retries every minute).

Quick decisions

A bundle is every unanswered proposal of one kind that foreman learn made: follow-ups (“Follow up on ACME-12: 3 minor finding(s)?”) or traits (“Add a trait for developer: <rule>?”). The tab shows one card per bundle, headed “3 follow-ups from recent runs: 7 minor findings” or “2 trait proposals”, with a line per item.

Action	What it does	What happens next
Create all (Add all for traits)	Answers Create a follow-up story, or Add as a trait, on every item listed. Over 5 items it asks first.	The run applies the answers at its next check. Any that could not be saved stay listed.
Ignore all	Answers Ignore on every item listed. Over 5 items it asks first.	The run closes them at its next check. An ignored proposal is not made again unless you run foreman learn reopen <id>.
Answer one by one	Draws each item’s own card under the bundle.	You answer each as a plain decision.

From the command line, foreman decide answer --bundle follow-ups "Create a follow-up story" or --bundle traits "Add as a trait" answers a whole bundle, and "Ignore" drops it; the command prints each item it answered.

Your tasks

An owner task is a story only you can do; Owner tasks says how to write one. Its card fetches What you need, Takes, Steps and Done when from the task’s brief, or says none are written yet, and its why line says what finishing it frees: “Frees ACME-13 now. 2 stories wait on it.”, “Frees nothing by itself: ACME-14 also waits on ACME-9.”, or just how many stories wait on it.

Action	What it does	What happens next
Mark done	Marks the task done in the story source, the same change as foreman story done. Anything you typed goes with it as a note.	The stories waiting on it can be built; on standby the first of them starts at the next tick.
Open	Opens the task in Jira or shows its file path.	Nothing changes.

A task that has held a story back for more than watchdog.ownerTaskHours (24 by default) is repeated once by email, naming the story it holds.

Later and FYI

Later holds owner tasks that cannot start yet because a story they depend on is still open. Each card lists what it waits on, and the section is folded. When nothing needs you now but tasks wait, the tab says so: “Nothing you can do yet. 2 tasks open up as stories ship; the first after ACME-9.”

FYI holds what Foreman did or noticed by itself. These items never count and never block anything.

Action	What it does	What happens next
Undo (on “ACME-12 now waits for ACME-9”)	Takes the dependency Foreman added off the story’s depends_on again (for Jira, the “is blocked by” link is removed).	The story can be picked without it. Anything it waited on before stays.
Keep (same note)	Keeps the dependency and clears the note.	The story still waits and starts by itself once those stories are done.
Undo the change (on “Foreman learned L-3 for tester” or “Foreman changed L-3 for tester”)	Runs foreman learning undo L-3 at once: the rule goes back one version, or is removed when it was new.	Stories that start after that go without it; a story already running keeps the rule it started with.
Keep the change (same note)	Runs foreman learning keep L-3 at once: the rule stays and is no longer on trial.	Foreman stops watching it. foreman learning undo L-3 still takes it out later.
Got it (on “Foreman rolled back L-3” or “Foreman retired L-3”)	Clears the note; Foreman already took the change out after watching the stories that used it.	Nothing changes. foreman learning show L-3 has its history and the numbers.
Undo and close them (on “Foreman created 2 follow-up stories”)	Runs foreman learn undo <id>: each story still waiting to be built is closed as Done with a note; one already started is left alone.	Those findings are not proposed again.
Keep them (same note)	Keeps the new stories and clears the note.	The run builds them like any other story.
End them (on “N stray processes running”)	Ends the supervisors, hook runs and foreman learn or notify runs that are not this run’s, as foreman doctor --end-strays does.	The page says “Ended N stray processes.” and names any still running.

FYI items with no button: a story that is slow (“slow: ACME-1 in its fix round for 1 h 45 min”), the run about to restart on new code, a wait for the Claude API with when it tries again, the highest-priority story waiting on a file another story holds (“ACME-2 waits for ACME-1: src/a.mjs”), and the run having moved to your Claude subscription because the platform credits ran out, with the foreman claude use-key command that moves it back.

Under the cards, the Answered list shows answers the run has not applied yet, each with Change answer, and the Learned list shows one row per item Foreman learned (id, kind, roles, version, status and reason) with Undo on each still in force.

Every decision, in words

An agent asks a decision with foreman decide add; the story skill does so at fixed points, and foreman learn for its proposals. These are all the questions, with what each option does.

“ACME-12 could not pass review”, asked when the builder has used every round (the rounds setting) and the tester or a reviewer still rejects. How a story ships has the rounds.

Action	What it does	What happens next
Retry with a note to the architect	Puts the story back to todo with “Note for the architect: <your note>”.	The architect designs it again, then it is built and reviewed again. Recommended unless an earlier retry already left a note.
I’ll take it	Claims the story for you (foreman lock owner-claim) and blocks it with “Taken by the owner”.	Its branch and draft pull request stay. The run leaves it alone until you press Hand back under Taken by you.
Drop	Closes the story branch’s open pull requests, deletes the remote branch and blocks the story with “Dropped by the owner”.	Nothing is built for it again unless you unblock it.

“Close ACME-12: nothing to build?”, asked when the architect finds the story’s Done when already holds.

Action	What it does	What happens next
Close it as Done	Runs foreman story done with the architect’s evidence and your note.	Nothing is built and no pull request is opened. Recommended.
Build it anyway	Puts the story back to todo with “Note for the architect: the owner wants it built anyway” and your note.	The architect designs it, then it is built and reviewed.

“Decide for ACME-12: <question>” is the architect’s own question when it needs a choice only you can make; its options and hints are the architect’s. Whichever you pick, the story goes back to todo with “Note for the architect: the owner answered <question> with <option>” and your note, so the architect reads it on the next pick.

“Add depends_on: ACME-9 to ACME-12?”, asked when the architect finds the story blocked by stories not yet in its depends_on, while features.dependsOnProposals is on and features.autoApplyDependsOn is off (on, Foreman adds them and tells you with Undo instead).

Action	What it does	What happens next
Apply	Adds the listed ids to the story’s depends_on, keeping the ones it has.	The story is not picked until they are done, then starts by itself. Recommended.
Ignore	Changes nothing; the proposal is closed.	The story is picked again as it is.

“Add a trait for developer: <rule>?”, proposed by foreman learn when one finding keeps sending stories back, while features.learnTraits is on.

Action	What it does	What happens next
Add as a trait	Writes the rule into that builder’s traits, or into all.md when the builder is no longer in the config.	Every later story that builder works on follows it. See Agents and traits.
Ignore	Changes nothing; the proposal is closed.	It is not proposed again unless you run foreman learn reopen <id>.

“Follow up on ACME-12: 3 minor finding(s)?”, proposed by foreman learn after a story ships with minor findings, while features.followUps is on (with features.autoCreateFollowUps on, the story is created at once and you get the “Foreman created” note instead).

Action	What it does	What happens next
Create a follow-up story	Adds a story “Follow-ups from ACME-12” to the story source, listing the minor findings.	The run picks it up like any other story.
Ignore	Changes nothing; the proposal is closed.	Those findings are not proposed again unless you run foreman learn reopen <id>.

“Allow deletes for ACME-12?”, asked by the Salesforce pack when a release would delete metadata components. 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.

Action	What it does	What happens next
Allow the deletes	Runs foreman sf deletes allow ACME-12 and puts the story back to todo.	On its next release the deletes go ahead only if the change still deletes exactly the same components; if they differ, you are asked again.
Keep them out	Runs foreman sf deletes keep-out ACME-12 and puts the story back to todo with “Note for the architect: the owner wants nothing deleted in this story”.	It is built again to keep those components.

The buttons on every card:

Action	What it does	What happens next
Save answer	Saves your answer.	The run picks it up at its next step. Until then you can change it under Answered.
Mark done	Marks the task done.	Anything you wrote goes with it as a note.
Change answer	Opens the question again with your answer filled in; the run has not used it yet.	Save to replace it, or keep the old one.
Keep the old answer	Closes the question again without changing your answer.	Nothing changes.

How an answer is applied

The supervisor reads the answers every tick, 5 seconds apart. Answers that need no story session (a dependency, a dependency note, a learned change, a “Foreman created” note, Close it as Done, Build it anyway, a “Decide for” answer and any free-text answer about a story nothing holds) are applied on the next tick, even while sessions run. Review, trait, follow-up and deletes answers are applied when no session is running; a story session that reaches its own “owner’s answers” step applies whatever is still pending. Nothing is applied twice, and an item stays under Answered until it is. From the command line, foreman decide answer <item> <option> [--note <text>] gives the same answer; the item id (d-…) is in foreman decide list.

Slot actions

A slot is one copy of the repository, w1 to wN. Its lane on the Command centre, and its card here when it is parked or down, offers the actions its state allows. The same actions are foreman slot <wN> skip|takeover|park|unpark|resume|restart|resume-as-is|discard; Park after this story is park on a slot that is building. Every action is applied at the run’s next check.

Action	What it does	What happens next
Skip story	Stops this story’s session and leaves the story out for the rest of this run, standby included. The branch is kept.	The slot moves on. foreman status lists the skipped stories; foreman next <id> (Build this story next) builds it again.
Take over	Commits and pushes whatever work is in the slot’s folder to the story branch, claims the story for you and blocks it with “Taken by the owner”.	The slot moves on to another story. The story shows under Taken by you until you press Hand back.
Park	On an idle or down slot: parks it at once.	It picks up nothing until you unpark it.
Park after this story	On a building slot: lets the story carry on to the end, then parks the slot.	It picks up nothing until you unpark it.
Unpark	Puts a slot you parked back to idle.	It takes the next story that can be built; a story it was parked on is picked again by priority.
Resume	On a slot parked for a crash: carries the story on from where it stopped, keeping what was done. On a down slot: puts it back to work. On a slot held for the Claude API: queues the story now rather than at the end of the wait.	The slot goes back to work on the same story. A slot held by a halt offers no Resume; it waits for I’ve fixed it.
Restart fresh from main	Throws the story’s work away: the folder is reset, the local branch deleted, and the story built again from the start.	The slot starts the story from the base branch.
Resume as is	On a slot parked because its folder has changes that belong to no story: keeps them. With a story, they are that story’s work and it carries on; with none, they are put aside in a git stash and the slot takes a new story.	The slot goes back to idle and picks or resumes.
Discard changes and reset	Hard resets the folder to the base branch and removes the changes for good. It asks you to confirm first.	The slot goes back to idle; a story it held is picked again by priority.

Which actions show: a building slot offers Skip story, Take over and Park after this story; an idle slot, Park; a down slot (its environment failed twice and could not repair itself), Resume and Park; a slot held after committing, Resume and Take over, or Take over alone while a halt holds it; a slot parked for a crash (the session crashed twice on the story, or reached the hard ceiling at 4 times the build limit), Resume, Restart fresh from main, Skip story and Take over; one parked because its folder is dirty, Resume as is and Discard changes and reset; one you parked, Unpark. Slots explains the states.

The run’s controls

The Command centre’s controls are the same commands as Run, pause and stop.

Action	What it does	What happens next
Pause	Starts no new stories; stories in progress carry on.	Each slot finishes the story it has, then waits, until you resume.
Resume	Lets the run start new stories again, and clears a pause the run made itself.	Every free slot picks at the next check.
Stop the run	Asks you to confirm, then stops the run once the stories in progress finish.	Start it again with foreman run.
I’ve fixed it	Runs foreman health.	Only if its checks pass does the halt clear and the held stories ship, oldest first.
Workers	Sets how many slots build at once, saved for this computer as the workers setting.	Applied at the next pick; a slot above the new count finishes its story first.
Build this story next (Request)	Asks the run to build the chosen story next. Only stories that can be built now are listed.	It goes to the next free slot, and clears a skip on that story.
Hand back	Gives a story you took over back to the run.	Your claim is removed and the story goes back to todo, so the run can pick it again.