PAUL Framework

1.2.0 · active · verified Sun Apr 19

PAUL (Plan-Apply-Unify Loop) is an AI-assisted development framework designed to bring structure and integrity to projects built using Claude Code. Currently at version 1.2.0, the framework emphasizes disciplined execution through a cyclical process: Plan, Apply, and Unify. It aims to combat "context rot" and improve the reliability of AI-generated output by enforcing loop integrity, prioritizing in-session context, and driving development with acceptance criteria. PAUL ensures that plans are closed, state is consistently managed, and decisions are logged, significantly reducing the debugging of AI output. It is not limited to software development but can manage diverse projects like marketing campaigns and workflows. Releases are driven by user feedback, focusing on enhancing workflow quality and depth, with the latest v1.2.0 introducing significant improvements to the initialization process.

Common errors

```
Error: Command '/paul:init' not found (or similar)
```
cause Attempting to run PAUL's internal commands outside of the Claude Code environment.

fix Execute all `/paul:` commands directly within a Claude Code session where the PAUL framework is active.
```
PAUL loop integrity compromised: Plan not closed. Run /paul:unify.
```
cause The Plan-Apply-Unify loop was not completed, meaning work was applied but not reconciled or finalized.

fix Execute `/paul:unify` after completing the `/paul:apply` phase to close the loop, update project state, and log decisions.
```
Error: Project not initialized. Run /paul:init first.
```
cause Attempting to use PAUL commands like `/paul:plan` or `/paul:apply` before the project has been properly set up.

fix Start your PAUL workflow by running `/paul:init` to initialize the project and gather initial requirements.

Warnings

breaking The `/paul:init` command behavior has changed significantly in v1.2.0. It no longer generates skeleton files with placeholder text. Instead, it initiates a 'type-adapted requirements conversation' to produce a populated `PROJECT.md`.
Fix: Update any automated scripts or workflows that relied on the previous skeleton file generation, and adapt to the new interactive requirements gathering process for initialization.
gotcha Failing to execute the `/paul:unify` command after `/paul:apply` will break the 'loop integrity,' leading to state inconsistencies, unclosed plans, and loss of critical decision logs.
Fix: Always ensure that every `/paul:apply` execution is followed by a `/paul:unify` command to properly close the loop, reconcile work, and persist project state. This is fundamental to PAUL's operational model.
gotcha PAUL commands (`/paul:init`, `/paul:plan`, etc.) are designed exclusively for the Claude Code environment. Attempting to run them in a standard terminal or shell will result in 'command not found' errors or similar execution failures.
Fix: Ensure that all PAUL operational commands are invoked directly within your Claude Code session, prefixed with `/paul:` as specified in the documentation.

Install

npm install paul-framework npm
yarn add paul-framework yarn
pnpm add paul-framework pnpm

Imports

paul-framework CLI installation/setup
wrong:
```
npm install paul-framework; paul-framework
```
correct:
```
npx paul-framework
```
The primary way to initiate the PAUL framework for a project is via `npx`. Avoid global installation (`npm install -g`) unless specifically required for your environment, as `npx` provides on-demand execution.
/paul:init command
wrong:
```
paul init
```
correct:
```
/paul:init
```
All PAUL operational commands (`/paul:init`, `/paul:plan`, `/paul:apply`, `/paul:unify`, `/paul:progress`) are designed to be run within the Claude Code environment and require the `/paul:` prefix. Running these commands in a standard terminal will result in an error.
/paul:unify command
wrong:
```
Simply ending a session after /paul:apply
```
correct:
```
/paul:unify
```
The `/paul:unify` command is crucial for 'loop integrity,' reconciling planned versus executed work and persisting state. Failing to run `/paul:unify` after `/paul:apply` will lead to state drift, orphan plans, and lost context, compromising the framework's core benefits.

Quickstart

Demonstrates the initial setup of PAUL via `npx` and the core Plan-Apply-Unify loop commands used within Claude Code to manage an AI-assisted project.

npx paul-framework

# Choose location (Global or local)
# Verify installation inside Claude Code:
/paul:help

# Quick Workflow inside Claude Code:
# 1. Initialize PAUL in your project with a type-adapted requirements conversation
/paul:init

# 2. Create a plan for your work, auto-detecting scope and validating coherence
/paul:plan

# 3. Execute the approved plan, with each task going through Execute/Qualify loop
/paul:apply

# 4. Close the loop, reconciling planned vs. actual outcomes and updating state
/paul:unify

# 5. Check progress anytime
/paul:progress

view raw JSON →