Product description

Engineering Board is a repository-owned pattern-intelligence system for engineering agents.

The system records bugs, features, questions, and observations as Markdown evidence. It connects recurring findings in a deterministic graph.

The graph helps an agent investigate a shared cause across different domains. This method reduces repeated corrections of individual symptoms.

Markdown is the canonical record. A pull request can show each change to this record.

BOARD.md, GRAPH.yml, JSON analysis, and HTML are derived views. The system can build these views again from the canonical record.

A hypothesis is separate from a deterministic graph fact. Only investigation evidence or fix evidence can confirm a hypothesis.

The optional tdd → review → validate loop can test a fix. This loop supports the pattern memory, but it does not define the product.

Milestone C adds:

• A transparent investigation score from 0 through 100
• A durable H### hypothesis lifecycle
• Negative memory for a rejected claim.

Each score component is visible. A score does not prove that a cause is true.

Milestone D puts this memory in the agent's decision path:

• board_context retrieves relevant clusters, hypotheses, negative memory, and Learnings before the agent selects a fix.
• Each result shows the structural signals, score components, reason, state, and canonical sources.
• board_outcomes records an explicit fix result against an H### hypothesis.
• Structured outcomes update Learning state and confidence through a separate preview and apply operation.
• A derived value report counts verified reuse and systemic fix evidence. It does not count prompts, sessions, or other activity.

Milestone D.1 adds a repository-only evaluation harness and eight sanitized cases. The harness prepares 32 isolated baseline/context pairs, records bounded evidence, and scores the accepted product-effect and false-positive gates. The live paired evidence run has not started. The project does not yet claim that the context improves agent diagnoses. See evaluation/README.md for the proof boundary and operator commands.

Product differences

Some Git boards show visible state but have little analysis. Some memory systems have useful analysis but keep the source outside the repository.

Engineering Board combines these properties:

• Repository evidence that a pull request can review
• A cross-domain pattern graph with evidence links
• H### records with alternatives and falsifiers
• Negative memory for rejected claims
• Atomic claims for parallel agents
• Passive capture
• A Claude Code plugin
• An MCP server.

Native Claude Code Tasks and Engineering Board have different purposes.

Native Tasks store personal task state in ~/.claude/tasks/. This state is not part of a project pull request.

Engineering Board stores shared project memory in the repository. Use Native Tasks for temporary personal work. Use Engineering Board for durable project knowledge.

Install the Claude Code plugin

Add the repository marketplace:

/plugin marketplace add GhostlyGawd/engineering-board

Install the plugin:

/plugin install engineering-board

Set up a board:

/board-setup

/board-setup creates the board structure. It also checks the required permissions.

Run the contained demonstration:

/board-demo

The command creates a synthetic run in .engineering-board/demo/pattern-intelligence/.

The command connects three findings from different domains. It then requests one hypothesis that cites the evidence.

The hypothesis has status: proposed. It includes an alternative explanation and a falsifier.

The report gives an exact cleanup command. The cleanup operation preserves a changed run.

For explicit setup values, use:

/board-init <project> [affects-prefix]
/board-install-permissions

Use the pattern-memory workflow

1. Work in Claude Code.
2. Let SessionStart and UserPromptSubmit retrieve relevant systemic memory.
3. Run /board-context <project> when you want the same bounded brief explicitly.
4. Investigate the cited cluster, hypothesis, negative memory, or Learning before you select a local fix.
5. Let the Stop hook capture a finding in engineering-board/<project>/_sessions/.
6. Run /board-promote to preview canonical changes.
7. Apply the unchanged promotion plan after you review it.
8. Run /board-insights <project> when you need the complete ranked investigation view.
9. Run /board-hypothesis <project> propose to preview an H### record.
10. Review the evidence, alternative, counter-evidence, confidence basis, and falsifier.
11. Apply the unchanged hypothesis plan.
12. After verification, run /board-outcome <project> preview ....
13. Apply the unchanged outcome plan. Review and apply each returned Learning plan separately.

An outcome records held, failed, partial, or inconclusive. It can confirm, weaken, reject, or leave a hypothesis unchanged only through a compatible explicit disposition.

Use /pm-start only for advanced batch promotion. Use the optional Worker loop only when you want to test a selected fix.

Use one session mode

/pm-start and /worker-start set .engineering-board/session-mode.json.

A session can have one mode. Start a new session to change the mode.

On Claude Code web, each session uses a new clone. On a local installation, the mode file stays on disk.

To return to passive capture:

1. Start a new session.
2. Read the SessionStart message.
3. If a mode remains, delete .engineering-board/session-mode.json.

Register the MCP server

Register the PyPI package with the Claude Code command-line interface (CLI):

claude mcp add engineering-board -- uvx engineering-board-mcp

To run the server from a clone:

git clone https://github.com/GhostlyGawd/engineering-board
claude mcp add engineering-board -- python3 "$(pwd)/engineering-board/mcp-server/engineering_board_mcp.py"

For Claude Desktop, add this object to claude_desktop_config.json:

{
  "mcpServers": {
    "engineering-board": {
      "command": "uvx",
      "args": ["engineering-board-mcp"]
    }
  }
}

mcp-server/README.md also contains setup procedures for Codex CLI, Gemini CLI, and Cursor.

The plugin registers the same server through .mcp.json.

Product surfaces

The plugin has four session modes:

Mode	Start method	Stop action
Passive	Default	Run finding-extractor
Paused	/board-pause	Do not capture a finding
PM	/pm-start	Run the four PM agents
Worker	/worker-start --discipline <tdd|review|validate>	Claim and process one entry

The canonical Stop procedure is hooks/stop-hook-procedure.md.

Commands (21): /board-setup, /board-demo, /board-context, /board-outcome, /board-promote, /board-pattern, /board-insights, /board-hypothesis, /board-run, /board-init, /board-rebuild, /board-graph, /board-view, /board-remember, /board-pause, /board-resume, /pm-start, /worker-start, /board-install-permissions, /board-claim-release, and /board-migrate.

Agents (8): board-manager, finding-extractor, consolidator, tidier, learnings-curator, tdd-builder, code-reviewer, and validator.

Skills (5): board-intake, board-triage, board-resolve, board-consolidate, and board-insights.

Hooks (4 events): SessionStart, PostToolUse(Write), UserPromptSubmit, and Stop.

The MCP server has 19 tools. All tools use the same canonical Markdown and the same deterministic core.

Tool	Function
board_init	Create a project board
board_list_projects	List router projects
board_create_entry	Create a valid entry
board_list_entries	List and filter entries
board_get_entry	Get one entry
board_update_entry	Change one entry
board_graph	Build the deterministic graph
board_context	Retrieve bounded and explainable systemic memory
board_insights	Rank clusters and return linked evidence
board_hypotheses	List, preview, or apply H### operations
board_outcomes	Preview or apply fix outcomes and Learning feedback
board_patterns	List, preview, or apply P### operations
board_promote_findings	Preview or apply scratch promotion
board_rebuild	Build BOARD.md again
board_capture_finding	Add a finding to the scratch inbox
board_claim	Acquire an entry claim
board_release	Release an entry claim
board_remember	Save a learning
board_status	Show board state and ready work

Architecture boundary

Canonical cards, hypotheses, Learnings, and BOARD-ROUTER.md use Markdown. Derived views include BOARD.md, GRAPH.yml, context briefs, value reports, JSON, and HTML.

The product does not require SQLite. A future SQLite index must be disposable and rebuildable. Measured query requirements must justify it.

The runtime uses Claude Code, bash, and python3. It has no runtime package dependency.

Read ARCHITECTURE.md for the full system map.

Roadmap boundary

Milestone D ships in v1.11.0.

The cross-session Conductor remains a draft RFC. /board-run <entry-id> ships only the single-session inner loop.

Cross-repository intelligence, hosted services, and a required database remain outside the current product boundary.

docs/PRODUCT_EVOLUTION_SPEC.md is the authoritative product-direction source.

Contribute

Run the complete test suite:

bash tests/run-all.sh

The run-all command uses the maintained suite list. Read CONTRIBUTING.md before you change the repository.

Support

• Use GitHub Discussions for questions.
• Use GitHub Issues for bugs and features.
• Use GitHub Security Advisories for a vulnerability.
• Use the live board for current project work.
• Use GitHub Sponsors to support the project.

GhostlyGawd maintains this open-source project.

License

The project uses the MIT License.

Language status

The owner approved the current controlled-English text. The project does not claim formal ASD-STE100 compliance, certification, or independent review.