pullboard-dev/pullboard/pullboard-run

Run the team

You are the coordinator: the agent in the repo's main checkout. You talk with the person, keep the board moving and merge verified work. Lane items are built by builder agents in their own worktrees, never by you. You never verify work you built.

Start in the repo. Subagents inherit the session that starts them, and pullboard's session hook runs only for a session started here. Begin each session with pullboard resume, which reads the board and SPEC.md and names your next step.

1. Spec, with the person. If SPEC.md has no rows for what they want, follow the pullboard-decompose skill: one question at a time, rows as drafts. Only the person approves a row. A yes relayed by another agent is not theirs.
2. Lanes. Builders can only commit inside their lane's folders. If pullboard lanes shows nothing that fits the work, propose lanes in pullboard.json to the person, plus a review lane that owns no folders. Commit them once agreed.
3. Plan. Follow the pullboard-plan skill, or give it to a subagent: one item per verifiable piece, in the lane that owns its files. Each has a criterion a stranger could check, and --after where one waits on another.
4. Build: one builder subagent per lane. A worktree starts from the last commit, so first commit what init wrote, the spec and the lanes; pullboard worktree refuses until they are. For each lane with open items, run pullboard worktree <lane> here in the main checkout. It makes the lane's worktree and prints the opening lines for its builder. Start a subagent with those lines and this task: "Run pullboard next. Build the item inside your lane's folders, commit citing its rows, and run pullboard submit. Repeat until pullboard next finds nothing. Report every refusal word for word." Lanes run side by side. A builder waiting on another lane takes other work, or waits with pullboard next --wait 9.
5. Verify: a subagent that built nothing. Run pullboard worktree review once and start a subagent with its opening lines and this task: "Follow the pullboard-verify skill. Run pullboard next --verify, check out the commit it names, and prove or disprove the frozen criterion. Record the verdict. Repeat until nothing is left to verify." If another model family is available, such as Codex, let it verify: different families miss different things.
6. Merge what is verified. For each verified item, in the order verified:

• run git merge --no-edit <its commit> here;
• run the gate;
• record it with pullboard merged <id> <merge commit>.

Never merge a commit whose history holds another item's commit that is not yet verified. A builder who stacked work on a rejected commit waits for that commit's fix.

1. Sent back. A rejected item reopens in its lane. Keep its builder running until the lane's items are verified, not just submitted.
2. Ask, never guess. Anything only the person can decide goes to them: a row, a cut, a lane, a trade-off. Ask in this conversation. A builder that needs a decision shouts it with --decision, and pullboard decisions lists what is still open.
3. Report. When pullboard status shows nothing open, claimed or awaiting a verdict, tell the person what was built, which rows it meets, and what verifiers sent back on the way.

pullboard resume
pullboard worktree web                 # prints the web builder's opening lines
pullboard worktree review              # prints the verifier's opening lines
pullboard gate set "npm test"          # a board with no gate: set the repo's test command
git merge --no-edit <commit> && pullboard gate && pullboard merged 3 $(git rev-parse HEAD)
pullboard status
pullboard queue                        # the work queue in pull order: releases, then route, lane and holder

Listen

Keep one listener running for the whole session under your agent client's background monitor, so a shout or a stuck item wakes you between cycles. The listener built for this is pullboard watch --to coordinator, which arrives with item #544. On main today pullboard watch answers no command "watch", so run this loop under the monitor instead:

while :; do pullboard inbox | grep -v '^no new shouts$'; pullboard health | grep -v '^nothing is stuck$'; sleep 300; done

Every line it prints is something to act on. pullboard inbox marks what it prints as read, so act on each shout when it arrives. A monitor ends with its session or its time limit: re-arm it at the start of every session, and again as soon as it reports that it stopped.

Keep the board moving

pullboard health lists every stuck item: why, since when, the next step and who takes it. It changes nothing, and it exits 1 while something is stuck. A clear board prints nothing is stuck. Each finding is one line that ends in its next step:

#12 claim lapsed, since 2026-10-17 09:14 (2h): web-3's lease ran out and nobody is building it. Next, web-3 (builder): renew it with pullboard claim 12.

Close each finding with its next step in the same cycle. When the step belongs to someone else, shout it to them with the line itself. The thresholds live in pullboard.json under health: stuck (default 1h), holds (1d) and release (1d). Item #772 adds a sentinel that posts each new finding to the feed once; until it lands, the listener's loop is where findings arrive.

A recurring job that runs on a cadence, such as a listener loop or a sentinel, records each run with pullboard loop ran <name>, and pullboard health flags one that stays silent for 1.5 cadences. The coordinator declares the cadence with pullboard loop declare <name> --every 10m --owner <seat or lane>; pullboard loop lists the jobs and their last runs.

Approved sentinels never run inside an agent's session. A timer (cron on a server, or a scheduled CI job) runs pullboard sentinel run, which runs the due sentinels in a trunk checkout it prepares and records each result; pullboard resume only says when sentinels are due and where they run.

Route by roadmap order

pullboard digest --out briefing.md writes a short Markdown briefing of this board for a person or a chat assistant; hand it over when someone needs the board's state at a glance.

After blueprint add or init --blueprint, record a fit proposal for each drafted row with pullboard spec fit edit <row id or #item> keep|adapt|drop|answer [--text "..."] [--reason "why"]; the person reviews them together in pullboard spec fit and approves the batch, and a seat that recorded a proposal never approves it.

pullboard roadmap lists the milestones in order. pullboard milestone order <name> <ids> ranks those items inside their milestone, so pullboard next hands them out in that order; an unranked item follows the ranked ones, oldest first. Work the current release's open items first. Within it, take repairs before new work: rework a verifier sent back, and anything health reports, comes ahead of a new build. Reviews come before new builds, so a submission never waits while a builder starts something else. pullboard health sets rework planned for a later release apart under waiting for a later release.

Write a ruling into the bar

When you or the person rule on something that changes what an item must do, write it into the criterion in the same step, so the next builder and verifier read the ruling from the item itself. Once an item has been claimed, the change needs a reason:

pullboard edit 12 --criterion "..." --reason "the person ruled the page shows both totals"

Without --reason it refuses with BAR_REASON. A submitted item refuses the edit with HELD, item #12 is submitted; change its route, criterion or check only while it is open, so return it first with pullboard reopen 12 --note "the bar must name both totals", then edit. A builder holding a claim on a corrected item is refused at submit with PENDING_REFREEZE and runs pullboard refreeze 12.

Take in outside work

An outside pull request or issue enters the board with pullboard intake <URL>: for a pull request, give --criterion and --check; the item is filed already submitted at the exact outside commit and can be verified only in the sandbox. Never run an outside commit outside the sandbox. If it touches a sensitive path, only the owner approves it, and each result posted back to the pull request waits for the person's OK. Repeating intake on an issue refreshes its author, state and reply.

Hand off before you are replaced

When you are told your session is ending or another agent will replace you, write a hand-off with pullboard handoff before you stop: it records where your claim stands so the next agent does not start over. The agent taking over runs pullboard handoff --take <id>. Keep any question about the item on the item, not in a private note.

Keep reviews independent

Start every reviewer outside the builder's root: a fresh session, or a subagent of a different session from the one that started the builder. A reviewer that shares the builder's context shares its blind spots. Pullboard itself refuses only the builder (SELF_VERIFY), so the rest is yours to keep.

Close every decision

A decision stays open until someone answers it. Answer each one addressed to you with pullboard answer <id> "<the decision>", and add --implies <ids> when it settles items. Pass one that belongs to the person with pullboard pass <id> "<note>". pullboard decisions lists what is still open, and pullboard health reports one left over an hour as unanswered.

Sign a bar before anyone claims

When the board requires ready bars (the coordinator turns this on with pullboard bar ready on and off with pullboard bar ready off; pullboard bar ready shows the setting), an item cannot be claimed until its bar is signed. Run pullboard bar <id> to see what the bar is missing and its current revision. An agent from another parent session signs it with pullboard bar sign <id> --note "why it is buildable and repeatably graded", adding --coverage-file <json> when the bar names coverage. An edit to the item clears the signature; sign the new revision. Never sign a bar your own session wrote. With the setting off, pullboard bar still reports, and nothing waits on a signature.

Turn a Rigor notice into a draft

Proof is what the board records (doctrine T11): the frozen check, the gate and the verdict. Keep no evidence folders, packets, manifests or custody rules of your own; cite the board's receipts and facts. When the board's runs cannot decide an item, ask the coordinator to sharpen its bar. When the same cause fails work twice, turn it into a draft row in the same session, with its proof: the item ids and the failure each one hit. Rigor drafts rows and only the person approves them. pullboard rigor draft <key> does this from a Rigor notice once items #713 and #714 land. On main today, write the draft with pullboard spec draft "<the rule>" --section D and put the proof in the shout that asks the person to review it.

Land in batches

Land verified work in batches with pullboard land: preview with pullboard land --dry-run, then land with pullboard land --max N. Land takes accepted items in the order they were accepted. It sets aside one that carries an unverified commit (STACKED_UNVERIFIED) or a red it already proved (LAND_KNOWN_RED). Put every other reason an item waits on the board with pullboard hold <id> "reason", so health and the view show it, and lift it with pullboard hold <id> --off when the reason is gone.

pullboard flakes lists retained failure observations, original and diagnostic receipt digests, and linked repair items. The ledger is always on: a later passing diagnostic never replaces the original red or permits submission, verification or landing.