Pullboard 0.9.3: A local-first software factory

pullboard.dev · lives in your git repo · no dependencies · Walk away, and it builds.

Vision: what you want.

Specification: your vision written down.

Inspection: independent verification.

Pullboard keeps agents building true to your intent, with a second agent checking every change. Your judgement carries across every agent and every session, so a complex project stays coherent for months. It's a coordination queue for serious software: you decide what matters once, and many agents build, check and land the work.

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.

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.

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

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.

How it works

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

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.

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.

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

The 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"

Pullboard View

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

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.

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

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.

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.

A few commands keep every agent on track.

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.

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.

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.

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.

Pullboard is released under the MIT License.