From 5ca81f553996eb6c9ff2486c7c4c446aa58f8e42 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 08:08:42 +0000 Subject: [PATCH] docs(spec): add agents plan revert and agents plan resume commands Closes #5574 Both commands are fully implemented in plan.py but were absent from the spec: agents plan revert [--to-phase ] [--reason/-r ] - Reverts a plan to a previous phase (default: strategize) for re-planning - Recovery path for plans in the constrained terminal state - Increments reversion_count; blocked at MAX_REVERSIONS agents plan resume [--dry-run] - Resumes a plan from its last checkpoint - --dry-run previews resume point without changing state - Only non-terminal plans can be resumed Added to: 1. Command synopsis (~line 344): two new entries before plan rollback 2. New ##### agents plan revert section with purpose, arguments, behavior, examples 3. New ##### agents plan resume section with purpose, arguments, behavior, examples --- docs/specification.md | 57 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index 4accaad8b..4c7af0ceb 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -343,6 +343,8 @@ The following standards are integrated into the architecture: agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) agents plan artifacts <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> +agents plan revert [--to-phase <PHASE>] [(--reason|-r) <REASON>] <PLAN_ID> +agents plan resume [--dry-run] <PLAN_ID> agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> agents plan errors <PLAN_ID> @@ -16037,6 +16039,61 @@ Provide additional guidance to a plan, typically when it is errored or awaiting - "Guidance queued" ``` +##### agents plan revert + +
agents plan revert [--to-phase <PHASE>] [(--reason|-r) <REASON>] <PLAN_ID>
+ +**Purpose** +Revert a plan to a previous phase (typically Strategize) so it can be re-planned with different constraints. This is the recovery path for plans in the `constrained` terminal state — when a plan cannot complete due to conflicting invariants or constraints, it can be reverted to Strategize for re-planning. + +**Arguments** + +- ``: The plan to revert. +- `--to-phase PHASE`: Target phase to revert to (default: `strategize`). Valid values: `strategize`. +- `--reason/-r REASON`: Optional human-readable reason for the reversion (recorded in the plan's audit trail). + +**Behavior** + +- Increments the plan's `reversion_count` field. +- Blocked when `reversion_count >= MAX_REVERSIONS` (prevents infinite reversion loops). +- Only non-terminal plans can be reverted. + +**Examples** + +``` +$ agents plan revert 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 +$ agents plan revert 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --to-phase strategize --reason "constraints too strict" +``` + +--- + +##### agents plan resume + +
agents plan resume [--dry-run] <PLAN_ID>
+ +**Purpose** +Resume a plan from its last checkpoint. Shows a resume summary (phase, state, last completed step, next step, decision ID, checkpoint, sandbox ref) before executing. Use `--dry-run` to preview the resume point without changing state. + +**Arguments** + +- ``: The plan to resume. +- `--dry-run`: Preview the resume point without changing plan state or executing. + +**Behavior** + +- Only non-terminal plans (not `applied`, `cancelled`, or `constrained`) can be resumed. +- Displays a resume summary showing where execution will continue from. +- Without `--dry-run`, immediately continues plan execution from the resume point. + +**Examples** + +``` +$ agents plan resume 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 +$ agents plan resume 01HXM9A1C2Q7W3R5G8Z0P4Q1X9 --dry-run +``` + +--- + ##### agents plan rollback 
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>
-- 2.52.0