PAUL makes plan closure mandatory, and its npm version is ahead of its release tags

A plan is not allowed to stay open, which is the entire point

The loop has three phases and the third one is compulsory: plan, apply, unify.

Plan defines executable work. Apply executes it. Unify reconciles what was planned against what actually happened, writes a summary document, records decisions and deferred issues, and updates a state file. The instruction attached to it is blunt, never skip unify, because that closure step is what separates structured development from an abandoned branch.

The reasoning behind it is a diagnosis of how agent assisted work fails. A session fills with context, output quality degrades, plans get created and never closed, state drifts, and the developer ends up debugging generated output instead of shipping. The stated fix is to make closure a step in the cycle rather than a habit, so the artifact that records what happened is produced by the same loop that did the work.

Everything the framework stores is therefore a markdown file in your project: a project brief from init, a plan, a summary and a state file.

Subagents are demoted to research because their output comes back rougher

The second principle is a deliberate restriction, and it is the one most likely to change how you work.

The premise is context rot. As a session fills up, quality degrades, and subagents are spawned with a clean context window but return work of noticeably lower quality that then needs cleanup before it can be used. The number given is blunt: around 70 percent quality. Implementation work done that way costs more in cleanup than it saves in context.

So PAUL keeps development in the session with managed context, and reserves subagents for discovery and research, on the grounds that gathering context is what they are actually good at. The summary line the project puts above its own name is a comparison of these two choices: in session context over subagent sprawl.

The consequence is practical. Parallel exploration still happens, but implementation does not leave your session, which means a long task list will be executed sequentially by the agent you are already talking to. That is a deliberate trade of throughput for coherence.

Plan ceremony is chosen by task count, and one task plans get almost nothing

Planning is not one process. It routes to one of three levels, and the routing key is the number of tasks rather than the importance of the work.

A quick fix is defined as one file and one change. It gets a compressed plan: an objective, a single task and a single acceptance criterion, with the full loop still applied. Standard work, two to five tasks, gets boundaries, multiple acceptance criteria and a verification checklist. Complex work, six tasks or more, gets the full plan and an active recommendation to split it.

Every plan carries the same core elements: an objective explaining what is being built and why, acceptance criteria written as given, when, then, and tasks that name files, verification steps and done criteria. Boundaries, which state what not to change, appear only for standard and complex plans.

There is also a check before approval: each plan is validated for coherence against the existing project context. So a plan that contradicts what is already in the repository is meant to fail before any code is written, which is the cheapest place for that class of mistake to surface.

Four statuses replace pass or fail, including one that admits doubt

The apply phase is built around verification rather than trust, and the vocabulary is the interesting part.

Each task runs an execute and qualify loop: after execution it is independently checked against the spec and its linked acceptance criteria before the next task starts. A task does not simply pass. It is recorded as DONE, as DONE WITH CONCERNS, as NEEDS_CONTEXT, or as BLOCKED. Three of those four admit something other than success, and DONE WITH CONCERNS in particular is a place where a task can be recorded as finished and still carry a caveat forward into the summary.

Two guards sit around that loop. Checkpoints can pause for human input, and when something fails, diagnostic routing classifies the problem as intent, spec or code before any fix is attempted, which is an attempt to avoid patching a symptom that lives in the requirements. Separately, anti rationalisation enforcement is there to block false completion claims.

None of these are verifiable claims about results. They are descriptions of the process the framework imposes on the agent doing the work.

Installation is one npx call that asks global or local

The install path is short enough to fit in one line, and the one decision it forces is scope.

npx paul-framework

Running it starts an installer that asks whether to install globally for all projects or locally for the current project only. The same choice exists as flags for unattended use, with the destination directories spelled out: the global flag installs into the home Claude directory, the local flag into a Claude directory in the current project.

npx paul-framework --global   # Install to ~/.claude/
npx paul-framework --local    # Install to ./.claude/

Updates are a matter of running the package again with the latest tag rather than a separate upgrade command. Verification happens inside Claude Code with the help command, which prints the full reference.

What gets installed is a set of command and template directories rather than a compiled application: the published file list is the installer plus five directories for commands, templates, references, workflows and rules. The package declares a minimum Node version and carries no runtime dependencies of its own, which fits a tool whose real output is markdown and slash commands.

Twenty six commands, and one of them is already deprecated

The command surface is large and grouped by purpose, which tells you what the author expects to happen in a session.

The core group is the loop itself: init, plan, apply and unify, plus a help command and a status command. That last one is marked deprecated in favour of a progress command, which is a small thing to notice and a useful one, because it shows the project renaming its own commands rather than accumulating them. In the quick workflow the progress command is also written in its short form, so the same idea exists under two names.

The session group handles interruption: pause takes a reason and writes a handoff, resume takes a path and restores context, and handoff generates a fuller summary of where things stand. The progress command is described as giving a status plus one next action, which is a deliberate constraint on a tool that could easily list everything.

Roadmap and milestone commands come next, covering appending and removing phases, creating a milestone, completing and archiving one, and articulating a vision before building it. The full reference is 26 commands, and the help command is the only entry point you are given.

The package file says 1.4.0 and the newest release tag says 1.2.0

Two version numbers describe this project and they are not the same, which matters more than usual for a tool you install by tag.

The package metadata declares version 1.4.0. The most recent published release is 1.2.0, from March, titled for quality and depth. The last push to the main branch came at the end of August, months after that tag. So the code on the branch, the version in the package and the newest release are three different points in the history, and running the latest tag gets you the branch's version number rather than anything a release page describes.

The repository is small and flat, which makes that easy to inspect. At the root sit an ideation document, a licence, the readme, an assets directory, the installer, the package file and a source directory. There is also a document whose name is a comparison against another framework, and the surrounding search traffic shows people arriving with that same question, which suggests the comparison is doing real work as a landing page.

Licensing is MIT, the package is published under the name paul-framework, and it targets Node 16.7 and above.

Editorial conclusion

PAUL is for someone who already uses Claude Code daily and has watched plans rot: it costs you a mandatory UNIFY step and a verification pass per task, and in exchange it gives you a populated project brief, bounded scope, recorded decisions and a resumable session. It is not only for software, since the initial walkthrough adapts to campaigns and workflows. Three things to check before adopting it. Your work has to be breakable into tasks with verifiable outcomes, or the qualification step has nothing to check. You have to accept the in-session bias, because the framework treats subagent work as lower quality by default. And pin your version deliberately, since the package version and the release tags are not the same number.

Frequently asked questions

Official sources

1. ChristopherKahler/paul on GitHub
2. License: MIT
3. Project website
4. README
5. Releases