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>