PromptWise

PromptWise

The governance & intelligence layer for AI agents. Role-aware prompting, model routing, cost & budget control, security/compliance scanning, responsible-AI advisories, workflow planning, a governed agile method, runtime enforcement hooks, and 83 portable skill packs — emitted in the formats every agent already reads.

Built on open standards, not against them. PromptWise is a conductor, not a replacement for Cursor / Copilot / Claude Code.

Works with: Claude Code · Claude Desktop (tools only, no hooks) · Codex · Cursor · Gemini CLI · Copilot · Windsurf · JetBrains AI Assistant · Cline · Aider · Goose · OpenHands · Grok Build/Grok CLI (reads CLAUDE.md natively) · any MCP host Standards: MCP · SKILL.md · AGENTS.md

📖 User Guide · Install · Configuration · Architecture · Landing page

---

Why

The ecosystem standardized. MCP (Linux Foundation–governed), SKILL.md, and AGENTS.md are now the shared substrate across every major coding agent. PromptWise doesn't fight that — it compiles its intelligence down to those three formats and adds the layer none of them have:

• Model routing — right tier (Haiku/Sonnet/Opus) per task, with budget awareness.
• Preflight pipeline — every prompt, in every connected host, gets one combined pass before work starts: rewrite advisory, secret/injection scan, task-type classification (bugfix/docs/refactor/enhancement/new-code), model/tier routing, and an opt-in shortlist of the last 2-3 current models per tier. Advisory-only by design (an MCP server can't force a host to swap models mid-turn) — surfaces as session context, never blocks. See core/preflight.py.
• Reasoning-effort routing — low/medium/high, independent of model tier — plus an outcome-learning adapter (mirrors the model-tier router's design) that blends in past results once there's enough evidence, fail-open to the static pick otherwise.
• Context-budget engineering — compression, caching, batching, thread handoff.
• Response-size governance — every tool response passes through one size cap at the call_tool choke point before reaching the caller; a generic recursive walker bounds any over-limit list at any nesting depth, exempting the handful of tools (exports) where the full payload is the point.
• Role intelligence — 83 role/technique skill packs (banking, HIPAA, QA, TDD, ADR, …).
• Compliance gating — auditable PRD→architecture→story→commit chain for regulated teams.
• Runtime enforcement — Claude Code lifecycle hooks auto-run security/policy/audit checks on every Write/Edit and tool call. A flagged write defers to Claude Code's normal allow/deny prompt (never a hard, opaque block) and is logged silently either way; standing exceptions are time-boxed JIT grants (grant_jit_permission), scoped to one file or a whole project. Destructive shell commands and runaway tool-call loops still hard-deny. Fail-open throughout: a hook error never wedges the session. See hooks/.
• Red-team regression harness — a durable, offline attack/benign corpus run against the security scanner, diffed against a stored baseline to catch both missed detections and false-positive regressions (run_red_team_harness). All scanning is air-gapped by default — no unconditional network calls.
• Continuous learning — corrections become durable, searchable rules (FTS5) replayed before relevant work; packs self-optimize offline. Local-first, air-gapped safe.
• Workflow planning — classify a task → an ordered chain of PromptWise's own skill packs (PRD → design → stories → TDD → review). Fully self-contained, no external tools.
• Governed agile method — analyst→pm→architect→po planning then per-story sm→dev→qa loop, with context-engineered stories, advisory quality gates, policy-as-code, and a hash-chained audit trail. See docs/AGILE_METHOD.md.
• In-editor dashboard — an optional local VS Code panel surfaces budget, security posture, and governance proposals at a glance, over the same MCP server. No external services, no daemon, no marketplace install required. See vscode-extension/.

Architecture — one source, three emitters

PromptWise core  (router · roles · compliance · context engine · workflow_planner)
        ├─▶ MCP tools      → route_request, plan_workflow, owasp_scan …  (144)
        ├─▶ SKILL.md packs → 83 portable packs in skill_packs/
        ├─▶ Lifecycle hooks→ enforce security/policy/audit at runtime (hooks/)
        └─▶ AGENTS.md      → project context + active constitution

Quickstart (Claude Code)

git clone https://github.com/u2anilgit/PromptWise.git
cd PromptWise
pip install -e .

Add the plugin marketplace (local) and enable it, or point your MCP host at the server:

// .mcp.json — already included
{
  "mcpServers": {
    "promptwise": {
      "command": "python",
      "args": ["-m", "promptwise.server"],
      "cwd": "${projectDir}",
      "env": { "PYTHONPATH": "${projectDir}/src" }
    }
  }
}

Restart your agent, run /mcp — PromptWise tools appear. Then just /promptwise.

What's inside

Path	What
src/promptwise/	Engine: MCP server + core logic, security, plugins, transports
skill_packs/	83 portable SKILL.md role/technique packs (incl. agile/ personas; copy into any agent)
hooks/	Claude Code lifecycle hooks — runtime security/policy/audit enforcement (fail-open)
commands/, agents/	Plugin slash commands and sub-agents
.claude-plugin/	Plugin + marketplace manifests, the /promptwise hub skill
config/	Pricing, providers, roles, security, compliance config
AGENTS.md	Universal project-context emitter
docs/	Integration guides (configuration reference, multi-platform setup)
vscode-extension/	Optional local VS Code panel — Budget/Security/Governance dashboard, TypeScript, builds to a local .vsix, zero external services

Workflow planner (self-contained)

plan_workflow classifies a task by intent · scale · risk and returns an ordered chain of PromptWise's own skill packs — each step runnable via invoke_skill. No external frameworks, CLIs, or network:

Task shape	→ Workflow (PromptWise skill packs)
Greenfield build	prd-generator → system-design → user-story-generator → tdd → code-review → verification-before-completion
Brownfield change	systematic-debugging → refactoring → test-generator → code-review → verify
Docs / spec only	prd-generator → user-story-generator → adr
Regulated (any of the above)	+ security-architecture + owasp_scan + get_sbom, compliance-gate flag set

VS Code panel (optional)

A local Budget/Security/Governance dashboard, in-editor. Spawns the same MCP server over stdio (via the official @modelcontextprotocol/sdk) — no external services, no daemon, no network calls, no marketplace publish.

cd vscode-extension
npm install
npm run package
code --install-extension promptwise-panel-0.1.0.vsix

Run PromptWise: Open Panel. See vscode-extension/README.md for settings and development notes.

Documentation

Doc	What
docs/USER_GUIDE.md	Hands-on: hub, working with skills, real examples
INSTALL.md	Install + register with any MCP host
CONFIGURATION.md	Config files, budgets, security, adding packs
docs/ARCHITECTURE.md	Functional / technical / ER / sequence diagrams

Testing

pip install -e ".[dev]"
python -m pytest tests -q        # packs, planner, agile method, governance, enforcement hooks, learning loop, policy intel, tracker, tools

VS Code panel (optional, separate package):

cd vscode-extension && npm install && node --test test/*.test.ts

Status

Early-stage, building in public. Package version 1.10.0 in pyproject.toml (the changelog trails a few shipped features — see docs/ROADMAP.md for the live, accurate ledger); 144 MCP tools, 83 portable skill packs, 1638 tests, registered through a decorator-based tool registry (one source of truth per tool, organized into a handlers/ package of 25 category files instead of one monolithic server.py). Everything runs directly from PromptWise — local-first, no third-party integrations, air-gapped by default.

Core engine: model-tier routing with budget awareness, a reasoning-effort axis (low/medium/high, independent of tier, with its own outcome-learning adapter), a response-size cap at the call_tool choke point so no tool response is ever unbounded, context-budget engineering (compression/caching/batching/handoff), and cost + audit logging for every skill invocation.

Cross-agent portability — one governance source, 11 native emitters: Claude, Codex/AGENTS.md, Cursor, Copilot, Cline, Gemini, Windsurf, JetBrains AI Assistant, Aider (CONVENTIONS.md), Goose (.goosehints), OpenHands (.openhands/microagents/repo.md) — plus Grok Build/Grok CLI, which needs no emitter of its own since it natively auto-reads CLAUDE.md/AGENTS.md. detect_agents() probes all of them (bar Grok, which has no marker file to detect) so propose_agent_config's auto-target-selection actually sees every host you've configured. Also: a single-file web-agent bundle (export_web_bundle) for ChatGPT/Gemini/Claude.ai web chat, where there's no IDE/CLI/MCP surface to emit into.

Zero-manual-step onboarding: python -m promptwise bootstrap --sync-agents detects every host present in a repo and writes their native config in one command — the skill-pack surface (active pack families + drift fingerprint) is included automatically, and Codex additionally gets its MCP server registered directly in a repo-scoped .codex/config.toml, no separate manual step required.

Governance & security: the runtime enforcement hooks layer (hooks/) — a flagged Write/Edit defers to Claude Code's normal allow/deny prompt instead of a hard block, logs silently either way, and standing exceptions are time-boxed JIT grants scoped to a file or a whole project; destructive shell commands and runaway tool-call loops still hard-deny. A compliance report card (OWASP LLM Top 10 2025 / NIST AI RMF / MITRE ATLAS), an OpenTelemetry GenAI exporter, policy inheritance (extends: org → team → project, tighten-only), SIEM-streamable audit sinks, within-tier cost-aware model routing, and dashboard auth/RBAC (binds 127.0.0.1 by default; non-loopback requires credentials). An append-only, human-reviewed injection-detection corpus refresh workflow (review_corpus_candidates/promote_corpus_candidates, before/after precision-recall diffed on every promotion) keeps the prompt-injection detector's benchmark corpus current without turning it into a live, unaudited ML classifier. A durable eval + red-team regression harness (offline, baseline-diffed, pass/fail gated), MCP supply-chain auditing, a searchable trace, and prompt version rollback/replay round out the governance surface.

Method & learning: the governed agile method (analyst→pm→architect→po planning, per-story sm→dev→qa loop, quality gates, policy-as-code, hash-chained audit trail), the self-contained workflow planner, a continuous learning loop with offline skill auto-optimization, an autonomous governor (policy-gated, reversible, advise-by-default) with a budget-guardian overlay, diagram generators, and a task/effort/usage tracker. An optional local VS Code panel (vscode-extension/) surfaces budget, security, and governance at a glance over the same MCP server, zero external services.

Known gaps, sized but not built: OAuth/third-party-connector support for remote MCP (ChatGPT Desktop-style apps and third-party agents need federated auth and multi-tenant state — out of scope for token-authenticated team use). Token-authenticated Streamable HTTP transport for your-own-devices/team use is now available (PROMPTWISE_TRANSPORT=http, see docs/OPS_REMOTE_MCP.md). Cost-conscious routing over deprecated/prior-gen models is also unbuilt (the registry already retains deprecated model pricing; the router just never reaches for it — a small, well-scoped addition once the default-on-vs-opt-in question is settled).

License

MIT — see LICENSE. Open standards are credited in NOTICE.