UAT: `agents skill refresh` CLI command implemented but absent from spec Command Synopsis #3810

New issue

Open

opened 2026-04-06 06:31:39 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 06:31:39 +00:00

Owner

Metadata

Branch: fix/spec-add-skill-refresh-command-synopsis
Commit Message: docs(spec): add agents skill refresh command to Command Synopsis
Milestone: Backlog (no milestone — see backlog note below)
Parent Epic: #397

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

What Was Tested

The agents skill CLI command group and its registered subcommands.

Expected Behavior (from spec)

According to docs/specification.md Command Synopsis section, the agents skill command group defines exactly 5 subcommands:

agents skill add --config|-c <FILE> [--update]
agents skill remove [--yes|-y] <NAME>
agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>]
agents skill show  <NAME>
agents skill tools <NAME>

Actual Behavior

The implementation in src/cleveragents/cli/commands/skill.py registers a 6th command agents skill refresh that is not present in the spec's Command Synopsis:

# From cleveragents/cli/commands/skill.py
@app.command("refresh")
def refresh(...) -> None:
    """Recompute tool flattening and sync MCP-backed skills."""

Verified by inspecting the registered commands:

from cleveragents.cli.commands.skill import app
commands = [cmd.name or cmd.callback.__name__ for cmd in app.registered_commands]
# Result: ['add', 'remove', 'list', 'show', 'tools', 'refresh']

The refresh command is fully implemented with:

agents skill refresh <NAME> — refresh a single skill
agents skill refresh --all — refresh all skills
--format option for JSON/YAML output

Impact

The spec is the source of truth. The refresh command either needs to be added to the spec or removed from the implementation.
Users relying on the spec as documentation will not know this command exists.
The spec's Command Reference section (agents skill section) also has no documentation for refresh.

Code Location

src/cleveragents/cli/commands/skill.py — refresh() function (line ~530+)
docs/specification.md — Command Synopsis section (agents skill commands)

Note

The refresh command itself is functional and well-implemented. The issue is purely a spec/implementation discrepancy. The spec should be updated to include agents skill refresh [--all] [<NAME>] OR the command should be removed from the implementation until the spec is updated.

Subtasks

Determine resolution path: update spec to document agents skill refresh OR remove the command from the implementation (decision for project owner)
If updating spec: Add agents skill refresh [--all] [<NAME>] [--format <FORMAT>] to the Command Synopsis section in docs/specification.md
If updating spec: Add a full Command Reference entry for agents skill refresh in docs/specification.md (description, options table, example output)
If removing command: Remove the refresh() function and its @app.command("refresh") decorator from src/cleveragents/cli/commands/skill.py
If removing command: Remove any tests that exercise agents skill refresh
Write or update Behave unit tests (in features/) to cover the chosen resolution
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

A clear decision has been made: spec updated to include refresh OR command removed from implementation
docs/specification.md Command Synopsis and Command Reference sections are consistent with the implementation
No undocumented CLI commands exist (implementation matches spec exactly)
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/spec-add-skill-refresh-command-synopsis` - **Commit Message**: `docs(spec): add agents skill refresh command to Command Synopsis` - **Milestone**: Backlog (no milestone — see backlog note below) - **Parent Epic**: #397 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## What Was Tested The `agents skill` CLI command group and its registered subcommands. ## Expected Behavior (from spec) According to `docs/specification.md` Command Synopsis section, the `agents skill` command group defines exactly 5 subcommands: ``` agents skill add --config|-c <FILE> [--update] agents skill remove [--yes|-y] <NAME> agents skill list [(--namespace|-n) <NS>] [--source <SOURCE>] agents skill show <NAME> agents skill tools <NAME> ``` ## Actual Behavior The implementation in `src/cleveragents/cli/commands/skill.py` registers a 6th command `agents skill refresh` that is **not present in the spec's Command Synopsis**: ```python # From cleveragents/cli/commands/skill.py @app.command("refresh") def refresh(...) -> None: """Recompute tool flattening and sync MCP-backed skills.""" ``` Verified by inspecting the registered commands: ```python from cleveragents.cli.commands.skill import app commands = [cmd.name or cmd.callback.__name__ for cmd in app.registered_commands] # Result: ['add', 'remove', 'list', 'show', 'tools', 'refresh'] ``` The `refresh` command is fully implemented with: - `agents skill refresh <NAME>` — refresh a single skill - `agents skill refresh --all` — refresh all skills - `--format` option for JSON/YAML output ## Impact - The spec is the source of truth. The `refresh` command either needs to be added to the spec or removed from the implementation. - Users relying on the spec as documentation will not know this command exists. - The spec's Command Reference section (agents skill section) also has no documentation for `refresh`. ## Code Location - `src/cleveragents/cli/commands/skill.py` — `refresh()` function (line ~530+) - `docs/specification.md` — Command Synopsis section (agents skill commands) ## Note The `refresh` command itself is functional and well-implemented. The issue is purely a spec/implementation discrepancy. The spec should be updated to include `agents skill refresh [--all] [<NAME>]` OR the command should be removed from the implementation until the spec is updated. ## Subtasks - [ ] Determine resolution path: update spec to document `agents skill refresh` OR remove the command from the implementation (decision for project owner) - [ ] **If updating spec**: Add `agents skill refresh [--all] [<NAME>] [--format <FORMAT>]` to the Command Synopsis section in `docs/specification.md` - [ ] **If updating spec**: Add a full Command Reference entry for `agents skill refresh` in `docs/specification.md` (description, options table, example output) - [ ] **If removing command**: Remove the `refresh()` function and its `@app.command("refresh")` decorator from `src/cleveragents/cli/commands/skill.py` - [ ] **If removing command**: Remove any tests that exercise `agents skill refresh` - [ ] Write or update Behave unit tests (in `features/`) to cover the chosen resolution - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] A clear decision has been made: spec updated to include `refresh` OR command removed from implementation - [ ] `docs/specification.md` Command Synopsis and Command Reference sections are consistent with the implementation - [ ] No undocumented CLI commands exist (implementation matches spec exactly) - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

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

#397 Epic: Server & Autonomy Infrastructure

freemo referenced this issue

2026-04-06 06:35:27 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 06:35:58 +00:00

freemo referenced this issue

2026-04-06 06:47:49 +00:00