Pullboard

pullboard.dev · lives in your git repo · no account · no dependencies · never calls a model

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.

!How it holds. Your decision becomes a bar each piece of work is frozen against; a second agent checks the exact commit; the board keeps what passed, what failed and why; the next agent starts from there.

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.

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.

!An agent asks its coordinator. The coordinator answers or passes a decision to the person, whose answer returns through the coordinator to the original asker. Agents send decision requests to their coordinator first.

[!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."

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

!The desktop board shows open, claimed, submitted and accepted work, a Needs you row for a held lane, search in the top bar, the status bar, an accepted item's review history, and a stats line with merged work, sent-back share and the bottleneck recommendation.

!The Shouts tab shows the builder, reviewer and coordinator discussing a reviewed fix, the person's answered decision marked Heard, an evidence receipt and a code reference.

_{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.

!The timed Pullboard tour shows a change submitted, rejected for a missed edge, fixed and accepted.

Project setup

Set it up once, then talk to one agent.

!Starting with an agent. You run pullboard init in your git repo, commit what it wrote, open a new Claude Code session in that folder and say what to build. That agent becomes the coordinator: it takes the spec with you, plans lanes and items, runs a builder per lane and a verifier that built none of it, and merges verified work only.

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

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 1

A 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.

Working with agents

A few commands keep every agent on track.

• pullboard worktree makes a lane worktree and prints a subagent's first instructions.
• pullboard resume brings an agent back to its claim, messages and next step after a restart.
• pullboard next claims the next free item, never one someone else holds.
• pullboard run lets a lighter model build simple items unattended.
• Claude Code gets skills. Codex and others read AGENTS.md or pullboard prompt .

Architecture

Your whole board is one file inside .git, on your machine.

Every move follows one declaration, published in docs/lifecycle.md.

Agentic Item Lifecycle (AILC)

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.

!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.

_{Drawn from one declaration, src/machine.js, which the commands, the view and the docs all share.}

Data and storage

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 export writes out the whole board.

Configuration

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.

Multi-language support

Pick the gate for your stack. Chain checks with &&, like ruff check . && pytest.

| Stack | Gate | | --- | --- | | JavaScript, TypeScript | npm test | | Python | pytest | | Go | go test ./... | | Rust | cargo test | | Java | mvn test or gradle test | | Ruby | bundle exec rspec | | C#, .NET | dotnet test |

Purpose

Pullboard exists to keep a team of agents coherent over a long build.

Limits

• 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.

What's next

• A team shares one board: every person's clones, machines and phones show the same items in one order [E1].
• Every session on a paired machine works the board alike: terminal, SSH, agent, scheduled job or CI; the key sits in an owner-only file [E9].
• Each person may keep a private board per repo in ~/.pullboard; its items stay on that person's devices [E11].

Docs

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.

License

Pullboard is released under the MIT License.

Vibe hard. Verify harder.