|
26 | 26 | npm run link-mcp |
27 | 27 | \\\ |
28 | 28 |
|
29 | | ---- |
30 | | -*For a deep dive into the internal graph architecture, please see the [Wiki](WIKI/Home.md).* |
| 29 | +- prompt governance before code execution |
| 30 | +- MCP-based integration instead of editor-specific glue |
| 31 | +- evidence-backed refinement using history, tests, and repo context |
| 32 | + |
| 33 | +## What It Demonstrates |
| 34 | + |
| 35 | +- **MCP integration**: the active implementation is the `universal-refiner` package, a TypeScript MCP server for cross-CLI prompt refinement |
| 36 | +- **Governance pipeline**: prompts can be captured, classified, refined, and linked to execution outcomes instead of being treated as disposable chat |
| 37 | +- **Repo-aware context**: detectors, memory, and retrieval components adapt refinement to the current codebase |
| 38 | +- **Proof-oriented design**: tests and architecture docs emphasize traceability, learning, and operational visibility rather than prompt rewriting alone |
| 39 | + |
| 40 | +## Features |
| 41 | + |
| 42 | +- **RAG snippets**: FlexSearch-based retrieval over the local codebase to inject relevant examples into prompt refinement |
| 43 | +- **Persistent memory**: SQLite-backed storage for reusable rules, learned patterns, and prompt history |
| 44 | +- **Context scouting**: detectors identify language, framework, and architectural signals at startup |
| 45 | +- **Operational traceability**: history, timelines, and prompt-to-outcome correlation are first-class design goals |
| 46 | + |
| 47 | +## Current Scope vs. Roadmap |
| 48 | + |
| 49 | +The repo contains both implemented components and forward-looking architecture. |
| 50 | + |
| 51 | +- **Implemented now**: the `universal-refiner` MCP server, Gemini-oriented packaging, tests, and install/build scripts |
| 52 | +- **Designed for later expansion**: broader routing, portal, and evidence workflows described in the architecture spec |
| 53 | + |
| 54 | +That distinction matters because this repo is about credible system direction, not vague AI middleware claims. |
| 55 | + |
| 56 | +## Architecture Snapshot |
| 57 | + |
| 58 | +```mermaid |
| 59 | +flowchart LR |
| 60 | + CLI["AI CLI\n(Claude / Cursor)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"] |
| 61 | + subgraph internal["PromptImprover Engine"] |
| 62 | + RAG["RAG Snippets\n(FlexSearch)"] |
| 63 | + Memory["SQLite Memory\n(LocalBrain)"] |
| 64 | + AutoHeal["Auto-Heal\n(BackgroundService)"] |
| 65 | + end |
| 66 | + PI --> RAG |
| 67 | + PI --> Memory |
| 68 | + PI --> AutoHeal |
| 69 | + internal --> Out["Augmented Prompt"] |
| 70 | +``` |
| 71 | + |
| 72 | +## Proof Points |
| 73 | + |
| 74 | +- [Portfolio proof notes](./docs/portfolio-proof.md) |
| 75 | +- [Architecture spec](./docs/promptimprover-autogen-architecture-spec.md) |
| 76 | +- [Operator testing guide](./docs/operator-testing.md) |
| 77 | +- [Enterprise release gates](./docs/enterprise-release-gates.md) |
| 78 | +- [`universal-refiner/package.json`](./universal-refiner/package.json) |
| 79 | +- [`universal-refiner/tests`](./universal-refiner/tests) |
| 80 | + |
| 81 | +## Quickstart |
| 82 | + |
| 83 | +```powershell |
| 84 | +git clone https://github.com/Coding-Autopilot-System/Promptimprover.git |
| 85 | +cd Promptimprover |
| 86 | +.\build_and_install.ps1 |
| 87 | +``` |
| 88 | + |
| 89 | +On Linux or macOS: |
| 90 | + |
| 91 | +```sh |
| 92 | +git clone https://github.com/Coding-Autopilot-System/Promptimprover.git |
| 93 | +cd Promptimprover |
| 94 | +./build_and_install.sh |
| 95 | +``` |
| 96 | + |
| 97 | +Both installers perform a deterministic dependency install, run the full test suite, build the package, install it globally, and verify the `universal-refiner` command. Add that command to your MCP client configuration. See the [Setup Guide](https://github.com/Coding-Autopilot-System/Promptimprover/wiki/Setup-Guide) for full configuration instructions. |
| 98 | + |
| 99 | +For optional automatic pre-prompt linting and post-execution recording, see the [cross-CLI automation guide](./docs/cross-cli-automation.md). Claude Code and Gemini CLI expose the required lifecycle hooks. Codex currently requires MCP-first instructions or explicit helper invocation because its hook lifecycle does not transparently intercept each prompt. |
| 100 | + |
| 101 | +## Local Semantic Model |
| 102 | + |
| 103 | +PromptImprover uses a local OpenAI-compatible endpoint before optional MCP sampling. The safe defaults target `http://localhost:9000/v1`, use `gemma3:12b` first, and fall back to `gemma3:1b`. If neither local model nor MCP sampling is available, rule-based refinement continues without semantic output. |
| 104 | + |
| 105 | +Override the defaults per repository with `.universal-refiner.json`: |
| 106 | + |
| 107 | +```json |
| 108 | +{ |
| 109 | + "semantic": { |
| 110 | + "localEnabled": true, |
| 111 | + "mcpSamplingEnabled": true, |
| 112 | + "baseUrl": "http://localhost:9000/v1", |
| 113 | + "models": ["gemma3:12b", "gemma3:1b"], |
| 114 | + "timeoutMs": 120000, |
| 115 | + "temperature": 0.2, |
| 116 | + "allowNonLoopback": false |
| 117 | + } |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +Non-loopback model endpoints are rejected unless `allowNonLoopback` is explicitly enabled. Generated lessons and templates remain pending until reviewed through the MCP learning-review tools. |
| 122 | + |
| 123 | +## License |
| 124 | + |
| 125 | +MIT - see [LICENSE](LICENSE) |
| 126 | + |
| 127 | +<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 --> |
0 commit comments