Skip to content

Commit ce1b148

Browse files
AitomatesAitomates
committed
docs(36-03): add docs/wiki tree (Home, Architecture, Operations, Decisions)
- Architecture.md documents the governance/blackboard flow (AgenticBlackboard) - Operations.md verified install/build/test/release-gate/CI commands - Decisions.md indexes phase history, ADR convention, and open PRs
1 parent dee3911 commit ce1b148

4 files changed

Lines changed: 177 additions & 0 deletions

File tree

‎docs/wiki/Architecture.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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 -->

‎docs/wiki/Decisions.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Decisions
2+
3+
## ADR convention
4+
5+
`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/
6+
Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in
7+
`.planning/phases/` and the `docs/` architecture specs instead.
8+
9+
## Phase history (`.planning/phases/`, this repo's own GSD project)
10+
11+
| Phase | Topic |
12+
|---|---|
13+
| 01 | FS watcher |
14+
15+
See [`docs/promptimprover-autogen-architecture-spec.md`](../promptimprover-autogen-architecture-spec.md),
16+
[`docs/enterprise-release-gates.md`](../enterprise-release-gates.md), and
17+
[`docs/operator-testing.md`](../operator-testing.md) for the broader design record beyond the
18+
single formal phase.
19+
20+
## Open decisions tracked in this Phase 36 refresh
21+
22+
- **PR #27** (`fix/dashboard-loopback-xss`) — bind dashboard to loopback and escape HTML in
23+
trace rendering; open, not yet merged.
24+
- **PR #28** (`ci/sha-pin-and-least-privilege`) — pins third-party GitHub Actions to commit
25+
SHAs and least-privilege permissions; open, not yet merged.
26+
27+
<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

‎docs/wiki/Home.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# PromptImprover Wiki
2+
3+
## Role in the CAS portfolio
4+
5+
`Promptimprover` is part of the **Governance plane** of the Coding-Autopilot-System
6+
three-plane model (Control / Execution / Governance). It is an MCP-first prompt governance
7+
layer: it sits between an AI CLI and execution tools, adds repo-aware context, applies
8+
refinement rules, and — via its `AgenticBlackboard` — coordinates intent and history across
9+
concurrent agent sessions rather than treating each prompt as disposable chat.
10+
11+
| Plane | This repo's responsibility |
12+
|---|---|
13+
| Control | *(not this repo — see `gsd-orchestrator`)* |
14+
| Execution | *(not this repo — see `autogen`)* |
15+
| Governance | Prompt refinement, cross-agent blackboard coordination, learning-review workflow |
16+
17+
## Quickstart
18+
19+
- [README.md](../../README.md) — Quickstart, Local Semantic Model, Proof Points
20+
- [Architecture](./Architecture.md) — governance/blackboard flow
21+
- [Operations](./Operations.md) — verified install/build/test/release-gate commands
22+
- [Decisions](./Decisions.md) — phase history and ADR convention
23+
24+
## Ecosystem links
25+
26+
Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org:
27+
[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) ·
28+
[autogen](https://github.com/Coding-Autopilot-System/autogen) (execution plane) ·
29+
[cas-contracts](https://github.com/Coding-Autopilot-System/cas-contracts) (shared schemas) ·
30+
[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate)
31+
32+
<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

‎docs/wiki/Operations.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Operations
2+
3+
## Setup
4+
5+
```powershell
6+
git clone https://github.com/Coding-Autopilot-System/Promptimprover.git
7+
cd Promptimprover
8+
.\build_and_install.ps1
9+
```
10+
11+
Linux/macOS:
12+
13+
```sh
14+
git clone https://github.com/Coding-Autopilot-System/Promptimprover.git
15+
cd Promptimprover
16+
./build_and_install.sh
17+
```
18+
19+
Both installers run a deterministic dependency install, run the full test suite, build the
20+
package, install it globally, and verify the `universal-refiner` command.
21+
22+
## Build and test (`universal-refiner/`)
23+
24+
```bash
25+
npm ci
26+
npm run build
27+
npm run test:coverage
28+
```
29+
30+
## Full local release gate
31+
32+
```powershell
33+
cd C:\PersonalRepo\portfolio\Promptimprover\universal-refiner
34+
npm.cmd run release:verify
35+
```
36+
37+
`release:verify` chains build, coverage tests, acceptance suites (MCP, semantic fallback,
38+
tracked-turn, stdio-MCP), e2e (Playwright), stress/recovery/soak checks, security audit
39+
(production + full) and secret scanning, package dry-run, and packaged runtime startup smoke —
40+
per `universal-refiner/package.json`.
41+
42+
## CI (`.github/workflows/ci.yml`, `ubuntu-latest`, working directory `universal-refiner/`)
43+
44+
**`build-and-test`** job (15-minute timeout):
45+
1. `actions/checkout@v7`
46+
2. `actions/setup-node@v6` (Node 22)
47+
3. `npm ci --no-fund`
48+
4. `npm rebuild better-sqlite3` (native module rebuild)
49+
5. `npm run build`
50+
6. `npm run test:coverage`
51+
52+
**`acceptance`** job (15-minute timeout, matrix `model-order: [primary, reversed]`):
53+
1. Same checkout/setup/install/rebuild/build steps as above
54+
2. Acceptance suite run against each model-order permutation
55+
56+
A separate `.github/workflows/codeql.yml` runs CodeQL analysis (badge in the root `README.md`).
57+
58+
## Global MCP registration doctor
59+
60+
```powershell
61+
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Check
62+
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Apply
63+
```
64+
65+
<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

0 commit comments

Comments
 (0)