engineering board

Connect findings.
Inspect the evidence.

Repository memory for engineering agents.

Start with Codex Explore example

First useAsk Codex to initialize Engineering Board in this repository.

Expected resultA repository-owned Markdown board.

Synthetic example · Read-only

B001Worker skips a review-ready entryB002Board shows the wrong laneB003Ready-work list omits the entry
Proposed hypothesisH001Lifecycle rules differ
across adapters.

Three findings.
One pattern to investigate.

01 / Follow the evidence

Synthetic example Read-only

Open hypothesis source
H001 / HYPOTHESISProposed hypothesis

Lifecycle rules differ across adapters.

Evidence
Three findings share a lifecycle-state pattern.
Alternative
Independent filtering errors.
Falsifier
All adapters use the same rule.
Outcome
No outcome recorded.
Inspect the sources before selecting a fix.Open source record
B001 / FINDINGOpen · Synthetic

Worker skips a review-ready entry

Affects
hooks/worker-routing
Observed
The worker selection path treats an otherwise eligible needs: review entry as unavailable.
Evidence
Synthetic trace: the entry is open, unblocked, and unclaimed, but the worker returns no work.
Next action
Inspect the adapter’s lifecycle rule and compare it with the same review-ready state in the other adapters.
View proposed hypothesisOpen source record
B002 / FINDINGOpen · Synthetic

Board shows the wrong lane

Affects
board-view/lifecycle-lanes
Observed
The HTML renderer places a needs: review entry in the To do lane.
Evidence
Synthetic snapshot: the Markdown state and rendered lane disagree for the same entry.
Next action
Inspect the adapter’s lifecycle rule and compare it with the same review-ready state in the other adapters.
View proposed hypothesisOpen source record
B003 / FINDINGOpen · Synthetic

Ready-work list omits the entry

Affects
mcp-server/ready-queue
Observed
The MCP ready queue omits an open, unblocked entry in the same lifecycle state.
Evidence
Synthetic response: the entry is present in the board but absent from ready results.
Next action
Inspect the adapter’s lifecycle rule and compare it with the same review-ready state in the other adapters.
View proposed hypothesisOpen source record

02 / Start in your repository

Your first board.
A lasting record.

Install the plugin in Codex, then start a new session in your repository. Your board lives alongside your code.

Run these commands in your terminal, then initialize a board in your repository.

01

Add the Codex plugin

codex plugin marketplace add GhostlyGawd/engineering-board
codex plugin add engineering-board@engineering-board

You need Codex CLI and Python 3 available on your machine. The plugin provides 19 tools. Six pure-read tools inspect repository memory; write-capable tools remain approval-gated.

02

Start a new Codex session

Open the repository you want to use, then ask:

Initialize Engineering Board in this repository and show me the board location.

03

Check the result

Expect a repository-owned Markdown board. Ask Codex to show the board and its location. Then capture a real engineering observation when one arises.

If the board tools are missing

Confirm both installation commands completed, then start a new Codex session. Check that Python 3 is available. Ask Codex whether the Engineering Board MCP server is connected before retrying initialization.

Using Claude Code or another MCP client

In Claude Code, run these commands in order:

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

After setup, /board-demo is an optional synthetic walkthrough in an isolated local directory.

Other MCP clients use the bundled Python server. See the client setup notes.