cleveragents/cleveragents-core

Fork 3

UAT: `agents actor update` is an undocumented separate command; spec only defines `agents actor add --update` #3617

New issue

Closed

opened 2026-04-05 20:40:23 +00:00 by freemo · 2 comments

freemo commented

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

Owner

Background

During UAT testing of the CleverAgents CLI, a deviation was discovered between the implemented CLI surface area and the authoritative specification (docs/specification.md).

The specification (lines 279 and 4939–4947) defines actor updates exclusively via the --update flag on agents actor add:

agents actor add --config|-c <FILE> [--update]

The spec explicitly states: "Add a new actor configuration, or replace an existing one with --update."

There is no agents actor update command defined anywhere in the specification.

Expected Behavior (per spec)

agents actor add --config ./actors/my-actor.yaml — adds a new actor
agents actor add --config ./actors/my-actor.yaml --update — replaces an existing actor
No separate agents actor update subcommand exists

Actual Behavior

The implementation in src/cleveragents/cli/commands/actor.py contains a separate agents actor update command (lines 600–720) that accepts <NAME> as a positional argument and --config as an optional option. This command is not defined in the specification.

The agents actor add command also has an --update flag (line 502–503), meaning the update functionality is duplicated across two commands.

Impact

The CLI surface area deviates from docs/specification.md, which is the authoritative source of truth per CONTRIBUTING.md.
Users following the spec documentation will not find agents actor update as a documented command, causing confusion.
The duplication creates unnecessary maintenance burden and risks divergence in behaviour between the two update paths.

Code Location

src/cleveragents/cli/commands/actor.py, update function (lines 600–720)

Metadata

Branch: fix/remove-undocumented-actor-update-command
Commit Message: fix(cli): remove undocumented agents actor update command; update handled by agents actor add --update per spec
Milestone: (none — backlog)
Parent Epic: #392

Subtasks

Audit src/cleveragents/cli/commands/actor.py to confirm the update subcommand (lines 600–720) is not referenced by any other module or integration test
Remove the agents actor update subcommand from actor.py
Verify agents actor add --update correctly handles the update path end-to-end
Update or add Behave unit tests in features/ to cover agents actor add --update behaviour
Update or add Robot Framework integration tests in robot/ to confirm agents actor update no longer exists in the CLI surface
Update any internal documentation or help strings that reference agents actor update
Run nox to confirm all quality gates pass

Definition of Done

The agents actor update subcommand is removed from the CLI
agents actor add --update is the sole mechanism for updating an existing actor, matching the spec exactly
No references to agents actor update remain in source, tests, or documentation
All Behave unit tests pass (nox -e unit_tests)
All Robot Framework integration tests pass (nox -e integration_tests)
All nox stages pass
Coverage >= 97%

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

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

## Background During UAT testing of the CleverAgents CLI, a deviation was discovered between the implemented CLI surface area and the authoritative specification (`docs/specification.md`). The specification (lines 279 and 4939–4947) defines actor updates exclusively via the `--update` flag on `agents actor add`: ``` agents actor add --config|-c <FILE> [--update] ``` The spec explicitly states: *"Add a new actor configuration, or replace an existing one with `--update`."* There is **no** `agents actor update` command defined anywhere in the specification. ## Expected Behavior (per spec) - `agents actor add --config ./actors/my-actor.yaml` — adds a new actor - `agents actor add --config ./actors/my-actor.yaml --update` — replaces an existing actor - No separate `agents actor update` subcommand exists ## Actual Behavior The implementation in `src/cleveragents/cli/commands/actor.py` contains a separate `agents actor update` command (lines 600–720) that accepts `<NAME>` as a positional argument and `--config` as an optional option. This command is **not** defined in the specification. The `agents actor add` command also has an `--update` flag (line 502–503), meaning the update functionality is duplicated across two commands. ## Impact - The CLI surface area deviates from `docs/specification.md`, which is the authoritative source of truth per CONTRIBUTING.md. - Users following the spec documentation will not find `agents actor update` as a documented command, causing confusion. - The duplication creates unnecessary maintenance burden and risks divergence in behaviour between the two update paths. ## Code Location `src/cleveragents/cli/commands/actor.py`, `update` function (lines 600–720) --- ## Metadata - **Branch**: `fix/remove-undocumented-actor-update-command` - **Commit Message**: `fix(cli): remove undocumented agents actor update command; update handled by agents actor add --update per spec` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 ## Subtasks - [ ] Audit `src/cleveragents/cli/commands/actor.py` to confirm the `update` subcommand (lines 600–720) is not referenced by any other module or integration test - [ ] Remove the `agents actor update` subcommand from `actor.py` - [ ] Verify `agents actor add --update` correctly handles the update path end-to-end - [ ] Update or add Behave unit tests in `features/` to cover `agents actor add --update` behaviour - [ ] Update or add Robot Framework integration tests in `robot/` to confirm `agents actor update` no longer exists in the CLI surface - [ ] Update any internal documentation or help strings that reference `agents actor update` - [ ] Run `nox` to confirm all quality gates pass ## Definition of Done - [ ] The `agents actor update` subcommand is removed from the CLI - [ ] `agents actor add --update` is the sole mechanism for updating an existing actor, matching the spec exactly - [ ] No references to `agents actor update` remain in source, tests, or documentation - [ ] All Behave unit tests pass (`nox -e unit_tests`) - [ ] All Robot Framework integration tests pass (`nox -e integration_tests`) - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 20:40:35 +00:00

#392 Epic: Actor YAML & Compiler

freemo commented

2026-04-05 20:42:00 +00:00

Author

Owner

Closing as duplicate of #3602. Both issues report the same problem: agents actor update exists as an undocumented separate command while the spec only defines agents actor add --update.

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

Closing as duplicate of #3602. Both issues report the same problem: `agents actor update` exists as an undocumented separate command while the spec only defines `agents actor add --update`. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo closed this issue

2026-04-05 20:42:01 +00:00

freemo referenced this issue

2026-04-05 20:42:47 +00:00

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

freemo referenced this issue

2026-04-05 20:43:01 +00:00

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

freemo commented

2026-04-05 20:45:18 +00:00

Author

Owner

State label reconciliation:

Previous state: State/Unverified
Corrected to: State/Completed
Reason: Issue is closed but had non-terminal state label. Corrected to State/Completed per CONTRIBUTING.md requirements.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

State label reconciliation: - Previous state: `State/Unverified` - Corrected to: `State/Completed` - Reason: Issue is closed but had non-terminal state label. Corrected to `State/Completed` per CONTRIBUTING.md requirements. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo referenced this issue

2026-04-05 20:45:33 +00:00

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

freemo referenced this issue

2026-04-05 20:51:04 +00:00

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