[!NOTE] Status: v0.2.1 released · PyPI · pip install planner-critic License: MIT

Why

Planning is the weakest part of agent systems. Most agents act too early, skip hard subproblems, and start executing a plan that was never reviewed. A single-pass decomposition embeds silent assumptions, and the first sign of trouble arrives mid-execution — after state has already diverged.

Single-pass planning fails silently on multi-step goals, and a model "reviewing" its own plan is agreement with extra steps. There is no draft to review, no independent reviewer to catch the gap, and no structured escalation.

PlannerCritic Engine closes this gap by treating planning as a first-class, productized artifact rather than a hidden chain-of-thought side effect.

What It Is

The Draft → Critique → Revise → Escalate Loop

 Goal + Constraints → PLANNER → typed plan → CRITIC → findings
                         ↑  │                        │
                         │  └────── revise ←──────────┘
                         │                             │
                         └──────── approved plan ──────┘
                                      │
                                   ESCALATE (if no convergence)

• Draft — a planner LLM decomposes a goal into a structured, typed plan: tasks, dependencies, ordering, verification steps, and rollback points.
• Critique — a separate critic LLM audits every subtask against six heuristic families: feasibility, risk, missing steps, unsafe sequencing, unverified dependencies, weak rollback — producing severity-graded findings.
• Revise — the planner revises in response, in a bounded loop with a revision budget and convergence detection, preserving draft history.
• Escalate — if the loop cannot converge, a human gets a minimal, precise question about exactly what is blocking approval.

The plan is a persisted, versioned artifact — you can diff revisions, see which critiques drove which changes, and trace whether a failed run was a planning failure or an execution failure.

Key Features

What It Is Not

• It does not execute the plan — an existing runner consumes the approved plan.
• It does not guarantee plan correctness — it reduces risk, it cannot eliminate it.
• It does not replace execution engines or agent frameworks (LangGraph, CrewAI, etc.).

Quick Start

Install

pip install planner-critic

Requires Python 3.11+.

Configure an LLM provider

Create a config file (or set an env var for the API key):

# plancritic.toml
[roles]
planner = "local"
critic = "local"

[providers.local]
transport = "openai-compatible"
base_url = "https://openrouter.ai/api/v1"      # or your provider
model = "openai/gpt-4o-mini"
api_key = "${OPENROUTER_API_KEY}"               # or set in your shell
max_tokens = 16384
timeout_s = 300.0

Run your first plan

plancritic plan path/to/goal.json --config plancritic.toml
plancritic demo       # run the bundled demo scenario
plancritic quickstart # create and run a sample goal

Requires an LLM provider (OpenRouter, OpenAI, or a local model). See the User Guide for a full walkthrough.

CLI

plancritic plan <goal.json>                # Plan a goal
plancritic critique <plan.json>            # Critique a plan
plancritic check --plan <plan.json>        # Quality check a plan
plancritic diagnose <plan-id>              # Diagnose plan issues
plancritic domains list                    # List available domain packs
plancritic policy check <plan.json>        # Evaluate Rego/CEL policies
plancritic templates list                  # List scaffold templates
plancritic field-test run --goals <dir>    # Run field test
plancritic eval --regression               # Security oracle regression
plancritic findings list                   # List plan findings
plancritic lessons                         # List learned lesson codes
plancritic plan replay <plan-id>           # Replay plan history
plancritic escalate list                   # List escalations
plancritic demo                            # Run demo scenario
plancritic quickstart                      # Quickstart demo
plancritic init [--dir]                    # Scaffold config + store
plancritic providers add/list/rm           # Manage LLM providers
plancritic migrate <old> <new>             # Migrate schema
plancritic serve                           # Start HTTP server
plancritic quota show                      # Show blast-radius quotas

See API Reference for full CLI docs, HTTP endpoints, and MCP tools.

Field Test

170 goals across 40 domains, all run against a real LLM (gpt-4o-mini via OpenRouter):

Full results: field-test-results-0.2.0.md

Documentation

Project Layout

planner-critic-engine/
├── docs/                    Documentation
│   ├── architecture/          System architecture and spec
│   ├── design/                PRD, design spec, design decisions
│   ├── field-test/            Field test plan + results (170 goals, 40 domains)
│   ├── reference/             API reference, quickstart, release notes
│   └── wbs/                   Work breakdown structure (M1–M10)
├── src/planner_critic/       Engine source
│   ├── adapters/               AutoGen, CrewAI, LangGraph, OpenAI Agents, PydanticAI adapters
│   ├── cli/                    21 CLI commands
│   ├── critique/               LLM critic with severity guardrail
│   ├── domains/                Domain-specific gate packs (SecOps, Supply Chain, FinOps, Data Eng)
│   ├── eval/                   Security oracle, injection harness, regression, label migration
│   ├── gates/                  7 deterministic gates
│   ├── llm/                    Provider registry, transport, logging
│   ├── loop/                   Plan revision loop, auto-repair, convergence, oscillation
│   ├── probe/                  Health probes (DB, deploy, env, HTTP)
│   ├── schema/                 Goal and plan schemas
│   ├── server/                 HTTP + MCP servers
│   └── store/                  SQLite plan store with versioning
├── tests/                    Test suite (field test + 90 deterministic tests)
├── .github/                  Issue templates, PR template, CI workflows
├── CHANGELOG.md               Release history
├── CONTRIBUTING.md            How to contribute
├── SECURITY.md                Security policy + OWASP + OpenSSF
└── pyproject.toml             Package metadata

Known Gaps (v0.3.0)

The authoritative register of known failure modes and load-bearing assumptions — each classified as an intentional trade-off or a claim still needing evidence — lives in docs/reference/failure-modes.md. Summary:

• Planner capability gap — strict mode = escalation for non-trivial plans (intentional posture; see register F-01).
• Local model support for planner — Qwen3-4B JSON valid; critic role still too weak (F-09).
• TUI / studio / IDE surfaces — deferred to v0.3.0 (F-11).
• Backstage developer portal plugin — deferred to v0.3.0 (F-12).
• Adaptive revision cap — detect strict goals and reduce cap to 1, saving LLM calls (F-10).

See CHANGELOG.md for full details.

License

MIT — see LICENSE.