pi-ralplan

Note: The docs/ folder is managed by the pi-docs package. Best with pi-subagentura: Works better when paired with the pi-subagentura package for spawning sub-agents.

Consensus-driven planning extension for Pi. Brings the RALPLAN pipeline from oh-my-claudecode to Pi as an extension + skill package.

Features

• Consensus Planning — Planner → Architect → Critic iteration loop
• Configurable Pipeline — RALPLAN → Execution → Verification → QA
• Pre-Execution Gate — Detects broad requests and suggests planning first
• Stage Prompt Injection — Automatic stage-specific prompts via before_agent_start
• Signal-Based Advancement — Detects PIPELINE_*_COMPLETE signals to auto-advance
• Session Persistence — Dual persistence: session entries (branch-safe) + file state (resume)
• UI Integration — Status line and progress widget
• Deliberate Mode — Enhanced scrutiny for high-risk work (auth, migrations, production)

Installation

As a Pi package

pi install npm:pi-ralplan

Or for local development:

cd ~/dev/pi-ralplan
pi install -l .

Manual (copy files)

Copy the extension and skill to your Pi directories:

mkdir -p ~/.pi/agent/extensions/ralplan
mkdir -p ~/.pi/agent/skills/ralplan
cp -r pi/extensions/ralplan/* ~/.pi/agent/extensions/ralplan/
cp -r pi/skills/ralplan/* ~/.pi/agent/skills/ralplan/

Then reload Pi with /reload.

Usage

Start a planning session

/ralplan build me a todo app

Or start Pi with the flag:

pi --ralplan "build me a todo app"

Commands

| Command | Description | | -------------------- | ------------------------ | | /ralplan [idea] | Start consensus planning | | /ralplan:status | Show pipeline status | | /ralplan:cancel | Cancel active session | | /ralplan:skip | Skip current stage | | /ralplan:artifacts | List planning artifacts |

Tools (callable by LLM)

| Tool | Description | | ------------------------- | ------------------------ | | ralplan_advance | Advance to next stage | | ralplan_submit_artifact | Save spec/plan/test-spec | | ralplan_set_config | Modify pipeline config |

Pipeline Stages

1. RALPLAN — Consensus planning (spec + plan creation)
2. Execution — Implement the approved plan
3. Verification (RALPH) — Review implementation quality
4. QA — Build / lint / test cycling

Completion Signals

The LLM emits these signals to advance stages:

• PIPELINE_RALPLAN_COMPLETE
• PIPELINE_EXECUTION_COMPLETE
• PIPELINE_RALPH_COMPLETE
• PIPELINE_QA_COMPLETE

Configuration

Add to .pi/settings.json:

{
  "ralplan": {
    "planning": "ralplan",
    "execution": "solo",
    "verification": {
      "engine": "ralph",
      "maxIterations": 100
    },
    "qa": true
  }
}

| Option | Values | Description | | -------------- | ------------------------------------------------ | -------------------------------- | | planning | "ralplan", "direct", false | Planning mode or skip | | execution | "solo", "team" | Sequential or parallel execution | | verification | { engine: "ralph", maxIterations: n }, false | Verification settings | | qa | true, false | Enable QA stage |

Pre-Execution Gate

When you make a broad request without concrete anchors (file paths, issue numbers, function names), the extension suggests using /ralplan first.

Bypass the gate: Prefix with force: or !

force: ralph refactor everything
! implement auth now

Passes the gate: Requests with concrete signals

ralph fix src/hooks/bridge.ts
implement #42
fix processKeywordDetector

Architecture

User Input → /ralplan Command → Pipeline Init → Stage Machine
                                      ↓
Agent Loop ← Signal Detection ← Agent Response ← Stage Prompt

pi/extensions/ralplan/
├── index.ts      # Main extension entry point
├── pipeline.ts   # Stage machine + config
├── adapters.ts   # Stage prompt generators
├── prompts.ts    # Prompt templates
├── state.ts      # Session + file persistence
├── signals.ts    # Signal detection
├── artifacts.ts  # Plan file management
└── utils.ts      # Helpers

pi/skills/ralplan/
├── SKILL.md                     # Skill definition
├── prompts/
│   ├── planner.md
│   ├── architect.md
│   └── critic.md
└── references/
    └── consensus-workflow.md

Troubleshooting

| Issue | Solution | | ----------------------------------- | ----------------------------------------------------------------- | | Gate fires on well-specified prompt | Add a file reference, function name, or issue number | | Want to bypass the gate | Prefix with force: or ! | | Signal not detected | Ensure the exact signal text appears in the assistant response | | State lost after /tree | State is branch-safe; check /.pi/ralplan/state.json as fallback | | Pipeline stuck | Use /ralplan:skip to skip the current stage | | Extension not loading | Verify paths in package.json pi.extensions and run /reload |

Testing

bun test

License

MIT