cleveragents/cleveragents-core

Fork 3

UAT: `agents actor add` requires undocumented positional NAME argument — spec defines config-as-sole-source-of-truth pattern #4965

New issue

Open

opened 2026-04-08 23:40:52 +00:00 by freemo · 1 comment

freemo commented

2026-04-08 23:40:52 +00:00

Owner

Bug Report

Summary

The agents actor add command requires a mandatory positional NAME argument that is not present in the specification. The spec defines agents actor add --config|-c <FILE> [--update] where the YAML config file is the sole source of truth for the actor name. The implementation adds an extra required positional NAME argument that overrides the name in the YAML file.

Expected Behavior (from spec)

The specification (Command Synopsis, line 279) defines:

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

The spec also states (line 30981):

Config-as-complete-definition pattern: For entity registration commands (actor add, skill add, tool add, validation add, resource type add, action create, automation-profile add), the YAML configuration file is the sole source of truth — the --config file fully defines the entity.

All spec examples use:

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

No positional NAME argument appears in any spec example.

Actual Behavior

The implementation requires a positional NAME argument:

# src/cleveragents/cli/commands/actor.py, line ~300
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", ...)],
    ...

This means users must run:

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

Instead of the spec-defined:

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

The positional NAME also overrides the name field in the YAML config, which violates the config-as-sole-source-of-truth principle.

Code Location

File: src/cleveragents/cli/commands/actor.py

The add() function signature (around line 300) has name as a required positional typer.Argument. The docstring even acknowledges this deviation:

"The positional NAME takes precedence over any name field in the config file."

Impact

Users following the spec documentation will get Error: Missing argument 'NAME' when running agents actor add --config ./actor.yaml
Scripts and automation tools written against the spec will fail
Inconsistent with skill add, tool add, and other entity registration commands that follow the config-as-sole-source-of-truth pattern
The actor name in the YAML file is silently ignored/overridden by the CLI positional argument

Steps to Reproduce

Create an actor YAML with name: local/my-actor
Run: agents actor add --config ./my-actor.yaml
Observe: Error: Missing argument 'NAME'.
Expected: Actor registered using name from YAML file

Suggested Fix

Remove the positional NAME argument from actor add and derive the actor name from the YAML config file's name field, consistent with the spec's config-as-sole-source-of-truth pattern:

@app.command()
def add(
    config: Annotated[Path, typer.Option("--config", "-c", help="Path to JSON/YAML actor config")],
    unsafe: Annotated[bool, typer.Option("--unsafe")] = False,
    update_existing: Annotated[bool, typer.Option("--update")] = False,
    ...
) -> None:
    """Add a new actor configuration from a YAML/JSON file."""
    # Name is derived from config file's 'name' field
    loaded = _load_config_text(config)
    name = loaded[1].get("name")  # from YAML
    if not name:
        raise typer.BadParameter("Config file must include a 'name' field.")
    ...

Definition of Done

agents actor add --config <FILE> works without a positional NAME argument
Actor name is read from the name field in the YAML config file
agents actor add --config <FILE> --update updates an existing actor
agents actor add --config <FILE> --unsafe registers an unsafe actor
Error message when config file has no name field
Consistent with skill add, tool add which also use config-as-sole-source-of-truth

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

## Bug Report ### Summary The `agents actor add` command requires a mandatory positional `NAME` argument that is not present in the specification. The spec defines `agents actor add --config|-c <FILE> [--update]` where the YAML config file is the sole source of truth for the actor name. The implementation adds an extra required positional `NAME` argument that overrides the name in the YAML file. ### Expected Behavior (from spec) The specification (Command Synopsis, line 279) defines: ``` agents actor add --config|-c <FILE> [--update] ``` The spec also states (line 30981): > **Config-as-complete-definition pattern**: For entity registration commands (`actor add`, `skill add`, `tool add`, `validation add`, `resource type add`, `action create`, `automation-profile add`), the YAML configuration file is the **sole source of truth** — the `--config` file fully defines the entity. All spec examples use: ```bash $ agents actor add --config ./actors/reviewer.yaml $ agents actor add --config ./actors/reviewer.yaml --update $ agents actor add --config research-pipeline.yaml --unsafe ``` No positional NAME argument appears in any spec example. ### Actual Behavior The implementation requires a positional NAME argument: ```python # src/cleveragents/cli/commands/actor.py, line ~300 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", ...)], ... ``` This means users must run: ```bash $ agents actor add local/my-actor --config ./actors/my-actor.yaml ``` Instead of the spec-defined: ```bash $ agents actor add --config ./actors/my-actor.yaml ``` The positional NAME also **overrides** the `name` field in the YAML config, which violates the config-as-sole-source-of-truth principle. ### Code Location **File:** `src/cleveragents/cli/commands/actor.py` The `add()` function signature (around line 300) has `name` as a required positional `typer.Argument`. The docstring even acknowledges this deviation: > "The positional `NAME` takes precedence over any `name` field in the config file." ### Impact - Users following the spec documentation will get `Error: Missing argument 'NAME'` when running `agents actor add --config ./actor.yaml` - Scripts and automation tools written against the spec will fail - Inconsistent with `skill add`, `tool add`, and other entity registration commands that follow the config-as-sole-source-of-truth pattern - The actor name in the YAML file is silently ignored/overridden by the CLI positional argument ### Steps to Reproduce 1. Create an actor YAML with `name: local/my-actor` 2. Run: `agents actor add --config ./my-actor.yaml` 3. Observe: `Error: Missing argument 'NAME'.` 4. Expected: Actor registered using name from YAML file ### Suggested Fix Remove the positional `NAME` argument from `actor add` and derive the actor name from the YAML config file's `name` field, consistent with the spec's config-as-sole-source-of-truth pattern: ```python @app.command() def add( config: Annotated[Path, typer.Option("--config", "-c", help="Path to JSON/YAML actor config")], unsafe: Annotated[bool, typer.Option("--unsafe")] = False, update_existing: Annotated[bool, typer.Option("--update")] = False, ... ) -> None: """Add a new actor configuration from a YAML/JSON file.""" # Name is derived from config file's 'name' field loaded = _load_config_text(config) name = loaded[1].get("name") # from YAML if not name: raise typer.BadParameter("Config file must include a 'name' field.") ... ``` ### Definition of Done - [ ] `agents actor add --config <FILE>` works without a positional NAME argument - [ ] Actor name is read from the `name` field in the YAML config file - [ ] `agents actor add --config <FILE> --update` updates an existing actor - [ ] `agents actor add --config <FILE> --unsafe` registers an unsafe actor - [ ] Error message when config file has no `name` field - [ ] Consistent with `skill add`, `tool add` which also use config-as-sole-source-of-truth --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

freemo added the

labels

2026-04-08 23:40:55 +00:00

freemo referenced this issue

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

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

freemo added

and removed

labels

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

HAL9000 added the

labels

2026-04-09 00:29:16 +00:00

HAL9000 commented

2026-04-09 00:51:12 +00:00

Owner

Issue triaged by project owner:

State: Verified
Priority: High — The agents actor add command deviates from the spec by requiring an undocumented positional NAME argument; this breaks the config-as-sole-source-of-truth pattern
Milestone: v3.2.0 (actor management is a core feature)
Story Points: 3 — M — Fix requires removing the positional NAME argument and reading the actor name from the YAML config file instead
MoSCoW: Must Have — The spec explicitly defines agents actor add --config|-c <FILE> [--update] with no positional argument; this is a spec compliance bug that breaks the documented workflow

This is a valid spec compliance bug. The implementation added an undocumented required positional argument that contradicts the spec config-as-sole-source-of-truth pattern.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — The `agents actor add` command deviates from the spec by requiring an undocumented positional NAME argument; this breaks the config-as-sole-source-of-truth pattern - **Milestone**: v3.2.0 (actor management is a core feature) - **Story Points**: 3 — M — Fix requires removing the positional NAME argument and reading the actor name from the YAML config file instead - **MoSCoW**: Must Have — The spec explicitly defines `agents actor add --config|-c <FILE> [--update]` with no positional argument; this is a spec compliance bug that breaks the documented workflow This is a valid spec compliance bug. The implementation added an undocumented required positional argument that contradicts the spec config-as-sole-source-of-truth pattern. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed