cleveragents/cleveragents-core

Fork 3

UAT: `agents plan resume` is an undocumented command not in the spec — plan resume should be handled by `agents plan execute` (which says "Start or resume execution") #4857

New issue

Open

opened 2026-04-08 20:09:41 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 20:09:41 +00:00

Owner

Summary

The CLI exposes an agents plan resume command that does not exist in the specification. The spec's agents plan execute command is documented as "Start or resume execution for a plan" — meaning plan execute handles both starting and resuming. The separate plan resume command is an undocumented addition that diverges from the spec's command surface.

What Was Tested

Code-level analysis of src/cleveragents/cli/commands/plan.py against the specification's plan command listing and agents plan execute documentation.

Expected Behavior (from spec)

The spec's command summary (§Plan Lifecycle at a Glance) lists these plan commands:

agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>]
agents plan use ...
agents plan execute <PLAN_ID>
agents plan apply [--yes|-y] <PLAN_ID>
agents plan status <PLAN_ID>
agents plan cancel [--reason|-r <REASON>] <PLAN_ID>
agents plan tree [--show-superseded] <PLAN_ID>
agents plan correct --mode (revert|append) --guidance <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID>
agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>)
agents plan explain [--show-context] [--show-reasoning] <DECISION_ID>
agents plan artifacts <PLAN_ID>
agents plan errors <PLAN_ID>
agents plan prompt <PLAN_ID> <GUIDANCE>
agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID>

The spec's agents plan execute section explicitly states:

Start or resume execution for a plan.

And shows an example of resuming a previously paused/errored plan:

$ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J
Phase: execute (resumed)
...
[OK] Execution resumed from checkpoint cp_01HXM8C2

There is no agents plan resume command in the spec.

Actual Behavior

The code registers a separate plan resume command at line 3354:

@app.command("resume")
def resume_plan_cmd(
    plan_id: Annotated[str, typer.Argument(help="Plan ID to resume")],
    dry_run: Annotated[bool, typer.Option("--dry-run", ...)] = False,
    ...

This command:

Is not in the spec's command surface
Duplicates functionality that plan execute should handle (resuming from a checkpoint)
Adds a --dry-run flag that the spec doesn't define for resume operations
Creates confusion about when to use plan execute vs plan resume

Code Location

src/cleveragents/cli/commands/plan.py, lines 3354–3444 (resume_plan_cmd)
src/cleveragents/application/services/plan_resume_service.py (backing service)

Impact

Undocumented command: Users following the spec will not know plan resume exists
Spec divergence: The spec says plan execute handles resume — having a separate command creates two ways to do the same thing
Inconsistent UX: Error messages in plan status say "use agents plan prompt to resume" but the actual resume mechanism is plan resume (or plan execute)

Note on Severity

This is a spec alignment issue. The plan resume command may be intentionally added as an extension, but it should either:

Be removed and its functionality folded into plan execute (spec-aligned approach), or
Be documented in the spec as an extension command

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Summary The CLI exposes an `agents plan resume` command that does not exist in the specification. The spec's `agents plan execute` command is documented as "Start or resume execution for a plan" — meaning `plan execute` handles both starting and resuming. The separate `plan resume` command is an undocumented addition that diverges from the spec's command surface. ## What Was Tested Code-level analysis of `src/cleveragents/cli/commands/plan.py` against the specification's plan command listing and `agents plan execute` documentation. ## Expected Behavior (from spec) The spec's command summary (§Plan Lifecycle at a Glance) lists these plan commands: ``` agents plan list [--phase <PHASE>] [--state <STATE>] [--project <PROJECT>] agents plan use ... agents plan execute <PLAN_ID> agents plan apply [--yes|-y] <PLAN_ID> agents plan status <PLAN_ID> agents plan cancel [--reason|-r <REASON>] <PLAN_ID> agents plan tree [--show-superseded] <PLAN_ID> agents plan correct --mode (revert|append) --guidance <GUIDANCE> [--dry-run] [--yes|-y] <DECISION_ID> agents plan diff (--correction <CORRECTION_ATTEMPT_ID>|<PLAN_ID>) agents plan explain [--show-context] [--show-reasoning] <DECISION_ID> agents plan artifacts <PLAN_ID> agents plan errors <PLAN_ID> agents plan prompt <PLAN_ID> <GUIDANCE> agents plan rollback [--yes|-y] <PLAN_ID> <CHECKPOINT_ID> ``` The spec's `agents plan execute` section explicitly states: > **Start or resume execution for a plan.** And shows an example of resuming a previously paused/errored plan: ``` $ agents plan execute 01HXM7K2ZK4Q7C2B3F2R4VYV6J Phase: execute (resumed) ... [OK] Execution resumed from checkpoint cp_01HXM8C2 ``` There is **no** `agents plan resume` command in the spec. ## Actual Behavior The code registers a separate `plan resume` command at line 3354: ```python @app.command("resume") def resume_plan_cmd( plan_id: Annotated[str, typer.Argument(help="Plan ID to resume")], dry_run: Annotated[bool, typer.Option("--dry-run", ...)] = False, ... ``` This command: 1. Is not in the spec's command surface 2. Duplicates functionality that `plan execute` should handle (resuming from a checkpoint) 3. Adds a `--dry-run` flag that the spec doesn't define for resume operations 4. Creates confusion about when to use `plan execute` vs `plan resume` ## Code Location - `src/cleveragents/cli/commands/plan.py`, lines 3354–3444 (`resume_plan_cmd`) - `src/cleveragents/application/services/plan_resume_service.py` (backing service) ## Impact 1. **Undocumented command**: Users following the spec will not know `plan resume` exists 2. **Spec divergence**: The spec says `plan execute` handles resume — having a separate command creates two ways to do the same thing 3. **Inconsistent UX**: Error messages in `plan status` say "use `agents plan prompt` to resume" but the actual resume mechanism is `plan resume` (or `plan execute`) ## Note on Severity This is a spec alignment issue. The `plan resume` command may be intentionally added as an extension, but it should either: 1. Be removed and its functionality folded into `plan execute` (spec-aligned approach), or 2. Be documented in the spec as an extension command --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 20:10:31 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:12:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:16:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added this to the v3.3.0 milestone

2026-04-08 20:17:28 +00:00

HAL9000 referenced this issue

2026-04-08 20:19:20 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 22:59:44 +00:00

freemo commented

2026-04-08 23:41:30 +00:00

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — agents plan resume is undocumented; spec says resume should be handled by agents plan execute
Milestone: v3.3.0 (Corrections + Subplans + Checkpoints)
Story Points: 2 — S — Removing or redirecting an undocumented command is a small task
MoSCoW: Should Have — CLI consistency with spec is important; undocumented commands create confusion
Parent Epic: #4942 (Decision Intelligence Legendary)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `agents plan resume` is undocumented; spec says resume should be handled by `agents plan execute` - **Milestone**: v3.3.0 (Corrections + Subplans + Checkpoints) - **Story Points**: 2 — S — Removing or redirecting an undocumented command is a small task - **MoSCoW**: Should Have — CLI consistency with spec is important; undocumented commands create confusion - **Parent Epic**: #4942 (Decision Intelligence Legendary) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

freemo added

and removed

labels

2026-04-08 23:41:52 +00:00

freemo added a new dependency

2026-04-08 23:42:05 +00:00

#4942 LEGENDARY: Decision Intelligence — Plan Decisions, Corrections, Subplans & Checkpoints