Ralplan

---
name: ralplan
description: Consensus-driven implementation planning via strict Planner/Architect/Critic iteration. Use when the user needs a detailed spec and implementation plan before coding. Trigger with /ralplan or by saying 'ralplan'. Execution-agnostic: RALPLAN defines roles, workflow, and artifact formats only; the host environment provides agent execution via any available method.
argument-hint: "[idea]"
level: intermediate
---

# ralplan — Consensus-Driven Implementation Planning

A strict three-role state machine that produces an implementation plan via adversarial review. Each role is a separately invoked agent; the parent agent does **not** perform role work itself. The pipeline prevents "Simulated Consensus" — the failure mode where a single generation hallucinates all three approvals in one block.

## Usage

Invoke one of:

- `/ralplan [idea]` — slash command, auto-starts the pipeline.
- `/ralplan:status` — show current iteration, last verdict, and produced artifacts.
- `/ralplan:artifacts` — list every file written under `plans/`.
- `/ralplan:skip` — advance past the current stage (use sparingly).
- `/ralplan:cancel` — end the session.
- `/brainstorm [idea]` — same pipeline under the brainstorm variant (see below).
- `--ralplan [idea]` / `--brainstorm [idea]` — CLI flag form for non-interactive hosts.

Auto-start is slash/flag only. Bare mentions of "ralplan" in prose do **not** re-trigger a fresh pipeline — the role prompts mention "ralplan" naturally during consensus rounds, and the loop must continue from where it is.

## Flags / Options

| Form                  | Effect                                                               |
| --------------------- | -------------------------------------------------------------------- |
| `/ralplan [idea]`     | Slash command — auto-starts the planning pipeline.                   |
| `/brainstorm [idea]`  | Slash command — auto-starts the brainstorm variant (open Q&A first). |
| `--ralplan [idea]`    | CLI flag — auto-starts the planning pipeline.                        |
| `--brainstorm [idea]` | CLI flag — auto-starts the brainstorm variant.                       |
| `/ralplan:status`     | Print the current iteration, last verdict, and artifact list.        |
| `/ralplan:artifacts`  | List every file produced under `plans/`.                             |
| `/ralplan:skip`       | Advance past the current stage (logged in the artifact trail).       |
| `/ralplan:cancel`     | End the session immediately; artifacts on disk are preserved.        |

## Core Directive

You are executing a strict multi-agent state machine. Your primary goal is to prevent **Simulated Consensus** — hallucinating all three approvals in a single generation. True consensus requires:

- Adversarial pushback (Architect and Critic must disagree before they agree).
- Isolated reasoning (each role is a separately invoked agent).
- Verifiable file-system checkpoints (artifacts written to `plans/` between roles).

**Self-approval is strictly prohibited.**

## Hard Constraints

1. **Isolated Roles.** Each role (Planner, Architect, Critic) MUST be executed by a separately invoked agent. The parent agent MUST NOT perform the work of any role itself.
2. **No Single-Turn Consensus.** The Planner's draft, the Architect's review, and the Critic's approval MUST NOT appear in the same output block.
3. **Mandatory Pushback.** The Architect or Critic must provide genuine pushback on the first pass. Rubber-stamping a first draft is a violation of the protocol.
4. **Auto-start is slash/flag only.** The pipeline auto-starts ONLY when the prompt begins with `/ralplan` or `/brainstorm` (or uses `--ralplan` / `--brainstorm` flags). Bare mentions of "ralplan" in prose do NOT trigger auto-start, because role prompts reference the skill name naturally and must not re-trigger a fresh pipeline for each consensus round.

## Iteration Loop

```
        +-----------+        REVISION NEEDED        +-----------+
        |  PLANNER  | <---------------------------+ | ARCHITECT |
        |  (State1) |                              +-----------+
        +-----------+                                      |
              |                                            | APPROVE
              v                                            v
        plans/drafts/plan_draft.md                  plans/drafts/architect_review.md
              |                                            |
              | APPROVE                                   |
              v                                            v
        +-----------+        REVISION NEEDED        +-----------+
        |  PLANNER  | <---------------------------+ |  CRITIC   |
        |  (State1) |                              +-----------+
        +-----------+                                      |
              ^                                            | APPROVE
              | REVISION NEEDED / REJECT                   v
              |                                  plans/plan.md
              +---------------------------------- PIPELINE_RALPLAN_COMPLETE
```

1. **State 1 — Planner.** Creates or revises the plan from the spec and prior feedback. Writes to `plans/drafts/plan_draft.md` and MUST include a RALPLAN-DR summary before handing off to the Architect.
2. **State 2 — Architect.** Reviews `plans/drafts/plan_draft.md` for technical feasibility. Must produce the strongest steelman antithesis. **REVISION NEEDED** routes back to State 1; **APPROVE** advances to State 3. **SEQUENTIAL** — await the Architect's complete verdict before invoking the Critic.
3. **State 3 — Critic.** Reviews the Architect-approved draft. Challenges assumptions, surfaces edge cases, verifies security/ops concerns. **REVISION NEEDED** or **REJECT** routes back to State 1; **APPROVE** saves the consensus-approved plan to `plans/plan.md`.
4. **Re-review loop.** Any non-APPROVE verdict loops back to State 1. Maximum **5 iterations** total.
5. **Termination.** Success — all three roles approve, emit `PIPELINE_RALPLAN_COMPLETE`. Failure — max iterations reached, halt and report. Escalation — fundamental disagreement between Architect and Critic, halt and request human input to break the tie.

## Output Artifacts

| File                               | Purpose                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plans/spec.md`                    | Foundational requirements. MUST contain `## Acceptance Criteria` (testable boolean statements) and `## Requirement Coverage Map`.                                                                                                                                                                        |
| `plans/drafts/plan_draft.md`       | Working plan during consensus review. MUST include an implementation plan (task breakdown, dependency graph, acceptance criteria, risk register) and the **RALPLAN-DR** summary block.                                                                                                                   |
| `plans/plan.md`                    | Consensus-approved implementation guide. MUST include `## Architecture Decision Record` (Decision, Drivers, Alternatives Considered, Why Chosen, Consequences, Follow-ups), `## Task Breakdown` with exact file paths, `## Dependency Graph`, `## Acceptance Criteria` per task, and `## Risk Register`. |
| `plans/drafts/architect_review.md` | Architect verdict — `APPROVE` or `REVISION NEEDED` (with steelman antithesis and tradeoff tension).                                                                                                                                                                                                      |
| `plans/drafts/critic_review.md`    | Critic verdict — `APPROVE`, `ITERATE`, or `REJECT` (with severity-tagged findings).                                                                                                                                                                                                                      |
| `plans/answers.md`                 | Brainstorm answers accumulation.                                                                                                                                                                                                                                                                         |
| `plans/open-questions.md`          | Brainstorm open questions.                                                                                                                                                                                                                                                                               |

The RALPLAN-DR block in `plan_draft.md` contains: **Principles** (3-5), **Decision Drivers** (top 3), and **Viable Options** (≥2 or explicit invalidation rationale). In **DELIBERATE** mode it additionally contains a **Pre-Mortem** (3 failure scenarios) and an **Expanded Test Plan** (unit / integration / e2e / observability).

## Completion Signals

The pipeline emits exactly one of these strings on termination. Hosts MUST treat them as the canonical stop markers:

- `PIPELINE_RALPLAN_COMPLETE` — consensus reached, `plans/plan.md` written.
- `PIPELINE_EXECUTION_COMPLETE` — execution stage finished (host-defined).
- `PIPELINE_RALPH_COMPLETE` — verification (RALPH) stage finished.
- `PIPELINE_QA_COMPLETE` — QA stage finished.
- `BRAINSTORM_OPEN_QUESTIONS_READY` — brainstorm variant surfaced its open questions.
- `CONSENSUS_APPROVED` — intermediate marker from the Critic on acceptance.
- `CONSENSUS_REJECTED` — intermediate marker from the Critic on rejection.
- `EXPANSION_COMPLETE` — DELIBERATE-mode pre-mortem + expanded test plan finished.
- `PLAN_CREATED` — Planner handed off its draft.
- `PLANNING_COMPLETE` — generic alias for `PIPELINE_RALPLAN_COMPLETE`.

## Termination Conditions

- **Success.** All three roles approve; emit `PIPELINE_RALPLAN_COMPLETE`; `plans/plan.md` exists.
- **Failure.** 5 iterations exhausted without unanimous approval; halt with the last verdict and a summary of unresolved disagreements.
- **Escalation.** Architect and Critic reach a fundamental disagreement the Planner cannot resolve; halt and request human input. Artifacts on disk are preserved.
- **Cancel.** `/ralplan:cancel` ends the session; artifacts on disk are preserved.

## Planning / Execution Boundary

The RALPLAN consensus loop runs entirely within the **planning** stage. On `PIPELINE_RALPLAN_COMPLETE` the pipeline advances to:

1. **Execution** — implements the approved plan.
2. **Verification (RALPH)** — reviews the implementation's quality.
3. **QA** — cycles build / lint / test until green.

Planning writes only markdown artifacts under `plans/` — **never** code files. Each pipeline run creates a single Git worktree under `<repo>-worktrees/` and all planning artifacts live inside that worktree. The `--ralplan` / `--brainstorm` CLI flags and the `/ralplan` slash command both auto-start a pipeline.

## Brainstorm Variant

`/brainstorm` runs the same consensus loop but opens with a question-elicitation phase that writes to `plans/open-questions.md` and accumulates user answers in `plans/answers.md` before the Planner drafts. The `BRAINSTORM_OPEN_QUESTIONS_READY` signal is emitted once questions are surfaced; the loop proceeds to `PIPELINE_RALPLAN_COMPLETE` after consensus on the resulting plan.

## Fallback Mode

There is no single-turn fallback. If the host cannot isolate the three roles into separate agent invocations (e.g. extremely constrained environments), the skill is **not applicable** — the protocol explicitly forbids parent-agent role substitution. In that case, halt and report "ralplan requires role-isolated agent execution; current host does not support it."