/rpi — Full RPI Lifecycle Orchestrator

Quick Ref: One command, full lifecycle. Discovery → Implementation → Validation. The session is the lead; sub-skills manage their own teams.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Quick Start

/rpi "add user authentication"                        # full lifecycle
/rpi --interactive "add user authentication"          # human gates in discovery only
/rpi --from=discovery "add auth"                      # resume discovery
/rpi --from=implementation ag-23k                      # skip to crank with existing epic
/rpi --from=validation                                 # run vibe + post-mortem only
/rpi --loop --max-cycles=3 "add auth"                 # optional iterate-on-fail loop
/rpi --test-first "add auth"                          # pass --test-first to /crank

Architecture

/rpi <goal | epic-id> [--from=<phase>] [--interactive]
  │ (session = lead, no TeamCreate)
  │
  ├── Phase 1: Discovery
  │   ├── /research
  │   ├── /plan
  │   └── /pre-mortem (gate)
  │
  ├── Phase 2: Implementation
  │   └── /crank (autonomous execution)
  │
  └── Phase 3: Validation
      ├── /vibe (gate)
      └── /post-mortem (retro + flywheel)

Human gates (default): 0 — fully autonomous. Human gates (--interactive): discovery approvals in /research and /plan. Retry gates: pre-mortem FAIL → re-plan, implementation BLOCKED/PARTIAL → re-crank, vibe FAIL → re-crank (max 3 attempts each). Optional loop (--loop): post-mortem FAIL can spawn another RPI cycle.

Phase Data Contracts

All phase transitions use filesystem-based artifacts (no in-memory coupling):

Execution Steps

Given /rpi <goal | epic-id> [--from=<phase>] [--interactive]:

Step 0: Setup

mkdir -p .agents/rpi

Determine starting phase:

• default: discovery
• --from=implementation (alias: crank)
• --from=validation (aliases: vibe, post-mortem)
• aliases research, plan, and pre-mortem map to discovery

If input looks like an epic ID (ag-*) and --from is not set, start at implementation.

Initialize state:

rpi_state = {
  goal: "<goal string>",
  epic_id: null,
  phase: "<discovery|implementation|validation>",
  auto: <true unless --interactive>,
  test_first: <true if --test-first>,
  complexity: null,
  cycle: 1,
  parent_epic: null,
  verdicts: {}
}

Phase 1: Discovery

Discovery is one context window that runs research, planning, and pre-mortem together:

/research <goal> [--auto]
/plan <goal> [--auto]
/pre-mortem

After discovery completes:

1. Extract epic ID from bd list --type epic --status open and store in rpi_state.epic_id.
2. Extract pre-mortem verdict (PASS/WARN/FAIL) from latest pre-mortem council report.
3. Store verdict in rpi_state.verdicts.pre_mortem.
4. Write summary to .agents/rpi/phase-1-summary-YYYY-MM-DD-<goal-slug>.md.
5. Record ratchet and telemetry:

ao ratchet record research 2>/dev/null || true
bash scripts/checkpoint-commit.sh rpi "phase-1" "discovery complete" 2>/dev/null || true
bash scripts/log-telemetry.sh rpi phase-complete phase=1 phase_name=discovery 2>/dev/null || true

Gate behavior:

• PASS/WARN: proceed to implementation.
• FAIL: re-run /plan with findings context (top 5 structured findings: description, fix, ref), then /pre-mortem again. Max 3 total attempts. If still FAIL after 3, stop and require manual intervention.

Phase 2: Implementation

Requires rpi_state.epic_id.

/crank <epic-id> [--test-first]

After implementation completes:

1. Check completion via crank output / epic child statuses.
2. Gate result:
   • DONE: proceed to validation
   • BLOCKED: re-run /crank with block context (max 3 total attempts). If still BLOCKED, stop and require manual intervention.
   • PARTIAL: re-run /crank with epic-id; it picks up unclosed issues (max 3 total attempts). If still PARTIAL, stop and require manual intervention.
3. Write summary to .agents/rpi/phase-2-summary-YYYY-MM-DD-<goal-slug>.md.
4. Record ratchet and telemetry:

ao ratchet record implement 2>/dev/null || true
bash scripts/checkpoint-commit.sh rpi "phase-2" "implementation complete" 2>/dev/null || true
bash scripts/log-telemetry.sh rpi phase-complete phase=2 phase_name=implementation 2>/dev/null || true

Phase 3: Validation

Validation runs final review and lifecycle close-out:

/vibe recent            # use --quick recent for low/medium complexity
/post-mortem <epic-id>  # use --quick for low/medium complexity

After validation completes:

1. Extract vibe verdict and store rpi_state.verdicts.vibe.
2. If present, extract post-mortem verdict and store rpi_state.verdicts.post_mortem.
3. Gate result:
   • PASS/WARN: finish RPI
   • FAIL: re-run implementation with findings, then re-run validation (max 3 total attempts)
4. Write summary to .agents/rpi/phase-3-summary-YYYY-MM-DD-<goal-slug>.md.
5. Record ratchet and telemetry:

ao ratchet record vibe 2>/dev/null || true
bash scripts/checkpoint-commit.sh rpi "phase-3" "validation complete" 2>/dev/null || true
bash scripts/log-telemetry.sh rpi phase-complete phase=3 phase_name=validation 2>/dev/null || true

Optional loop (--loop): If post-mortem verdict is FAIL and --loop is enabled, extract 3 concrete fixes from the report and re-invoke /rpi from Phase 1 with a tightened goal (up to --max-cycles total cycles). PASS/WARN stops the loop.

Optional spawn-next (--spawn-next): After a PASS/WARN finish, read .agents/rpi/next-work.jsonl for harvested follow-up items. Report them to the user with a suggested next /rpi command but do NOT auto-invoke.

Step Final: Report

Read references/report-template.md for the final output format and next-work handoff pattern.

Read references/error-handling.md for failure semantics and retries.

Complexity-Aware Ceremony

RPI automatically classifies each goal’s complexity at startup and adjusts the ceremony accordingly. This prevents trivial tasks from paying the full validation overhead of a refactor.

Classification Levels

Keyword Signals

Complex-operation keywords (trigger full): refactor, migrate, migration, rewrite, redesign, rearchitect, overhaul, restructure, reorganize, decouple, deprecate, split, extract module, port

Scope keywords (1 → standard; 2+ → full): all, entire, across, everywhere, every file, every module, system-wide, global, throughout, codebase

All keywords are matched as whole words to prevent false positives (e.g. “support” does not match “port”).

Logged Output

At RPI start you will see:

RPI mode: rpi-phased (complexity: fast)
Complexity: fast — skipping validation phase (phase 3)

or for standard/full:

RPI mode: rpi-phased (complexity: standard)

The complexity level is persisted in .agents/rpi/phased-state.json as the complexity field.

Override

• --fast-path: force fast-path regardless of classification (useful for quick patches).
• --deep: force full-ceremony regardless of classification (useful for sensitive changes).

Flags

Examples

Full Lifecycle

User says: /rpi "add user authentication"

What happens:

1. Discovery runs /research, /plan, /pre-mortem and produces epic ag-5k2.
2. Implementation runs /crank ag-5k2 until children are complete.
3. Validation runs /vibe then /post-mortem, extracts learnings, and suggests next work.

Resume from Implementation

User says: /rpi --from=implementation ag-5k2

What happens:

1. Skips discovery.
2. Runs /crank ag-5k2.
3. Runs validation (/vibe + /post-mortem).

Interactive Discovery

User says: /rpi --interactive "refactor payment module"

What happens:

1. Discovery runs with human gates in /research and /plan.
2. Implementation and validation remain autonomous.

Troubleshooting

Emergency control (external operator loop)

Use external operator controls from a terminal to cancel in-flight runs and clean stale worktrees/branches. Keep these controls out-of-band from /rpi skill chaining.

See Also

• skills/research/SKILL.md — discovery exploration
• skills/plan/SKILL.md — discovery decomposition
• skills/pre-mortem/SKILL.md — discovery risk gate
• skills/crank/SKILL.md — implementation execution
• skills/vibe/SKILL.md — validation gate
• skills/post-mortem/SKILL.md — validation close-out

Reference Documents

• references/complexity-scaling.md
• references/context-windowing.md
• references/gate-retry-logic.md
• references/gate4-loop-and-spawn.md
• references/phase-data-contracts.md