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:
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.
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.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
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:
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:
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
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
| Command | What it does |
|---------|--------------|
| /paul:init | Initialize PAUL with type-adapted requirements walkthrough |
| /paul:plan [phase] | Create an executable plan (auto-routes quick-fix/standard/complex) |
| /paul:apply [path] | Execute an approved plan |
| /paul:unify [path] | Reconcile and close the loop |
| /paul:help | Show command reference |
| /paul:status | Show loop position (deprecated — use progress) |
Session
| Command | What it does |
|---------|--------------|
| /paul:pause [reason] | Create handoff for session break |
| /paul:resume [path] | Restore context and continue |
| /paul:progress [context] | Smart status + ONE next action |
| /paul:handoff [context] | Generate comprehensive handoff |
Roadmap
| Command | What it does |
|---------|--------------|
| /paul:add-phase <desc> | Append phase to roadmap |
| /paul:remove-phase <N> | Remove future phase |
Milestone
| Command | What it does |
|---------|--------------|
| /paul:milestone <name> | Create new milestone |
| /paul:complete-milestone | Archive and tag milestone |
| /paul:discuss-milestone | Articulate vision before starting |
Pre-Planning
| Command | What it does |
|---------|--------------|
| /paul:discuss <phase> | Capture decisions before planning |
| /paul:assumptions <phase> | See Claude's intended approach |
| /paul:discover <topic> | Explore options before planning |
| /paul:consider-issues | Triage deferred issues |
Research
| Command | What it does |
|---------|--------------|
| /paul:research <topic> | Deploy research agents |
| /paul:research-phase <N> | Research unknowns for a phase |
Specialized
| Command | What it does |
|---------|--------------|
| /paul:flows | Configure skill requirements |
| /paul:config | View/modify PAUL settings |
| /paul:map-codebase | Generate codebase overview |
Quality
| Command | What it does |
|---------|--------------|
| /paul:verify | Guide manual acceptance testing |
| /paul:plan-fix | Plan fixes for UAT issues |
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
├── 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, verify, done. If you can't specify all four, the task is too vague.
CARL Integration
PAUL has a companion: CARL (Context Augmentation & R
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
