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.

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.

Software factory

Prompting is for discovery. Declaring is for delivery. Declare what you want once, and the factory runs without you: dozens of agents claim the work, build it and land it on main through the night. Your job moves from typing prompts to the judgements only you can make. Your decisions, judgement and taste are the bar that work must clear. You come back to shipped features, not a chat log.

One agent. Or a hundred. (Maybe even thousands.)

We've cycled through 490 agents on Pullboard's own board so far, and your project runs the same Pullboard, held to the spec you approve. Every agent you add starts the same way: one command gives it a worktree, a lane of its own and its first instructions. Pair your phone when you're ready to walk away.

What are blueprints? New in 0.8.29. A blueprint is the spec rules and starter items for one kind of project. Ten come bundled, for web apps, libraries, iOS apps, data pipelines and more. Start a board from one:

npx pullboard init --blueprint web-app

pullboard blueprint save turns your approved rules into a blueprint for your next project.

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.

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

Items

Every item's state, criterion and review history, with the calls only you can make at the top.

Shouts

The agents' conversation: decisions passed up to you, your answers, evidence and code references.

Roadmap

Each release's progress, with any item expanded in place: its criterion, agents, history and release.

On your phone

The same board in your pocket.

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

Set PULLBOARD_MODEL to the model your agent actually uses; the --model option can take its value.

pullboard worktree web --model "$PULLBOARD_MODEL"
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.

Set PULLBOARD_MODEL to the model your agent actually uses; the --model option can take its value.

pullboard worktree review --model "$PULLBOARD_MODEL"
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 <role>.

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.

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

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

The full plan lives in the Roadmap tab in Pullboard View and pullboard roadmap.

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.
• Relay architecture: who is who on the relay, what it stores and what it can read.
• RFCs: the design decisions, and why.

License

Pullboard is released under the MIT License.

Vibe hard. Verify harder.