UAT: agents server command group is implemented but absent from spec CLI synopsis #3913

Open
opened 2026-04-06 07:22:17 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: docs/spec-add-server-cli-synopsis
  • Commit Message: docs(spec): add agents server command group to CLI synopsis
  • Milestone: (none — see backlog note below)
  • Parent Epic: #397

Description

The implementation registers an agents server command group with three subcommands (connect, status, serve) in src/cleveragents/cli/main.py (lines 221–225) and src/cleveragents/cli/commands/server.py. However, the docs/specification.md CLI Command Synopsis section (lines 207–367) does not include any agents server commands.

Per the project's source-of-truth policy, the specification is authoritative. Any command implemented in the CLI must be documented in the spec's synopsis section, or it must be removed until the spec describes it.

What Was Tested

Compared the CLI command synopsis in docs/specification.md (lines 207–367) against the registered CLI commands in src/cleveragents/cli/main.py.

Expected Behaviour (from spec)

The spec's CLI synopsis is the authoritative list of all supported commands. Any command implemented in the CLI should be documented in the spec's synopsis section.

Actual Behaviour

The agents server connect, agents server status, and agents server serve commands are registered and functional (as stubs) but are not listed in the spec's CLI synopsis section.

Code Locations

  • src/cleveragents/cli/main.py lines 221–225 — server_app registration
  • src/cleveragents/cli/commands/server.py — full stub implementation
  • docs/specification.md lines 207–367 — CLI synopsis (missing server commands)

Steps to Reproduce

  1. Search docs/specification.md for "agents server" — no results in the CLI synopsis section.
  2. Run agents server --help — command exists and works.

Impact

Either the spec needs to be updated to document the server commands, or the server commands need to be removed until the spec describes them. The spec is the source of truth.


Subtasks

  • Confirm with project owner whether agents server commands are intended to be part of the current spec or are premature implementation
  • If spec should be updated: add agents server connect, agents server status, and agents server serve to the CLI Command Synopsis section of docs/specification.md with correct usage, arguments, and descriptions
  • If commands should be removed: open a separate issue to remove the premature implementation from src/cleveragents/cli/main.py and src/cleveragents/cli/commands/server.py
  • Verify no other implemented CLI commands are absent from the spec synopsis
  • Update any related documentation or cross-references in docs/specification.md

Definition of Done

  • The agents server command group (and all subcommands) is either fully documented in the CLI synopsis of docs/specification.md, or a follow-up issue is filed to remove the premature implementation
  • docs/specification.md CLI synopsis is consistent with all registered CLI commands in src/cleveragents/cli/main.py
  • The associated PR has been reviewed and merged
  • All nox stages pass
  • Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.


Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `docs/spec-add-server-cli-synopsis` - **Commit Message**: `docs(spec): add agents server command group to CLI synopsis` - **Milestone**: *(none — see backlog note below)* - **Parent Epic**: #397 ## Description The implementation registers an `agents server` command group with three subcommands (`connect`, `status`, `serve`) in `src/cleveragents/cli/main.py` (lines 221–225) and `src/cleveragents/cli/commands/server.py`. However, the `docs/specification.md` CLI Command Synopsis section (lines 207–367) does not include any `agents server` commands. Per the project's source-of-truth policy, the specification is authoritative. Any command implemented in the CLI must be documented in the spec's synopsis section, or it must be removed until the spec describes it. ### What Was Tested Compared the CLI command synopsis in `docs/specification.md` (lines 207–367) against the registered CLI commands in `src/cleveragents/cli/main.py`. ### Expected Behaviour (from spec) The spec's CLI synopsis is the authoritative list of all supported commands. Any command implemented in the CLI should be documented in the spec's synopsis section. ### Actual Behaviour The `agents server connect`, `agents server status`, and `agents server serve` commands are registered and functional (as stubs) but are **not** listed in the spec's CLI synopsis section. ### Code Locations - `src/cleveragents/cli/main.py` lines 221–225 — `server_app` registration - `src/cleveragents/cli/commands/server.py` — full stub implementation - `docs/specification.md` lines 207–367 — CLI synopsis (missing server commands) ### Steps to Reproduce 1. Search `docs/specification.md` for `"agents server"` — no results in the CLI synopsis section. 2. Run `agents server --help` — command exists and works. ### Impact Either the spec needs to be updated to document the server commands, or the server commands need to be removed until the spec describes them. The spec is the source of truth. --- ## Subtasks - [ ] Confirm with project owner whether `agents server` commands are intended to be part of the current spec or are premature implementation - [ ] If spec should be updated: add `agents server connect`, `agents server status`, and `agents server serve` to the CLI Command Synopsis section of `docs/specification.md` with correct usage, arguments, and descriptions - [ ] If commands should be removed: open a separate issue to remove the premature implementation from `src/cleveragents/cli/main.py` and `src/cleveragents/cli/commands/server.py` - [ ] Verify no other implemented CLI commands are absent from the spec synopsis - [ ] Update any related documentation or cross-references in `docs/specification.md` ## Definition of Done - [ ] The `agents server` command group (and all subcommands) is either fully documented in the CLI synopsis of `docs/specification.md`, or a follow-up issue is filed to remove the premature implementation - [ ] `docs/specification.md` CLI synopsis is consistent with all registered CLI commands in `src/cleveragents/cli/main.py` - [ ] The associated PR has been reviewed and merged - [ ] All nox stages pass - [ ] Coverage >= 97% --- > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
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.

Blocks
#397 Epic: Server & Autonomy Infrastructure
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3913
No description provided.