cleveragents/cleveragents-core

Fork 3

UAT: `agents skill refresh` command exists in implementation but is not defined in the specification #3522

New issue

Open

opened 2026-04-05 18:51:03 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 18:51:03 +00:00

Owner

Metadata

Branch: fix/skill-refresh-spec-alignment
Commit Message: fix(cli): align agents skill refresh command with specification or remove
Milestone: None (backlog)
Parent Epic: #392

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

Background and Context

The specification (docs/specification.md) defines the following agents skill 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>

The spec does NOT include agents skill refresh in the CLI command list.

Problem

The implementation in src/cleveragents/cli/commands/skill.py includes a refresh command that is not in the specification:

@app.command("refresh")
def refresh(
    name: Annotated[str | None, ...] = None,
    all_skills: Annotated[bool, typer.Option("--all", ...)] = False,
    fmt: Annotated[str, ...] = "rich",
) -> None:
    """Recompute tool flattening and sync MCP-backed skills."""

This command allows refreshing a single skill or all skills (--all), recomputing tool flattening and syncing MCP-backed skills.

Impact

The command is not documented in the spec, so users have no official documentation for it
It may represent a feature that needs to be added to the spec, or it may be an implementation artifact that should be removed
BDD tests exist for this command (in features/skill_cli.feature), suggesting it was intentionally implemented

Recommended Resolution

Either:

Add to spec: If agents skill refresh is an intentional feature, add it to docs/specification.md with proper documentation
Remove from implementation: If it's not intended to be a user-facing command, remove it from the CLI

Code Location

src/cleveragents/cli/commands/skill.py, refresh() function
features/skill_cli.feature, scenarios starting with "Refresh"

Subtasks

Review whether agents skill refresh is an intentional user-facing feature or an implementation artifact
If keeping: add agents skill refresh to docs/specification.md with full CLI documentation
If removing: delete the refresh() function from src/cleveragents/cli/commands/skill.py
If removing: remove or update BDD scenarios in features/skill_cli.feature that cover the refresh command
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

A decision has been made: either the spec is updated to include agents skill refresh, or the command is removed from the implementation
The chosen resolution is fully implemented with no spec/code divergence
All BDD tests in features/skill_cli.feature reflect the final state
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
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/skill-refresh-spec-alignment` - **Commit Message**: `fix(cli): align agents skill refresh command with specification or remove` - **Milestone**: None (backlog) - **Parent Epic**: #392 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context The specification (`docs/specification.md`) defines the following `agents skill` 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> ``` The spec does NOT include `agents skill refresh` in the CLI command list. ## Problem The implementation in `src/cleveragents/cli/commands/skill.py` includes a `refresh` command that is not in the specification: ```python @app.command("refresh") def refresh( name: Annotated[str | None, ...] = None, all_skills: Annotated[bool, typer.Option("--all", ...)] = False, fmt: Annotated[str, ...] = "rich", ) -> None: """Recompute tool flattening and sync MCP-backed skills.""" ``` This command allows refreshing a single skill or all skills (`--all`), recomputing tool flattening and syncing MCP-backed skills. ## Impact 1. The command is not documented in the spec, so users have no official documentation for it 2. It may represent a feature that needs to be added to the spec, or it may be an implementation artifact that should be removed 3. BDD tests exist for this command (in `features/skill_cli.feature`), suggesting it was intentionally implemented ## Recommended Resolution Either: 1. **Add to spec**: If `agents skill refresh` is an intentional feature, add it to `docs/specification.md` with proper documentation 2. **Remove from implementation**: If it's not intended to be a user-facing command, remove it from the CLI ## Code Location - `src/cleveragents/cli/commands/skill.py`, `refresh()` function - `features/skill_cli.feature`, scenarios starting with "Refresh" ## Subtasks - [ ] Review whether `agents skill refresh` is an intentional user-facing feature or an implementation artifact - [ ] If keeping: add `agents skill refresh` to `docs/specification.md` with full CLI documentation - [ ] If removing: delete the `refresh()` function from `src/cleveragents/cli/commands/skill.py` - [ ] If removing: remove or update BDD scenarios in `features/skill_cli.feature` that cover the `refresh` command - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] A decision has been made: either the spec is updated to include `agents skill refresh`, or the command is removed from the implementation - [ ] The chosen resolution is fully implemented with no spec/code divergence - [ ] All BDD tests in `features/skill_cli.feature` reflect the final state - [ ] 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 - [ ] 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-05 18:51:16 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-05 18:51:50 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 18:52:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 19:05:02 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo added this to the v3.7.0 milestone

2026-04-05 20:07:05 +00:00

freemo commented

2026-04-05 20:07:19 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — agents skill refresh exists in implementation but not in spec. Needs a decision: add to spec or remove from code.
Milestone: v3.7.0
Story Points: 1 — XS — Either add a spec entry or remove the command. Straightforward either way.
MoSCoW: Could Have — Spec/code alignment issue. The command exists and works; it's just undocumented. Not blocking anything.
Parent Epic: #392 (dependency link already exists)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — `agents skill refresh` exists in implementation but not in spec. Needs a decision: add to spec or remove from code. - **Milestone**: v3.7.0 - **Story Points**: 1 — XS — Either add a spec entry or remove the command. Straightforward either way. - **MoSCoW**: Could Have — Spec/code alignment issue. The command exists and works; it's just undocumented. Not blocking anything. - **Parent Epic**: #392 (dependency link already exists) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 20:08:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this issue

2026-04-05 20:29:17 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo commented

2026-04-06 18:51:55 +00:00

Author

Owner

Milestone Triage Decision: Moved to Backlog

This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints.

Reasoning:

v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality
This issue: Infrastructure improvement not directly blocking core milestone functionality
Impact: System enhancement, not core corrections/subplans/checkpoints functionality

Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.

**Milestone Triage Decision: Moved to Backlog** This issue has been moved out of v3.3.0 during aggressive milestone triage. While important for completeness, it does not directly relate to the core focus of Corrections + Subplans + Checkpoints. **Reasoning:** - v3.3.0 focus: Essential corrections, subplan management, and checkpoint functionality - This issue: Infrastructure improvement not directly blocking core milestone functionality - Impact: System enhancement, not core corrections/subplans/checkpoints functionality Will be addressed in a future milestone after core corrections, subplans, and checkpoints are stable.