cleveragents/cleveragents-core

Fork 3

UAT: `agents actor add` requires a positional NAME argument — spec says name is derived from the config file #4751

New issue

Open

opened 2026-04-08 18:53:02 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 18:53:02 +00:00

Owner

Bug Report

Feature Area: Actor add command / actor YAML schema
Severity: Medium
Found by: UAT tester instance uat-worker-actor-yaml
Spec reference: docs/specification.md §agents actor add (line 4938–5109)

What Was Tested

Code-level analysis of src/cleveragents/cli/commands/actor.py — the add command implementation — compared against the spec's command signature.

Expected Behavior (from spec)

The spec (line 4940) defines the actor add command signature as:

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

The spec (line 4947) explicitly states:

--config/-c FILE: Actor config file (required). The file must fully define the actor, including the name field which determines the actor's registered name.

The spec examples (lines 4955, 5115, 5185) all use:

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

No positional NAME argument appears in any spec example. The spec also states (line 30981):

For entity registration commands (actor add, skill add, tool add, ...), the YAML configuration file is the sole source of truth — the --config file fully defines the entity.

Actual Behavior

The implementation in src/cleveragents/cli/commands/actor.py (line 508–558) requires a mandatory 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,
    ...

The docstring (line 551) even documents this non-spec behavior:

Signature:
``agents actor add <NAME> --config <FILE> [--update] [--unsafe]
[--set-default] [--option key=value] [--format FORMAT]``

This means users must run:

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

instead of the spec-defined:

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

The positional NAME also overrides the name field in the YAML config file (line 573–578), violating the spec's "config file is sole source of truth" principle.

Code Location

Affected file: src/cleveragents/cli/commands/actor.py lines 508–558
Spec reference: docs/specification.md lines 4938–4948, 30981

Impact

Users must provide the actor name twice (once in the YAML, once on the CLI)
The CLI name overrides the YAML name, creating a confusing dual-source-of-truth situation
Scripts and automation that follow the spec signature will fail with "Missing argument 'NAME'"
The actor add command is inconsistent with skill add and tool add which follow the spec pattern

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

## Bug Report **Feature Area:** Actor add command / actor YAML schema **Severity:** Medium **Found by:** UAT tester instance `uat-worker-actor-yaml` **Spec reference:** docs/specification.md §agents actor add (line 4938–5109) --- ### What Was Tested Code-level analysis of `src/cleveragents/cli/commands/actor.py` — the `add` command implementation — compared against the spec's command signature. ### Expected Behavior (from spec) The spec (line 4940) defines the `actor add` command signature as: ``` agents actor add --config|-c <FILE> [--update] ``` The spec (line 4947) explicitly states: > `--config/-c FILE`: Actor config file (required). The file must **fully define the actor**, including the `name` field which determines the actor's registered name. The spec examples (lines 4955, 5115, 5185) all use: ``` $ agents actor add --config ./actors/reviewer.yaml $ agents actor add --config ./actors/reviewer.yaml --update ``` No positional NAME argument appears in any spec example. The spec also states (line 30981): > For entity registration commands (`actor add`, `skill add`, `tool add`, ...), the YAML configuration file is the **sole source of truth** — the `--config` file fully defines the entity. ### Actual Behavior The implementation in `src/cleveragents/cli/commands/actor.py` (line 508–558) requires a **mandatory 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, ... ``` The docstring (line 551) even documents this non-spec behavior: ``` Signature: ``agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default] [--option key=value] [--format FORMAT]`` ``` This means users must run: ``` agents actor add local/my-actor --config ./actors/reviewer.yaml ``` instead of the spec-defined: ``` agents actor add --config ./actors/reviewer.yaml ``` The positional NAME also **overrides** the `name` field in the YAML config file (line 573–578), violating the spec's "config file is sole source of truth" principle. ### Code Location - **Affected file:** `src/cleveragents/cli/commands/actor.py` lines 508–558 - **Spec reference:** docs/specification.md lines 4938–4948, 30981 ### Impact - Users must provide the actor name twice (once in the YAML, once on the CLI) - The CLI name overrides the YAML name, creating a confusing dual-source-of-truth situation - Scripts and automation that follow the spec signature will fail with "Missing argument 'NAME'" - The `actor add` command is inconsistent with `skill add` and `tool add` which follow the spec pattern --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 18:59:36 +00:00

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

HAL9000 added the

labels

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

HAL9000 commented

2026-04-09 03:05:00 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:05:11 +00:00

HAL9000 added this to the v3.5.0 milestone