UAT: agents actor add CLI requires undocumented positional NAME argument — spec says name comes from YAML file #5855

Open
opened 2026-04-09 10:56:33 +00:00 by HAL9000 · 5 comments
Owner

Bug Report

Feature Area: Actor System — agents actor add CLI command
Severity: Critical (blocks milestone acceptance — users cannot use the spec-documented command signature)
Discovered by: UAT Testing (uat-pool-1, worker: actor-system)


What Was Tested

The agents actor add CLI command signature as defined in the specification vs the actual implementation.

Expected Behavior (from spec)

Per docs/specification.md (CLI Command Synopsis section):

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

Purpose (spec): "Add a new actor configuration, or replace an existing one with --update. The actor is fully defined by the YAML configuration file specified with --config. If a local actor with the same name already exists, the command fails unless the --update flag is provided."

Arguments (spec):

  • --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.
  • --update: Replace an existing local actor with the same name.

The spec explicitly states the name comes from the YAML file's name field — there is no positional NAME argument.

Actual Behavior (from implementation)

src/cleveragents/cli/commands/actor.py lines 508–557:

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 implementation requires a mandatory positional <NAME> argument before --config. The docstring even documents this deviation:

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

Furthermore, the positional NAME overrides any name field in the YAML file (line 547: "The positional NAME takes precedence over any name field in the config file"), which directly contradicts the spec.

Code Location

  • src/cleveragents/cli/commands/actor.py, function add(), lines 508–557
  • The positional name argument at line 509–515
  • The override behavior documented at line 547

Steps to Reproduce

# Spec-compliant invocation (should work, currently fails with "Missing argument 'NAME'"):
agents actor add --config ./actors/my-actor.yaml

# Implementation-required invocation (not in spec):
agents actor add local/my-actor --config ./actors/my-actor.yaml

Impact

  • Users following the spec documentation cannot add actors
  • The positional NAME argument allows registering an actor under a different name than declared in the YAML, creating a mismatch between the YAML file and the registry
  • All documentation examples in the spec are broken
  • The registry.add() YAML-first method (which correctly reads name from YAML) is bypassed in favor of registry.upsert_actor() with the CLI-provided name

Fix

Remove the positional name argument from the add() command. Read the actor name from the YAML file's name field (as registry.add() already does). Use registry.add() instead of registry.upsert_actor() to preserve the YAML-first path.


Metadata

Field Value
Commit Message fix(cli): remove positional NAME from agents actor add — read name from YAML file
Branch fix/actor-add-positional-name
Milestone v3.1.0

Subtasks

  • Remove positional name argument from actor.add() CLI command
  • Read actor name from YAML file's name field
  • Route through registry.add() instead of registry.upsert_actor()
  • Update CLI help text and examples
  • Add regression test (Behave feature)

Definition of Done

  • agents actor add --config <FILE> works without positional NAME
  • Actor name is taken from YAML name field
  • agents actor add --config <FILE> --update replaces existing actor
  • All spec examples work as documented
  • Regression test added

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

## Bug Report **Feature Area**: Actor System — `agents actor add` CLI command **Severity**: Critical (blocks milestone acceptance — users cannot use the spec-documented command signature) **Discovered by**: UAT Testing (uat-pool-1, worker: actor-system) --- ## What Was Tested The `agents actor add` CLI command signature as defined in the specification vs the actual implementation. ## Expected Behavior (from spec) Per `docs/specification.md` (CLI Command Synopsis section): ``` agents actor add --config|-c <FILE> [--update] ``` **Purpose** (spec): "Add a new actor configuration, or replace an existing one with `--update`. The actor is fully defined by the YAML configuration file specified with `--config`. If a local actor with the same name already exists, the command fails unless the `--update` flag is provided." **Arguments** (spec): - `--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**. - `--update`: Replace an existing local actor with the same name. The spec explicitly states the name comes from the YAML file's `name` field — there is no positional NAME argument. ## Actual Behavior (from implementation) `src/cleveragents/cli/commands/actor.py` lines 508–557: ```python 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 implementation requires a **mandatory positional `<NAME>` argument** before `--config`. The docstring even documents this deviation: ``` Signature: ``agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default] [--option key=value] [--format FORMAT]`` ``` Furthermore, the positional NAME **overrides** any `name` field in the YAML file (line 547: "The positional `NAME` takes precedence over any `name` field in the config file"), which directly contradicts the spec. ## Code Location - `src/cleveragents/cli/commands/actor.py`, function `add()`, lines 508–557 - The positional `name` argument at line 509–515 - The override behavior documented at line 547 ## Steps to Reproduce ```bash # Spec-compliant invocation (should work, currently fails with "Missing argument 'NAME'"): agents actor add --config ./actors/my-actor.yaml # Implementation-required invocation (not in spec): agents actor add local/my-actor --config ./actors/my-actor.yaml ``` ## Impact - Users following the spec documentation cannot add actors - The positional NAME argument allows registering an actor under a different name than declared in the YAML, creating a mismatch between the YAML file and the registry - All documentation examples in the spec are broken - The `registry.add()` YAML-first method (which correctly reads name from YAML) is bypassed in favor of `registry.upsert_actor()` with the CLI-provided name ## Fix Remove the positional `name` argument from the `add()` command. Read the actor name from the YAML file's `name` field (as `registry.add()` already does). Use `registry.add()` instead of `registry.upsert_actor()` to preserve the YAML-first path. --- ### Metadata | Field | Value | |-------|-------| | Commit Message | `fix(cli): remove positional NAME from agents actor add — read name from YAML file` | | Branch | `fix/actor-add-positional-name` | | Milestone | v3.1.0 | ### Subtasks - [ ] Remove positional `name` argument from `actor.add()` CLI command - [ ] Read actor name from YAML file's `name` field - [ ] Route through `registry.add()` instead of `registry.upsert_actor()` - [ ] Update CLI help text and examples - [ ] Add regression test (Behave feature) ### Definition of Done - `agents actor add --config <FILE>` works without positional NAME - Actor name is taken from YAML `name` field - `agents actor add --config <FILE> --update` replaces existing actor - All spec examples work as documented - Regression test added --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester
HAL9000 added this to the v3.1.0 milestone 2026-04-09 11:03:22 +00:00
Author
Owner

MoSCoW classification: Must Have

Rationale: This is a Priority/Critical bug — agents actor add requires an undocumented positional NAME argument that contradicts the spec. CLI commands must match the specification exactly. A CLI that doesn't match the spec is a blocker for user acceptance testing and milestone sign-off. The spec defines the exact CLI interface, and deviations are Must Have fixes.


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

MoSCoW classification: **Must Have** Rationale: This is a `Priority/Critical` bug — `agents actor add` requires an undocumented positional NAME argument that contradicts the spec. CLI commands must match the specification exactly. A CLI that doesn't match the spec is a blocker for user acceptance testing and milestone sign-off. The spec defines the exact CLI interface, and deviations are Must Have fixes. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
Author
Owner

Label compliance fix applied:

  • Added missing labels and/or milestone 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 and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Author
Owner
PR #8640 has been opened for this issue: https://git.cleverthis.com/cleveragents/cleveragents-core/pull/8640
Author
Owner

Implementation Attempt — Tier 1: haiku — Success

Summary

Successfully implemented the fix for issue #5855. The agents actor add CLI command no longer requires a positional NAME argument.

Changes Made

  1. Removed positional name argument from the add() command in src/cleveragents/cli/commands/actor.py
  2. Actor name now read from YAML file — extracted from the name field in the configuration file
  3. Routed through registry.add() instead of registry.upsert_actor() for YAML-first persistence
  4. Updated CLI help text and examples to match the specification
  5. Added regression test — Created Behave feature actor_add_no_positional_name.feature with step definitions
  6. Updated CHANGELOG.md with fix details

Command Signature Change

  • Before: agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default]
  • After: agents actor add --config <FILE> [--update] [--unsafe] [--set-default]

PR Created

Implementation Details

  • The actor name is now extracted from the YAML/JSON config file's name field
  • If the name is not namespaced (no /), it's automatically prefixed with local/
  • The --set-default flag is applied after the actor is added via registry.set_default_actor()
  • Option overrides and unsafe flags are properly handled
  • Validation ensures the YAML file includes required name, provider, and model fields

Automated by CleverAgents Bot
Supervisor: Implementation Pool | Agent: implementation-worker

**Implementation Attempt** — Tier 1: haiku — Success ## Summary Successfully implemented the fix for issue #5855. The `agents actor add` CLI command no longer requires a positional NAME argument. ## Changes Made 1. **Removed positional `name` argument** from the `add()` command in `src/cleveragents/cli/commands/actor.py` 2. **Actor name now read from YAML file** — extracted from the `name` field in the configuration file 3. **Routed through `registry.add()`** instead of `registry.upsert_actor()` for YAML-first persistence 4. **Updated CLI help text and examples** to match the specification 5. **Added regression test** — Created Behave feature `actor_add_no_positional_name.feature` with step definitions 6. **Updated CHANGELOG.md** with fix details ## Command Signature Change - **Before:** `agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default]` - **After:** `agents actor add --config <FILE> [--update] [--unsafe] [--set-default]` ## PR Created - **PR #8640:** [fix(cli): remove positional NAME from agents actor add — read name from YAML file](https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/8640) - Linked to issue via closing keyword `Closes #5855` - Milestone: v3.1.0 - Type: Bug ## Implementation Details - The actor name is now extracted from the YAML/JSON config file's `name` field - If the name is not namespaced (no `/`), it's automatically prefixed with `local/` - The `--set-default` flag is applied after the actor is added via `registry.set_default_actor()` - Option overrides and unsafe flags are properly handled - Validation ensures the YAML file includes required `name`, `provider`, and `model` fields --- **Automated by CleverAgents Bot** Supervisor: Implementation Pool | Agent: implementation-worker
HAL9000 modified the milestone from v3.1.0 to v3.2.0 2026-04-13 23:35:32 +00:00
Author
Owner

[GROOMED]

  • Updated milestone from closed v3.1.0 to v3.2.0 per grooming rules for actor system bugs.
  • Verified required labels (State/ In Review, Type/ Bug, Priority/ Critical) are present; no label manager action needed.
  • Reassigned linked PR #8640 to milestone v3.2.0 to keep it aligned.

No other gaps found in title or description—they already meet the template requirements.

Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor

[GROOMED] - Updated milestone from closed **v3.1.0** to **v3.2.0** per grooming rules for actor system bugs. - Verified required labels (State/ In Review, Type/ Bug, Priority/ Critical) are present; no label manager action needed. - Reassigned linked PR #8640 to milestone v3.2.0 to keep it aligned. No other gaps found in title or description—they already meet the template requirements. --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#5855
No description provided.