SUPER-PAUL

A standalone Claude Code plugin that merges PAUL's structured project loop with Superpowers' methodology guardrails — without either hijacking the other.

No dependency on PAUL or Superpowers being installed. Everything is self-contained.

The Problem This Solves

PAUL and Superpowers both want to drive the conversation. Without coordination:

You: "/paul:apply phase 2"
Superpowers: [sees "building something" → fires brainstorming]
Superpowers: "STOP! We must brainstorm first!"
Result: Your approved plan is derailed by a design session you didn't ask for.

SUPER-PAUL fixes this with one rule:

When a loop is active (.superpaul/STATE.md exists with an active phase), SUPER-PAUL owns the process. Superpowers steps back to guardrail mode only.

How It Works

SUPER-PAUL gives you a structured project loop with automatic methodology enforcement:

discuss → plan → apply → verify → unify → (repeat)

Each phase activates exactly the right guardrails:

| Phase | Guardrails Active | |-------|-------------------| | discuss | brainstorming ✅ | | plan | dispatching-parallel-agents ✅ | | apply | TDD + systematic-debugging + verification-before-completion + code-review + git-worktrees ✅ | | verify | systematic-debugging + verification-before-completion + code-review ✅ | | unify | verification-before-completion ✅ |

Suppressed everywhere: brainstorming (outside discuss), writing-plans, executing-plans — SUPER-PAUL owns these phases.

Install

Both Claude Code + OpenCode (recommended)

npx super-paul install

Claude Code only

npx super-paul install claude

OpenCode only

npx super-paul install opencode

Then add the plugin to your OpenCode config (~/.opencode/config.json):

{
  "plugin": ["./plugins/super-paul.js"]
}

Update to latest

npx super-paul update

Uninstall

npx super-paul uninstall

Manual install (alternative)

git clone https://github.com/therswamhtetai/super-paul.git ~/SUPERPAUL

# Claude Code
cp ~/SUPERPAUL/skills/superpaul/*.md ~/.claude/commands/superpaul/

# OpenCode
cp ~/SUPERPAUL/opencode/super-paul-plugin.js ~/.opencode/plugins/super-paul.js

Quick Start

/superpaul:init              ← set up project (.superpaul/ structure)
/superpaul:discuss 01        ← explore phase vision (brainstorming fires here)
/superpaul:plan 01           ← create plan with acceptance criteria
[approve the plan]
/superpaul:apply .superpaul/phases/01-name/01-01-PLAN.md
/superpaul:verify            ← guided UAT testing
/superpaul:unify .superpaul/phases/01-name/01-01-PLAN.md

Repeat from discuss for each phase.

Command Reference

Core Loop

| Command | Purpose | |---------|---------| | /superpaul:init | Initialize .superpaul/ in current project | | /superpaul:discuss <phase> | Explore phase vision — brainstorming fires here | | /superpaul:plan <phase> | Create PLAN.md with acceptance criteria | | /superpaul:apply <plan-path> | Execute approved plan with all guardrails | | /superpaul:verify [scope] | Guide manual UAT testing | | /superpaul:unify <plan-path> | Reconcile plan vs actual, close loop |

Navigation

| Command | Purpose | |---------|---------| | /superpaul:progress [context] | Show status + ONE next action | | /superpaul:resume [handoff] | Restore context after session break | | /superpaul:pause | Save context, prepare for break | | /superpaul:handoff | Full handoff doc for team or long break |

Project Management

| Command | Purpose | |---------|---------| | /superpaul:milestone <name> | Create new milestone | | /superpaul:add-phase <name> | Add phase to current milestone | | /superpaul:remove-phase <N> | Remove pending phase (safety checked) | | /superpaul:complete-milestone | Archive milestone, prep for next |

Research & Planning Helpers

| Command | Purpose | |---------|---------| | /superpaul:research <topic> | Research unknowns before planning | | /superpaul:assumptions <phase> | Surface hidden assumptions | | /superpaul:help [command] | Show command reference |

Project Structure

When you run /superpaul:init, it creates:

.superpaul/
├── PROJECT.md          ← project name, value, description
├── STATE.md            ← loop position, current phase/plan
├── ROADMAP.md          ← milestones and phases
├── SPECIAL-FLOWS.md    ← required guardrails for this project
└── phases/
    └── 01-phase-name/
        ├── CONTEXT.md       ← from discuss
        ├── ASSUMPTIONS.md   ← from assumptions (optional)
        ├── RESEARCH.md      ← from research (optional)
        ├── 01-01-PLAN.md    ← from plan
        ├── 01-01-SUMMARY.md ← from unify
        └── 01-01-UAT.md     ← from verify (if issues found)

Guardrail Hierarchy

1. User's explicit instructions (CLAUDE.md, direct requests)  ← highest
2. SUPER-PAUL loop commands (own the process when active)
3. Superpowers guardrails (fire inside the loop as methodology)
4. Default Claude behavior                                     ← lowest

Guardrail Map

| Behavior | discuss | plan | apply | verify | unify | |---|---|---|---|---|---| | brainstorming | ✅ | ❌ | ❌ | ❌ | ❌ | | writing-plans | ❌ | ❌ | ❌ | ❌ | ❌ | | executing-plans | ❌ | ❌ | ❌ | ❌ | ❌ | | test-driven-development | — | — | ✅ | — | — | | systematic-debugging | — | — | ✅ | ✅ | — | | verification-before-completion | — | — | ✅ | ✅ | ✅ | | requesting-code-review | — | — | ✅ | ✅ | — | | dispatching-parallel-agents | — | ✅ | ✅ | — | — | | using-git-worktrees | — | — | ✅ | — | — |

Repository Structure

super-paul/
├── skills/superpaul/
│   ├── _core.md              ← shared guardrail logic
│   ├── init.md
│   ├── discuss.md
│   ├── plan.md
│   ├── apply.md
│   ├── verify.md
│   ├── unify.md
│   ├── progress.md
│   ├── resume.md
│   ├── pause.md
│   ├── milestone.md
│   ├── add-phase.md
│   ├── remove-phase.md
│   ├── complete-milestone.md
│   ├── handoff.md
│   ├── research.md
│   ├── assumptions.md
│   └── help.md
├── docs/
│   ├── plans/
│   └── conversation-log.md
└── README.md

Design Rationale

PAUL provides a structured project loop (discuss → plan → apply → verify → unify) with state tracking via STATE.md. Superpowers provides methodology guardrails (TDD, systematic debugging, verification before completion) that auto-trigger aggressively.

The conflict: Superpowers' "1% rule" means brainstorming fires before any implementation — including during apply, where the design is already done and approved. This derails execution.

The fix: STATE.md is the coordination signal. If it shows an active loop position, SUPER-PAUL owns the process. Superpowers guardrails that overlap with PAUL's phases (brainstorming, writing-plans, executing-plans) are suppressed. Guardrails that add value inside the loop (TDD, debugging, verification) still fire.

Result: PAUL's structure + Superpowers' discipline, without conflict.

Credits

Inspired by:

• PAUL by Christopher Kahler — project loop and state management
• Superpowers by Jesse Vincent — methodology guardrails

SUPER-PAUL is an independent project and is not affiliated with either.

License

MIT