rpi

/rpi - Full Lifecycle Orchestrator

Quick ref: /discovery -> /crank -> /validate, then report.

Execute this workflow. Do not only describe it. RPI is autonomous unless --interactive is set. The user touchpoint is after validation, or after a real blocked state exhausts retries. Read references/autonomous-execution.md when you need the full autonomy contract.

--auto means pivot autonomously, NOT execute the initial plan to the letter. Autonomy is agility, not waterfall: between waves the orchestrator re-plans the remaining work and changes course on its own — refactoring, adding, dropping, reordering waves as evidence arrives — without the operator saying so (touched only at the terminal objective or a circuit-breaker trip). See Agile Re-Plan Loop.

Loop position

/rpi is the orchestrator across every move of the operating loop: BDD intent → vertical slices → per-slice narrow-waist micro-cycle (acceptance test RED → green → refactor-under-green) → conflict-free wave → bead acceptance → evidence + learning mined back into the next loop. It delegates each move to the skill that owns it (/discovery, /plan, /crank, /validate, /curate --mode=forge//post-mortem), and enforces these loop-level invariants:

• Agile, not waterfall — the plan is a hypothesis. Every wave closes with a re-plan, not just a retry (the Agile Re-Plan Loop, autonomous under --auto).
• No move-skipping, but validation cadence is pawl-gated, not per-tread. The acceptance roll-up plus heavy gates (/validate, optional council, /pawl-review, then ao pawl) fire once at bead acceptance. Intermediate slices use cheap local checks.
• The first failing test is the bead's contract. With --test-first on (the default), /crank is invoked with the TDD-per-slice discipline; --no-test-first is an explicit opt-out, not a fast path. /crank runs refactor-under-green as its own step after green — the load-bearing quality move — and a refactor must never change a test (S4; test-first ordering alone is not the quality lever).
• Acceptance examples close the bead, not activity. Validation FAIL re-cranks on the same objective up to 3 attempts; DONE requires the acceptance roll-up in the slice-validation template to be fully green.
• Ports stay visible. Preserve the Intent-to-Loop Hexagon boundary as the objective crosses shape_intent, persist_intent, plan_slices, execute_wave, validate_acceptance, and record_evidence.
• Context density survives phase boundaries. Apply the Context Density Rule to every phase handoff and final report: keep intent, boundary, evidence, decision, constraint, and next action; omit or link anything else.

Folded triggers (ag-s43tg): operating-loop-skill + operating-loop-workflow route here

• operating-loop-skill — driving one bead end-to-end through claim, work, independent validation, closeout, and persistence: /rpi <bead-id> runs that exact arc.
• operating-loop-workflow — installing or running the seven-move operating-loop Workflow for AgentOps plugin users and multi-agent orchestration: /rpi is the in-session orchestrator of the same seven moves.

Core Contract

RPI delegates via Skill(skill="discovery", ...), Skill(skill="crank", ...), and Skill(skill="validate", ...) as separate tool invocations. Keep strict delegation on by default; do not compress phases, replace phase skills with direct agent spawns, or skip validation. Read ../shared/references/strict-delegation-contract.md for the full anti-compression contract. See references/isolation-contract.md for the four-lever model, phase-isolated skill transport, and the compression patterns scripts/check-skill-isolation.sh flags. See references/best-practices.md for the principle and anti-pattern citation table.

When the runtime supports phase isolation, keep /rpi visible in the main session and run each phase contract through isolated transport: phase skill name in, bounded handoff artifact in, phase artifact/verdict/next action out. The transport may be a daemon job, process runner, or subagent wrapper, but it must execute the declared phase skill contract rather than doing phase work directly.

RPI owns one lifecycle objective across all phases. Preserve the discovered epic_id when present; otherwise preserve the original goal and execution packet objective. A child bead or one ready slice is context, not a replacement objective. <promise>PARTIAL</promise> from /crank means retry Phase 2 on the same objective.

Phase Receipt Contract

RPI cannot rely on memory or a final narrative to prove delegated skills ran. Every execution packet and phase summary MUST carry compact receipts — JSON skills_loaded + phase_receipts (canonical slugs, no sigils) and a ## Skill Receipts bullet list in each markdown phase summary. Receipts do not replace transcript/runtime proof; they make delegation auditable from disk when the transcript is unavailable and give validation or pre-land review a deterministic surface to reject missing phase execution. Full schema + example (the phase-receipt rule + fields): references/phase-data-contracts.md.

Route And Classify

1. Create .agents/rpi/.
2. Resolve --from:
   • default, research, plan, pre-mortem, brainstorm -> discovery
   • implementation or crank -> implementation
   • validation, vibe, or post-mortem -> validation
3. If the input is a bead and --from is absent, resolve it with ao beads exec show:
   • epic -> implementation with that epic
   • child with parent -> implementation with the parent epic
4. Classify complexity:
   • fast: short/simple goal or --fast-path
   • standard: medium goal or one scope keyword
   • full: --deep, complex-operation keyword, 2+ scope keywords, or >120 chars
5. Log RPI mode: rpi-phased (complexity: <level>).

Track state compactly as rpi_state: goal (string), epic_id (null until discovered), phase (discovery|implementation|validation), complexity (fast|standard|full), test_first (true unless --no-test-first), cycle (from 1), and verdicts ({}).

Complex-operation keywords include refactor, migrate, rewrite, redesign, rearchitect, overhaul, decouple, deprecate, split, extract module, and port. Scope keywords include all, entire, across, everywhere, every file, system-wide, global, and codebase.

Phase DAG

Enter at the routed phase and run every phase after it.

1. Discovery: invoke /discovery <goal> [--interactive] --complexity=<level> directly or through phase-isolated skill transport. On DONE, read .agents/rpi/execution-packet.json or the run archive and preserve its objective spine. On BLOCKED, stop with the discovery verdict.
2. Implementation: invoke /crank <epic-id> when the packet has epic_id; otherwise invoke /crank .agents/rpi/execution-packet.json, directly or through phase-isolated skill transport. Pass --test-first or --no-test-first through. On DONE, record ao ratchet record implement 2>/dev/null || true and continue. On PARTIAL or BLOCKED, retry the same objective up to 3 total attempts. Before accepting a slice/wave the orchestrator reads the actual diff itself (scope + claim match) — not just the <promise>DONE</promise> and evidence JSON, but its own diff-read, distinct from the delegated sub-judges. /crank enforces this as the anti-green-washing Step 3.5 of its Wave Acceptance (crank wave-patterns.md §Wave Acceptance Check).
3. Validation: invoke /validate <epic-id> --complexity=<level> when an epic exists; otherwise invoke /validate --complexity=<level>, directly or through phase-isolated skill transport. Add --strict-surfaces when --quality is set. On FAIL, extract findings, re-run /crank on the same objective, then re-run /validate, up to 3 total validation attempts. On DONE, record ao ratchet record vibe 2>/dev/null || true. This Phase-3 /validate is the bead-acceptance pawl, once per objective. Any work crossing shared trunk obtains fresh evidence through /pawl-review; ao pawl applies the complexity-scaled diversity and verdict gate.
4. Re-plan (mandatory between waves; the loop's hinge). With remaining waves, run the Agile Re-Plan Loop before the next — a post-mortem/discovery delta that MAY mutate the remaining plan (autonomous under --auto). No remaining waves → straight to Report.
5. Report: summarize phase verdicts, the re-plan deltas taken, and epic status using references/report-template.md. With --loop, restart from discovery on FAIL while cycle < max_cycles. With --spawn-next, read .agents/rpi/next-work.jsonl and suggest the next command without invoking it. Before emitting the report, apply the Context Density Rule: every line should carry intent, boundary, evidence, decision, constraint, or next action.

Agile Re-Plan Loop (the anti-waterfall rule)

The initial plan is a hypothesis; each wave is an experiment whose evidence re-plans the rest. At every wave boundary (and after validation): reflect (a bounded /post-mortem + /discovery re-plan delta over what shipped/broke) → re-plan the REMAINING waves (refactor / insert / drop / reorder / re-scope / escalate, persisting the mutated plan so the next wave reads the current one) → proceed. Under --auto this is autonomous, bounded by the run's circuit breakers (budget / attempt cap / oscillation detection) and the ≥5-ship post-mortem checkpoint; the operator is touched only at the terminal objective or a breaker trip. /crank and /validate surface findings UP for re-planning (never a silent local retry); /discovery is the re-plan engine. Anti-patterns: waterfall (run the plan to the letter), retry-not-replan (re-crank forever instead of changing the remaining plan), permission-seeking (pause to approve a pivot --auto already authorizes). Full detail: references/agile-replan-loop.md.

Phase Data Contract

The execution packet carries the repo execution profile through contract_surfaces, done_criteria, and queue claim/finalize metadata. Keep the latest alias at .agents/rpi/execution-packet.json and read references/phase-data-contracts.md for schemas and archive paths.

Complexity-Scaled Gates

The pawl gates (pawls.md) fire at the irreversible doors — bead-acceptance and merge-to-main — never per slice/wave; chaos between pawls. The merge-to-main pawl fires regardless of complexity (see Phase 3); complexity below only scales the DEPTH of the gate, never whether it runs.

Complexity scales the gate's depth: low/fast and medium/standard → 2-judge minimum panel (inline / --quick); high/full → full council; max 3 total attempts. The gate still fires at the door at every complexity.

• Pre-mortem (planning-time, chaos-side — NOT a pawl): high/full → full council, 2-judge minimum; max 3 total attempts. Pre-mortem stress-tests the plan before work; it is not an irreversible door and carries no heavy gate of its own outside this optional full-arc depth.
• Final Vibe (at the bead-acceptance pawl): high/full → full council, 2-judge minimum; max 3 total attempts.
• Post-mortem (STEP 2, at the bead-acceptance pawl): high/full → full council; same scale as above.

Flags

Examples

• /rpi "add user authentication" — discovery → implementation → validation → report.
• /rpi --from=implementation ag-23k — resolve the bead scope, run implementation + validation.
• /rpi --deep "refactor payment module" — full council gates across the lifecycle.

Read references/examples.md for resume, interactive, loop, and artifact-mode examples.

Output Specification

Format: a markdown report to stdout (report-template) — phase verdicts, re-plan deltas, and epic status. Files: reads/updates .agents/rpi/execution-packet.json (+ runs/<id>/) and .agents/rpi/next-work.jsonl (with --spawn-next); records ao ratchet record per phase. Exit signal: the per-phase verdict roll-up; <promise>PARTIAL</promise> from /crank means retry Phase 2 on the same objective.

Troubleshooting

Related skills

• /agent-native + /ntm — portable out-of-session workers and NTM pane mechanics for whole /rpi loops.

Reference Documents

• references/agile-replan-loop.md — the anti-waterfall rule: inter-wave re-plan, --auto-pivot bounds, anti-patterns
• references/rpi.feature — Executable spec: strict ordered phases, validation-never-skipped, context-density across handoffs (soc-qk4b.2)
• references/orchestrator-compression-anti-pattern.md — Phase-skipping failure mode; rationalizations to reject
• references/installed-plugin-version-not-repo-head.md — /rpi loads from ~/.claude/plugins/cache/, not the repo working tree; verify which version is active before measuring
• references/complexity-scaling.md
• references/context-windowing.md — OPT-IN large-repo mode (--large-repo); NOT part of the default RPI path. Default discovery/research does not generate .agents/rpi/context-shards/latest.json.
• references/discovery-artifact-mode.md
• references/error-handling.md
• references/gate-retry-logic.md
• references/gate4-loop-and-spawn.md
• references/phase-budgets.md
• references/troubleshooting.md

Also referenced inline above: autonomous-execution, codex-executor, examples, phase-data-contracts, report-template.