Proposal [AUTO-SPEC-1]: Document agents plan revert and agents plan resume CLI commands in specification #9888

Open
opened 2026-04-15 23:31:50 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Commit message: docs: add agents plan revert and agents plan resume to CLI specification
  • Branch name: docs/spec-add-plan-revert-resume-commands

Background and Context

The specification's CLI synopsis for agents plan subcommands does not document two user-facing commands — agents plan revert and agents plan resume — that are already present in the implementation. This creates a gap between what users can actually do and what the specification describes, making the spec an incomplete reference for both users and contributors.

The implementation contains:

  1. agents plan revert — Located at src/cleveragents/cli/commands/plan.py:3196-3365. Allows users to revert a plan to a previous state.
  2. agents plan resume — Located at src/cleveragents/cli/commands/plan.py:3725-3890. Allows users to resume a plan that was paused or interrupted.

These are intentional, user-facing CLI commands exposed in the agents plan command group, not internal implementation details. They complement the existing plan rollback and plan correct commands and represent a more complete approach to plan lifecycle management.


Discrepancy Report

Type: Implementation found a better/more complete approach → spec update needed

Area: CLI Commands — Plan Lifecycle

Current Spec State

The specification's CLI synopsis documents the following agents plan subcommands:

  • agents plan list
  • agents plan use
  • agents plan execute
  • agents plan apply
  • agents plan status
  • agents plan cancel
  • agents plan tree
  • agents plan explain
  • agents plan correct
  • agents plan diff
  • agents plan artifacts
  • agents plan prompt
  • agents plan rollback
  • agents plan errors

The spec does not document agents plan revert or agents plan resume as user-invokable commands.

Implementation State

The implementation contains two additional plan commands:

  1. agents plan revert — Located at src/cleveragents/cli/commands/plan.py:3196-3365. Allows users to revert a plan to a previous state.

  2. agents plan resume — Located at src/cleveragents/cli/commands/plan.py:3725-3890. Allows users to resume a plan that was paused or interrupted.

These are user-facing CLI commands exposed in the agents plan command group, not internal implementation details.

Proposed Spec Change

Update the §CLI Commands section to add agents plan revert and agents plan resume to the plan command synopsis:

agents plan revert [--yes|-y] <PLAN_ID>
agents plan resume <PLAN_ID>

Additionally, add brief descriptions of these commands in the plan lifecycle documentation:

  • plan revert: Reverts a plan to a previous checkpoint or state, undoing any changes made since that point.
  • plan resume: Resumes execution of a plan that was paused, interrupted, or placed in a waiting state.

Classification

Implementation found a better approach — The implementation provides explicit user-facing commands for plan reversion and resumption that complement the existing plan rollback and plan correct commands. These are intentional features that should be documented in the spec.


Expected Behavior

After this issue is resolved, docs/specification.md accurately reflects all user-facing agents plan subcommands, including agents plan revert and agents plan resume. Users consulting the specification can discover and understand these commands without needing to inspect the source code. The commands are clearly distinguished from related commands (plan rollback, plan correct) with concise descriptions of their distinct purposes.


Acceptance Criteria

  • docs/specification.md CLI synopsis includes agents plan revert and agents plan resume
  • Brief descriptions of both commands are added to the plan lifecycle section
  • The commands are distinguished from plan rollback (checkpoint-based) and plan correct (decision-tree correction)
  • Synopsis entries follow the existing format: agents plan revert [--yes|-y] <PLAN_ID> and agents plan resume <PLAN_ID>
  • No other spec sections are inadvertently modified

Subtasks

  • Review src/cleveragents/cli/commands/plan.py:3196-3365 to confirm plan revert signature, options, and behavior
  • Review src/cleveragents/cli/commands/plan.py:3725-3890 to confirm plan resume signature, options, and behavior
  • Add agents plan revert [--yes|-y] <PLAN_ID> to the CLI synopsis in docs/specification.md
  • Add agents plan resume <PLAN_ID> to the CLI synopsis in docs/specification.md
  • Add descriptions for both commands in the plan lifecycle section, distinguishing them from plan rollback and plan correct
  • Open a PR targeting the appropriate branch with the spec changes
  • Request review from a spec maintainer

Definition of Done

This issue should be closed when:

  1. docs/specification.md has been updated to include both agents plan revert and agents plan resume in the CLI synopsis and plan lifecycle documentation.
  2. The PR has been reviewed and merged.
  3. The spec accurately reflects the implementation with no remaining gaps for these two commands.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor


Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit message**: `docs: add agents plan revert and agents plan resume to CLI specification` - **Branch name**: `docs/spec-add-plan-revert-resume-commands` --- ## Background and Context The specification's CLI synopsis for `agents plan` subcommands does not document two user-facing commands — `agents plan revert` and `agents plan resume` — that are already present in the implementation. This creates a gap between what users can actually do and what the specification describes, making the spec an incomplete reference for both users and contributors. The implementation contains: 1. **`agents plan revert`** — Located at `src/cleveragents/cli/commands/plan.py:3196-3365`. Allows users to revert a plan to a previous state. 2. **`agents plan resume`** — Located at `src/cleveragents/cli/commands/plan.py:3725-3890`. Allows users to resume a plan that was paused or interrupted. These are intentional, user-facing CLI commands exposed in the `agents plan` command group, not internal implementation details. They complement the existing `plan rollback` and `plan correct` commands and represent a more complete approach to plan lifecycle management. --- ## Discrepancy Report **Type**: Implementation found a better/more complete approach → spec update needed **Area**: CLI Commands — Plan Lifecycle ### Current Spec State The specification's CLI synopsis documents the following `agents plan` subcommands: - `agents plan list` - `agents plan use` - `agents plan execute` - `agents plan apply` - `agents plan status` - `agents plan cancel` - `agents plan tree` - `agents plan explain` - `agents plan correct` - `agents plan diff` - `agents plan artifacts` - `agents plan prompt` - `agents plan rollback` - `agents plan errors` The spec does **not** document `agents plan revert` or `agents plan resume` as user-invokable commands. ### Implementation State The implementation contains two additional plan commands: 1. **`agents plan revert`** — Located at `src/cleveragents/cli/commands/plan.py:3196-3365`. Allows users to revert a plan to a previous state. 2. **`agents plan resume`** — Located at `src/cleveragents/cli/commands/plan.py:3725-3890`. Allows users to resume a plan that was paused or interrupted. These are user-facing CLI commands exposed in the `agents plan` command group, not internal implementation details. ### Proposed Spec Change Update the §CLI Commands section to add `agents plan revert` and `agents plan resume` to the plan command synopsis: ``` agents plan revert [--yes|-y] <PLAN_ID> agents plan resume <PLAN_ID> ``` Additionally, add brief descriptions of these commands in the plan lifecycle documentation: - **`plan revert`**: Reverts a plan to a previous checkpoint or state, undoing any changes made since that point. - **`plan resume`**: Resumes execution of a plan that was paused, interrupted, or placed in a waiting state. ### Classification **Implementation found a better approach** — The implementation provides explicit user-facing commands for plan reversion and resumption that complement the existing `plan rollback` and `plan correct` commands. These are intentional features that should be documented in the spec. --- ## Expected Behavior After this issue is resolved, `docs/specification.md` accurately reflects all user-facing `agents plan` subcommands, including `agents plan revert` and `agents plan resume`. Users consulting the specification can discover and understand these commands without needing to inspect the source code. The commands are clearly distinguished from related commands (`plan rollback`, `plan correct`) with concise descriptions of their distinct purposes. --- ## Acceptance Criteria - [ ] `docs/specification.md` CLI synopsis includes `agents plan revert` and `agents plan resume` - [ ] Brief descriptions of both commands are added to the plan lifecycle section - [ ] The commands are distinguished from `plan rollback` (checkpoint-based) and `plan correct` (decision-tree correction) - [ ] Synopsis entries follow the existing format: `agents plan revert [--yes|-y] <PLAN_ID>` and `agents plan resume <PLAN_ID>` - [ ] No other spec sections are inadvertently modified --- ## Subtasks - [ ] Review `src/cleveragents/cli/commands/plan.py:3196-3365` to confirm `plan revert` signature, options, and behavior - [ ] Review `src/cleveragents/cli/commands/plan.py:3725-3890` to confirm `plan resume` signature, options, and behavior - [ ] Add `agents plan revert [--yes|-y] <PLAN_ID>` to the CLI synopsis in `docs/specification.md` - [ ] Add `agents plan resume <PLAN_ID>` to the CLI synopsis in `docs/specification.md` - [ ] Add descriptions for both commands in the plan lifecycle section, distinguishing them from `plan rollback` and `plan correct` - [ ] Open a PR targeting the appropriate branch with the spec changes - [ ] Request review from a spec maintainer --- ## Definition of Done This issue should be closed when: 1. `docs/specification.md` has been updated to include both `agents plan revert` and `agents plan resume` in the CLI synopsis and plan lifecycle documentation. 2. The PR has been reviewed and merged. 3. The spec accurately reflects the implementation with no remaining gaps for these two commands. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator
Author
Owner

[AUTO-OWNR-1] Triage complete.

Verified — Valid spec documentation gap. agents plan revert and agents plan resume are implemented but not documented in the specification. This creates a gap between implementation and spec.

  • Type: Documentation (spec update)
  • Priority: Medium
  • MoSCoW: Should Have — spec completeness improves developer experience
  • Milestone: v3.2.0 — CLI spec documentation

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

[AUTO-OWNR-1] Triage complete. **Verified** ✅ — Valid spec documentation gap. `agents plan revert` and `agents plan resume` are implemented but not documented in the specification. This creates a gap between implementation and spec. - **Type**: Documentation (spec update) - **Priority**: Medium - **MoSCoW**: Should Have — spec completeness improves developer experience - **Milestone**: v3.2.0 — CLI spec documentation --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9888
No description provided.