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

npx qwen-paul

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 Qwen 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.
2. In-session context — Subagents are expensive and produce lower quality for implementation work. PAUL keeps development in-session.
3. Acceptance-driven development — Acceptance criteria are first-class citizens, not afterthoughts. BDD format: Given [precondition] / When [action] / Then [outcome].

Who This Is For

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

Getting Started

npx qwen-paul

The installer prompts you to choose:

1. Location — Global (all projects) or local (current project only)
2. Verify with /paul:help inside Qwen Code.

Quick Workflow

# 1. Initialize PAUL in your project
/paul:init

# 2. Create a plan
/paul:plan

# 3. Execute the approved plan
/paul:apply

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

# 5. Check progress anytime
/paul:progress

Staying Updated

npx qwen-paul@latest

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.
• Standard (2-5 tasks) — Full plan with boundaries, multiple ACs.
• Complex (6+ tasks) — Full plan + actively recommends splitting.

APPLY

Execute the approved plan with built-in quality enforcement:

• Tasks follow an Execute/Qualify loop
• Escalation statuses: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED
• Checkpoints pause for human input

UNIFY

Close the loop (required!):

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

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:progress | Smart status + ONE next action |

Session

| Command | What it does | |---------|--------------| | /paul:pause [reason] | Create handoff for session break | | /paul:resume [path] | Restore context and continue | | /paul:handoff [context] | Generate comprehensive handoff |

Pre-Planning

| Command | What it does | |---------|--------------| | /paul:discuss <phase> | Capture decisions before planning | | /paul:assumptions <phase> | See Qwen'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 <phase> | Research unknowns for a phase |

Quality

| Command | What it does | |---------|--------------| | /paul:verify | Guide manual acceptance testing | | /paul:plan-fix | Plan fixes for UAT issues | | /paul:audit [path] | Enterprise architectural audit |

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

What Gets Installed

~/.qwen/
├── commands/qwen-paul/   # 26 slash commands (/paul:init, etc.)
└── paul-framework/
    ├── templates/        # PLAN.md, PROJECT.md, STATE.md, etc.
    ├── workflows/        # Execution workflows
    ├── references/       # Format guides, best practices
    ├── rules/            # Command authoring rules
    └── carl/             # CARL integration files

State Management

STATE.md tracks:

• Current phase and plan
• Loop position (PLAN/APPLY/UNIFY markers)
• Session continuity
• Accumulated decisions
• Blockers and deferred issues

Quality Enforcement

Execute/Qualify Loop:

Execute → Report Status → Qualify Against Spec → (fix gaps) → Next Task

Escalation Statuses:

| Status | Meaning | |--------|---------| | DONE | Completed, no concerns | | DONE_WITH_CONCERNS | Completed, but flagged doubts | | NEEDS_CONTEXT | Can't complete — missing information | | BLOCKED | Can't complete — structural impediment |

CARL Integration

PAUL has a companion: CARL-Qwen (Context Augmentation & Reinforcement Layer).

CARL is a dynamic rule injection system. Instead of bloating your context with static prompts, CARL loads PAUL rules just-in-time based on what you're doing.

Install both:

npx carl-qwen   # Dynamic rule injection
npx qwen-paul   # Structured development workflow

When you type /paul:plan, CARL automatically loads the 13 PAUL rules that govern:

• Loop enforcement (PLAN → APPLY → UNIFY — no shortcuts)
• Boundary protection (DO NOT CHANGE sections are real)
• State consistency checks at phase transitions
• Verification requirements for every task
• Skill blocking (required skills must load before APPLY)

Philosophy

Acceptance-Driven Development (A.D.D.)

1. AC defined before tasks — Know what "done" means
2. Tasks reference AC — Every task links to AC-1, AC-2, etc.
3. Verification required — Every task needs a verify step
4. BDD format — Given/When/Then for testability

In-Session Context

PAUL keeps implementation in-session with proper context management. Subagents reserved for discovery and research only.

Loop Integrity

The loop isn't optional:

PLAN ──▶ APPLY ──▶ UNIFY
  ✓        ✓        ✓     [Loop complete]

• No orphan plans — Every PLAN gets a SUMMARY
• State reconciliation — UNIFY catches drift
• Decision logging — Choices are recorded for future sessions

Troubleshooting

Commands not found after install?

• Restart Qwen Code to reload slash commands
• Verify files exist in ~/.qwen/commands/qwen-paul/ (global) or ./.qwen/commands/qwen-paul/ (local)

Commands not working as expected?

• Run /paul:help to verify installation
• Re-run npx qwen-paul to reinstall

Loop position seems wrong?

• Check .paul/STATE.md for current state
• Run /paul:progress for guided next action

Resuming after a break?

• Run /paul:resume — it reads state and handoffs automatically

License

MIT License. See LICENSE for details.

Author

Chris Kahler — Chris AI Systems Adapted for Qwen Code by tylergriffin1350

Qwen Code is powerful. PAUL makes it reliable.