pullboard.dev · lives in your git repo · no account · no dependencies · never calls a model
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.
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.
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.
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.
Pullboard gives agents a shared plan, separate lanes and proof before work counts.
- Spec. Approved rows in SPEC.mdare the contract, frozen when an agent claims the work.
- Doctrine. DOCTRINE.mdholds 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).
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.
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.
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.jsThe id is a section letter and a number. A row stays a draft until you approve it, and only approved rows count.
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"
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 --exportwrites a static, replayable snapshot.
pullboard viewWhat's being built, what's in review, and the calls only you can make, in one place.
Thirty seconds to see it, then your own repo. You need git and Node 22.13 or newer.
npm i -g pullboard
pullboard tourOn 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.
Set it up once, then talk to one agent.
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"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: G1Write 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
pullboard submit 1A builder claims it, commits citing the row as feat(web): pay by card [G1], and submits green.
pullboard worktree review
cd ../myapp-review-1
pullboard next --verify
pullboard verify 1 accept --note "paid in one step; without the fix the test fails"A verifier checks out that exact commit, then accepts with evidence or rejects with a reason.
A few commands keep every agent on track.
- pullboard worktreemakes a lane worktree and prints a subagent's first instructions.
- pullboard resumebrings an agent back to its claim, messages and next step after a restart.
- pullboard nextclaims the next free item, never one someone else holds.
- pullboard runlets a lighter model build simple items unattended.
- Claude Code gets skills. Codex and others read AGENTS.mdorpullboard prompt <role>.
Your whole board is one file inside .git, on your machine.
Every move follows one declaration, published in docs/lifecycle.md.
Items are state machines. Every item starts open. An agent claims it and it's claimed; if the agent goes quiet, it reopens. Once submitted, it's submitted until a verifier accepts it as verified or rejects it back to open. Only the coordinator can withdraw an item. The board refuses any move the declaration doesn't allow.
Drawn from one declaration, src/machine.js, which the commands, the view and the docs all share.
Everything lives in your repo. Nothing is hosted.
- Spec, doctrine and config: plain files, committed with your code.
- The board: one SQLite file inside .git, shared by every worktree, never committed.
- Submitted work: pinned in git, so it survives a deleted worktree.
- Backups: pullboard exportwrites out the whole board.
pullboard.json sets the gate and the lanes.
{
"gate": "npm test",
"lanes": {
"web": { "owns": ["apps/web/"], "specs": ["G"] },
"review": { "owns": [] }
}
}The gate is any command that proves your code, like npm test or pytest, and it runs before every submit and push. Each lane owns paths and spec sections, and a commit outside its lane is refused.
Pick the gate for your stack. Chain checks with &&, like ruff check . && pytest.
Pullboard exists to keep a team of agents coherent over a long build.
- Worktree identity only means something on one machine. It's not a security boundary.
- You can skip a hook with --no-verify. The pre-push gate and the verifier are the backstops.
- CI runs on Linux and macOS. Windows isn't tested yet.
- The relay. Your boards, live on your phone and other machines. Sealed records, never code.
- A roadmap in Pullboard View. Every milestone and what's left in it, at a glance.
The reference docs, in reading order.
- Lifecycle: how an item moves, state by state.
- CLI JSON API: every command's output, for scripts and tools.
- Stored formats: the board's files, exports and their versions.
- RFCs: the design decisions, and why.
Pullboard is released under the MIT License.
Vibe hard. Verify harder.