Reviewed plan runs

RalphTerm can execute checked-list plans through a terminal agent, validate the result, require an independent review, and record the artifacts needed to audit what happened.

Run a plan with review

ralphterm run docs/plans/example.md --agent claude \
  --require-review \
  --review-agent codex

ralphterm run docs/plans/example.md --agent claude \
  --require-review \
  --review-command "codex exec review-task"

--require-review is a hard gate. If it is used without --review-command or --review-agent, RalphTerm fails before starting implementation. That includes --dry-run: a dry run fails before agent execution when the review gate is required but not configured. The implementation and review commands must also be different; the same command is rejected in dry-run too. With review configured, the implementation agent runs in one PTY and the reviewer runs later in a separate PTY.

Validation before acceptance

Plan-level validation commands from the ## Validation Commands section run after each implementation attempt. RalphTerm includes the validation output in the reviewer prompt. A task is not checked off until validation succeeds and review passes.

Review decisions

The reviewer receives the task text, implementation transcript, validation output, current diff, and untracked file names. The decision must be explicit:

• REVIEW_PASS accepts the task.
• REVIEW_FAIL rejects the current attempt and, by default, triggers one REVIEW_FAIL retry by returning the reviewer feedback to the implementation agent.

If the retry also fails review, RalphTerm leaves the task unchecked and exits failed instead of committing partial progress. Use --max-review-retries N to configure the review retry budget: higher values allow more failed reviews before blocking, and --max-review-retries 0 blocks on the first failed review.

Resume after failure

You can resume after a failed run by invoking the same plan again. RalphTerm skips tasks already marked [x], keeps failed context available to the next implementation prompt, and continues with pending tasks.

Artifacts and audit trail

Plan runs preserve transcripts for each implementation and review attempt. They also write progress logs, summary.md, summary.json, and diff.patch so another tool or human can inspect the exact terminal output and code changes.

Workspace-isolated plan runs

ralphterm run docs/plans/example.md --workspace-id docs-slice --agent claude

Add --workspace-id <id> when a plan should run in a managed git worktree instead of the checkout you invoked from. RalphTerm creates .ralphterm/workspaces/<id>, checks out a managed branch, preserves the caller-relative plan path, and runs from the corresponding directory inside the worktree. The run does not auto-clean the worktree when it finishes; inspect it or remove it later with ralphterm workspace cleanup <id>. With --dry-run --workspace-id <id>, dry run only previews the workspace path and pending plan work without creating the worktree or starting an agent.

Commit progress

After validation and REVIEW_PASS, RalphTerm marks the task checkbox, writes the run artifacts, and commits task progress. This commit progress step only happens after the review gate passes. Failed validation or review leaves the task uncommitted for follow-up.