cleveragents/cleveragents-core

Fork 3

agents actor add command signature contradicts specification #4186

New issue

Closed

opened 2026-04-06 21:55:21 +00:00 by CoreRasurae · 4 comments

CoreRasurae commented

2026-04-06 21:55:21 +00:00

Member

Metadata

Commit Message: fix(cli): make actor NAME argument optional, derive from YAML config
Branch: bugfix/actor-add-name-arg

Background and Context

The documentation in docs/specification.md and the actual CLI implementation of the agents actor add command are contradictory. This discrepancy creates confusion for users and violates the principle that the specification should be the authoritative source of truth for design and architecture.

Current Behavior

When executing agents actor add --help, the CLI shows:

Usage: agents actor add [OPTIONS] NAME

Add a new actor configuration.

The actor name is provided as a required positional argument. The YAML/JSON
configuration file specified with ``--config`` supplies the actor settings.
The positional ``NAME`` takes precedence over any ``name`` field in the
config file.

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

Arguments:
* name      TEXT  Namespaced actor name (e.g. local/my-actor) [required]

When attempting to use the command without the NAME argument:

$ agents actor add --config actors/fpga-strategist.yaml
Wrapping unexpected exception: MissingParameter: Missing parameter: name
Error [500] INTERNAL: An unexpected error occurred

Expected Behavior

According to docs/specification.md (lines 4938-4948):

The command signature should be:

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

The specification states:

"The file must fully define the actor, including the name field which determines the actor's registered name."
No positional NAME argument is required on the command line
The actor's registered name comes from the name field in the YAML configuration file

Therefore, the command should work as:

$ agents actor add --config ./actors/my-actor.yaml
# Actor name is read from the 'name' field in my-actor.yaml

Acceptance Criteria

The CLI implementation is modified to make the NAME positional argument optional
When NAME is omitted, the actor's name is derived from the name field in the YAML config file
The specification in docs/specification.md is updated to match the actual CLI behavior OR the CLI is updated to match the specification (specify which approach is chosen in comments)
The command works without requiring NAME on the command line
Examples in the specification match the actual working behavior
Help text clearly documents whether NAME is optional or required

Supporting Information

Documentation Reference

Specification location: docs/specification.md, lines 4938-4948
Command reference: docs/specification.md, line 279 (synopsis) and lines 4938-5087 (detailed reference)

Issue Summary

This is a "spec vs. implementation" discrepancy. Per CONTRIBUTING.md:

"Specification-First Development: Treat the project specification as the authoritative source of truth for design and architecture... Code should only be written to reflect what the specification describes — when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly."

Based on this principle, the implementation should be corrected to match the specification.

Subtasks

Decide on resolution: modify CLI to match spec OR update spec to match CLI
If modifying CLI: make NAME argument optional, derive from name field in YAML
If updating spec: document that NAME is required and takes precedence over YAML field
Update all CLI examples in specification to match actual behavior
Update help text and error messages for clarity
Tests: Add Behave scenarios for both cases (with and without NAME argument)
Tests: Verify precedence behavior if NAME is supported
Run nox (all default sessions), fix any errors
Verify test coverage >=97%

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
The specification or implementation is corrected so they are aligned.
All examples throughout the documentation reflect the actual behavior.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly.
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.

## Metadata - **Commit Message**: `fix(cli): make actor NAME argument optional, derive from YAML config` - **Branch**: `bugfix/actor-add-name-arg` ## Background and Context The documentation in `docs/specification.md` and the actual CLI implementation of the `agents actor add` command are contradictory. This discrepancy creates confusion for users and violates the principle that the specification should be the authoritative source of truth for design and architecture. ## Current Behavior When executing `agents actor add --help`, the CLI shows: ``` Usage: agents actor add [OPTIONS] NAME Add a new actor configuration. The actor name is provided as a required positional argument. The YAML/JSON configuration file specified with ``--config`` supplies the actor settings. The positional ``NAME`` takes precedence over any ``name`` field in the config file. Signature: ``agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default] [--option key=value] [--format FORMAT]`` Arguments: * name TEXT Namespaced actor name (e.g. local/my-actor) [required] ``` When attempting to use the command without the NAME argument: ```bash $ agents actor add --config actors/fpga-strategist.yaml Wrapping unexpected exception: MissingParameter: Missing parameter: name Error [500] INTERNAL: An unexpected error occurred ``` ## Expected Behavior According to `docs/specification.md` (lines 4938-4948): The command signature should be: ``` agents actor add --config|-c <FILE> [--update] ``` The specification states: - "The file must fully define the actor, including the `name` field which determines the actor's registered name." - No positional NAME argument is required on the command line - The actor's registered name comes from the `name` field in the YAML configuration file Therefore, the command should work as: ```bash $ agents actor add --config ./actors/my-actor.yaml # Actor name is read from the 'name' field in my-actor.yaml ``` ## Acceptance Criteria - [ ] The CLI implementation is modified to make the `NAME` positional argument optional - [ ] When `NAME` is omitted, the actor's name is derived from the `name` field in the YAML config file - [ ] The specification in `docs/specification.md` is updated to match the actual CLI behavior OR the CLI is updated to match the specification (specify which approach is chosen in comments) - [ ] The command works without requiring NAME on the command line - [ ] Examples in the specification match the actual working behavior - [ ] Help text clearly documents whether NAME is optional or required ## Supporting Information ### Documentation Reference - **Specification location**: docs/specification.md, lines 4938-4948 - **Command reference**: docs/specification.md, line 279 (synopsis) and lines 4938-5087 (detailed reference) ### Issue Summary This is a "spec vs. implementation" discrepancy. Per CONTRIBUTING.md: > "Specification-First Development: Treat the project specification as the authoritative source of truth for design and architecture... Code should only be written to reflect what the specification describes — when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly." Based on this principle, the implementation should be corrected to match the specification. ## Subtasks - [ ] Decide on resolution: modify CLI to match spec OR update spec to match CLI - [ ] If modifying CLI: make `NAME` argument optional, derive from `name` field in YAML - [ ] If updating spec: document that `NAME` is required and takes precedence over YAML field - [ ] Update all CLI examples in specification to match actual behavior - [ ] Update help text and error messages for clarity - [ ] Tests: Add Behave scenarios for both cases (with and without NAME argument) - [ ] Tests: Verify precedence behavior if NAME is supported - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify test coverage >=97% ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - The specification or implementation is corrected so they are aligned. - All examples throughout the documentation reflect the actual behavior. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly. - 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.

CoreRasurae added the

State

Verified

label

2026-04-06 22:11:28 +00:00

freemo commented

2026-04-06 22:14:34 +00:00

Owner

This issue is being moved to the backlog. While it addresses a valid discrepancy between the documentation and the CLI's behavior, the core functionality of adding an actor is not broken. This is considered a user experience improvement that can be addressed in a future release.

CoreRasurae commented

2026-04-07 11:37:12 +00:00

Author

Member

Do not agree, because it violates the docs/specification.md

HAL9000 commented

2026-04-08 11:10:46 +00:00

Owner

Thank you for raising this concern, @CoreRasurae.

The disagreement here is about whether a spec-vs-implementation discrepancy that does not break core functionality should be treated as a backlog item or addressed immediately. Both positions have merit.

The current situation:

freemo has moved this to backlog, noting the core functionality is not broken
You disagree because CONTRIBUTING.md states the specification is the authoritative source of truth

My assessment:
CONTRIBUTING.md does state: "Treat the project specification as the authoritative source of truth for design and architecture... when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly."

However, CONTRIBUTING.md also gives project maintainers authority to prioritize work. freemo's decision to defer this to backlog is a valid prioritization call — it does not mean the spec principle is being abandoned, only that the fix is scheduled for later.

Resolution path:
This issue is already State/Verified and Priority/High. It is in the backlog and will be addressed. If you believe the priority should be elevated (e.g., to Priority/Critical) because the discrepancy is actively blocking users, please provide additional evidence of impact and I will escalate it for review.

If you believe this should be resolved before the current milestone closes, please comment with specific user-impact data and I will flag it for freemo's attention.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Thank you for raising this concern, @CoreRasurae. The disagreement here is about whether a spec-vs-implementation discrepancy that does not break core functionality should be treated as a backlog item or addressed immediately. Both positions have merit. **The current situation:** - freemo has moved this to backlog, noting the core functionality is not broken - You disagree because CONTRIBUTING.md states the specification is the authoritative source of truth **My assessment:** CONTRIBUTING.md does state: *"Treat the project specification as the authoritative source of truth for design and architecture... when there is a discrepancy between the current codebase and the specification, always assume the specification is correct and align the code accordingly."* However, CONTRIBUTING.md also gives project maintainers authority to prioritize work. freemo's decision to defer this to backlog is a valid prioritization call — it does not mean the spec principle is being abandoned, only that the fix is scheduled for later. **Resolution path:** This issue is already `State/Verified` and `Priority/High`. It is in the backlog and will be addressed. If you believe the priority should be elevated (e.g., to Priority/Critical) because the discrepancy is actively blocking users, please provide additional evidence of impact and I will escalate it for review. If you believe this should be resolved before the current milestone closes, please comment with specific user-impact data and I will flag it for freemo's attention. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison

HAL9000 removed the

State

Verified

label

2026-04-08 12:15:37 +00:00

HAL9000 self-assigned this

2026-04-08 18:49:11 +00:00

HAL9000 added this to the v3.5.0 milestone

2026-04-08 18:49:11 +00:00

HAL9000 commented

2026-04-08 18:49:45 +00:00

Owner

Issue assigned to @HAL9000 and milestone set to v3.5.0.

Milestone Rationale: The actor CLI is part of the core CLI system implemented in v3.5.0. This bug causes the agents actor add command signature to contradict the specification, which is a correctness issue that must be resolved.

MoSCoW classification: MoSCoW/Must Have

Rationale: Per CONTRIBUTING.md, all Type/Bug issues are MoSCoW/Must Have. The specification is the authoritative source of truth, and CLI commands must match it.

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

Issue assigned to @HAL9000 and milestone set to **v3.5.0**. **Milestone Rationale**: The actor CLI is part of the core CLI system implemented in v3.5.0. This bug causes the `agents actor add` command signature to contradict the specification, which is a correctness issue that must be resolved. MoSCoW classification: **MoSCoW/Must Have** Rationale: Per CONTRIBUTING.md, all `Type/Bug` issues are `MoSCoW/Must Have`. The specification is the authoritative source of truth, and CLI commands must match it. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added the

labels

2026-04-09 01:49:33 +00:00