PAUL-Qwen Framework

Plan-Apply-Unify Loop — A structured AI-assisted development framework for Qwen CLI.

What is PAUL?

PAUL is a productivity framework for Qwen CLI that combats "vibe coding" and context rot through a disciplined workflow:

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

Never skip UNIFY. Every plan needs a summary.

Quick Start

Install

npx paul-qwen

Or specify location:

# Global (all projects)
npx paul-qwen --global

# Local (current project)
npx paul-qwen --local

Initialize

/paul/init

Your First Loop

/paul/plan    # Create a plan
/paul/apply   # Execute the plan
/paul/unify   # Close the loop (required!)

Core Philosophy

1. Loop must complete — PLAN → APPLY → UNIFY, no shortcuts
2. State is tracked — STATE.md knows where you are
3. Acceptance criteria first — Define done before starting
4. Boundaries are real — Respect DO NOT CHANGE sections
5. Skills are enforced — Required skills block APPLY until loaded

Commands

Core Loop (6)

| Command | Description | |---------|-------------| | /paul/init | Initialize PAUL in your project | | /paul/plan | Create an executable plan | | /paul/apply | Execute the approved plan | | /paul/unify | Reconcile and close the loop | | /paul/help | Show command reference | | /paul/status | Show loop position (deprecated — use progress) |

Session (4)

| Command | Description | |---------|-------------| | /paul/pause | Create handoff for session break | | /paul/resume | Restore context and continue | | /paul/progress | Smart status + ONE next action | | /paul/handoff | Generate comprehensive handoff |

Roadmap (2)

| Command | Description | |---------|-------------| | /paul/add-phase | Append phase to roadmap | | /paul/remove-phase | Remove future phase |

Milestone (3)

| Command | Description | |---------|-------------| | /paul/milestone | Create milestone with phases | | /paul/complete-milestone | Archive and tag milestone | | /paul/discuss-milestone | Articulate vision before starting |

Pre-Planning (4)

| Command | Description | |---------|-------------| | /paul/discuss | Capture decisions before planning | | /paul/assumptions | See AI's intended approach | | /paul/discover | Explore codebase patterns | | /paul/consider-issues | Triage deferred issues |

Research (2)

| Command | Description | |---------|-------------| | /paul/research | Deploy research agents | | /paul/research-phase | Research unknowns for phase |

Specialized (3)

| Command | Description | |---------|-------------| | /paul/flows | Configure skill requirements | | /paul/config | View/modify settings | | /paul/map-codebase | Generate codebase overview |

Quality (4)

| Command | Description | |---------|-------------| | /paul/verify | Guide manual acceptance testing | | /paul/audit | Enterprise architectural audit | | /paul/plan-fix | Plan fixes for UAT issues | | /paul/register | Register satellite manifest |

File Structure

.paul/
├── PROJECT.md           # Project context and value prop
├── ROADMAP.md           # Phase breakdown and milestones
├── STATE.md             # Loop position and session state
├── config.md            # Optional integrations config
├── SPECIAL-FLOWS.md     # Optional skill requirements
├── MILESTONES.md        # Completed milestone archive
├── paul.json            # Satellite manifest for external discovery
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md
    │   ├── 01-01-AUDIT.md    (if enterprise audit enabled)
    │   └── 01-01-SUMMARY.md
    └── 02-features/
        ├── 02-01-PLAN.md
        └── 02-01-SUMMARY.md

Common Workflows

Starting a New Project

/paul/init      # Initialize
/paul/plan      # Create first plan
/paul/apply     # Execute
/paul/unify     # Close loop

Enterprise Workflow (with Audit)

/paul/plan      # Create plan
/paul/audit     # Audit + auto-fix plan
/paul/apply     # Execute audited plan
/paul/unify     # Close loop

Checking Progress

/paul/progress  # State + ONE next action

Resuming Work

/paul/resume    # Restores context, suggests next action

Pausing Work

/paul/pause     # Creates handoff, updates state

Pre-Planning Exploration

/paul/discuss 3           # Articulate vision for phase 3
/paul/assumptions 3       # See AI's assumptions
/paul/research "topic"    # Gather external info
/paul/plan 3              # Now create the plan

Managing Roadmap

/paul/add-phase "New Feature"    # Add phase
/paul/remove-phase 5             # Remove future phase
/paul/milestone "v2.0"           # Create milestone
/paul/complete-milestone         # Archive milestone

PLAN.md Structure

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

<objective>
## Goal
[What this plan accomplishes]

## Purpose
[Why this matters]

## Output
[What artifacts created]
</objective>

<context>
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
</context>

<acceptance_criteria>

## AC-1: [Name]
```gherkin
Given [precondition]
When [action]
Then [outcome]

</acceptance_criteria>

DO NOT CHANGE

• [Protected files]

Task Types

| Type | Use For | |------|---------| | auto | Fully autonomous execution | | checkpoint:decision | Choices requiring human input | | checkpoint:human-verify | Visual/functional verification | | checkpoint:human-action | Manual steps (rare) |

Skills Integration

PAUL integrates with Qwen's native skills system.

Configure Skills

/paul/flows

Creates .paul/SPECIAL-FLOWS.md:

# Special Flows

## Skills Registry

| Skill | Work Type | Priority |
|-------|-----------|----------|
| /frontend-design | frontend | required |
| /api-design | api | required |

Skill Enforcement

Required skills BLOCK /paul/apply until loaded:

⛔ BLOCKED: Required skills not loaded

This plan requires:
- /frontend-design

Run: /skills frontend-design
Or type "override" to proceed without (not recommended).

MCP Integration

PAUL works with Qwen's native MCP server support.

Configure SonarQube

During /paul/init or in .paul/config.md:

sonarqube:
  enabled: true
  project_key: my-project

Configure MCP Server

In ~/.qwen/settings.json:

{
  "mcpServers": {
    "sonarqube": {
      "command": "npx",
      "args": ["@sonarqube/mcp-server"],
      "env": {
        "SONAR_TOKEN": "$SONAR_TOKEN"
      }
    }
  }
}

Installation Options

Interactive (Default)

npx paul-qwen

Prompts for global or local install.

Non-Interactive

# Global
npx paul-qwen --global

# Local
npx paul-qwen --local

# Custom path
npx paul-qwen --config-dir ~/.qwen-custom

Help

npx paul-qwen --help

Updating

npx paul-qwen@latest

Comparison: PAUL vs Ad-Hoc AI Coding

| Aspect | Ad-Hoc | PAUL | |--------|--------|------| | Structure | No structure | Explicit planning gates | | State | Drifts | STATE.md tracks everything | | Closure | No closure | Mandatory UNIFY | | Decisions | Lost | Logged | | Context | Rotates | Managed per task | | Quality | Variable | Acceptance-driven |

When to Use PAUL

Good Fit

• Medium-to-large projects
• Multi-session work
• Team collaboration
• Audit requirements
• Complex refactors

Overkill

• Quick scripts
• One-off changes
• Simple bug fixes
• Experiments

Troubleshooting

Commands Not Found

# Verify installation
ls ~/.qwen/commands/paul/

# Restart Qwen CLI

STATE.md Missing

# Re-initialize
/paul/init

Loop Stuck

# Check current state
/paul/progress

# Reset if needed (manual edit of STATE.md)

Contributing

1. Fork the repo
2. Make changes
3. Test with real projects
4. Submit PR

GitHub: https://github.com/tyler1350/paul-qwen

License

MIT License — see LICENSE file.

Credits

PAUL-Qwen is a port of the PAUL Framework by Chris Kahler, adapted for Qwen CLI.

PAUL-Qwen v1.0 | For Qwen CLI | Plan-Apply-Unify Loop