UAT: agents plan use allows creating a plan with no projects — spec requires at least one <PROJECT> argument #3521

New issue

Open

opened 2026-04-05 18:50:48 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 18:50:48 +00:00

Owner

Metadata

Branch: fix/plan-use-require-project-argument
Commit Message: fix(cli): require at least one project argument in agents plan use command
Milestone: None (backlog)
Parent Epic: #397

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background

Code-level analysis of src/cleveragents/cli/commands/plan.py against docs/specification.md §"agents plan use" revealed a validation gap: the agents plan use command allows creating a plan with no projects bound to it, but the spec requires at least one <PROJECT> argument.

Spec synopsis (§"agents plan use"):

agents plan use [options] <ACTION> <PROJECT>...

The spec defines <PROJECT> as a required positional argument (one or more). The spec description states: "Apply an action to one or more projects and start the Strategize phase." A plan without a project has no context to work in.

Actual implementation (src/cleveragents/cli/commands/plan.py, lines 1398–1411):
Both the positional projects argument and the --project/-p option are optional:

projects: Annotated[
    list[str] | None,
    typer.Argument(help="Projects to apply the action on (one or more)"),
] = None,
project: Annotated[
    list[str] | None,
    typer.Option("--project", "-p", ...),
] = None,

Running agents plan use local/my-action (no project) succeeds and creates a plan with an empty project_links list. This plan cannot be executed meaningfully since there are no project resources to work with.

Steps to reproduce:

Create an action: agents action create --config my-action.yaml
Run: agents plan use local/my-action (no project specified)
Observe: Plan is created successfully with empty project_links list
Expected: Error "At least one project is required"

Fix suggestion — add a validation check after merging projects (line ~1511):

all_projects: list[str] = list(projects or []) + list(project or [])
if not all_projects:
    console.print("[red]Error:[/red] At least one project is required.")
    raise typer.Abort()

Subtasks

Add post-merge validation in use_action() (plan.py ~line 1511) that raises an error when all_projects is empty
Update CLI help text / docstring to reflect that at least one project is required
Tests (Behave): Add scenario — agents plan use <ACTION> with no project argument returns an error
Tests (Behave): Add scenario — agents plan use <ACTION> <PROJECT> succeeds as before (regression)
Tests (Robot): Add integration test verifying the validation error is surfaced correctly
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/plan-use-require-project-argument` - **Commit Message**: `fix(cli): require at least one project argument in agents plan use command` - **Milestone**: None (backlog) - **Parent Epic**: #397 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background Code-level analysis of `src/cleveragents/cli/commands/plan.py` against `docs/specification.md` §"agents plan use" revealed a validation gap: the `agents plan use` command allows creating a plan with no projects bound to it, but the spec requires at least one `<PROJECT>` argument. **Spec synopsis (§"agents plan use")**: ``` agents plan use [options] <ACTION> <PROJECT>... ``` The spec defines `<PROJECT>` as a required positional argument (one or more). The spec description states: "Apply an action to one or more projects and start the Strategize phase." A plan without a project has no context to work in. **Actual implementation** (`src/cleveragents/cli/commands/plan.py`, lines 1398–1411): Both the positional `projects` argument and the `--project/-p` option are optional: ```python projects: Annotated[ list[str] | None, typer.Argument(help="Projects to apply the action on (one or more)"), ] = None, project: Annotated[ list[str] | None, typer.Option("--project", "-p", ...), ] = None, ``` Running `agents plan use local/my-action` (no project) succeeds and creates a plan with an empty `project_links` list. This plan cannot be executed meaningfully since there are no project resources to work with. **Steps to reproduce**: 1. Create an action: `agents action create --config my-action.yaml` 2. Run: `agents plan use local/my-action` (no project specified) 3. Observe: Plan is created successfully with empty `project_links` list 4. Expected: Error "At least one project is required" **Fix suggestion** — add a validation check after merging projects (line ~1511): ```python all_projects: list[str] = list(projects or []) + list(project or []) if not all_projects: console.print("[red]Error:[/red] At least one project is required.") raise typer.Abort() ``` ## Subtasks - [ ] Add post-merge validation in `use_action()` (`plan.py` ~line 1511) that raises an error when `all_projects` is empty - [ ] Update CLI help text / docstring to reflect that at least one project is required - [ ] Tests (Behave): Add scenario — `agents plan use <ACTION>` with no project argument returns an error - [ ] Tests (Behave): Add scenario — `agents plan use <ACTION> <PROJECT>` succeeds as before (regression) - [ ] Tests (Robot): Add integration test verifying the validation error is surfaced correctly - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 18:50:57 +00:00

#397 Epic: Server & Autonomy Infrastructure

freemo added this to the v3.7.0 milestone

2026-04-05 20:07:06 +00:00

freemo commented

2026-04-05 20:07:23 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — agents plan use allows creating a plan with no projects, but the spec requires at least one <PROJECT> argument. A plan without a project has no context to work in and cannot be executed meaningfully.
Milestone: v3.7.0
Story Points: 1 — XS — Add a simple validation check after merging the projects list. Clear fix path provided in the issue.
MoSCoW: Should Have — Input validation is important for correct CLI behavior. The spec is explicit that <PROJECT> is required. Creating plans without projects leads to confusing downstream failures.
Parent Epic: #397 (dependency link already exists)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — `agents plan use` allows creating a plan with no projects, but the spec requires at least one `<PROJECT>` argument. A plan without a project has no context to work in and cannot be executed meaningfully. - **Milestone**: v3.7.0 - **Story Points**: 1 — XS — Add a simple validation check after merging the projects list. Clear fix path provided in the issue. - **MoSCoW**: Should Have — Input validation is important for correct CLI behavior. The spec is explicit that `<PROJECT>` is required. Creating plans without projects leads to confusing downstream failures. - **Parent Epic**: #397 (dependency link already exists) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

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

[Automated] CleverAgents Build Session - 2026-04-05 #3572