pullboard README

项目的 README,来自 github.com/pullboard-dev/pullboard。合并为一个 markdown 文件:README.md。

Pullboard

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

pullboard: finished items npm MIT license

Pullboard enforces your intent and decisions. Build autonomously.

  1. Vision: what you want.
  2. Specification: your vision written down.
  3. 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.

Pullboard's own board, 28 Oct 2026: 32 agents, 22 building, 3 reviewing, 180 items landed in 24 hours. Each building and reviewing agent's last four hours as a timeline, and the item it holds now.

Watch Pullboard build itself, live →


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.

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.

A builder agent says done and tests pass. A second agent checks the work, finds a problem and sends it back with the reason. The fix passes and merges.

▶ Watch the 90-ish second explainer · Read the white paper

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 night on Pullboard's own board, 16 October 2026: 38 agents, 9.6 hours from 11:17 pm to 8:51 am, with no moves from the person. 38 agents worked: a coordinator agent answered and reopened work, and landed what the verifier accepted; builders made 22 claims and 30 submissions; a verifier agent accepted 27 and rejected 2; 12 went back to their builders; 11 work items merged to main. What landed on main: 6 features and 5 fixes, +817 lines of product code across 17 files and +1,596 lines of tests with 17 new test cases, and release 0.8.27 on npm at 7:56 am. Among the features: The view signs in and links every board; pullboard.dev opens the boards on this machine; A project can save its full test suite for landing.

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

We've cycled through 4,858 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.

One board. Every agent. Every machine. All of it is in Pullboard 0.9.0. Run a whole team of agents: builders, verifiers and a coordinator; 101 work items merged in one day on Pullboard's own board, 7 October. Your board, on your phone: Answer what's waiting, anywhere. Sealed: the relay can't read it. Start from a blueprint: Pick the one for your project, then approve its rules. Plug in any agent: Keep Claude Code or Codex, and add any MCP client. Across your machines: Pair a machine once. Its agents share your board, in one order.

What are blueprints? 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.

Validation and verification, with a wall between them. Validation is yours: you say what correct is, and it is frozen as tests, the bar. Only the frozen bar crosses the wall. Verification is the machine's: untrusted agents build, the machine checks every step, and the work is proven or sent back with the reason. Every step goes into a record anyone can re-check.

Key concepts

Five primitives. Everything else is built on them.

Why

Past the demo, the same things break.

Where vibe coding breaks, and what holds instead. Pullboard enforces each fix, so none of it depends on you watching. Vibe coding: It said done. It wasn't.; It forgot what you decided; Two agents, one file; You review every line. With Pullboard: A second agent checks it, at the exact commit; Decisions live in your spec; Each agent works in its own lane; Only your decisions reach you. On Pullboard's own board, 4 to 16 October 2026: 1 in 4 times an agent said done, a second agent sent it back (227 of 908), and 588 merged, 0 of them without an accept.

How it works

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

How work moves. You decide the rows of SPEC.md. An item freezes its bar when an agent claims it. Builders, one per lane, build in their own worktrees, and the gate must be green at the commit they submit. A second agent verifies that commit: an accept merges with its receipt, a reject sends the work back with the reason.

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.

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, in SPEC.md:

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

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 in October nearly one in four reviews sent the work 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, bar and review history, one line each.

The desktop board lists items one line each, with who holds them and their stage. An opened landed item shows the review that passed it, its journey through the stages, its bar proven, and its history, including the time it was sent back.

Shouts

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

The Shouts tab shows threads by item: the person's answer, a sentinel releasing a stale claim, and the coordinator; beside them, the agents at work and the lanes.

Roadmap

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

The demo release with its stage bar and legend, one line per item, and one item expanded: its criterion, agents, the reason it was sent back, its history and its release.

On your phone

The same board in your pocket, with a drawer for pages and projects.

The board on a phone The phone board shows the same item list and the opened item, with its passing review, journey and proven bar.

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

Upgrading from 0.9.3? Run the same install. Your boards and runners keep working.

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

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.

From then on, just talk to your agent. It runs the commands below for you.

Starting with an agent. You ask your agent to install Pullboard and set it up for what you're building. It runs the install and pullboard init, commits the setup, then walks you through your requirements and questions in the view it opens for you.

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"

Working with agents

A few commands keep every agent on track.

Claude Code gets skills. Codex reads AGENTS.md. Both get Pullboard's MCP server, and any other agent can read pullboard prompt <role>. The triage skill handles outside issues and pull requests, with your approval.

Runners and landing

Runners are the machines that run your tests and land your work, so your dev box doesn't overload.

pullboard runner list
pullboard runner status

With no runner set up, your own machine is the runner, and you do nothing. Add more machines when the tests queue up. Each runner pulls a job from the board while it has cores to spare, runs it and posts a signed receipt. pullboard stats runners shows wait times, run times and health.

Add a runner

Serve the board on your network, then point a runner at the address it prints.

pullboard serve --address 192.168.1.20
pullboard runner serve <runner address> --key <board key>

serve prints the runner address and where the board key is kept. Anyone on your network who holds that key can use the board, so keep it private. On a Mac you can reach over SSH, pullboard runner install-serve <host> --board <runner address> installs the runner as a service that restarts by itself. pullboard runner drain <host> takes a runner out of rotation.

Tests on runners

An agent tests its change without waiting for the result.

pullboard test test/checkout.test.js
pullboard test --status <run id>

The run goes on the queue and the command returns. A green run at the item's head ticks the parts of the bar it proves. Review and landing reuse that proof, and a test still green on unchanged inputs is skipped.

Landing

Accepted work lands on its own, as a job on a runner. The lander takes every accepted item that merges cleanly, lands them in the order they were accepted, refuses a candidate that fails its checks, and moves main forward. Your trunk remote refuses a push to main that has no landing receipt.

pullboard why
pullboard land --why

why shows the release on one screen: the one thing holding each unlanded item. land --why says why nothing landed. An accepted item that no longer merges goes back to its lane with the conflict named.

Boards anywhere

A clone on another machine can work the same board.

pullboard settings board.url <board address>
pullboard settings board.token <board key>
pullboard join web --model "$PULLBOARD_MODEL"

Run those in the clone. Its agents then work the board over its API: next, claim, submit, verify and test all work from there. For your phone, pullboard view --lan gives a private link on your own network, and pullboard relay on links the board through pullboard.dev, sealed so the relay can't read it.

Architecture

Your whole board is one file inside .git, on your machine. You can serve it to your other machines and runners.

Every move follows one declaration, printed by pullboard lifecycle.

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, and with withdraw.review on, a second agent must confirm it. The board refuses any move the declaration doesn't allow.

An item's life, drawn from the lifecycle declaration: 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, which the commands, the view and the docs all share.

Data and storage

Everything lives in your repo. Nothing is hosted unless you link the relay.

Where things live. The main checkout is the coordinator and holds SPEC.md, DOCTRINE.md, pullboard.json, AGENTS.md and the git hooks. Inside .git, shared by every worktree, are the board and the pinned submitted commits. Beside it, each agent works in its own worktree, builders in their lanes and a verifier, all on the same board. pullboard view lists every project on this machine.

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. Submit queues it on a runner and returns. Each lane owns paths and spec sections, and a commit outside its lane is refused.

Multi-language support

init finds each language in the repo and sets a gate for each one. To set one yourself, 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

What's next

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

Docs

The reference docs, in reading order.

License

Pullboard is released under the MIT License.


Vibe hard. Verify harder.

yolo: verified

pullboard (pullboard-dev/pullboard)

正在搜索数据库…

这是什么?Pullboard 用于协调多个 AI 编程代理(如 Claude Code 或 Codex),让它们按你批准的需求规格自主构建软件。由构建代理实现每个条目,再由一个独立的验证代理依据需求证明其达标,该条目才算完成。
它本身是编程代理,还是管理代理的工具?它是一个命令行工具,加上一个本地网页仪表盘(Pullboard View),用于管理你已在使用的代理(Claude Code、Codex 等)的工作树、需求规格、规则和验证工作。它本身不编写代码。
我该如何在仓库中运行它?对你的编程代理说「在这里安装 Pullboard 并完成设置」,它会安装 Pullboard、运行 pullboard init,并提交 SPEC.md、DOCTRINE.md、钩子和看板。你也可以自己运行 pullboard init,再启动 Pullboard View,按步骤完成设置。
我需要先安装什么?只需要 git 和 Node 22.13 或更高版本。Claude Code 会自动识别专用技能,Codex 和其他代理则读取 AGENTS.md 或 pullboard prompt。
用之前有哪些需要注意的问题?工作树的身份识别只在同一台机器上有意义,因此它不是真正的安全边界;任何人都可以用 --no-verify 绕过钩子(推送前检查门和验证代理才是真正的兜底手段)。Windows 支持也尚未经过测试,因为持续集成(CI)只在 Linux 和 macOS 上运行。
我的代码或数据会离开我的电脑吗?不会。所有内容都保存在你自己的仓库中:看板是 .git 目录内的一个 SQLite 单文件,且从不提交;也没有任何内容托管在外部服务器上。
需求规格(Spec)和工作准则(Doctrine)有什么区别?需求规格(SPEC.md)是你希望构建的已批准需求清单,每条需求占一行,一旦某个代理认领该条目就会锁定。工作准则(DOCTRINE.md)是规定工作必须如何完成的内部规则集,每条规则都由 git 钩子或代码审查等方式强制执行。
什么是蓝图?蓝图是针对某类项目的入门需求规格和规则集,例如网页应用、代码库、iOS 应用或数据管道。随附十个蓝图,你也可以用 pullboard blueprint save 把自己已批准的配置保存为可复用的蓝图。
“先构建后验证”的循环实际是如何运作的?构建代理认领一个条目,提交时注明对应的需求行,并在测试门通过后提交审核。随后,另一个验证代理会检出该确切的提交,要么附上证据予以通过,要么给出理由予以驳回,使其退回待办状态。
我不在办公桌前时,能查看代理的进度吗?可以。Pullboard View 是一个本地仪表盘,你也可以在手机上打开它。它只显示需要你决定的事项、每次认领、提交和裁决的时间线,以及发布进度路线图。
大小
67.5 MB
星标
846
时长
1个月
提交 · 90 天