pullboard

Accumulated judgement for agents. Agents are good at tasks and bad at projects: every new session starts without what you decided, so you become the glue. The agents scale; your judgement doesn't. Pullboard is a structural approach to orchestrating agents coherently over long-term builds, so you can trust your agentic workforce to fill in the blanks the way you would, without re-prompting them.

Vibe code a real product. Agents build from a spec you approved, in lanes that keep them out of each other's way, and nothing they build is done until a second agent verifies it against the requirements you agreed. Pullboard is a coordination queue for serious software. It's how we develop our quantitative systems.

You follow progress, answer questions and approve changes from one board, and the team picks up where it left off. Coherency is built in: agents shout to each other and cite the items and code they mean. It's a vibe-first, spec-driven, test-proven methodology that reserves judgement for the human in the loop.

Philosophy

You do not explain twice. You rule the agents. Hierarchy is enforced. Judgement is yours. Declare it, and the Doctrine (the house rules for agentic development) stands. You speak the constraints, agents fill in the blanks. The Spec is canon. Then code. Then proof.

Key concepts

Five primitives. Everything else is built on them.

• Items. The tasks. Each has a bar it is checked against, and one agent works it at a time.
• Shouts. How agents talk. Questions go up the chain, and only your calls reach you.
• Spec. The plan, one row per requirement. Only the rows you approve count.
• Doctrine. Each rule has an enforcer, from a git hook to review.
• Activity. Every claim, submit, reject and accept, in order. Nothing happens off the record.

Why

Past the demo, the same things break.

• It said done. It wasn't. Another agent checks the work, at the exact commit.
• It forgot what you decided. Decisions live in your spec, not in a chat that ended.
• Two agents, one file. Each agent gets its own worktree and lane.
• A fix broke something. Nothing is submitted until your tests pass.

On Pullboard itself, a second agent's check catches one in three tasks that already passed their own tests.

How it works

Pullboard gives agents a shared plan, separate lanes and proof before work counts.

• Spec. Approved rows in SPEC.md are the contract, frozen when an agent claims the work.
• Doctrine. DOCTRINE.md holds the repo's rules. Hooks enforce what a machine can check.
• Lanes. Each agent works in its own worktree. Claims are atomic, and items can wait on others.
• Proof. Submit needs a green gate. Then a different agent verifies that exact commit.

You decide what to build. Agents build it and check each other's work. This is the Agentic Development Lifecycle (ADLC).

Questions

Agents ask when a call isn't theirs to make. Their coordinator settles what it can, and only your calls reach you.

[!TIP] Recommended best practice: work deeply with one agent, your coordinator. It fans work out to the lanes and writes your preferences down, so you never explain twice. Always let one agent lead the others.

Doctrine

A Spec is what you build. Doctrine is how you build it.

• Doctrine: "We keep only the data we need."
• Spec: "A shopper can pay by card in one step."

Every repo starts with Pullboard's standard doctrine. Add to it, override it, or decline any part of it.

Spec

Every requirement is one row of SPEC.md, in one format:

- <id> [<status>, <priority>] <what must be true> | gate: <what proves it>

For example:

- G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js

The id is a section letter and a number. A row stays a draft until you approve it, and only approved rows count.

Receipts

We build Pullboard this way, and nearly one in three items goes back. One receipt:

#13  worktree prints a subagent's opening lines

     REJECT  BEHAVIOR_MISMATCH  by tests-2
             "the printed cd line double-quoted the token without escaping it;
              copying it expanded the token away and exited 1"

     resubmitted 85f0f5d
     ACCEPT  CRITERION_MET  by tests-2
             "runs the printed cd line with a conflicting value and reaches the
              real target; removing either escape makes the test fail"

Pullboard View

Your agents work in terminals. You watch them here: every project on this machine, live on one page.

• Needs you: only your calls. Decisions passed up, rows to approve, held lanes.
• Timeline: every item's claims, submits and verdicts, with the reason for a reject.
• Actions: add items, answer decisions, shout to a lane, hold a lane.
• API: it runs on local API v1, which your own scripts can use too.
• Export: view --export writes a static, replayable snapshot.

pullboard view

What's being built, what's in review, and the calls only you can make, in one place.

Get started

Thirty seconds to see it, then your own repo. You need git and Node 22.13 or newer.

Installation

npm i -g pullboard
pullboard tour

On a throwaway repo, you approve one rule: greet a blank name as "world". The coordinator files it, a builder builds it, and a verifier tries a blank name and rejects it. The builder fixes it and adds a test. The verifier breaks the fix on purpose, sees the test fail, and accepts. The coordinator merges it with a receipt.

Project setup

Give your agent this line in an empty or existing git repo.

Install Pullboard and set it up here; it's for <what you are building>.

Your agent installs Pullboard, runs pullboard init and commits the setup. It then walks you through setup in the view it opens. You approve your requirements and answer its questions.

You can also run it yourself.

init writes your spec, doctrine and agent instructions, and installs the hooks and the board. Commit what it wrote, then open Claude Code in the repo and say what to build. That agent becomes your coordinator.

pullboard init
git add -A && git commit -m "chore(repo): set up pullboard"

Manual workflow

Every step the coordinator takes, you can take yourself from the repo's main checkout.

## G · Goals: what the client asked for
- G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js
- G2 [draft, aim] Saved carts follow a shopper across devices. | serves: G1

Write the spec in SPEC.md.

Then set the gate and the lanes in pullboard.json, as in Configuration.

pullboard add web "Checkout" --specs G1 --criterion "card payment takes one step"

File the work. Its bar freezes when an agent claims it.

pullboard worktree web
cd ../myapp-web-1
pullboard next