Foreman task handoffs
Foreman creates draft coding jobs from Tasks comments. Install Foreman and Tasks in
the same group and run one Foreman daemon for that group. Post a comment whose entire
text is foreman (case-insensitive; surrounding whitespace is allowed). The resulting
draft keeps the task's title and body unchanged and credits the comment author.
Review the draft and choose Plan or Implement before any agent work starts.
Plan asks which planner to use and defaults to Sol. Implement asks which implementer
to use. The choices are Grok, Sol, Opus, Astra, and Fable. Opus and Fable run through
Claude Code on the daemon machine's Claude subscription. Those runs stay on that
login: Foreman does not pass API keys or Claude settings, loads no MCP servers, read-only calls
cannot edit or run commands, and the calls do not write into the interactive Claude
session. An unknown model blocks the job.
After the daemon activates Foreman at startup, local comment inserts are handled
immediately. Every 30 seconds the daemon also sweeps all pending comments, covering
remote/PWA comments, edits, and comments synchronized later from devices that cannot
run isolated providers. Each sweep queries comments containing foreman, checks
for exact trimmed matching, and reads all matching pages from the beginning. Ordinary comments do not use recovery
RPC pages. Tasks is an optional dependency; missing or delayed registration is retried without blocking Foreman.
Ordinary UI comments use this live path even when optional fields, such as logged time,
are unset; the Tasks contract omits undefined fields before transporting the event.
The trigger's comment ID is also the job ID, so listener/recovery races converge on one job. The trigger comment link is immutable after job creation. The job is saved first, then Tasks receives a system acknowledgement with a link to it, and the trigger is soft-deleted. Failed acknowledgements or deletions are retried without recreating the job. A task that has not synchronized yet remains pending. Recovery does not require task creation-device metadata or a checkpoint file.
Foreman posts best-effort system comments when a plan or branch is ready for review,
when a job is done (with merged refs), or when it is blocked (with the reason). Tasks
comment failures do not undo job transitions. Follow the acknowledgement's job link,
or Open task in the Foreman header, to navigate between the two. These links use
?jobId= and ?taskId= in the current group, including when the destination tab is
already open. Links also open jobs beyond the list's first 500 records: Foreman fetches
the selected job directly and keeps it current on refresh. Foreman saves pending document
edits and waits for an in-progress detail action before switching jobs; a failed save
keeps the current job and its unsaved edits
open for retry and restores the URL to that job. Open the same link again to retry
saving and navigation. This also applies to the first external job link after a cold load,
before you have selected any jobs manually. Foreman keeps
its current jobId in the tab link, updates it when you select another job, and clears it
when you close or delete the job. This preserves selection while the UI loads and when
switching tabs. Tasks saves its selection and opens task details on mobile before removing
taskId from the link, including when you were viewing the task list or subtasks. Ordinary
mobile list selection still uses two taps to open details. Tasks
contract writes stay in the authorized group, use the authenticated caller for authorship,
and reject extra arguments that could impersonate another author or IDs from other groups.
Use one daemon per group. Deterministic job IDs prevent duplicate records but do not prevent two daemons from executing the same job. Multiple active daemons require a future lease/leader-election design. The local PID file is not a distributed lock.
Sequential child batches
After a job changes stage, Foreman refreshes its children before choosing between Children and the current document. A tab you choose during that refresh stays selected.
On a job that has only draft children, Children can stay on Review each child or switch to Run sequentially, review once. Start is available from a draft or a plan that is ready for review. Every direct child must still be a draft, and no child may depend on a later sibling, even through an outside job. The parent cannot depend on its own snapshot children, and a child cannot depend on the parent. An unfinished outside job waits for the batch to merge, so a child also cannot reach an earlier sibling or the parent through one. Parent dependencies must finish before children start and before combined review opens; a canceled dependency blocks the run. Other outside dependency waits keep the parent in Needs You.
Start sequential run asks which planner and implementer every child should use, defaulting to the parent's choices. Foreman writes those models onto each child before the run begins, so a model changed later on one child cannot send that child to a different agent mid-run. The parent's conversation records the models each child was routed to.
Foreman then plans and implements those children one at a time. It still runs
checks and model review for each child, and it does not stop for a human plan
or implementation review. The reviewer asks for another round on any must
finding, and on should findings when it judges the change not ready; the
implementer fixes each one or explains why it rejects it, and a new review
confirms the result. A child is never included on an unreviewed fix.
Successful children are collected onto one parent
branch. When the last child finishes, the parent opens a single review. Stage
for review, approve, and merge work the same way as any other job.
If a child fails, raises a blocking open question during planning or implementation, or tries to split again, the batch pauses. Earlier children stay included. A blocking question is a product or scope decision only a person can make, or a problem that keeps the work from being trustworthy. Checks the agent could not run, such as live device or hardware verification, an environment or permission it did not have, or a failure that is unrelated or pre-existing, are recorded as verification notes instead. They stay in the child's summary for the reviewer and for you, and they do not pause the run.
A child paused on blocking questions shows them in its header and offers two ways on.
Continue without changes keeps the implementation already on the branch, records your
optional reason, and runs checks and review on that work; use it when the answer does
not change the code. Retry implementation runs the implementer again; add a note
first when the answer should change the code. If a change request arrives during checks,
review, or a repair, Foreman runs the implementer with that feedback and checks and reviews
the result before including the child. A withdrawn decision requires implementation again,
even after a restart; the saved acceptance line alone cannot approve continuation.
Retry plan replans the child, or cancel the run. A retry can select a new model; omitting it
or naming it in clear keeps the frozen route, and an invalid model is rejected.
Canceling the parent, including from the combined review, also cancels children
that are not already done. A child reopened as a draft after that cancel can
run on its own through later planning and implementation, including automatic
merge when eligible. A merging child prevents cancellation before any other
child is saved as canceled. Interrupted cancellations finish after restart.
A child in the run cannot be deleted, moved to another parent,
started ahead of the child Foreman is waiting on, or turned into its own
sequential run. An included child is canceled only by canceling the batch. If
a snapshotted child goes missing, the batch pauses; restore that child and
press Resume sequential run, or cancel the batch. Empty or unreadable snapshots
permit only Cancel. Once all children are included, failures during the parent’s
own work offer the normal Retry plan, Retry implementation, and Retry merge
actions. Direct or indirect later sibling dependencies added after the run
starts are rejected. A paused batch does not offer a partial subset as the
final review. The fixed snapshot can start again from
draft or plan-review only when every direct child is a draft again.
Updating and clearing fields
Foreman 0.2.0 requires Peers 0.28.5 or later. Upgrading keeps existing jobs, notes,
and attempts, with no data migration or reset. The same six tools remain available:
write-job, add-note, record-attempt, delete-job,
create-job-from-task-comment, and recover-task-comments.
For write-job, omit a field to leave it unchanged. To remove an optional field,
name it in the clear array. Sending null leaves the field unchanged. For example,
to remove a job's prerequisites and return its children to individual review:
{
"operation": "update",
"jobId": "<job-id>",
"clear": ["dependsOnJobIds", "childExecutionMode"]
}
Clearing follows the same actor, stage, and batch rules as setting a field. Humans
can clear summary only with an update outside daemon-owned stages. The daemon
can clear dependencies only while the job is a draft. A started sequential run
keeps its execution mode and snapshot; its child models remain frozen except for
the supported retries. Required fields, unknown field names, and fields the actor
cannot change are rejected. If a field has both a value and an entry in clear,
the clear request takes precedence, subject to those rules.
The UI sends these clear requests when you remove the last dependency or choose
Review each child. The updated daemon also sends clear and converts legacy
operator calls containing null into clear requests. Activate Foreman 0.2.0 before
using clears through that daemon; ordinary writes continue to work with 0.1.0.