PAUL (paul-framework): The Plan-Apply-Unify Loop for Claude Code

The problem PAUL names: context rot and orphan plans

The README states the problem in its own words: as a session fills up, quality degrades, and subagents that spawn with fresh context "return ~70% quality work that needs cleanup." The second half of the complaint is process rather than model behaviour. Plans get created but never closed, state drifts, and the developer ends up debugging AI output instead of shipping features.

PAUL is aimed at that pair of failures. It is a command set for Claude Code, not a model, a runtime, or an editor plugin. The README says it is for "builders who use AI to ship" and explicitly extends beyond code to marketing campaigns, funnel builds, email sequences, and automation workflows. That breadth is a claim about the command structure being domain-neutral, not evidence that it has been validated outside software.

The design position is stated as a slogan in the README: quality over speed-for-speed's-sake, in-session context over subagent sprawl. Whether you agree with that trade-off determines whether the rest of the tool makes sense to you. If your bottleneck is wall-clock time and you accept cleanup cost, PAUL's insistence on closing every loop will feel like overhead.

How the loop enforces itself: PLAN, APPLY, UNIFY

The mechanism is a three-stage cycle, and the enforcement lives in the third stage. PLAN produces an executable plan with scope-adaptive ceremony. The README describes three tiers: quick-fix for one file and one change, standard for two to five tasks, and complex for six or more, where the tool actively recommends splitting the work. Every plan carries an objective, acceptance criteria written in Given/When/Then form, tasks with files and verification steps, and (for standard and complex) boundaries describing what not to change. Coherence is auto-checked against project context before approval.

APPLY executes the approved plan through what the README calls an Execute/Qualify loop. After a task runs, it is verified against the spec and its linked acceptance criteria before the next task starts. Escalation statuses add nuance beyond pass/fail: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED. Checkpoints pause for human input, and the README describes diagnostic failure routing that classifies a problem as intent, spec, or code before a fix is attempted. There is also what the README calls anti-rationalization enforcement, intended to prevent claims of completion that the evidence does not support.

UNIFY is the part that makes the loop a loop. It creates a SUMMARY.md, compares plan against actual, records decisions and deferred issues, and updates STATE.md. The README is blunt that skipping it breaks the model: "Never skip UNIFY." That is the clearest design statement in the document. A plan that never closes leaves state drifting, which is the exact condition PAUL was written to remove.

Installing paul-framework and running a first loop

PAUL ships as the npm package paul-framework, with a bin entry named paul-framework pointing at bin/install.js. The README gives a single install command. Node 16.7.0 or later is required according to the engines field in package.json.

npx paul-framework

The installer prompts for a location: global, meaning all projects, or local, meaning the current project only. For scripted setups the README documents non-interactive flags.

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

After installation, the README says to verify with /paul:help inside Claude Code. That command is also the reference for the full command set, which the README counts at 26 commands organized by purpose. A first real loop follows the documented order: initialize, plan, apply, unify.

/paul:init
/paul:plan
/paul:apply
/paul:unify
/paul:progress

/paul:init runs a type-adapted requirements walkthrough (app, campaign, or workflow) and is meant to produce a populated PROJECT.md rather than empty placeholders. /paul:plan auto-routes to quick-fix, standard, or complex and validates coherence against project context before you approve it. /paul:apply executes the approved plan. /paul:unify reconciles and closes it. /paul:progress reports status and, per the README, exactly one next action. Note that /paul:status is marked deprecated in the command table in favour of /paul:progress.

Where PAUL is the wrong tool

The acceptance-criteria requirement is the constraint that will decide most adoptions. Every task references an AC, and ACs are written as Given/When/Then. For exploratory work where you cannot state the outcome before you start, that format is friction with no payoff. The README's own framing, define done before starting, is honest about this: PAUL assumes you know what done looks like. Spike work, throwaway prototypes, and open-ended research do not fit that assumption, and the tool does not claim to make them fit.

The second limitation is the one the README states as a virtue. PAUL keeps implementation in-session and reserves subagents for discovery and research. That is a deliberate bet against subagent quality, but it means PAUL does not give you parallel execution. If your work is genuinely parallelizable and you are willing to pay the cleanup cost, the in-session model is a ceiling rather than a safeguard.

The third is host coupling. The commands are Claude Code slash commands, and nothing in the README or package.json describes a host other than Claude Code. There is no library API and no CLI that runs the loop headlessly; the bin entry installs files. If your team is not on Claude Code, PAUL is not a candidate regardless of how much you like the loop.

Finally, the README does not document rollback. There is no described way to undo an APPLY that went wrong beyond the escalation statuses and checkpoints that stop it mid-run. Verify that gap against your own risk tolerance before running PAUL against a repository you cannot restore.

PAUL versus GSD, and what the comparison file implies

The repository contains a top-level file named PAUL-VS-GSD.md, and the package homepage points at it directly. That is the project's own framing of the alternative. GSD is the comparison the author chose to make, and the file exists because the two are used for overlapping purposes in the Claude Code ecosystem.

The README does not summarize the contents of PAUL-VS-GSD.md, so the substantive difference has to be read from that document rather than assumed here. What the README does establish is the axis of comparison: PAUL's stated principles are loop integrity, in-session context, and acceptance-driven development, with subagents reserved for discovery and research. A framework that leans on subagents for implementation would differ on the second principle by construction, and one that does not require closure would differ on the first.

If you are choosing between them, read PAUL-VS-GSD.md as the author's argument rather than a neutral evaluation, then check the claim you care about against your own workflow. The relevant question is not which tool is faster but which one leaves your repository in a state you can describe at the end of a session. PAUL's answer is SUMMARY.md and STATE.md; whether the competing tool produces an equivalent artifact is the thing to confirm before switching.

Maintenance, versioning, and the MIT licence

The repository is not archived, and the last push was on 2026-08-21. That is recent enough that the project is being touched, though the README and package.json disagree on version in a way worth noting: the most recent release listed is v1.2.0 (titled "Quality & Depth") from 2026-03-24, while package.json at the repository root reads 1.4.0. Both can be true if releases were tagged less often than the version field was bumped, but it means the release list is not a reliable map of what npx paul-framework will install. Check the installed version after running the installer.

Upgrade cost is low by design. The README's staying-updated instruction is to re-run the installer with the latest tag.

npx paul-framework@latest

Because the package installs command and template files rather than a runtime dependency, upgrading is a file replacement rather than a migration. The risk is the opposite of the usual one: a global install under ~/.claude/ is shared across every project, so a behaviour change in a new version reaches all of them at once. If you have projects mid-loop, prefer the local install until you have seen the new version behave.

The licence is MIT, declared in both the README badge and the license field of package.json. That permits commercial use and modification with the copyright notice retained. This is a description of the licence text, not legal advice; if you redistribute PAUL or embed it in a product, read the LICENSE file in the repository yourself.

Editorial conclusion

Adopt PAUL if you already work inside Claude Code and your failure mode is unfinished or unverified AI work, not a shortage of speed. Skip it if you want an autonomous agent that runs unattended, or if you do not use Claude Code at all, since the commands are slash commands and nothing in the README describes another host. Before committing, verify two things yourself: that /paul:init produces a populated PROJECT.md rather than placeholders in your repository, and that /paul:unify writes a SUMMARY.md you consider accurate. The v1.2.0 release notes name the quality and depth work; the package.json at the repository root reads 1.4.0, so confirm which version npx pulls before you standardize on it.

Frequently asked questions

Official sources

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