A protoAgent plugin that turns an idea into merged PRs: a lean 6-state board
backed by beads-rust (br), an ACP spawn loop
that dispatches a coding agent per feature into an isolated git worktree, an
adversarial planning layer, and a Kanban/list console view.
Install into any protoAgent agent from this git URL — it's not tied to any one agent.
backlog → ready → in_progress → in_review → done
│
└── blocked (a flag, not a lane)
Want a complete, working example of an agent built around this plugin?
roxy is a protoLabs operator/orchestrator
agent that installs this plugin as its coding-orchestration layer — it's the
reference host. It consumes this repo exactly the way you would (plugin install +
a pinned plugins.lock), enables it, and ships the surrounding agent (the A2A
server, the React console the Board view renders in, the delegate roster the
loop dispatches against, persona, evals). Read it to see how a board-driven coding
agent is wired end to end — including a live run shipping real features through the
board to a PR — or fork it as a starting point.
- Board = a projection over beads (
.beads/*.db+ git-committed JSONL) — no separate store, so the work graph can't drift out of sync. - The loop pulls the top-priority
readyfeature → creates a disposablegit worktreeofforigin/<base>→ dispatches a coder (acpdelegate) scoped to it → commits/pushes → opens a PR →in_review. A merge webhook setsdone(and reaps the worktree); where GitHub can't reach a webhook URL, a PR reconcile poll (merge_poll, on by default) drives the terminal edges itself — merged →done, closed-unmerged →blocked. Setmax_concurrent > 1to build several features in parallel, each in its own worktree. - Resilience — every
awaitin a drive is bounded (a coder dispatch is hard-capped bycoder_timeout_s); transient failures (rate-limit / network / merge-conflict) retry with backoff while capability failures (no diff / timeout) escalate a tier or block; and on restart the loop recovers features stranded mid-build (adopt an already-opened PR →in_review, else reset →ready). - DAG + gates —
depends_onareblocksedges; a dependent stays out of the puller until its blocker is merged (foundation merge-gate). The Ready gate requires a spec, EARS acceptance criteria, and explicitfiles_to_modify. - Escalation (opt-in) — with a
codersmap of >1 distinct delegate, a capability failure climbs a model tier (fast→smart→reasoning) and blocks at the top. - Planning layer — two reasoning subagents (
decompose+antagonist) driven by thedecompose-projectskill: idea → outline → MADR ADRs → epics › milestones › features, hardened by an adversary, with a per-epic human gate. - Console view — a Kanban + list projection over the
/featuresAPI (ADR 0026).
It composes the upstream delegates plugin (ADR 0024/0025) for the ACP/A2A
spawn primitive — it does not reimplement it.
- protoAgent ≥ 0.27.0 (console views + the ACP delegate teardown).
- beads-rust — the
brCLI onPATH, the board's DAG/status store. Install withcargo install beads_rust. NOT the stale homebrewbd(a different, write- broken package); thebd-/br-prefix in issue ids is just the workspace namespace. Override the binary withBR_BINif needed. git+ theghCLI (authenticated) for branch push + PR creation.- The
delegatesplugin enabled, with anacpcoder delegate declared.protois the first-class coder — it's the purpose-built protoLabs coding agent, speaks ACP natively (proto --acp), and runs its full long-horizon harness (durable session-memory checkpoint, compaction, memory consolidation) over ACP, so it holds context across a long feature build. Any ACP agent works (Claude Code, Codex, Gemini CLI), but proto is the recommended default. A reviewera2adelegate is optional (review dispatch is off by default — most fleets review PRs via a pipeline on open).
python -m server plugin install https://github.com/protoLabsAI/projectBoard-plugin --ref main
python -m server plugin enable project_board # the trust decision; then restartThen in config/langgraph-config.yaml:
plugins:
enabled: [delegates, project_board]
delegates:
- { name: proto, type: acp, command: proto, args: ["--acp"], workdir: ~/dev/my-repo, permissions: allowlist }
project_board:
coder: proto # the first-class ACP coder (protoCLI)
repo: ~/dev/my-repo
base_branch: main
loop_enabled: false # flip true to start the background puller
max_concurrent: 1 # >1 builds features in parallel (each its own worktree)
merge_poll: true # poll merged PRs as a fallback to the webhook Done edge
goal_verify: false # flip true: verify the coder's diff vs acceptance_criteria before opening a PR
max_mode_n: 1 # >1 = best-of-N "Max-Mode": N coders per feature, a judge keeps the best diff (#21, WIP)
# webhook_secret: "..." # set before exposing /webhook/pr publicly- Headless / via the agent:
board_create_epic,board_create_feature(title,spec,acceptance_criteria,files_to_modify,depends_on, …),board_mark_ready,board_list. - Plan a project: the
decompose-projectskill ("decompose ") runs the adversarial pipeline and populates the board. - HTTP API (
/plugins/project_board/*):epics,milestones,features,features/{id}/{ready,dep,block,unblock,ci}, and/webhook/pr(the Done edge — a stable public URL GitHub posts to; ungated so GitHub, which can't send a bearer, reaches it). - Watch it: the Board console view (left-rail) at
/plugins/project_board/board— Kanban + list, live-refreshing, served by the same router as the API (so the declared view path is genuinely mounted).
| File | What |
|---|---|
store.py |
the br/beads wrapper — board projection + the Ready/Done invariants |
loop.py |
the puller: ready → worktree → coder → PR → in_review (+ opt-in escalation) |
worktree.py |
per-feature worktree lifecycle, scoped coder dispatch, open_pr |
api.py |
the HTTP API + the /webhook/pr Done edge (HMAC-verified) |
board_view.py |
the Kanban/list console view |
subagents.py + skills/ |
the decompose/antagonist planning layer |
__init__.py |
register() — wires it all |
Ships disabled; nothing runs until you enable it and declare a coder.