cleveragents/cleveragents-core

Fork 3

UAT: `agents actor add` CLI signature requires positional NAME argument contrary to spec #5425

New issue

Open

opened 2026-04-09 06:38:46 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 06:38:46 +00:00

Owner

Bug Report

Feature Area

Actor System Compilation — CLI actor add command

What Was Tested

Code-level analysis of src/cleveragents/cli/commands/actor.py against the specification's agents actor add command signature.

Expected Behavior (from spec)

Per docs/specification.md line 4940, the command signature is:

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

The spec explicitly states:

"The actor is fully defined by the YAML configuration file specified with --config. The file must fully define the actor, including the name field which determines the actor's registered name."

No positional NAME argument is mentioned in the spec. The name comes from the YAML file's name field.

Actual Behavior (from code)

src/cleveragents/cli/commands/actor.py lines 508-558 define the add command with a required positional NAME argument:

@app.command()
def add(
    name: Annotated[
        str,
        typer.Argument(
            help="Namespaced actor name (e.g. local/my-actor)",
            metavar="NAME",
        ),
    ],
    config: Annotated[
        Path | None,
        typer.Option("--config", "-c", help="Path to JSON/YAML actor config"),
    ] = None,
    ...

This means users must run:

agents actor add local/my-actor --config ./actors/my-actor.yaml

Instead of the spec-compliant:

agents actor add --config ./actors/reviewer.yaml

Evidence

features/actor_add_name_positional.feature has @skip tags on the scenarios that test the spec-compliant behavior (scenarios 1 and 2 are skipped), confirming this is a known deviation.
Scenario 3 ("actor add without NAME positional argument fails") is active, meaning the current behavior (requiring NAME) is tested and enforced.
The spec examples at lines 4955, 5185 all show agents actor add --config ./actors/reviewer.yaml without a positional NAME.

Impact

Users following the spec documentation will get a "Missing argument 'NAME'" error.
The CLI is not spec-compliant, breaking the documented user experience.
This is a milestone-blocking discrepancy for v3.x actor system acceptance.

Steps to Reproduce

Create an actor YAML file with a name field
Run: agents actor add --config ./my-actor.yaml
Observe: Error — missing required argument NAME

Code Location

src/cleveragents/cli/commands/actor.py lines 508-558 (the add command definition)
features/actor_add_name_positional.feature (skipped spec-alignment tests)

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

## Bug Report ### Feature Area Actor System Compilation — CLI actor add command ### What Was Tested Code-level analysis of `src/cleveragents/cli/commands/actor.py` against the specification's `agents actor add` command signature. ### Expected Behavior (from spec) Per `docs/specification.md` line 4940, the command signature is: ``` agents actor add --config|-c <FILE> [--update] ``` The spec explicitly states: > "The actor is fully defined by the YAML configuration file specified with `--config`. The file must fully define the actor, including the `name` field which determines the actor's registered name." No positional `NAME` argument is mentioned in the spec. The name comes from the YAML file's `name` field. ### Actual Behavior (from code) `src/cleveragents/cli/commands/actor.py` lines 508-558 define the `add` command with a **required positional `NAME` argument**: ```python @app.command() def add( name: Annotated[ str, typer.Argument( help="Namespaced actor name (e.g. local/my-actor)", metavar="NAME", ), ], config: Annotated[ Path | None, typer.Option("--config", "-c", help="Path to JSON/YAML actor config"), ] = None, ... ``` This means users must run: ``` agents actor add local/my-actor --config ./actors/my-actor.yaml ``` Instead of the spec-compliant: ``` agents actor add --config ./actors/reviewer.yaml ``` ### Evidence - `features/actor_add_name_positional.feature` has `@skip` tags on the scenarios that test the spec-compliant behavior (scenarios 1 and 2 are skipped), confirming this is a known deviation. - Scenario 3 ("actor add without NAME positional argument fails") is active, meaning the current behavior (requiring NAME) is tested and enforced. - The spec examples at lines 4955, 5185 all show `agents actor add --config ./actors/reviewer.yaml` without a positional NAME. ### Impact - Users following the spec documentation will get a "Missing argument 'NAME'" error. - The CLI is not spec-compliant, breaking the documented user experience. - This is a milestone-blocking discrepancy for v3.x actor system acceptance. ### Steps to Reproduce 1. Create an actor YAML file with a `name` field 2. Run: `agents actor add --config ./my-actor.yaml` 3. Observe: Error — missing required argument NAME ### Code Location - `src/cleveragents/cli/commands/actor.py` lines 508-558 (the `add` command definition) - `features/actor_add_name_positional.feature` (skipped spec-alignment tests) --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 06:44:20 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 06:49:37 +00:00

HAL9000 commented

2026-04-09 06:50:11 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — agents actor add requires a positional NAME argument contrary to the spec, which defines it as --name NAME (named option). This is a spec compliance gap that breaks scripting and documentation.
Milestone: v3.2.0 — actor CLI is a core v3.2.0 feature
Story Points: 2 — S — requires changing the parameter from positional to named option
MoSCoW: Should Have — the spec defines the interface. Deviating from it breaks users who follow the spec. However, the command works with the positional argument.
Parent Epic: Needs linking to the actor CLI epic

Triage Rationale: CLI interface spec compliance is important for documentation accuracy and scripting. The fix is straightforward (change from positional to named option), but requires careful testing to avoid breaking existing usage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — `agents actor add` requires a positional NAME argument contrary to the spec, which defines it as `--name NAME` (named option). This is a spec compliance gap that breaks scripting and documentation. - **Milestone**: v3.2.0 — actor CLI is a core v3.2.0 feature - **Story Points**: 2 — S — requires changing the parameter from positional to named option - **MoSCoW**: Should Have — the spec defines the interface. Deviating from it breaks users who follow the spec. However, the command works with the positional argument. - **Parent Epic**: Needs linking to the actor CLI epic **Triage Rationale**: CLI interface spec compliance is important for documentation accuracy and scripting. The fix is straightforward (change from positional to named option), but requires careful testing to avoid breaking existing usage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 commented

2026-04-09 06:50:40 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels to bring issue into compliance with CONTRIBUTING.md

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

Label compliance fix applied: - Added missing labels to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 added

and removed

labels

2026-04-09 06:50:53 +00:00

HAL9000 referenced this issue

2026-04-09 06:52:21 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 26) #5296