Standalone Claude Code plugin: PAUL project loop + Superpowers guardrails, no dependencies required

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

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

super-paul