|
| 1 | +# Architecture |
| 2 | + |
| 3 | +## Governance / blackboard flow |
| 4 | + |
| 5 | +`universal-refiner` (the active MCP server) intercepts a raw prompt from an AI CLI, runs it |
| 6 | +through context and refinement, and — via `AgenticBlackboard` (`src/core/blackboard.ts`) — |
| 7 | +publishes and reads shared state so concurrent agent sessions can coordinate rather than act |
| 8 | +on disjoint local knowledge. |
| 9 | + |
| 10 | +```mermaid |
| 11 | +flowchart LR |
| 12 | + CLI["AI CLI\n(Claude / Cursor / Gemini)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"] |
| 13 | + subgraph Engine["Governance & Refinement Engine"] |
| 14 | + Scout["Context Scout\nlanguage/framework detectors"] |
| 15 | + RAG["RAG Snippets\nFlexSearch retrieval"] |
| 16 | + Memory[("SQLite Memory\nLocalBrain")] |
| 17 | + Semantic["Local Semantic Model\ngemma3:12b / 1b"] |
| 18 | + end |
| 19 | + subgraph BB["AgenticBlackboard (blackboard.json)"] |
| 20 | + Intents["Active agent intents\n(agentName, toolType, expiresAt)"] |
| 21 | + Logs["System logs\n(per-project)"] |
| 22 | + LastRefine["Last refinement record\n(gain metric)"] |
| 23 | + end |
| 24 | + PI --> Scout --> RAG --> Memory --> Semantic --> PI |
| 25 | + PI -->|"publish intent"| BB |
| 26 | + BB -->|"read concurrent intents"| PI |
| 27 | + PI --> Out["Augmented Prompt"] |
| 28 | + Out -.->|"event store"| Memory |
| 29 | +``` |
| 30 | + |
| 31 | +<!-- codex:generate-image prompt="A shared glowing chalkboard in the center of a room, with several small agent robots (labeled Claude, Cursor, Gemini) posting colored intent cards onto it and reading each other's cards before acting; one robot writes a refined prompt scroll that flows out to a waiting execution robot; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" --> |
| 32 | + |
| 33 | +## Component breakdown |
| 34 | + |
| 35 | +- **Context Scout** — startup detectors identify language, framework, and architectural |
| 36 | + signals so refinement is tailored to the current codebase (`src/detectors/project-scout.ts`). |
| 37 | +- **RAG Snippets** — FlexSearch-based retrieval over the local codebase injects relevant |
| 38 | + examples into the refined prompt. |
| 39 | +- **AgenticBlackboard** — a JSON-file-backed shared store (`.refiner/blackboard.json`, |
| 40 | + project-scoped, with a global fallback under `~/.refiner`) recording active agent intents |
| 41 | + (`agentName`, `toolType`, `intent`, `expiresAt`), system logs, and the last refinement's |
| 42 | + gain metric. A serialized write queue (`writeQueue`) and listener registry prevent |
| 43 | + concurrent-write corruption when multiple CLI sessions touch the same project. |
| 44 | +- **LocalBrain (SQLite)** — persistent storage for reusable refinement rules, learned |
| 45 | + patterns, and prompt history. |
| 46 | +- **Local Semantic Model** — an optional OpenAI-compatible local endpoint (`gemma3:12b`, |
| 47 | + falling back to `gemma3:1b`) that produces the final refined prompt; rule-based refinement |
| 48 | + continues if neither the local model nor MCP sampling is available. |
| 49 | +- **Governance gate** — generated lessons and templates remain pending until reviewed through |
| 50 | + the MCP learning-review tools (see the root README's Local Semantic Model section) — the |
| 51 | + blackboard records the intent and history that gate reviews against. |
| 52 | + |
| 53 | +<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 --> |
0 commit comments