plandesk-foreman
Runs the Plan Desk board floor — takes one task or a whole frontier of todos, grooms each into a build contract, cuts slices, dispatches implementation to worker CLIs, verifies their claims, gates each slice by its risk lane, and commits what clears. Use whenever asked to work a task, ship a ticket, take the next task, clear the todos, run the board, or hand implementation to a worker — even when the factory is not named.
- License 许可
- MIT
- 最近更新
- 2026-10-04
- Stars
- ★ 16
- Forks
- 1
01 前言 Front Matter
- name
- plandesk-foreman
- description
- Runs the Plan Desk board floor — takes one task or a whole frontier of todos, grooms each into a build contract, cuts slices, dispatches implementation to worker CLIs, verifies their claims, gates each slice by its risk lane, and commits what clears. Use whenever asked to work a task, ship a ticket, take the next task, clear the todos, run the board, or hand implementation to a worker — even when the factory is not named.
- argument-hint
- <task id | 'next' | 'all todo' | goal name> [--to <worker>]
- user-invocable
- true
03 SKILL.md 正文
Foreman
Takes board work to committed. Planning fills the board, the foreman runs the floor, workers build, a human decides what merges.
The policy this runs on lives beside it and is not repeated here — the cycle contract in factory.md, dispatch and verification in protocol.md, worker selection in routing.md, gates in lanes.md, slice shapes in slicing.md, the brief's additions in brief.md, the worker's standard in workmanship.md. Read the ones a run touches.
Workflow
-
Preflight. Confirm the tree is clean, no dispatch is already running (
pgrep -f), the board answers, and at least one worker in workers/ passes its probe. Each of these turns a long run into wasted tokens if it fails halfway, so check before starting, not on the way past. Open the run withstart_agent_run. -
Resolve the scope. A named task label (looked up with
list_tasks/get_task) works one item.nextcallsget_next_task.all todoor a goal name takes the whole frontier — onlytodotasks whose prerequisites aredone;scopeandbacklogare waiting on a human and are not yours to release. Read each task's linked spec before judging it. -
Groom inline — do not dispatch this. Judge each task against the Definition of Ready in groom-task and rewrite anything short of it with
update_taskyourself, following that skill's procedure — it is the one readiness bar this project keeps, so do not invent a second one here. Grooming is judgment about intent, and shipping that judgment to a worker is how a plan drifts from what was actually wanted. If a task cannot be groomed without a decision you do not own, return it toscopewith a comment naming the decision, and carry on with the rest.Grooming as a prelude to dispatch does not wait on groom-task's own
approvegate: post the groom comment (what changed, what was inferred) for traceability, then proceed — the rewrite is reviewed together with the work it produced, at the item's own lane gate, where a human can still reject both. A groom left uncommented is still the violation. -
Cut slices when the frontier is wider than one item. One task needs no slicing. Several become deliverable units per slicing.md — complete paths through the layers they touch, sized to one worker's context, grouped so parallel workers do not edit the same lines. The grouping goes in each brief's WBS snapshot, not in a file of its own — the task descriptions already hold the build contract, so do not restate the work anywhere.
-
Dispatch implementation — default async. One dispatch per tree, per protocol.md. Pick the worker from routing.md unless one was named; a named worker wins, and several named workers split the slices across worktrees. Build the brief from brief-template.md — copy, substitute, paste workmanship in full — which carries protocol.md's five-section contract: the bar, the result contract, the ground, the WBS snapshot, and a live
Context:link.Fire async unless the slice is trivial. Background is the default for every real dispatch. Run foreground only when the slice is genuinely small (one obvious edit, expected under a few minutes) and the user asked for inline work. The recipe:
- Reset the task's
.agents/factory/runs/state and capture the baseline per protocol.md dispatch step 2 — a stale result file fires the monitor instantly, and verification needs the pre-dispatch test counts to diff against. - Run the worker's
probe; substitute{prompt_file}and{repo_path}in itscommandtemplate — flags come from workers/, never from memory. - Append the log redirect the engine owns:
> .agents/factory/runs/worker-<task>.log 2>&1(never put redirects in worker files). - Background through the harness —
run_in_background: trueon the Shell/Bash tool. Never append&or wrap innohup … &; that orphan-detaches, the harness fires a false "completed", and the real leaf keeps writing to a tree nobody is watching. - Arm the monitor in the same step, also backgrounded — the watch loop in protocol.md's Watching a live dispatch. Do not dispatch and "remember to watch later."
- Do not poll the harness completion notification. Wrapper exit is
unreliable (orphan shell, transient API blip). The monitor watches
.agents/factory/runs/result-<task>.json; useAwaiton the monitor shell when you are ready to verify, or continue other foreman work while it runs.
Stdin is per worker — getting this wrong backgrounds a hang:
delivery workers rule prompt via stdin claude, cursor, opencode < {prompt_file}— no< /dev/nullprompt via @fileor argpi, codex, grok pi: @{prompt_file}; codex:"$(cat …)"; grok:--prompt-file— add< /dev/nullMint the live link explicitly:
create_share_linkon the task (or the goal, for a multi-slice run),expires: 7d, and put the returnedmarkdown_urlin the brief asContext:. The worker has no MCP access, so this is the only way it reads live board state instead of a copy that goes stale the moment someone edits the task. Derive the WBS snapshot fromlist_tasks+list_edgesso the worker sees the agreed order and the paths a later item owns; a worker given one node and no map finishes the next one too.Never dispatch a
kind: 'decision'task. Its resolution is a conversation with whoever owns the outcome; a worker given one will answer its own question and record a fabrication as a decision. Report it by task label as awaiting a human and take the next frontier item — a decision task blocks only itself; unlike a lane gate it does not stop the run. - Reset the task's
-
Stage the moment a worker returns, before reading anything. Review takes minutes and unstaged work is defenceless for all of them; staged work survives a later
git checkoutbecause git restores it from the index. This ordering is the cheapest real protection in the whole run.Unless the dispatch was killed. No result file means it ran no gates and wrote no result, so the tree holds unverified partial output rather than work product. Discard it and re-dispatch clean per protocol.md — staging it makes salvage look like a deliverable, and the next reader cannot tell the difference.
-
Verify the claims. Follow the verification sequence in protocol.md — gate integrity before re-running anything, then suppressions, then per-package test counts against the pre-dispatch baseline, then debris. Exit codes decide, not the worker's summary. A dispatch that fails verification is recorded and re-scoped, not retried blindly with the same brief.
-
Review what landed. Read the diff — the hunks, not the worker's transcript, from the staged index (
git diff --staged). For anything beyond an isolated change, dispatch a fresh reviewer that did not write the code, a different model family per routing.md, and give it the acceptance criteria and the diff. A reviewer inheriting the author's context confirms the author's assumptions. -
Apply the lane. lanes.md decides what happens next:
autocontinues;approveposts a diff summary;fullneeds the independent review from step 8. Who resolves the gate is lanes.md's call — a human when attended, the agent itself under autonomy with the reasoning chain posted first. Either way the resolution lives as a comment, which is the human's override surface. -
Commit when the gate clears — each slice on its own. One work item, one commit, the subject naming the task; the work stays staged until its gate resolves and enters history only after. Commit the moment the gate clears — batching commits until the end of a run means a single later failure puts every earlier success at risk, and it breaks the 1:1 between history and board. Flip the task to
donein the same step, callrecord_agent_progress, and append the cycle to.agents/factory/runs/metrics.jsonl(tracked — include it in the slice's commit). -
Take the next slice, or stop. Repeat from step 5 while the frontier has work and no gate is blocking. On long runs, pulse per heartbeat.md — a worker with no output, no file changes, and flat CPU is stalled rather than thinking, and the tree may already hold most of its work. Close with
complete_agent_runand report at diff level — naming tasks by label, not bare id (see.plandesk/skill.md): what shipped, what is waiting on a human, what failed and why.
Stopping
Stop the run and report — do not work around it — when:
- a lane gate needs a human,
- a worker returns
blockedwith a question you cannot answer from the board, - a gate cannot be satisfied honestly, or
- the frontier empties.
Skip dispatch, but continue the run, when a frontier item is kind: 'decision'.
Unlike a lane gate — which blocks the tree because uncommitted work occupies it —
a decision task blocks only itself. Report it by label as awaiting a human
and take the next frontier item.
Never merge, and never release scope → todo; both belong to whoever owns the outcome.
Leave the board true on the way out. A status that does not match what actually happened is worse than no status, because the next run trusts it.
Boundaries
- Groom inline, dispatch implementation. Reversing this is the common failure.
- Never dispatch a
kind: 'decision'task. Its resolution is a conversation with whoever owns the outcome; a worker given one will answer its own question and record a fabrication as a decision. Report it as awaiting a human and take the next frontier item. - Do not restate the readiness bar; it lives in groom-task and a second copy would drift from it.
- Do not restate the task's spec in a brief — link it live.
- Do not run two dispatches in one tree; give concurrent slices their own worktrees.
- Do not batch commits, and do not commit work whose gate has not cleared.
- If a change balloons past its triaged size, return it to
scopewith the reason rather than absorbing it.
04 同仓库更多 Skills
connecting-agents
Agent conventions for Plan Desk MCP — task labels, docs, notes, files, artifacts, sharing, edges, and agent runs.
.plandesk
暂无简介
plandesk
暂无简介
plandesk-timebox
暂无简介
plandesk-standup
暂无简介
plandesk-standdown
暂无简介