[!NOTE] Status: v0.1.0 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

pip install planner-critic
plancritic quickstart  # creates a demo goal and runs the loop
plancritic demo        # runs the full demo scenario

Requires Python 3.11+ and an LLM provider (OpenRouter, OpenAI, or local model).

CLI

plancritic plan <goal.json>              # Plan a goal
plancritic critique <plan.json>          # Critique a plan
plancritic field-test run --goals <dir>   # Run field test
plancritic demo                          # Run demo scenario
plancritic quickstart                    # Quickstart demo
plancritic migrate <old> <new>           # Migrate config
plancritic serve                         # Start HTTP server

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

Field Test

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

Full results: field-test-results-0.1.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 (157 goals, 35 domains)
│   ├── reference/             API reference, quickstart
│   └── wbs/                   Work breakdown structure (M1–M10)
├── src/planner_critic/       Engine source
│   ├── cli/                    CLI commands
│   ├── critique/               LLM critic with severity guardrail
│   ├── gates/                  7 deterministic gates
│   ├── llm/                    Provider registry, transport, logging
│   ├── loop/                   Plan revision loop, convergence detection
│   └── server/                 HTTP server
├── tests/                    Test suite
├── .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.2.0)

• Planner capability gap — 132 concrete blockers across 63 strict goals. A deterministic precondition closer would eliminate 48%.
• CLI, HTTP, adapter surfaces — partial coverage
• Multi-model sweeps — only gpt-4o-mini tested
• Finding quality audit — not yet measured
• Executor usability — not yet audited

See CHANGELOG.md for full details.

License

MIT — see LICENSE.