Skip to content

protoLabsAI/projectBoard-plugin

Repository files navigation

Project Board — coding orchestration plugin

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)

See it running — a working board-driven agent

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.

What it does

  • 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 ready feature → creates a disposable git worktree off origin/<base> → dispatches a coder (acp delegate) scoped to it → commits/pushes → opens a PR → in_review. A merge webhook sets done (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. Set max_concurrent > 1 to build several features in parallel, each in its own worktree.
  • Resilience — every await in a drive is bounded (a coder dispatch is hard-capped by coder_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 + gatesdepends_on are blocks edges; 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 explicit files_to_modify.
  • Escalation (opt-in) — with a coders map 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 the decompose-project skill: 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 /features API (ADR 0026).

It composes the upstream delegates plugin (ADR 0024/0025) for the ACP/A2A spawn primitive — it does not reimplement it.

Requirements

  • protoAgent ≥ 0.27.0 (console views + the ACP delegate teardown).
  • beads-rust — the br CLI on PATH, the board's DAG/status store. Install with cargo install beads_rust. NOT the stale homebrew bd (a different, write- broken package); the bd-/br- prefix in issue ids is just the workspace namespace. Override the binary with BR_BIN if needed.
  • git + the gh CLI (authenticated) for branch push + PR creation.
  • The delegates plugin enabled, with an acp coder delegate declared. proto is 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 reviewer a2a delegate is optional (review dispatch is off by default — most fleets review PRs via a pipeline on open).

Install

python -m server plugin install https://github.com/protoLabsAI/projectBoard-plugin --ref main
python -m server plugin enable project_board          # the trust decision; then restart

Then 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

Use

  • 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-project skill ("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).

Layout

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.

About

Board-driven coding-orchestration plugin for protoAgent: beads board + ACP spawn loop + planning layer + console view. Install via plugin install <git-url>.

Topics

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages