Most agent work products end up as a pile of markdown: ISSUE-*.md, a TODO checklist, a commit message that
says "fixes the thing". It works until you need to answer three questions at once — what is in flight, who owns
it, and what actually happened to it — and then you are grepping.
ProjectBoard (https://github.com/amgio38/Y20260923, MIT) is my attempt at the smallest thing that answers
those: one SQLite file, one tree, one typed lifecycle, and three faces on top of it (CLI, MCP, read-only
dashboard). Single Go binary, no cgo, no database server, no Node build step.
The shape
Project
└─ REQ a requirement
├─ ISSUE a unit of work
├─ BUG
└─ REPORT notes, reviews, evidence
Every node has a type and a status drawn from an explicit state machine
(todo → in_progress → review → done, plus blocked, hold, cancel, archived). Two rules matter more than
the rest:
-
Illegal transitions are errors, not silent writes.
todo → doneis refused. So isblocked → review. The edge list is a table, not aswitchscattered across handlers. -
review → doneis a separate operation that requires evidence. It is not "set status to done"; it takes a note (test command and result, coverage number,file:line, commit sha) that gets written into the history as averifyevent. If an agent closes its own ticket, the note is prefixed[self-verified]— visible, not hidden.
Everything else follows: an append-only history with an actor on every write, depends_on edges between nodes,
optimistic locking (expected_updated_at) so two agents cannot clobber each other, and delete only for leaf
report nodes that nothing references.
Three faces, one logic
-
CLI (
pb) — ~30 subcommands:init,seed,serve,mcp,tree,get,create,move,assign,link,verify,search,deps,history,stats,commit attach,export, … -
MCP —
pb mcpspeaks JSON-RPC over stdio,pb serveexposes the same over HTTP. The built binary answerstools/listwith 21 tools (pb_tree,pb_create,pb_transition,pb_move,pb_verify,pb_search,pb_commit_attach,pb_hook, …). Same logic as the CLI, not a second implementation. - Dashboard — a single HTML page, read-only by design, dark theme, four tabs (focus / progress / master checklist / weekly). Read-only is deliberate: writes go through the lifecycle, never through a form that can skip it.
The integration I actually wanted
Commits attach themselves. Put a node id in the commit message, e.g. #PROJ/REQ-AUTH/ISSUE-LOGIN-TIMEOUT, and
the post-commit hook calls pb commit attach with the sha. No "remember to update the ticket" step, so the ticket
cannot quietly fall behind the code.
Subscriptions wake an agent. A node can be subscribed to by a harness name and target; when that node or a
descendant changes state, pb serve notifies the target. That is how a REQ moving to review reaches the reviewer
without a polling loop.
Measured today (2026-10-23), not estimated
- Release
v0.20261005.001: six assets (linux/darwin/windows × amd64/arm64) each with a.sha256. I downloadedprojectboard-linux-amd64.tar.gz,sha256sum -cpassed, the binary inside reportsV0.20261005.001, 4.7 MB tarball → 11 MB binary. - Repo: 90 Go files, 22,327 lines, 352 test functions,
go test ./... -count=1green across all packages (cmd/pb,store,httpapi,mcp,importer,integrations,web,domain). - 21 MCP tools, 9 SQL migrations, ~30 CLI subcommands.
What it is not
- Not a Jira replacement. No sprints, no story points, no burndown.
pb statsgives counts per status, per owner, and per REQ completion — that is the whole reporting story. - Not multi-writer over the network. It is SQLite with WAL; concurrent writers across machines are out of scope.
- The dashboard has no user auth; bind it to
127.0.0.1or a private network. It is a read view for a human, not a public portal. - Young: two tagged releases, and yes, one star. The parts I trust are the ones with tests, not the parts described in the README.
Trying it
curl -fsSL https://raw.githubusercontent.com/amgio38/Y20260923/main/install.sh | sh
pb init --db var/board.db # create the database
pb seed --db var/board.db --actor human # seed a demo project
pb tree # see the tree
pb serve --addr 127.0.0.1:8787 # dashboard + MCP over HTTP
pb mcp --db var/board.db # or JSON-RPC over stdio
Repo and docs: https://github.com/amgio38/Y20260923
If you are building agent workflows and have opinions about the state machine — especially about what should be
impossible — I would rather hear it now than after the schema settles.
Top comments (1)
Current state and transition history answer different questions. Status tells me where a task is now; an append-only event log tells me who moved it, from which state, and what evidence justified the transition. That matters when an agent says “done” but the test, merge, or external side effect never actually happened.