cleveragents/cleveragents-core

Fork 3

[BUG] `agents actor add` requires undocumented positional NAME argument — spec says only `--config|-c FILE [--update]` #9311

New issue

Open

opened 2026-04-14 14:38:47 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-14 14:38:47 +00:00

Owner

Metadata

Commit Message: fix(cli): remove positional NAME argument from actor add command to match spec
Branch: fix/actor-add-remove-positional-name-arg

Background and Context

The specification defines agents actor add with the following signature:

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

The spec explicitly states (§ agents actor add): "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." The name field in the YAML config file determines the actor's registered name.

However, the current implementation in src/cleveragents/cli/commands/actor.py requires a positional NAME argument in addition to --config:

@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/reviewer.yaml instead of the spec-compliant agents actor add --config ./actors/reviewer.yaml.

Current Behavior

Running agents actor add --config ./actors/reviewer.yaml fails because the positional NAME argument is required. The actual command signature is:

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

Expected Behavior

Per the specification, the command should accept only:

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

The actor name should be read from the name field inside the YAML config file, not from a positional CLI argument.

Acceptance Criteria

agents actor add --config ./actors/reviewer.yaml works without a positional NAME argument
The actor name is read from the name field in the YAML config file
agents actor add --config ./actors/reviewer.yaml --update works for updating existing actors
All existing BDD tests for actor add pass
The command help text matches the spec signature

Supporting Information

Spec reference: docs/specification.md line 279 and §4938 (agents actor add)
Implementation: src/cleveragents/cli/commands/actor.py lines 507–655
The spec states: "The file must fully define the actor, including the name field which determines the actor's registered name."
Related BDD feature files: features/actor_cli_yaml.feature, features/actor_cli_coverage.feature
Note: Several BDD scenarios in features/actor_cli_coverage.feature are tagged @tdd_issue @tdd_issue_4232 @tdd_expected_fail which suggests this deviation was previously known

Subtasks

Remove the positional NAME argument from actor add command in src/cleveragents/cli/commands/actor.py
Update actor add to read the actor name from the YAML config file's name field
Update the --update flag logic to use the name from config
Update all BDD step definitions in features/steps/actor_cli_yaml_steps.py and features/steps/actor_cli_coverage_steps.py that pass a positional name
Update BDD feature files to use the spec-compliant command signature
Remove @tdd_expected_fail tags from scenarios that were blocked by this bug
Run nox -s unit_tests and verify all actor add tests pass
Verify coverage remains above threshold

Definition of Done

This issue is complete when:

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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(cli): remove positional NAME argument from actor add command to match spec` - **Branch**: `fix/actor-add-remove-positional-name-arg` ## Background and Context The specification defines `agents actor add` with the following signature: ``` agents actor add --config|-c <FILE> [--update] ``` The spec explicitly states (§ agents actor add): "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." The `name` field in the YAML config file determines the actor's registered name. However, the current implementation in `src/cleveragents/cli/commands/actor.py` requires a positional `NAME` argument in addition to `--config`: ```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/reviewer.yaml` instead of the spec-compliant `agents actor add --config ./actors/reviewer.yaml`. ## Current Behavior Running `agents actor add --config ./actors/reviewer.yaml` fails because the positional `NAME` argument is required. The actual command signature is: ``` agents actor add NAME --config FILE [--update] ``` ## Expected Behavior Per the specification, the command should accept only: ``` agents actor add --config|-c FILE [--update] ``` The actor name should be read from the `name` field inside the YAML config file, not from a positional CLI argument. ## Acceptance Criteria - [ ] `agents actor add --config ./actors/reviewer.yaml` works without a positional NAME argument - [ ] The actor name is read from the `name` field in the YAML config file - [ ] `agents actor add --config ./actors/reviewer.yaml --update` works for updating existing actors - [ ] All existing BDD tests for `actor add` pass - [ ] The command help text matches the spec signature ## Supporting Information - Spec reference: `docs/specification.md` line 279 and §4938 (`agents actor add`) - Implementation: `src/cleveragents/cli/commands/actor.py` lines 507–655 - The spec states: "The file must fully define the actor, including the `name` field which determines the actor's registered name." - Related BDD feature files: `features/actor_cli_yaml.feature`, `features/actor_cli_coverage.feature` - Note: Several BDD scenarios in `features/actor_cli_coverage.feature` are tagged `@tdd_issue @tdd_issue_4232 @tdd_expected_fail` which suggests this deviation was previously known ## Subtasks - [ ] Remove the positional `NAME` argument from `actor add` command in `src/cleveragents/cli/commands/actor.py` - [ ] Update `actor add` to read the actor name from the YAML config file's `name` field - [ ] Update the `--update` flag logic to use the name from config - [ ] Update all BDD step definitions in `features/steps/actor_cli_yaml_steps.py` and `features/steps/actor_cli_coverage_steps.py` that pass a positional name - [ ] Update BDD feature files to use the spec-compliant command signature - [ ] Remove `@tdd_expected_fail` tags from scenarios that were blocked by this bug - [ ] Run `nox -s unit_tests` and verify all actor add tests pass - [ ] Verify coverage remains above threshold ## Definition of Done This issue is complete when: - 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

HAL9000 added the

labels

2026-04-14 14:45:11 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-14 14:45:11 +00:00

HAL9000 commented

2026-04-14 14:45:11 +00:00

Author

Owner

✅ Triage: Verified [AUTO-OWNR-1]

Valid bug: agents actor add requires a positional NAME argument that is not in the specification. The spec defines the signature as agents actor add --config|-c FILE [--update] — the actor name should be read from the YAML config file's name field, not from a positional CLI argument. This is a significant spec compliance issue that breaks the expected workflow.

Assigning to v3.2.0 as actor management is a core M3 feature. Priority High — the command signature deviates significantly from the spec, breaking the expected user workflow.

MoSCoW: Must Have — the correct CLI signature is required for spec compliance. Users following the spec documentation will be unable to use the command as documented.

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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `agents actor add` requires a positional `NAME` argument that is not in the specification. The spec defines the signature as `agents actor add --config|-c FILE [--update]` — the actor name should be read from the YAML config file's `name` field, not from a positional CLI argument. This is a significant spec compliance issue that breaks the expected workflow. Assigning to **v3.2.0** as actor management is a core M3 feature. Priority **High** — the command signature deviates significantly from the spec, breaking the expected user workflow. MoSCoW: **Must Have** — the correct CLI signature is required for spec compliance. Users following the spec documentation will be unable to use the command as documented. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-14 15:01:39 +00:00

[AUTO-UAT-POOL] Status: UAT Test Pool Supervisor (Cycle 6) #9331