|
1 | 1 | # Architecture |
2 | 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 --> |
| 3 | + |
0 commit comments