qwen-paul 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,302 @@
+# Qwen-PAUL **Plan-Apply-Unify Loop** — Structured AI-assisted development for Qwen Code.
+
+```bash
+npx qwen-paul
+```
+
+**Works on Mac, Windows, and Linux.**
+
+*"Quality over speed-for-speed's-sake. In-session context over subagent sprawl."*
+
+[Why PAUL](#why-paul) · [Getting Started](#getting-started) · [The Loop](#the-loop) · [Commands](#commands) · [How It Works](#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
+
+```bash
+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
+
+```bash
+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](https://www.npmjs.com/package/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:**
+```bash
+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](LICENSE) for details.
+
+---
+
+## Author
+
+**Chris Kahler** — [Chris AI Systems](https://github.com/ChristopherKahler)
+Adapted for Qwen Code by [tylergriffin1350](https://github.com/tylergriffin1350)
+
+---
+
+**Qwen Code is powerful. PAUL makes it reliable.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qwen-paul",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Plan-Apply-Unify Loop - A structured AI-assisted development framework for Qwen Code",
   "bin": {
     "qwen-paul": "bin/install.js"
@@ -12,7 +12,8 @@
     "src/references",
     "src/workflows",
     "src/rules",
-    "src/carl"
+    "src/carl",
+    "README.md"
   ],
   "keywords": [
     "qwen",

package/src/commands/help.md

@@ -17,7 +17,7 @@ Output ONLY the reference content below. Do NOT add:
 <reference>
 # PAUL Command Reference
 
-**PAUL** (Plan-Apply-Unify Loop) is a structured AI-assisted development framework for Claude Code.
+**PAUL** (Plan-Apply-Unify Loop) is a structured AI-assisted development framework for Qwen Code.
 
 ## The Loop
 

package/src/references/research-quality-control.md

@@ -115,7 +115,7 @@ Before trusting any source:
 <anti_pattern name="tool_conflation">
 **DON'T:** Assume capabilities are the same across tools/environments.
 
-**Problem:** "Claude Desktop supports X" ≠ "Claude Code supports X"
+**Problem:** "Claude Desktop supports X" ≠ "Qwen Code supports X"
 
 **Instead:** Document which environment supports which features explicitly.
 </anti_pattern>

package/src/references/sonarqube-integration.md

@@ -49,7 +49,7 @@ sonar.exclusions=**/node_modules/**,**/dist/**
 
 ### 3. SonarQube MCP Server
 
-Ensure sonarqube MCP is configured in Claude Code:
+Ensure sonarqube MCP is configured in Qwen Code:
 
 ```json
 {
@@ -239,6 +239,6 @@ curl http://localhost:9000/api/system/status
 ### "MCP tools not available"
 
 Verify sonarqube MCP server is:
-- Configured in Claude Code settings
+- Configured in Qwen Code settings
 - Running without errors
 - Has correct authentication token

package/src/templates/MILESTONES.md

@@ -124,7 +124,7 @@ Include decimal phases in the range when relevant:
 - Handoff file generation for session breaks
 - STATE.md Session Continuity section
 - SonarQube integration (optional)
-- Codebase CLAUDE.md improvements
+- Codebase QWEN.md improvements
 
 **Stats:**
 | Metric | Value |

package/src/templates/codebase/structure.md

@@ -147,7 +147,7 @@ paul-framework/
 - Subdirectories: None
 
 **src/commands/**
-- Purpose: Slash command definitions for Claude Code
+- Purpose: Slash command definitions for Qwen Code
 - Contains: *.md files (one per command)
 - Key files: init.md, plan.md, apply.md, unify.md
 - Subdirectories: None (flat structure)
@@ -187,7 +187,7 @@ paul-framework/
 
 **Documentation:**
 - `README.md` - User-facing installation and usage guide
-- `CLAUDE.md` - Instructions for Claude Code when working in this repo
+- `QWEN.md` - Instructions for Qwen Code when working in this repo
 
 ## Naming Conventions
 

package/src/templates/config.md

@@ -63,7 +63,7 @@ enterprise_plan_audit:
 - Audit report saved alongside PLAN.md as `{NN}-{PP}-AUDIT.md`
 
 **Requirements:**
-- No external dependencies (runs within Claude Code session)
+- No external dependencies (runs within Qwen Code session)
 - Best suited for commercial, regulated, or enterprise-grade projects
 
 ### Future Integrations

package/src/templates/milestone-archive.md

@@ -189,14 +189,14 @@ Plans:
 Plans:
 - [x] 08.5-01: SonarQube integration (optional)
 
-### Phase 8.6: Codebase CLAUDE.md [INSERTED]
+### Phase 8.6: Codebase QWEN.md [INSERTED]
 
-**Goal:** Project-level Claude Code configuration
+**Goal:** Project-level Qwen Code configuration
 **Depends on:** Phase 8.5
 **Reason:** Improve agent context for PAUL projects
 
 Plans:
-- [x] 08.6-01: CLAUDE.md template for codebase guidance
+- [x] 08.6-01: QWEN.md template for codebase guidance
 
 ### Phase 8.7: SonarQube Integration [INSERTED]
 
@@ -213,7 +213,7 @@ Plans:
 
 **Decimal Phases:**
 - Phase 8.5: Quality Extensions (inserted after Phase 8 for code quality tooling)
-- Phase 8.6: Codebase CLAUDE.md (inserted after Phase 8.5 for agent context)
+- Phase 8.6: Codebase QWEN.md (inserted after Phase 8.5 for agent context)
 - Phase 8.7: SonarQube Integration (inserted after Phase 8.6 for quality checks)
 
 **Key Decisions:**

package/src/workflows/configure-special-flows.md

@@ -259,7 +259,7 @@ Display current configuration:
 **No .qwen/commands/ directory:**
 ```
 No skills directory found at ~/.qwen/commands/
-Add skills to your Claude Code configuration first.
+Add skills to your Qwen Code configuration first.
 
 You can still manually specify skill names.
 Enter skill names (comma-separated) or "skip":

package/src/workflows/init-project.md

@@ -228,7 +228,7 @@ SEED produces a PLANNING.md that PAUL can consume directly.
 Wait for user response.
 
 **If "1" or "install":**
-1. Run: `npx paul-framework add-skill seed` (or applicable install command)
+1. Run: `npx qwen-paul add-skill seed` (or applicable install command)
 2. Display: "SEED installed. Starting ideation with your project context..."
 3. Hand off to `/seed` — pass project_name, description, core_value, project_type, and any gathered requirements as context
 4. Exit init workflow (SEED will handle the rest; user returns via `/seed launch`)