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
• 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"

Auto-start is slash-only. The pipeline auto-starts ONLY when the prompt begins with /ralplan or /brainstorm (or when --ralplan / --brainstorm flags are used). Bare mentions of ralplan or brainstorm in prose — including action verbs like use ralplan to plan this or start-of-prompt directives like ralplan: build auth — do NOT trigger auto-start. This prevents the planner/architect/critic role prompts (which all mention ralplan naturally in their role descriptions) from accidentally re-triggering a fresh pipeline for each consensus round. To start a pipeline from prose, prefix the prompt with /:

/ralplan build me a todo app

Worktrees

Each pipeline run creates a single Git worktree under <repo>-worktrees/. Follow-up sessions launched from inside that worktree reuse the same worktree instead of creating a sibling — one worktree per pipeline run, regardless of how many consensus rounds are run. This is detected via git rev-parse --git-dir vs --git-common-dir and works automatically; no configuration required.

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 |

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
├── worktree.ts       # Git worktree management (with reuse rule)
├── brainstorm.ts     # Brainstorm mode sub-phase logic
├── naming.ts         # Filename generation helpers
└── utils.ts          # Shared helpers

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

Troubleshooting

| Issue | Solution | | ------------------------ | ----------------------------------------------------------------- | | 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

npm test

License

MIT