PatchBoard

PatchBoard is a small, opinionated, repo-native task board and annotation linter.

Tasks are Markdown files. Folders are workflow states. Git history is the audit trail. The tool makes that system easier to use, but the files remain readable and meaningful if the binary disappears.

Why PatchBoard

Product plans and implementation reality often drift apart. A feature may be marked complete while its code still contains a TODO, FIXME, or other known follow-up that never reaches the people planning the work.

PatchBoard keeps both sides close to the repository:

• Product and project collaborators can open tasks/kanban.html and use a familiar board.
• Engineering collaborators can use Markdown, the CLI, Git, code review, and their existing editor.
• Linked code annotations are checked against the same task files that describe feature and maintenance work.

PatchBoard is intentionally not a database. The durable record is the file tree, and the tool helps inspect, repair, and automate it.

The patchboard executable is replaceable infrastructure. Its installation location does not select a project; PatchBoard discovers the board from the working directory or an explicit -C/--repo path.

Who It Is For

PatchBoard fits small product, design, infrastructure, and engineering teams that want planning context close to implementation context. It is especially useful when work must remain legible in pull requests, local checkouts, offline clones, or long-lived repositories.

It is not intended to replace portfolio planning, customer-support queues, or company-wide reporting. It works best as the repo-local layer of truth: the concrete plan for what this repository is doing next.

Install

From a source checkout, install the standalone binary into your configured Go binary directory:

go install ./cmd/patchboard

Make sure $(go env GOBIN)—or $(go env GOPATH)/bin when GOBIN is empty—is on your PATH. Versioned binaries for Linux, macOS, and Windows (amd64 and arm64) are published on GitHub Releases, with a GitLab release backup. See release instructions for archive formats and checksums. Run patchboard --version to identify an installed release.

Quick Start

Initialize a board and inspect it:

patchboard init
patchboard status
patchboard doctor

Create a task, move it into active work, and finish it:

patchboard create --state ready --slug fix-login-timeout --title "Fix login timeout handling"
patchboard start fix-login-timeout
patchboard done fix-login-timeout

Connect implementation follow-up to a task:

// TODO[task-20260512-auth-timeout]: handle expired refresh token

Then inspect or validate annotations:

patchboard todos
patchboard lint

You can also open tasks/kanban.html for a visual board. Browsers with local directory write support can move cards after you choose the project's tasks/ directory. CI also publishes a read-only, single-file snapshot of this board to GitHub Pages and GitLab Pages, with task contents included.

See Getting Started for installation, repository selection, troubleshooting, development commands, and a fuller first-board walkthrough.

Documentation

• Publishing examples — wire your own board into GitHub Pages, GitLab Pages, or an existing static site

• Manifest — the vision and principles behind PatchBoard

• Core concepts — the filesystem contract and design principles

• Getting started — initialize and use a board

• Command reference — CLI commands, JSON output, and exit codes

• Task files — Markdown format, identity, state, and metadata

• Code annotations — marker syntax and lint behavior

• Configuration — board config, defaults, and naming

• Repository resolution — how PatchBoard selects a project and task root

• Browser kanban — visual board behavior and limitations

• Workflows — doctor, fix, undo, CI, and future releases

• Development — repository architecture and testing

• Releases — versions, CI, platform downloads, and publication

Status

PatchBoard is early, but its main filesystem workflow is usable. It can initialize, inspect, create, move, repair, and validate boards; expose structured JSON for automation; and provide a browser-based kanban view.

Planned work includes explicit lint follow-up task generation, broader writable browser support, and done-task cleanup during releases. The dogfood board under tasks/ is the current record of project work.

Contributing

Read CONTRIBUTING.md before submitting changes.

License

This project is dual-licensed under MIT OR Zlib. See LICENSE, LICENSE.MIT, and LICENSE.zlib.

Copyright (c) 2026 Andrew David LeTourneau