cleveragents/cleveragents-core

Fork 3

UAT: `agents actor add` requires undocumented positional NAME argument not in spec #3756

New issue

Open

opened 2026-04-05 22:30:34 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 22:30:34 +00:00

Owner

Metadata

Branch: fix/actor-add-remove-positional-name-arg
Commit Message: fix(cli): remove undocumented positional NAME arg from agents actor add command
Milestone: (none — backlog)
Parent Epic: #392

Background

During UAT testing of src/cleveragents/cli/commands/actor.py, the agents actor add command signature differs from the specification. The implementation requires an extra positional NAME argument that is not shown in the spec.

Expected Behavior (from spec)

Per docs/specification.md CLI Command Synopsis:

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

The spec shows that agents actor add takes only --config|-c <FILE> and optionally --update. The actor name is expected to come from the config file itself.

Actual Behavior (from code)

In src/cleveragents/cli/commands/actor.py, the add command is defined as:

def add(
    name: Annotated[str, typer.Argument(help="Namespaced actor name (e.g. local/my-actor)")],
    config: Annotated[Path | None, typer.Option("--config", "-c", ...)],
    ...

The command requires a positional NAME argument as the first argument. The actual CLI signature is:

agents actor add <NAME> --config <FILE> [--update]

This means users must specify the name twice (once on the command line and once in the config file), which is inconsistent with the spec and with how agents tool add and agents skill add work (both use config-only, no positional name).

Code Location

src/cleveragents/cli/commands/actor.py — add function

Steps to Reproduce

Run agents actor add --help
Observe that NAME is listed as a required positional argument
Compare with agents tool add --help — no positional NAME argument

Comparison with Other Commands

agents tool add --config <FILE> [--update] — no positional NAME ✅ (matches spec)
agents skill add --config <FILE> [--update] — no positional NAME ✅ (matches spec)
agents actor add <NAME> --config <FILE> [--update] — has positional NAME ❌ (does NOT match spec)

Impact

Users must specify the actor name twice (in the command and in the config file)
The positional NAME overrides any name field in the config file, creating confusion
Inconsistent UX compared to tool add and skill add
Scripts and documentation written per the spec will fail

Subtasks

Remove the positional name argument from actor add command
Extract the actor name from the config file's name field
Raise a clear error if the config file has no name field
Update docstring and help text
Add/update unit tests (Behave) to match new signature
Verify agents actor add --help matches spec

Definition of Done

agents actor add --help shows only --config/-c <FILE> and [--update] as required/optional args
Actor name is derived from the config file
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%

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

## Metadata - **Branch**: `fix/actor-add-remove-positional-name-arg` - **Commit Message**: `fix(cli): remove undocumented positional NAME arg from agents actor add command` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 ## Background During UAT testing of `src/cleveragents/cli/commands/actor.py`, the `agents actor add` command signature differs from the specification. The implementation requires an extra positional `NAME` argument that is not shown in the spec. ## Expected Behavior (from spec) Per `docs/specification.md` CLI Command Synopsis: ``` agents actor add --config|-c <FILE> [--update] ``` The spec shows that `agents actor add` takes only `--config|-c <FILE>` and optionally `--update`. The actor name is expected to come from the config file itself. ## Actual Behavior (from code) In `src/cleveragents/cli/commands/actor.py`, the `add` command is defined as: ```python def add( name: Annotated[str, typer.Argument(help="Namespaced actor name (e.g. local/my-actor)")], config: Annotated[Path | None, typer.Option("--config", "-c", ...)], ... ``` The command requires a positional `NAME` argument as the first argument. The actual CLI signature is: ``` agents actor add <NAME> --config <FILE> [--update] ``` This means users must specify the name twice (once on the command line and once in the config file), which is inconsistent with the spec and with how `agents tool add` and `agents skill add` work (both use config-only, no positional name). ## Code Location `src/cleveragents/cli/commands/actor.py` — `add` function ## Steps to Reproduce 1. Run `agents actor add --help` 2. Observe that `NAME` is listed as a required positional argument 3. Compare with `agents tool add --help` — no positional NAME argument ## Comparison with Other Commands - `agents tool add --config <FILE> [--update]` — no positional NAME ✅ (matches spec) - `agents skill add --config <FILE> [--update]` — no positional NAME ✅ (matches spec) - `agents actor add <NAME> --config <FILE> [--update]` — has positional NAME ❌ (does NOT match spec) ## Impact - Users must specify the actor name twice (in the command and in the config file) - The positional NAME overrides any `name` field in the config file, creating confusion - Inconsistent UX compared to `tool add` and `skill add` - Scripts and documentation written per the spec will fail ## Subtasks - [ ] Remove the positional `name` argument from `actor add` command - [ ] Extract the actor name from the config file's `name` field - [ ] Raise a clear error if the config file has no `name` field - [ ] Update docstring and help text - [ ] Add/update unit tests (Behave) to match new signature - [ ] Verify `agents actor add --help` matches spec ## Definition of Done - [ ] `agents actor add --help` shows only `--config/-c <FILE>` and `[--update]` as required/optional args - [ ] Actor name is derived from the config file - [ ] 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% > **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 22:30:56 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-05 22:33:37 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:34:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo referenced this issue

2026-04-05 22:35:43 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654

freemo commented

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

Author

Owner

Duplicate Report — Additional Context from UAT

A second UAT report was submitted for this same bug. Rather than creating a duplicate issue, the additional context from that report is captured here.

Supplementary Details

Spec Reference (explicit): docs/specification.md line 4940 defines the command signature as:

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

Line 4947 states: "The file must fully define the actor, including the name field which determines the actor's registered name."

Exact code location: src/cleveragents/cli/commands/actor.py, add() function, lines ~400–500.

Steps to Reproduce (from second report):

Create a valid actor YAML file with a name field
Run: agents actor add --config ./my-actor.yaml
Observe: Error "Missing argument 'NAME'"

Impact (from second report):

Users following the spec will get a "Missing argument 'NAME'" error
The spec's example agents actor add --config ./actors/reviewer.yaml fails with the current implementation
Breaks spec compliance for the primary actor registration workflow

This issue already has the correct labels, parent Epic (#392), and backlog routing. No new issue was created.

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

## Duplicate Report — Additional Context from UAT A second UAT report was submitted for this same bug. Rather than creating a duplicate issue, the additional context from that report is captured here. ### Supplementary Details **Spec Reference (explicit):** `docs/specification.md` line 4940 defines the command signature as: ``` agents actor add --config|-c <FILE> [--update] ``` Line 4947 states: *"The file must fully define the actor, including the `name` field which determines the actor's registered name."* **Exact code location:** `src/cleveragents/cli/commands/actor.py`, `add()` function, lines ~400–500. **Steps to Reproduce (from second report):** 1. Create a valid actor YAML file with a `name` field 2. Run: `agents actor add --config ./my-actor.yaml` 3. Observe: Error `"Missing argument 'NAME'"` **Impact (from second report):** - Users following the spec will get a `"Missing argument 'NAME'"` error - The spec's example `agents actor add --config ./actors/reviewer.yaml` fails with the current implementation - Breaks spec compliance for the primary actor registration workflow This issue already has the correct labels, parent Epic (#392), and backlog routing. No new issue was created. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-06 06:44:13 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775