\n\n\n \n \n \n\n\n# Engineering Board\n\n**Repository pattern memory that helps an engineering agent find a root cause.**\n\n_The board is the database._\n\n[](https://ghostlygawd.github.io/engineering-board/)\n[](LICENSE)\n[](CHANGELOG.md)\n[](https://github.com/GhostlyGawd/engineering-board/actions/workflows/test.yml)\n[](https://developers.openai.com/codex/plugins)\n[](https://code.claude.com/docs/en/plugin-marketplaces)\n[](mcp-server/README.md)\n[](https://github.com/GhostlyGawd/engineering-board/stargazers)\n[](https://github.com/GhostlyGawd/engineering-board/releases)\n\n\n\n_Run `/board-demo` to make this synthetic example._\n\n\n\n_This visual shows real deterministic fixture output for the pattern pipeline._\n\n\n\n_This visual shows real deterministic fixture output for root-cause memory._\n\n\n\n_This visual shows the tested context-to-outcome memory loop._\n\n\n\n_This repository uses its own Engineering Board._\n\n
\n\n## Product description\n\nEngineering Board is a repository-owned pattern-intelligence system for\nengineering agents.\n\nThe system records bugs, features, questions, and observations as Markdown\nevidence. It connects recurring findings in a deterministic graph.\n\nThe graph helps an agent investigate a shared cause across different domains.\nThis method reduces repeated corrections of individual symptoms.\n\nMarkdown is the canonical record. A pull request can show each change to this\nrecord.\n\n`BOARD.md`, `GRAPH.yml`, JSON analysis, and HTML are derived views. The system\ncan build these views again from the canonical record.\n\nA hypothesis is separate from a deterministic graph fact. Only investigation\nevidence or fix evidence can confirm a hypothesis.\n\nThe optional `tdd → review → validate` loop can test a fix. This loop supports\nthe pattern memory, but it does not define the product.\n\nMilestone C adds:\n\n- A transparent investigation score from 0 through 100\n- A durable H### hypothesis lifecycle\n- Negative memory for a rejected claim.\n\nEach score component is visible. A score does not prove that a cause is true.\n\nMilestone D puts this memory in the agent's decision path:\n\n- `board_context` retrieves relevant clusters, hypotheses, negative memory, and\n Learnings before the agent selects a fix.\n- Each result shows a stable title, a typed summary of at most 2,000\n characters, the epistemic state, structural signals, score components,\n match reason, and canonical sources.\n- A task-only miss tells the caller to add a file, entry identifier, or current\n directory. Task words do not bypass structural eligibility.\n- `board_outcomes` records an explicit fix result against an H### hypothesis.\n- Structured outcomes update Learning state and confidence through a separate\n preview and apply operation.\n- A derived value report counts verified reuse and systemic fix evidence. It\n does not count prompts, sessions, or other activity.\n\nMilestone D.1 adds a repository-only evaluation harness and eight sanitized\ncases. The default contract prepares 24 isolated baseline/context pairs for a\nCodex reference run. Other clients can run as optional replications without\nchanging the product gate. Protocol and package tests establish supported\nclient surfaces without requiring provider accounts. The first Codex run\nscored 100 percent in both positive baseline and context arms, so the corpus\nwas retained as a non-scored calibration set. A separate locked evidence\ncorpus excludes declared scoring oracles and requires rejected memory in its\nlexical-decoy contexts. Its reference run scored 100 percent for context and\n83.33 percent for baseline. The 16.67-point difference did not meet the\nrequired 25-point improvement. The project does not claim that the context\nimproves agent diagnoses.\n\nThe unlocked version 4 proposal now limits each positive case to one visible\ncurrent incident. It also requires a positive classification to connect that\nincident to prior repository evidence. A non-scored proposal preflight found\nthat v1.11.0 ranks the expected memory but does not include the memory title,\ncause, or summary in the returned result. Context contract version 2 added\nthat bounded canonical content with its separate epistemic state, match\nreason, and sources. Current contract version 3 preserves those limits and\nadds confidence for moment-of-need Learning delivery. A current-source,\none-repetition preflight then produced zero qualifying cross-incident first\ncauses in both the four baseline arms and the four context arms. The expected\nmemories ranked first or second, but the responses did not connect their\ncurrent incident to the prior incident. This is not a scored product-effect\nresult. The proposal remains unlocked, and the exact baseline decision remains\nwith the product owner. See\n[`evaluation/README.md`](evaluation/README.md) for the proof boundary and\noperator commands.\n\n## Product differences\n\nSome Git boards show visible state but have little analysis. Some memory\nsystems have useful analysis but keep the source outside the repository.\n\nEngineering Board combines these properties:\n\n- Repository evidence that a pull request can review\n- A cross-domain pattern graph with evidence links\n- H### records with alternatives and falsifiers\n- Negative memory for rejected claims\n- Atomic claims for parallel agents\n- Passive capture\n- Codex and Claude Code plugins\n- An MCP server.\n\nNative Claude Code Tasks and Engineering Board have different purposes.\n\nNative Tasks store personal task state in `~/.claude/tasks/`. This state is not\npart of a project pull request.\n\nEngineering Board stores shared project memory in the repository. Use Native\nTasks for temporary personal work. Use Engineering Board for durable project\nknowledge.\n\n## Install the Codex plugin\n\nAdd the repository marketplace:\n\n```sh\ncodex plugin marketplace add GhostlyGawd/engineering-board\n```\n\nInstall the plugin:\n\n```sh\ncodex plugin add engineering-board@engineering-board\n```\n\nThe Codex marketplace installs the repository root from the immutable Git tag\nthat matches the advertised plugin version. Refresh the marketplace before\ninstalling a newer released version.\n\nStart a new Codex session. The plugin supplies five board skills and starts the\n19-tool Engineering Board MCP server. It does not require a model-provider\naccount. The Codex manifest explicitly selects `hooks/codex-hooks.json`, which\ncontains no automatic hooks. Codex therefore uses the skills and MCP server\nwithout loading the Claude Code hook workflow from `hooks/hooks.json`.\n\nAsk Codex to initialize Engineering Board in the active repository. The agent\npasses the absolute repository root to `board_init` and uses the MCP tools for\ncapture, promotion, context, graph, hypothesis, outcome, claim, and lifecycle\noperations.\n\n## Install the Claude Code plugin\n\nAdd the repository marketplace:\n\n```text\n/plugin marketplace add GhostlyGawd/engineering-board\n```\n\nInstall the plugin:\n\n```text\n/plugin install engineering-board\n```\n\nSet up a board:\n\n```text\n/board-setup\n```\n\n`/board-setup` creates the board structure. It also checks the required\npermissions.\n\nRun the contained demonstration:\n\n```text\n/board-demo\n```\n\nThe command creates a synthetic run in\n`.engineering-board/demo/pattern-intelligence/`.\n\nThe command connects three findings from different domains. It then requests\none hypothesis that cites the evidence.\n\nThe hypothesis has `status: proposed`. It includes an alternative explanation\nand a falsifier.\n\nThe report gives an exact cleanup command. The cleanup operation preserves a\nchanged run.\n\nFor explicit setup values, use:\n\n```text\n/board-init [affects-prefix]\n/board-install-permissions\n```\n\n## Use the pattern-memory workflow\n\nWith Codex or another MCP client:\n\n1. Initialize one project with `board_init`.\n2. Retrieve relevant memory with `board_context` before selecting a fix.\n3. Capture findings with `board_capture_finding`.\n4. Preview and apply promotion with `board_promote_findings`.\n5. Use `board_insights` and `board_hypotheses` for evidence-linked shared-cause\n analysis.\n6. Record the observed result with `board_outcomes`.\n\nPass the absolute repository root in each bundled-plugin tool call. The plugin\ndoes not guess which open workspace a raw MCP call targets.\n\nWith Claude Code hooks and commands:\n\n1. Work in Claude Code.\n2. Let SessionStart and UserPromptSubmit retrieve relevant systemic memory.\n3. Run `/board-context ` when you want the same bounded brief\n explicitly.\n4. Read the memory title, typed summary, epistemic state, match reason, and\n sources. Inspect the cited canonical record before you rely on a proposed\n cause.\n5. In PM mode, read the matched medium/high-confidence Learnings appended to\n the pass summary after new findings promote.\n6. Let the Stop hook capture a finding in\n `engineering-board//_sessions/`.\n7. Run `/board-promote` to preview canonical changes.\n8. Apply the unchanged promotion plan after you review it.\n9. Run `/board-insights ` when you need the complete ranked\n investigation view.\n10. Run `/board-hypothesis propose` to preview an H### record.\n11. Review the evidence, alternative, counter-evidence, confidence basis, and\n falsifier.\n12. Apply the unchanged hypothesis plan.\n13. After verification, run `/board-outcome preview ...`.\n14. Apply the unchanged outcome plan. Review and apply each returned Learning\n plan separately.\n\nAn outcome records `held`, `failed`, `partial`, or `inconclusive`. It can\nconfirm, weaken, reject, or leave a hypothesis unchanged only through a\ncompatible explicit disposition.\n\nUse `/pm-start` only for advanced batch promotion. Use the optional Worker loop\nonly when you want to test a selected fix.\n\n## Use one session mode\n\n`/pm-start` and `/worker-start` set\n`.engineering-board/session-mode.json`.\n\nA session can have one mode. Start a new session to change the mode.\n\nOn Claude Code web, each session uses a new clone. On a local installation, the\nmode file stays on disk.\n\nTo return to passive capture:\n\n1. Start a new session.\n2. Read the `SessionStart` message.\n3. If a mode remains, delete `.engineering-board/session-mode.json`.\n\n## Register the MCP server without a plugin\n\nRegister the PyPI package with the Claude Code command-line interface (CLI):\n\n```sh\nclaude mcp add engineering-board -- uvx engineering-board-mcp\n```\n\nTo run the server from a clone:\n\n```sh\ngit clone https://github.com/GhostlyGawd/engineering-board\nclaude mcp add engineering-board -- python3 \"$(pwd)/engineering-board/mcp-server/engineering_board_mcp.py\"\n```\n\nFor Claude Desktop, add this object to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"engineering-board\": {\n \"command\": \"uvx\",\n \"args\": [\"engineering-board-mcp\"]\n }\n }\n}\n```\n\n[`mcp-server/README.md`](mcp-server/README.md) also contains setup procedures\nfor Codex CLI, Gemini CLI, and Cursor.\n\nThe Claude Code plugin registers the server through [`.mcp.json`](.mcp.json).\nThe Codex manifest selects [codex-mcp.json](codex-mcp.json). Both files start\nonly Engineering Board through the same cross-platform launcher. The\nCodex-specific file uses the `writes` approval policy: read-only memory tools\ncan run without a per-call prompt, while every write-capable tool stays gated.\n\n## Product surfaces\n\nThe plugin has four session modes:\n\n| Mode | Start method | Stop action |\n|---|---|---|\n| Passive | Default | Run `finding-extractor` |\n| Paused | `/board-pause` | Do not capture a finding |\n| PM | `/pm-start` | Run the four PM agents |\n| Worker | `/worker-start --discipline ` | Claim and process one entry |\n\nThe canonical Stop procedure is\n[`hooks/stop-hook-procedure.md`](hooks/stop-hook-procedure.md).\n\n**Commands (21):** `/board-setup`, `/board-demo`, `/board-context`,\n`/board-outcome`, `/board-promote`, `/board-pattern`, `/board-insights`,\n`/board-hypothesis`, `/board-run`, `/board-init`, `/board-rebuild`,\n`/board-graph`, `/board-view`, `/board-remember`, `/board-pause`,\n`/board-resume`, `/pm-start`, `/worker-start`,\n`/board-install-permissions`, `/board-claim-release`, and `/board-migrate`.\n\n**Agents (8):** `board-manager`, `finding-extractor`, `consolidator`, `tidier`,\n`learnings-curator`, `tdd-builder`, `code-reviewer`, and `validator`.\n\n**Skills (5):** `board-intake`, `board-triage`, `board-resolve`,\n`board-consolidate`, and `board-insights`.\n\n**Claude Code hooks (4 events):** `SessionStart`, `PostToolUse(Write)`,\n`UserPromptSubmit`, and `Stop`. The Codex plugin selects its separate empty\nhook manifest and uses the MCP-first workflow.\n\nThe MCP server has 19 tools. All tools use the same canonical Markdown and the\nsame deterministic core.\n\n| Tool | Function |\n|---|---|\n| `board_init` | Create a project board |\n| `board_list_projects` | List router projects |\n| `board_create_entry` | Create a valid entry |\n| `board_list_entries` | List and filter entries |\n| `board_get_entry` | Get one entry |\n| `board_update_entry` | Change one entry and archive a new resolution |\n| `board_graph` | Build the deterministic graph |\n| `board_context` | Retrieve bounded and explainable systemic memory |\n| `board_insights` | Rank clusters and return linked evidence |\n| `board_hypotheses` | List, preview, or apply H### operations |\n| `board_outcomes` | Preview or apply fix outcomes and Learning feedback |\n| `board_patterns` | List, preview, or apply P### operations |\n| `board_promote_findings` | Preview or apply scratch promotion without reusing resolved IDs; an unchanged plan id restores an omitted preview session selector |\n| `board_rebuild` | Build `BOARD.md` again |\n| `board_capture_finding` | Add a finding to the scratch inbox |\n| `board_claim` | Acquire an entry claim |\n| `board_release` | Release an entry claim |\n| `board_remember` | Save a learning |\n| `board_status` | Show board state and ready work |\n\nThe six pure-read tools are `board_list_projects`, `board_list_entries`,\n`board_get_entry`, `board_insights`, `board_context`, and `board_status`. Their\nMCP schemas set `readOnlyHint: true`. Every other tool is classified by its\nmaximum capability. A tool that can preview and apply a change is therefore\nwrite-capable for approval purposes. The Codex plugin's `writes` approval\npolicy lets the six pure-read tools run without a prompt and keeps every\nwrite-capable tool approval-gated. These annotations are advisory metadata.\nThey do not replace host policy, root containment, content-bound plans, or\nclaim ownership.\n\n## Architecture boundary\n\nCanonical cards, hypotheses, Learnings, and `BOARD-ROUTER.md` use Markdown.\nDerived views include `BOARD.md`, `GRAPH.yml`, context briefs, value reports,\nJSON, and HTML.\n\nThe product does not require SQLite. A future SQLite index must be disposable\nand rebuildable. Measured query requirements must justify it.\n\nThe shared MCP runtime uses Python 3 and has no third-party package dependency.\nThe Codex plugin uses Node.js only to select a Python interpreter on Windows or\nLinux. Claude Code commands and hooks use Bash and Python 3.\n\nRead [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full system map.\n\n## Roadmap boundary\n\nMilestone D ships in v1.11.0.\n\nThe cross-session Conductor remains a draft RFC. `/board-run ` ships\nonly the single-session inner loop.\n\nCross-repository intelligence, hosted services, and a required database remain\noutside the current product boundary.\n\n[`docs/PRODUCT_EVOLUTION_SPEC.md`](docs/PRODUCT_EVOLUTION_SPEC.md) is the\nauthoritative product-direction source.\n\n## Contribute\n\nRun the complete test suite:\n\n```sh\nbash tests/run-all.sh\n```\n\nThe run-all command uses the maintained suite list. Read\n[`CONTRIBUTING.md`](CONTRIBUTING.md) before you change the repository.\n\n## Support\n\n- Use [GitHub Discussions](https://github.com/GhostlyGawd/engineering-board/discussions) for questions.\n- Use [GitHub Issues](https://github.com/GhostlyGawd/engineering-board/issues/new/choose) for bugs and features.\n- Use [GitHub Security Advisories](https://github.com/GhostlyGawd/engineering-board/security/advisories/new) for a vulnerability.\n- Use the [live board](https://ghostlygawd.github.io/engineering-board/board.html) for current project work.\n- Use [GitHub Sponsors](https://github.com/sponsors/GhostlyGawd) to support the project.\n\nGhostlyGawd maintains this open-source project.\n\n## License\n\nThe project uses the [MIT License](LICENSE).\n\n## Language status\n\nThe owner approved the current controlled-English text. The project does not\nclaim formal ASD-STE100 compliance, certification, or independent review.\n",
"bytes": 18367,
"sha": "b0f87f851848db07f8f6c252bd4d759a6e9b8eaeec160cb21e239a1809dd08f4",
"repo_slug": "ghostlygawd/engineering-board",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ghostlygawd_engineering_board_ccb14948/readme"
}
![\"Engineering](\"brand/logomark-light.svg\")
\n![\"Three](\"docs/assets/pattern-intelligence-demo.png\")
\n\n_Run `/board-demo` to make this synthetic example._\n\n![\"The](\"docs/assets/milestone-b-pattern-pipeline.svg\")
\n\n_This visual shows real deterministic fixture output for the pattern pipeline._\n\n![\"The](\"docs/assets/milestone-c-root-cause-intelligence.svg\")
\n\n_This visual shows real deterministic fixture output for root-cause memory._\n\n![\"The](\"docs/assets/milestone-d-context-outcome-intelligence.svg\")
\n\n_This visual shows the tested context-to-outcome memory loop._\n\n![\"The](\"docs/assets/board-screenshot.png\")
\n\n_This repository uses its own Engineering Board._\n\n