PAUL plugin
PAUL runs Claude Code work as a loop: a plan with acceptance criteria, execution with per-task checks and a required close-out
- 1,255 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The installer writes commands and references into a `.claude` directory, home or project, and creates a `.paul` folder in the project
- The commands have the agent edit project files according to a plan; change boundaries are set in the plan but enforced only by the agent itself
Install
- Works in
Manual install
npx paul-frameworkThe installer asks whether to install globally or into the current project. Verify with /paul:help.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer writes commands and references into a `.claude` directory, home or project, and creates a `.paul` folder in the project
- The commands have the agent edit project files according to a plan; change boundaries are set in the plan but enforced only by the agent itself
This is third-party code. Review the repository files before installing.
What it does
PAUL is a set of 26 slash commands for Claude Code that turns project work into a repeating plan, apply, unify loop. `npx paul-framework` asks where to install and copies files into `commands/paul` and a `paul-framework` directory inside `.claude`, either in the home folder (all projects) or in the current project. `/paul:help` confirms the install. Inside a project, `/paul:init` runs a requirements walkthrough adapted to the work type (app, campaign, workflow) and produces a filled-in `PROJECT.md`. Next to it, a `.paul` folder holds `ROADMAP.md`, `STATE.md` with the loop position, `paul.toml`, `ledger.toml` and a `phases` folder with plans and summaries. `/paul:plan` picks a plan size: a quick fix, a standard plan of 2–5 tasks, or a complex plan of 6 or more tasks that PAUL recommends splitting. A plan has an objective, acceptance criteria in `Given`, `When`, `Then` form, tasks with files, verification and a done condition, and boundaries listing files that must not change. `/paul:apply` executes the approved plan. After each task PAUL re-reads the result and checks it against the task spec and the acceptance criteria. A task ends with one of four statuses: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT` or `BLOCKED`. Then `/paul:unify` compares plan with outcome, writes `SUMMARY.md`, records decisions and deferred issues and updates `STATE.md`. `/paul:resume` picks a session back up with one suggested next step.
Who it is for. For developers and project leads who work in Claude Code across many sessions and want to write down the definition of done up front.
Good fit when
- A project grows in phases and you need to keep the plan position, decisions and deferred issues between sessions
- The agent reports completion and you want every task checked against acceptance criteria before the plan closes
- You need a one-file change but still want the same order: objective, criterion, task, close-out
- The work is more than code: a campaign, a funnel, a mailing or an automation that also needs stages and criteria
- Before planning you want to talk through the approach and read the agent's assumptions with `/paul:discuss` and `/paul:assumptions`
Not a fit when
- You do not use Claude Code: the installer only writes into a `.claude` folder
- You need a one-off task of a few minutes with no plan or log: the loop asks you to fill `.paul` and close the plan
- You want to spread implementation across subagents: PAUL keeps development in one session and leaves subagents for research
- You want a flow built around a written specification with requirements and design: OpenSpec in the catalog is built for that
Example request
Install PAUL in this project, run init and write the plan for the first phase so every task has an acceptance criterionLimitations
- The project targets Claude Code; the author does not claim support for other agents.
- The loop only holds if a plan is closed with `/paul:unify`: the author calls it a required step, and without it `STATE.md` drifts from reality.
- Implementation stays in one session and subagents are used for research. Large jobs should be cut into plans: a plan of 6 or more tasks counts as complex, and PAUL itself suggests splitting it.
- `/paul:status` is marked deprecated in favor of `/paul:progress`.
- Installing needs Node.js 16.7 or newer. Integration with BASE v2 (a separate Rust binary that reads `.paul/paul.toml` and `ledger.toml`) is optional; PAUL works without it.
- MIT license, package version 1.4.0.
How to disable. Delete the `commands/paul` and `paul-framework` folders from the `.claude` directory you installed into (home or project), and the `.paul` folder in the project if you do not need the log.
FAQ
How do I structure Claude Code development around a plan and acceptance criteria?
Install PAUL with `npx paul-framework`, run `/paul:init`, then `/paul:plan`. The plan gets criteria in `Given`, `When`, `Then` form, tasks that reference them and boundaries for changes. After approval `/paul:apply` executes the tasks and `/paul:unify` closes the plan.
How does a quick fix differ from a standard or complex plan?
`/paul:plan` picks the size itself. A quick fix (one file, one change) shrinks to an objective, one task and one criterion, yet still runs the full loop. A standard plan has 2–5 tasks with boundaries and a verification checklist. PAUL recommends splitting a complex plan of 6 or more tasks.
What do the DONE_WITH_CONCERNS and NEEDS_CONTEXT statuses mean?
They are two of the four task statuses. `DONE_WITH_CONCERNS` means the task is finished but the agent flagged doubts for review. `NEEDS_CONTEXT` means information is missing. The others are `DONE` with no concerns and `BLOCKED` for a structural impediment.
What happens when a check or acceptance test finds a problem?
PAUL first classifies the cause: the intent changed, the spec was wrong, or the code does not match a correct plan. The first case re-plans the phase, the second fixes the spec, the third fixes the code in place. `/paul:plan-fix` plans fixes for acceptance issues.
Can PAUL be used for work that is not code?
Yes, the author names campaigns, funnels, email sequences and automations. The `/paul:init` walkthrough adapts to the project type (app, campaign or workflow).
How do I install PAUL for one project only?
Run `npx paul-framework --local` or choose the local option in the prompt. Files go into `./.claude` of the current folder. `--global` covers all projects and writes to `~/.claude`.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code plugin: 39 commands for PRs, review, commits and specs, nine expert roles and hooks, in eight language versions
Goal Workflow
goal-workflow
19 skills for Claude Code: PRD, spec, GitHub Issues, batch implementation with review and pull request merging, plus refactoring and diagrams
A plugin with three skills for large development work: project analysis, phased tasks tracked as GitHub Issues, parallel agents and code review
A dev process built from composable skills for Claude Code and Codex: plan, implement, review, test, commit and PR
A universal workflow plugin for Claude Code: 7 agents, 26 commands, 14 skills and 14 hooks for any project
Claude Code plugins with development recipes: agree on the outcome, design, implement with checks and run an independent review
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| PAUL (this entry) | no | 1,255 | |
| GSD Core | no | 10,814 | a discuss, plan, execute, verify and ship cycle in fresh contexts; PAUL keeps work in one session and requires closing each plan |
| Spec Kit | no | 142,610 | GitHub's kit with the specify CLI that goes from principles to implementation; PAUL is built around acceptance criteria and state in STATE.md |
| OpenSpec | no | 72,863 | proposal, requirements and design first, code after; PAUL works in a plan, apply, unify loop |
README in short
The repository holds the `bin/install.js` installer and a `src` directory with commands, templates, references, workflows and rules. The front page covers three principles (closing every plan, working in one session, acceptance criteria), installation and a five-command quick workflow. It continues with a table of all commands by group, the `.paul` folder layout, a sample plan file with XML markup, and sections on task checks and philosophy. A separate file compares PAUL with GSD.