engineering-board

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="brand/logomark-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="brand/logomark-light.svg">
  <img src="brand/logomark-light.svg" alt="engineering-board" width="88" height="88">
</picture>

# engineering-board

**Git-committed pattern memory that helps AI agents find the root cause.**

_The board is the database._

[![Website](https://img.shields.io/badge/website-ghostlygawd.github.io-E6A94E.svg)](https://ghostlygawd.github.io/engineering-board/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.8.0-E6A94E.svg)](CHANGELOG.md)
[![tests](https://img.shields.io/github/actions/workflow/status/GhostlyGawd/engineering-board/test.yml?label=tests)](https://github.com/GhostlyGawd/engineering-board/actions/workflows/test.yml)
[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-171719.svg)](https://code.claude.com/docs/en/plugin-marketplaces)
[![MCP](https://img.shields.io/badge/MCP-server-171719.svg)](mcp-server/README.md)
[![GitHub stars](https://img.shields.io/github/stars/GhostlyGawd/engineering-board)](https://github.com/GhostlyGawd/engineering-board/stargazers)
[![Last release](https://img.shields.io/github/release-date/GhostlyGawd/engineering-board?label=last%20release&color=E6A94E)](https://github.com/GhostlyGawd/engineering-board/releases)

<img src="docs/assets/pattern-intelligence-demo.png" alt="Three synthetic findings from worker routing, the board renderer, and MCP ready-work output connect into cluster C001 and a proposed root-cause hypothesis, with supporting evidence, an alternative explanation, and a falsifier." width="720">

_Three surface-different symptoms become one evidence-linked systemic investigation candidate. Run `/board-demo` to reproduce the contained synthetic sample locally._

<img src="docs/assets/board-screenshot.png" alt="Screenshot of this repo's real rendered board: a search input, type/priority/status filter chips, and kanban columns — to do, review, validate, done — populated with entry cards." width="720">

_the real thing — this repo's own board, as `/board-view` renders it_

</div>

## What it is

**engineering-board is a repository-owned pattern-intelligence system for engineering agents.** It records bugs, features, questions, and observations as visible Markdown evidence; connects recurring signals into a deterministic graph; and gives agents durable context for investigating shared root causes across domains instead of repeatedly patching symptoms in isolation.

Markdown remains the canonical, PR-reviewable record. `BOARD.md`, `GRAPH.yml`, and the HTML views are rebuildable projections over that evidence—not a competing source of truth. Proposed root-cause hypotheses stay visibly separate from deterministic graph facts and cannot become confirmed knowledge without investigation or fix evidence. Passive capture, atomic multi-agent claims, and the optional `tdd → review → validate` loop support that memory by collecting and testing evidence; they are not the product's headline.

### Why it's different

The market splits into two camps: **visible-but-shallow** git-markdown boards and **smart-but-opaque** memory-and-coordination engines whose useful state lives in a database or outside the repo. engineering-board joins the strengths of both and adds an explicit evidence → graph → hypothesis boundary:

- **git-committed evidence and memory** — reviewed in the same PRs as your code
- **cross-domain pattern graph** — recurring signals become explainable clusters with member evidence
- **bounded agent interpretation** — root-cause candidates cite evidence and remain `proposed`
- **atomic multi-agent claim-locking** — parallel worker agents never collide
- **native to Claude Code** — plus an MCP server for any MCP client

### Why not Claude Code's built-in Tasks?

Use both — they solve different problems. Native Tasks are genuinely good personal tracking: they persist across sessions, support dependencies, and come with a Ctrl+T board. But they live in `~/.claude/tasks/` — per-user and per-machine, outside the repo — so they're invisible in PRs and invisible to your teammates. They also have no capture pipeline, no review states, and no committed learnings. engineering-board is the **repo's** board: shared, PR-reviewable state that travels with the code and outlives any one user's machine. Keep native Tasks for in-session personal tracking; put the project's durable, team-visible state on the board — the two compose.

## Value props

**VP1 — Root-cause intelligence from accumulated findings.** Bugs that look unrelated in one-off chats can cluster through shared patterns and affected domains. Every cluster keeps the evidence trail and edge reason visible, so agents can investigate the systemic cause instead of guessing.

**VP2 — Visible, durable memory.** Canonical findings, hypotheses, and learnings are plain Markdown in the repo. Deterministic graph and visual projections are rebuildable. Recurring lessons promote into committed `Learning` entries (`L###`) that survive session boundaries.

**VP3 — Collision-free parallel agents.** Atomic `mkdir`-based claim-locking with heartbeat, stale reclamation, and cloud-sync detection lets multiple worker agents run without stepping on each other (`board-claim-acquire/release/reclaim-stale.sh`, tested under `tests/claims/`).

**VP4 — Falsifiable verification feedback.** When a fix is ready, the optional `tdd → review → validate` state machine can test the proposed explanation and feed the result back into durable memory.

**VP5 — Runs where you already are, and everywhere else.** A native Claude Code plugin (commands, agents, hooks, skills) **and** an MCP server exposing the same board format to any MCP client — Claude Desktop, Claude Code, or your own.

## Quickstart

Two paths. The plugin gives you the full autonomous pipeline inside Claude Code (requires [Claude Code](https://claude.com/claude-code), free); the MCP server exposes the board to any MCP client.

### Plugin (Claude Code)

Install from this repo's own marketplace:

```
/plugin marketplace add GhostlyGawd/engineering-board
/plugin install engineering-board
```

Then run the one-command setup (scaffolds the board with smart defaults and
checks the pipeline's permissions in a single step):

```
/board-setup
```

To see the product's pattern-intelligence loop before using real project data:

```
/board-demo
```

The command creates a contained synthetic run under
`.engineering-board/demo/pattern-intelligence/`, connects three findings from
different domains into a deterministic cluster, and asks the agent for one
evidence-cited hypothesis. The result stays `status: proposed` and includes an
alternative explanation and falsifier. The report prints the exact
manifest-verified cleanup command; modified runs are preserved rather than
deleted.

Prefer explicit control? `/board-init <project> [affects-prefix]` scaffolds with
your own names, and `/board-install-permissions` manages the permission
allowlist on its own — `/board-setup` simply composes the two.

**Now you have a board. Here's how real project memory accumulates:**

1. **Capture is automatic.** Just work in Claude Code as usual. When a turn ends, the Stop hook extracts any bug/feature/question/observation you or the agent surfaced and writes it to the board's scratch inbox at `engineering-board/<project>/_sessions/`. You don't run anything — when at least one finding is captured, a one-line summary confirms the count and names `/pm-start` as the next action.
2. **Promote when you're ready.** Run `/pm-start`, then end a turn: the PM pipeline consolidates the scratch findings into real, committed board entries under `engineering-board/<project>/bugs/` (etc.) and updates `BOARD.md`. That's your first entry on the board.
3. **Inspect patterns before fixing symptoms.** Run `/board-graph` and `/board-view` to expose recurring signals, connected entries, and cross-domain structure. The production graph remains deterministic; interpreted root-cause hypotheses are kept separate from graph facts.
4. **Verify a chosen fix when useful.** Start a fresh Claude Code session, run `/worker-start --discipline tdd`, then end a turn. A worker claims a `needs: tdd` entry and drives it through the optional `tdd → review → validate` proof loop. To drive one entry through all three disciplines in one session, use `/board-run <entry-id>`.

> **One session, one mode.** `/pm-start` and `/worker-start` set a *session mode* (stored in `.engineering-board/session-mode.json`). A session holds one mode at a time, so switching from PM to Worker — or back to passive capture — is done by starting a new session, not by running the other command mid-session (it will decline and tell you to restart). On Claude Code web each session is a fresh clone, so a new session starts clean; on a local install the mode file persists on disk, so to return to plain passive capture, start a new session and, if it still shows a mode, delete `.engineering-board/session-mode.json`. The `SessionStart` banner prints the current mode so you always know where you are.

**What to expect (measured, following only this page):** first captured finding in ~5 minutes from install; first promoted board entry in ~10–15 minutes once you run `/pm-start`. A successful non-empty capture prints a one-line confirmation; run `/board-view` to open a themed visual Kanban of the board (or `/board-rebuild` to refresh the markdown `BOARD.md` index). Full mode reference is the [feature tour](#feature-tour) below.

### MCP server

Register the zero-dependency `python3` server with the Claude Code CLI — one line from PyPI:

```sh
claude mcp add engineering-board -- uvx engineering-board-mcp
```

Fallback — run it from a clone:

```sh
git clone https://github.com/GhostlyGawd/engineering-board
claude mcp add e