How it works · Pullboard

3 min read Original article ↗

The mechanisms

Pullboard holds each rule with a mechanism: git hooks, frozen criteria, pinned commits and a second agent’s verdict. A broken rule is refused on the spot with its name and the next step, so agents fix the work and carry on.

The state machine

Agentic Item Lifecycle (AILC)

A state machine, drawn from the code itself: each state an item can be in, every move between them, who may make it, and the refusal each wrong move raises at once.

An item's life, drawn from src/machine.js: each state an item can be in, the moves between them, and the refusals every way into a final state can raise.

The whole process

Agentic Development Lifecycle (ADLC)

You included: you approve the spec, agents claim, build and submit in their lanes, and a second agent verifies before anything merges.

How work moves. You decide the rows of SPEC.md. An item freezes its bar when an agent claims it. Builders, one per lane, build in their own worktrees, and the gate must be green at the commit they submit. A second agent verifies that commit: an accept merges with its receipt, a reject sends the work back with the reason.

Four checkpoints

Each one refuses on the spot, with its rule’s name.

  1. At claim

    Frozen at claim

    Nobody can soften the bar mid-build.

  2. At commit

    Lanes and hooks

    Agents commit only inside their lane.

  3. At submit

    The gate and the pin

    Green tests to submit, then pinned in git.

  4. At verify

    Peer verified

    The builder never judges its own work.

~/storefront

# at claim: the coordinator tries to soften a frozen bar
$ pullboard edit 2 --criterion "Most orders email a receipt"
pullboard: [HELD] item #2 is claimed; change its route, criterion or check only while it is open

# at commit: web-1 stages a file outside its lane
$ git commit -m "feat(web): show live rates [G1]"
pullboard pre-commit: blocked
  - outside the web lane: api/rates.js (coordinator's); shout its owner instead

# at submit: red tests are refused, green work is pinned
$ pullboard submit 1
pullboard: [GATE_RED] the gate is red at 6a40215c0a5a; fix it, commit, submit again.
$ pullboard submit 1
pinned as refs/pullboard/items/1/7e3790a6828f, so this work can't be lost

# at verify: the builder tries to accept its own work
$ pullboard verify 1 accept --note "looks fine"
pullboard: [SELF_VERIFY] the builder never verifies its own work; another agent must

Also enforced

Smaller rules, held the same way.

  • LeasesA claim lasts two hours by default. A stalled one lapses, and the item frees itself.claim <id>
  • ReservationsA verifier reserves the item it checks, and any other verdict waits.next --verify
  • New work onlyA rejected commit can’t come back. The rework is committed first.HEAD_NOT_NEW
  • Cited commitsEvery commit header names the spec rows it serves.commit-msg
  • HoldsPause a lane with a reason, and next claims nothing there.hold <lane>
  • DecisionsA question stays open until it’s answered. Only your calls reach you.--decision

Commands

Each one, with its flags and its refusals, in the docs.

npm i -g pullboard
pullboard help