paul-framework

library1.2.0jsnpmunverified

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.

llm-agents devops workflow web-framework testing

npm install paul-framework

github ↗package ↗

INSTALL

IMPORT

SIG · PAUL-FRAMEWORK

paul-framework

llm-agentsjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

paul-framework CLI installation/setup

✓ npx paul-framework

✗ npm install paul-framework; 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

✓ /paul:init

✗ 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

✓ /paul:unify

✗ Simply ending a session after /paul:apply

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.

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

paul --version

Debug

Known issues

breakingThe `/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.

affects: >=1.2.0

gotchaFailing 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.

affects: >=1.0.0

gotchaPAUL 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Command '/paul:init' not found (or similar)

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.

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.

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.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

57 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ChristopherKahler/paul ↗

packagehttps://www.npmjs.com/package/paul-framework ↗