/rpi — Full RPI Lifecycle Orchestrator

Quick Ref: One command, full lifecycle.

/discovery

→

/crank

→

/validation

. Thin wrapper that delegates to phase orchestrators. YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it. THREE-PHASE RULE + FULLY AUTONOMOUS. Read

references/autonomous-execution.md

— it defines the mandatory 3-phase lifecycle, autonomous execution rules, anti-patterns, and phase completion logging. Unless

--interactive

is set, RPI runs hands-free. Do NOT stop after Phase 2. Do NOT ask the user anything between phases.

Strict Delegation Contract (default)

RPI delegates via

Skill(skill="discovery", ...)

Skill(skill="crank", ...)

Skill(skill="validation", ...)

--full

Anti-pattern to reject: compressing phases into one pass, substituting

Agent()

Skill()

/validation

../shared/references/strict-delegation-contract.md

--quick

--fast-path

--from=<phase>

--no-retro

--no-forge

--no-budget

A live compression was observed 2026-04-19; see

.agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md

Quick Start

Run

/rpi "<goal>"

references/examples.md

Lifecycle Ownership

Phase orchestrators own all sub-skill sequencing, retry gates, and phase budgets.

/discovery

/crank

/validation

/rpi

Execution Steps

Step 0: Setup + Classify

mkdir -p .agents/rpi

Determine starting phase:

• default:

  discovery

• --from=implementation --discovery-artifact=<path>

  → skip to Phase 2, use the artifact as the discovery handoff (see Discovery Artifact Mode)

• --from=implementation

  (aliases:

  crank

  ) → skip to Phase 2

• --from=validation

  (aliases:

  vibe

  ,

  post-mortem

  ) → skip to Phase 3
• aliases

  research

  ,

  plan

  ,

  pre-mortem

  ,

  brainstorm

  map to

  discovery

• If input is a bead ID and

  --from

  is not set, resolve it before routing:

  • bd show <id>

    says

    issue_type=epic

    → Phase 2 using that epic ID
  • child issue with

    parent

    → Phase 2 using the parent epic ID
• If beads are absent or the input is plain goal text:
  • preserve the goal as the lifecycle objective
  • use

    .agents/rpi/execution-packet.json

    as the phase-2 handoff when discovery does not yield an epic
  • default to Phase 1 unless the user explicitly set

    --from

• Do not infer epic scope from

  ag-*

  alone. Classify complexity:

fast

--quick

standard

--quick

full

Complex-operation keywords:

refactor

migrate

migration

rewrite

redesign

rearchitect

overhaul

restructure

reorganize

decouple

deprecate

split

extract module

port

Scope keywords:

all

entire

across

everywhere

every file

every module

system-wide

global

throughout

codebase

Overrides:

--deep

full

--fast-path

fast

RPI mode: rpi-phased (complexity: <level>)

Initialize state:

rpi_state = {
  goal: "<goal string>",
  epic_id: null,
  phase: "<discovery|implementation|validation>",
  complexity: "<fast|standard|full>",
  test_first: <true by default; false only when --no-test-first>,
  cycle: 1,
  max_cycles: <3 when --loop; overridden by --max-cycles>,
  verdicts: {}
}

Phase 1: Discovery

Delegate to

/discovery

Skill(skill="discovery", args="<goal> [--interactive] --complexity=<level>")

After

/discovery

1. Check completion marker:

   <promise>DONE</promise>

   or

   <promise>BLOCKED</promise>

2. If BLOCKED: stop. Discovery handles its own retries (max 3 pre-mortem attempts). Manual intervention needed.
3. If DONE: read

   .agents/rpi/execution-packet.json

   (or the matching run archive when

   run_id

   is known), preserve the execution-packet objective spine, and extract

   epic_id

   only when it exists
4. Store

   rpi_state.epic_id

   when present and

   rpi_state.verdicts.pre_mortem

5. Log:

   PHASE 1 COMPLETE ✓ (discovery) — proceeding to Phase 2

Phase 2: Implementation

If the execution packet has

epic_id

Skill(skill="crank", args="<epic-id> [--test-first] [--no-test-first]")

Otherwise:

Skill(skill="crank", args=".agents/rpi/execution-packet.json [--test-first] [--no-test-first]")

Implementation gate (max 3 attempts):

• <promise>DONE</promise>

  : proceed to validation

• <promise>BLOCKED</promise>

  : retry with block context (max 2 retries)
  • Re-invoke

    /crank

    on the same lifecycle objective + block reason
  • If still BLOCKED after 3 total: stop, manual intervention needed

• <promise>PARTIAL</promise>

  : retry remaining (max 2 retries)
  • Re-invoke

    /crank

    on the same epic or execution packet (picks up remaining work)
  • If still PARTIAL after 3 total: stop, manual intervention needed

Record:

ao ratchet record implement 2>/dev/null || true

Log:

PHASE 2 COMPLETE ✓ (implementation) — proceeding to Phase 3

DO NOT STOP HERE. Do not ask the user to commit. Do not summarize and wait. Proceed IMMEDIATELY to Phase 3. Implementation without validation is incomplete work — the flywheel does not turn, learnings are not captured, and quality is unverified.

Phase 3: Validation

MANDATORY for all complexity levels.

/validation

/vibe

/post-mortem

/retro

/forge

/vibe

/rpi

/validation

fast

--quick

/validation

epic_id

Skill(skill="validation", args="<epic-id> --complexity=<level> [--strict-surfaces if --quality]")

Otherwise:

Skill(skill="validation", args="--complexity=<level> [--strict-surfaces if --quality]")

Validation-to-crank loop (max 3 total attempts):

• <promise>DONE</promise>

  : finish RPI

• <promise>FAIL</promise>

  : vibe found defects
  1. Extract findings from validation output
  2. Re-invoke

     /crank

     on the same epic or execution packet + findings context (preserve

     --test-first

     /

     --no-test-first

     from original invocation)
  3. Re-invoke

     /validation

  4. If still FAIL after 3 total: stop, manual intervention needed

Record:

ao ratchet record vibe 2>/dev/null || true

Log:

PHASE 3 COMPLETE ✓ (validation) — RPI DONE

Step Final: Report + Loop

Report: Summarize all phase verdicts and epic status. Optional loop (

--loop

cycle < max_cycles

1. Extract 3 concrete fixes from the post-mortem report
2. Increment

   rpi_state.cycle

3. Re-invoke

   /rpi

   from discovery with a tightened goal
4. PASS/WARN stops the loop

Optional spawn-next (

--spawn-next

1. Read

   .agents/rpi/next-work.jsonl

   for harvested follow-up items
2. Report with suggested next

   /rpi

   command
3. Do NOT auto-invoke

Read

references/report-template.md

references/error-handling.md

Flags

--from=<phase>

discovery

discovery

implementation

validation

--discovery-artifact=<path>

--from=implementation

/council

/crank

--interactive

--auto

--interactive

/discovery

/plan

--loop

--max-cycles=<n>

3

--loop

--spawn-next

--test-first

/crank

--no-test-first

--fast-path

--deep

--quality

--strict-surfaces

/validation

--dry-run

--no-budget

Phase Data Contracts

All transitions use filesystem artifacts (no in-memory coupling). The execution packet (

.agents/rpi/execution-packet.json

.agents/rpi/runs/<run-id>/execution-packet.json

contract_surfaces

done_criteria

references/phase-data-contracts.md

Complexity-Scaled Council Gates

Pre-mortem

• complexity == "low"

  or

  complexity == "fast"

  : inline review, no spawning (

  --quick

  )

• complexity == "medium"

  or

  complexity == "standard"

  : inline fast default (

  --quick

  )

• complexity == "high"

  or

  complexity == "full"

  : full council, 2-judge minimum; retry gate max 3 total attempts

Final Vibe

• complexity == "low"

  or

  complexity == "fast"

  : inline review, no spawning (

  --quick

  )

• complexity == "medium"

  or

  complexity == "standard"

  : inline fast default (

  --quick

  )

• complexity == "high"

  or

  complexity == "full"

  : full council, 2-judge minimum; retry gate max 3 total attempts

Post-mortem (STEP 2)

• complexity == "low"

  or

  complexity == "fast"

  : inline review, no spawning (

  --quick

  )

• complexity == "medium"

  or

  complexity == "standard"

  : inline fast default (

  --quick

  )

• complexity == "high"

  or

  complexity == "full"

  : full council, 2-judge minimum; retry gate max 3 total attempts

Examples

Read

references/examples.md

--fast-path

Troubleshooting

Read

references/troubleshooting.md

Runtime Compatibility

RPI runs in three runtime modes. All must produce identical phase artifacts.

session-start.sh

ao codex start

session-end.sh

ao codex stop

gcExecutor

streamExecutor

directExecutor

directExecutor

ao:phase

ao:gate

ao:failure

ao:metric

.agents/rpi/phased-state.json

.agents/rpi/phased-state.json

.agents/rpi/phased-state.json

ao ratchet check

ao ratchet check

ao ratchet check

gc status --json

gc is the default when available.

ao rpi

gcExecutor

gc

city.toml

streamExecutor

--runtime stream

--runtime tmux

Minimal contract across all modes: phase state is always written to

.agents/rpi/phased-state.json

1=discovery

2=implementation

3=validation

ao ratchet check

Reference Documents

• references/complexity-scaling.md
• references/context-windowing.md
• references/gate-retry-logic.md
• references/gate4-loop-and-spawn.md
• references/phase-budgets.md
• references/phase-data-contracts.md
• references/report-template.md
• references/error-handling.md
• references/examples.md
• references/autonomous-execution.md
• references/troubleshooting.md
• references/discovery-artifact-mode.md