qwen-paul 1.0.0

package/bin/install.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}   \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557
+  \u2588\u2588\u2554\u2550\u2550\u2550\u255d\u2588\u2588\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d
+  \u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2557  
+  \u2588\u2588\u2551     \u2588\u2588\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u255d  
+  \u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
+   \u255a\u2550\u2550\u2550\u2550\u2550\u2550 \u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d${reset}
+
+  PAUL Framework ${dim}v${pkg.version}${reset}
+  Plan-Apply-Unify Loop for Qwen Code
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    return configDirArg.split('=')[1];
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx qwen-paul [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to Qwen config directory)
+    ${cyan}-l, --local${reset}               Install locally (to ./.qwen in current directory)
+    ${cyan}-c, --config-dir <path>${reset}   Specify custom Qwen config directory
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install to default ~/.qwen directory${reset}
+    npx qwen-paul --global
+
+    ${dim}# Install to custom config directory${reset}
+    npx qwen-paul --global --config-dir ~/.qwen-custom
+
+    ${dim}# Install to current project only${reset}
+    npx qwen-paul --local
+
+  ${yellow}What gets installed:${reset}
+    commands/qwen-paul/  - Slash commands (/paul:init, /paul:plan, etc.)
+    paul-framework/      - Templates, workflows, references, rules
+`);
+  process.exit(0);
+}
+
+/**
+ * Expand ~ to home directory
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Recursively copy directory, replacing paths in .md files
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix);
+    } else if (entry.name.endsWith('.md')) {
+      // Replace ~/.qwen/ with the appropriate prefix in markdown files
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = content.replace(/~\/\.qwen\//g, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Install to the specified directory
+ */
+function install(isGlobal) {
+  const src = path.join(__dirname, '..');
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.QWEN_CONFIG_DIR);
+  const defaultGlobalDir = configDir || path.join(os.homedir(), '.qwen');
+
+  const qwenDir = isGlobal
+    ? defaultGlobalDir
+    : path.join(process.cwd(), '.qwen');
+
+  const locationLabel = isGlobal
+    ? qwenDir.replace(os.homedir(), '~')
+    : qwenDir.replace(process.cwd(), '.');
+
+  // Path prefix for file references
+  const pathPrefix = isGlobal
+    ? (configDir ? `${qwenDir}/` : '~/.qwen/')
+    : './.qwen/';
+
+  console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
+
+  // Create commands directory
+  const commandsDir = path.join(qwenDir, 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  // Copy src/commands to commands/qwen-paul
+  const commandsSrc = path.join(src, 'src', 'commands');
+  const commandsDest = path.join(commandsDir, 'qwen-paul');
+  copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix);
+  console.log(`  ${green}\u2713${reset} Installed commands/qwen-paul`);
+
+  // Copy src/* (except commands) to paul-framework/
+  const skillDest = path.join(qwenDir, 'paul-framework');
+  fs.mkdirSync(skillDest, { recursive: true });
+
+  const srcDirs = ['templates', 'workflows', 'references', 'rules', 'carl'];
+  for (const dir of srcDirs) {
+    const dirSrc = path.join(src, 'src', dir);
+    const dirDest = path.join(skillDest, dir);
+    if (fs.existsSync(dirSrc)) {
+      copyWithPathReplacement(dirSrc, dirDest, pathPrefix);
+    }
+  }
+  console.log(`  ${green}\u2713${reset} Installed paul-framework`);
+
+  console.log(`
+  ${green}Done!${reset} Launch Qwen Code and run ${cyan}/paul:help${reset}.
+`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.QWEN_CONFIG_DIR);
+  const globalPath = configDir || path.join(os.homedir(), '.qwen');
+  const globalLabel = globalPath.replace(os.homedir(), '~');
+
+  console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalLabel})${reset} - available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.qwen)${reset} - this project only
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    const choice = answer.trim() || '1';
+    const isGlobal = choice !== '2';
+    install(isGlobal);
+  });
+}
+
+// Main
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+  process.exit(1);
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
+  process.exit(1);
+} else if (hasGlobal) {
+  install(true);
+} else if (hasLocal) {
+  install(false);
+} else {
+  promptLocation();
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "qwen-paul",
+  "version": "1.0.0",
+  "description": "Plan-Apply-Unify Loop - A structured AI-assisted development framework for Qwen Code",
+  "bin": {
+    "qwen-paul": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "src/commands",
+    "src/templates",
+    "src/references",
+    "src/workflows",
+    "src/rules",
+    "src/carl"
+  ],
+  "keywords": [
+    "qwen",
+    "qwen-code",
+    "qwen-cli",
+    "ai",
+    "planning",
+    "structured-development",
+    "paul",
+    "plan-apply-unify"
+  ],
+  "author": "Chris Kahler (adapted for Qwen by tylergriffin1350)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tylergriffin1350/qwen-paul.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tylergriffin1350/qwen-paul/issues"
+  },
+  "homepage": "https://github.com/tylergriffin1350/qwen-paul#readme",
+  "engines": {
+    "node": ">=16.7.0"
+  }
+}

package/src/carl/PAUL

@@ -0,0 +1,26 @@
+# CARL Domain: PAUL (Plan-Apply-Unify Loop)
+# AI-assisted development workflow. Activates when .paul/ exists in project.
+PAUL_STATE=active
+PAUL_ALWAYS_ON=false
+
+# Rule 0: Scope
+PAUL_RULE_0=PAUL governs structured AI development via Plan-Apply-Unify loop. Requires .paul/ directory.
+
+# MUST (critical)
+PAUL_RULE_1=LOAD BEFORE EXECUTE: Before ANY /paul:* command, MUST Read the command file (~/.qwen/paul-framework/src/commands/{name}.md) AND its execution_context workflow file. NEVER execute PAUL commands from memory or inference - always load the actual files first. If files cannot be loaded, STOP and inform user.
+PAUL_RULE_2=No implementation code without approved PLAN.md. Research/exploration OK. Violation = stop, request approval.
+PAUL_RULE_3=Every APPLY must be followed by UNIFY. UNIFY reconciles plan vs actual, updates STATE.md, logs decisions.
+PAUL_RULE_4=Respect PLAN.md "Boundaries" / "DO NOT CHANGE" sections. Stop and confirm before modifying protected items.
+PAUL_RULE_5=When blocked: document in STATE.md Blockers, notify human, await approval before workarounds.
+PAUL_RULE_6=At phase transition: VERIFY state consistency (STATE.md, PROJECT.md, ROADMAP.md aligned). Blocking error if misaligned. Re-read full files, check all fields.
+
+# SHOULD (quality)
+PAUL_RULE_7=Tasks require verification criteria: <verify>[proof of success]</verify>. No verify = cannot complete.
+PAUL_RULE_8=Log all APPLY deviations: what, why, downstream impact. Audit trail for UNIFY.
+PAUL_RULE_9=Use BDD acceptance criteria: Given [precondition] / When [action] / Then [outcome].
+
+# MAY (patterns)
+PAUL_RULE_10=Size tasks for single session (~50% context). Split larger tasks during planning.
+PAUL_RULE_11=One commit per phase at transition. Format: {type}({phase}): {description}. WIP commits optional at pause. Version alignment required at milestone.
+PAUL_RULE_12=Urgent work uses decimal phases (2.1, 2.2). Integers = planned, decimals = interruptions.
+

package/src/carl/PAUL.manifest

@@ -0,0 +1,11 @@
+# ============================================================================
+# PAUL - Plan-Apply-Unify Loop (AI-assisted development workflow)
+# ============================================================================
+# Installation:
+#   1. Copy the PAUL domain file to ~/.carl/PAUL (or project .carl/PAUL)
+#   2. Append this block to your ~/.carl/manifest (or project .carl/manifest)
+# ============================================================================
+PAUL_STATE=active
+PAUL_ALWAYS_ON=false
+PAUL_RECALL=paul,plan phase,apply phase,unify phase,PLAN.md,STATE.md,development workflow,vibe coding,ai development,planning framework,.paul/
+# PAUL_EXCLUDE=

package/src/commands/add-phase.md

@@ -0,0 +1,36 @@
+---
+name: paul:add-phase
+description: Add a new phase to current milestone
+argument-hint: "[phase-name]"
+allowed-tools: [Read, Write, Edit, Bash]
+---
+
+<objective>
+Add a new phase to the current milestone's roadmap.
+
+**When to use:** Scope expansion during milestone, adding planned work.
+</objective>
+
+<execution_context>
+@{~/.qwen/paul-framework/workflows/roadmap-management.md}
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.paul/PROJECT.md
+@.paul/STATE.md
+@.paul/ROADMAP.md
+</context>
+
+<process>
+Follow workflow: @{~/.qwen/paul-framework/workflows/roadmap-management.md}
+
+Execute: **add-phase** operation
+</process>
+
+<success_criteria>
+- [ ] Phase added to ROADMAP.md
+- [ ] Phase directory created
+- [ ] STATE.md updated with new phase
+</success_criteria>

package/src/commands/apply.md

@@ -0,0 +1,83 @@
+---
+name: paul:apply
+description: Execute an approved PLAN
+argument-hint: "[plan-path]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion]
+---
+
+<objective>
+Execute an approved PLAN.md file, handling checkpoints as they occur.
+
+**When to use:** After PLAN phase complete and plan is approved.
+
+Executes tasks in sequence, pauses at checkpoints for user input, reports completion.
+</objective>
+
+<execution_context>
+@{~/.qwen/paul-framework/workflows/apply-phase.md}
+@{~/.qwen/paul-framework/references/checkpoints.md}
+</execution_context>
+
+<context>
+Plan path: $ARGUMENTS
+
+@.paul/STATE.md
+</context>
+
+<process>
+
+<step name="validate_plan">
+1. Confirm plan file exists at $ARGUMENTS path
+2. Error if not found: "Plan not found: {path}"
+3. Derive SUMMARY path (replace PLAN.md with SUMMARY.md)
+4. If SUMMARY exists: "Plan already executed. SUMMARY: {path}"
+   - Offer: re-execute or exit
+</step>
+
+<step name="execute">
+Follow workflow: @{~/.qwen/paul-framework/workflows/apply-phase.md}
+
+Execute tasks sequentially. For each task:
+- Read task definition
+- Execute action
+- Run verification
+- Confirm done criteria
+</step>
+
+<step name="handle_checkpoints">
+When a checkpoint task is reached:
+
+**checkpoint:decision**
+- Present decision context and options
+- Wait for user selection
+- Record decision
+- Continue execution
+
+**checkpoint:human-verify**
+- Present what was built
+- Present verification steps
+- Wait for "approved" or issue description
+- If issues: address and re-verify
+- Continue execution
+
+**checkpoint:human-action**
+- Present required action
+- Wait for "done" confirmation
+- Continue execution
+</step>
+
+<step name="complete">
+After all tasks complete:
+- Report: "APPLY complete. Run /paul:unify to close loop."
+- Show files modified
+- Show SUMMARY path to create
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All tasks executed
+- [ ] All checkpoints handled
+- [ ] User informed of completion
+- [ ] Next action clear (run /paul:unify)
+</success_criteria>

package/src/commands/assumptions.md

@@ -0,0 +1,37 @@
+---
+name: paul:assumptions
+description: Surface Claude's assumptions about a phase before planning
+argument-hint: "<phase-number>"
+allowed-tools: [Read, Bash]
+---
+
+<objective>
+Surface Claude's assumptions about a phase to validate understanding before planning.
+
+**When to use:** Before planning to catch misconceptions early.
+
+**Distinction from /paul:discuss:** This command shows what CLAUDE thinks. The discuss command gathers what USER wants.
+</objective>
+
+<execution_context>
+@{~/.qwen/paul-framework/workflows/phase-assumptions.md}
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+@.paul/PROJECT.md
+@.paul/STATE.md
+@.paul/ROADMAP.md
+</context>
+
+<process>
+Follow workflow: @{~/.qwen/paul-framework/workflows/phase-assumptions.md}
+</process>
+
+<success_criteria>
+- [ ] Assumptions presented across 5 areas
+- [ ] Confidence levels indicated
+- [ ] User can provide corrections
+- [ ] Clear path to planning after validation
+</success_criteria>

package/src/commands/audit.md

@@ -0,0 +1,57 @@
+---
+name: paul:audit
+description: Run enterprise-grade architectural audit on current plan
+argument-hint: "[plan-path]"
+allowed-tools: [Read, Write, Edit, Glob, AskUserQuestion]
+---
+
+<objective>
+Run a senior principal engineer + compliance review audit on the current PLAN.md.
+Automatically applies must-have and strongly-recommended findings to the plan.
+Produces an AUDIT.md report in the same phase directory.
+
+**When to use:** After PLAN phase complete, before APPLY.
+**Optional:** Only runs when explicitly invoked or suggested by `enterprise_plan_audit` config.
+**Who audits:** Claude performs the audit assuming the role of senior principal engineer + compliance reviewer.
+</objective>
+
+<execution_context>
+@{~/.qwen/paul-framework/workflows/audit-plan.md}
+</execution_context>
+
+<context>
+Plan path: $ARGUMENTS
+
+@.paul/STATE.md
+@.paul/config.md
+</context>
+
+<process>
+**Follow workflow: @{~/.qwen/paul-framework/workflows/audit-plan.md}**
+
+The workflow implements:
+1. Validate preconditions (PLAN exists, loop at PLAN complete)
+2. Load and parse the PLAN.md
+3. Execute enterprise audit (6-section structured review)
+4. Classify findings (must-have, strongly-recommended, can-safely-defer)
+5. Auto-apply must-have and strongly-recommended findings to PLAN.md
+6. Create AUDIT.md report in phase directory
+7. Update STATE.md with audit completion
+8. Present summary and route to APPLY
+</process>
+
+<success_criteria>
+- [ ] PLAN.md audited against enterprise standards
+- [ ] Must-have and strongly-recommended findings applied to PLAN.md
+- [ ] AUDIT.md report created in phase directory
+- [ ] STATE.md updated to reflect audit completion
+- [ ] User presented with next action (run APPLY)
+</success_criteria>
+
+<anti_patterns>
+- Don't invent requirements not implied by the plan
+- Don't assume "future phases" will fix gaps
+- Don't say "this is fine for v1" unless justified
+- Don't optimize for politeness over correctness
+- Don't skip applying findings - the whole point is automatic remediation
+</anti_patterns>

package/src/commands/complete-milestone.md

@@ -0,0 +1,36 @@
+---
+name: paul:complete-milestone
+description: Mark current milestone as complete
+argument-hint: "[version]"
+allowed-tools: [Read, Write, Edit, Bash, Glob]
+---
+
+<objective>
+Complete the current milestone, archive it, and evolve PROJECT.md.
+
+**When to use:** All phases in current milestone are complete and verified.
+</objective>
+
+<execution_context>
+@{~/.qwen/paul-framework/workflows/complete-milestone.md}
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.paul/PROJECT.md
+@.paul/STATE.md
+@.paul/ROADMAP.md
+@.paul/MILESTONES.md
+</context>
+
+<process>
+Follow workflow: @{~/.qwen/paul-framework/workflows/complete-milestone.md}
+</process>
+
+<success_criteria>
+- [ ] Milestone archived with summary
+- [ ] PROJECT.md evolved with learnings
+- [ ] Git tag created for version
+- [ ] STATE.md updated to reflect completion
+</success_criteria>