PAUL

Plan-Apply-Unify Loop — Structured AI-assisted development for Claude Code.

npx paul-framework

Works on Mac, Windows, and Linux.

"Quality over speed-for-speed's-sake. In-session context over subagent sprawl."

Why PAUL · Getting Started · The Loop · Commands · How It Works

Why PAUL

I build with Claude Code every day. It's incredibly powerful — when you give it the right context.

The problem? Context rot. As your session fills up, quality degrades. Subagents spawn with fresh context but return ~70% quality work that needs cleanup. Plans get created but never closed. State drifts. You end up debugging AI output instead of shipping features.

PAUL fixes this with three principles:

1. Loop integrity — Every plan closes with UNIFY. No orphan plans. UNIFY reconciles what was planned vs what happened, updates state, logs decisions. This is the heartbeat.

2. In-session context — Subagents are expensive and produce lower quality for implementation work. PAUL keeps development in-session with properly managed context. Subagents are reserved for discovery and research — their job IS to gather context.

3. Acceptance-driven development — Acceptance criteria are first-class citizens, not afterthoughts. Define done before starting. Every task references its AC. BDD format: Given [precondition] / When [action] / Then [outcome].

The complexity is in the system, not your workflow. Behind the scenes: structured state management, XML task formatting, loop enforcement. What you see: a few commands that keep you on track.

Who This Is For

Builders who use AI to ship — software, campaigns, workflows, automations, anything that benefits from structured execution.

PAUL isn't just for code. It manages marketing campaigns, funnel builds, email sequences, and automation workflows with the same rigor it brings to software development.

You describe what you want, Claude Code builds it, and PAUL ensures:

• Init gathers real requirements — type-adapted walkthrough produces a populated project brief, not empty placeholders
• Plans have clear acceptance criteria
• Every task is qualified against the spec — not just executed and assumed correct
• Execution stays bounded with explicit scope control
• Every unit of work gets closed properly
• State persists across sessions
• Decisions are logged for future reference

No sprint ceremonies. No story points. No enterprise theater. Just a system that keeps AI-assisted development reliable.

Getting Started

npx paul-framework

The installer prompts you to choose:

1. Location — Global (all projects) or local (current project only)

Verify with /paul:help inside Claude Code.

Quick Workflow

# 1. Initialize PAUL in your project
#    Walks through type-adapted requirements (app, campaign, workflow)
#    Produces a populated PROJECT.md — not empty placeholders
/paul:init

# 2. Create a plan for your work
#    Auto-detects scope: quick-fix, standard, or complex
#    Validates coherence against project context before approval
/paul:plan

# 3. Execute the approved plan
#    Each task goes through Execute/Qualify loop
#    Escalation statuses: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED
/paul:apply

# 4. Close the loop (required!)
/paul:unify

# 5. Check progress anytime
/paul:progress

Staying Updated

npx paul-framework@latest

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

The Loop

Every unit of work follows this cycle:

┌─────────────────────────────────────┐
│  PLAN ──▶ APPLY ──▶ UNIFY          │
│                                     │
│  Define    Execute    Reconcile     │
│  work      tasks      & close       │
└─────────────────────────────────────┘

PLAN

Create an executable plan with scope-adaptive ceremony:

• Quick-fix (1 file, 1 change) — Compressed: objective + 1 task + 1 AC. Full loop, minimal ceremony.
• Standard (2-5 tasks) — Full plan with boundaries, multiple ACs, verification checklist.
• Complex (6+ tasks) — Full plan + actively recommends splitting.

All plans include:

• Objective — What you're building and why
• Acceptance Criteria — Given/When/Then definitions of done
• Tasks — Specific actions with files, verification, done criteria
• Boundaries — What NOT to change (standard/complex only)
• Coherence validation — Auto-checked against project context before approval

APPLY

Execute the approved plan with built-in quality enforcement:

• Tasks follow an Execute/Qualify loop — after execution, each task is independently verified against the spec and linked acceptance criteria before moving on
• Escalation statuses give nuance beyond pass/fail: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED
• Checkpoints pause for human input when needed — with diagnostic failure routing that classifies issues as intent, spec, or code before attempting fixes
• Anti-rationalization enforcement prevents false completion claims

UNIFY

Close the loop (required!):

• Create SUMMARY.md documenting what was built
• Compare plan vs actual
• Record decisions and deferred issues
• Update STATE.md

Never skip UNIFY. Every plan needs closure. This is what separates structured development from chaos.

Commands

PAUL provides 26 commands organized by purpose. Run /paul:help for the complete reference.

Core Loop

Session

Roadmap

Milestone

Pre-Planning

Research

Specialized

Quality

How It Works

Project Structure

.paul/
├── PROJECT.md           # Project context and requirements
├── ROADMAP.md           # Phase breakdown and milestones
├── STATE.md             # Loop position and session state
├── paul.toml            # Machine-readable manifest (BASE-v2 graph integration)
├── ledger.toml          # Session history (cost/time attribution)
├── MILESTONES.md        # Completed milestone log
├── config.md            # Optional integrations
├── SPECIAL-FLOWS.md     # Optional skill requirements
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md
    │   └── 01-01-SUMMARY.md
    └── 02-features/
        ├── 02-01-PLAN.md
        └── 02-01-SUMMARY.md

State Management

STATE.md tracks:

• Current phase and plan
• Loop position (PLAN/APPLY/UNIFY markers)
• Session continuity (where you stopped, what's next)
• Accumulated decisions
• Blockers and deferred issues

When you resume work, /paul:resume reads STATE.md and suggests exactly ONE next action. No decision fatigue.

PLAN.md Structure

---
phase: 01-foundation
plan: 01
type: execute
autonomous: true
---

<objective>
Goal, Purpose, Output
</objective>

<context>
@-references to relevant files
</context>

<acceptance_criteria>
## AC-1: Feature Works
Given [precondition]
When [action]
Then [outcome]
</acceptance_criteria>

<tasks>
<task type="auto">
  <name>Create login endpoint</name>
  <files>src/api/auth/login.ts</files>
  <action>Implementation details...</action>
  <verify>curl command returns 200</verify>
  <done>AC-1 satisfied</done>
</task>
</tasks>

<boundaries>
## DO NOT CHANGE
- database/migrations/*
- src/lib/auth.ts
</boundaries>

Every task has: files, action