refactor(cli): relocate context commands under `actor context` hierarchy per specification #888

New issue

Closed

opened 2026-03-13 23:27:00 +00:00 by freemo · 4 comments

freemo commented

2026-03-13 23:27:00 +00:00

Owner

Metadata

Commit Message: refactor(cli): move context commands to actor context subgroup
Branch: feature/m4-actor-context-hierarchy

Background and Context

The specification defines actor context management commands under agents actor context:

agents actor context remove [--yes|-y] (--all|-a|<NAME>)
agents actor context list [<REGEX>]
agents actor context show <NAME>
agents actor context export (--output|-o) <FILE> <NAME>
agents actor context import [--update] (--input|-i) <FILE> [<NAME>]
agents actor context clear [--yes|-y] (--all|-a|<NAME>)

The current implementation places these commands under a top-level agents context group (in src/cleveragents/cli/commands/context.py) instead of under agents actor context. Additionally, the remove command is named rm (not remove as the spec requires).

This structural mismatch means:

agents actor context list (spec) → agents context list (code)
agents actor context remove (spec) → agents context rm (code)
Users following the spec will get "unknown command" errors

Note: Issue #869 tracks adding the missing actor context remove/export/import commands but does not address the hierarchy relocation or the rm → remove rename.

Expected Behavior

Context commands should be accessible under both agents actor context (canonical spec path) and potentially as aliases at the top level for backward compatibility.

Acceptance Criteria

agents actor context list is a valid command path
agents actor context show is a valid command path
agents actor context remove is a valid command path (not rm)
agents actor context export is a valid command path
agents actor context import is a valid command path
agents actor context clear is a valid command path
Command behavior is identical regardless of invocation path
agents context * remains as a deprecated alias (with deprecation warning) for one release cycle

Subtasks

Register context as a sub-app of actor in main.py
Add deprecation wrapper for top-level agents context commands
Rename rm subcommand to remove (add rm as alias with deprecation warning)
Update command help text to reflect new hierarchy
Tests (Behave): Verify commands work at new path
Tests (Behave): Verify deprecated aliases still work with warning
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

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.

## Metadata - **Commit Message**: `refactor(cli): move context commands to actor context subgroup` - **Branch**: `feature/m4-actor-context-hierarchy` ## Background and Context The specification defines actor context management commands under `agents actor context`: ``` agents actor context remove [--yes|-y] (--all|-a|<NAME>) agents actor context list [<REGEX>] agents actor context show <NAME> agents actor context export (--output|-o) <FILE> <NAME> agents actor context import [--update] (--input|-i) <FILE> [<NAME>] agents actor context clear [--yes|-y] (--all|-a|<NAME>) ``` The current implementation places these commands under a **top-level** `agents context` group (in `src/cleveragents/cli/commands/context.py`) instead of under `agents actor context`. Additionally, the `remove` command is named `rm` (not `remove` as the spec requires). This structural mismatch means: - `agents actor context list` (spec) → `agents context list` (code) - `agents actor context remove` (spec) → `agents context rm` (code) - Users following the spec will get "unknown command" errors Note: Issue #869 tracks adding the missing `actor context remove/export/import` commands but does not address the hierarchy relocation or the `rm` → `remove` rename. ## Expected Behavior Context commands should be accessible under both `agents actor context` (canonical spec path) and potentially as aliases at the top level for backward compatibility. ## Acceptance Criteria - [ ] `agents actor context list` is a valid command path - [ ] `agents actor context show` is a valid command path - [ ] `agents actor context remove` is a valid command path (not `rm`) - [ ] `agents actor context export` is a valid command path - [ ] `agents actor context import` is a valid command path - [ ] `agents actor context clear` is a valid command path - [ ] Command behavior is identical regardless of invocation path - [ ] `agents context *` remains as a deprecated alias (with deprecation warning) for one release cycle ## Subtasks - [ ] Register `context` as a sub-app of `actor` in `main.py` - [ ] Add deprecation wrapper for top-level `agents context` commands - [ ] Rename `rm` subcommand to `remove` (add `rm` as alias with deprecation warning) - [ ] Update command help text to reflect new hierarchy - [ ] Tests (Behave): Verify commands work at new path - [ ] Tests (Behave): Verify deprecated aliases still work with warning - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## 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.

freemo added the

Session	Result
lint	pass
typecheck	pass (0 errors, 0 warnings)
unit_tests	495 features, 12731 scenarios, 0 failures
integration_tests	1818/1819 pass (1 pre-existing failure in `core_cli_commands.robot` project-status-without-project test — unrelated)
coverage_report	97%

Rows
Columns

refactor(cli): relocate context commands under actor context hierarchy per specification #888

Metadata

Background and Context

Expected Behavior

Acceptance Criteria

Subtasks

Definition of Done

Implementation Notes

Changes

Nox Results

Backward Compatibility

refactor(cli): relocate context commands under `actor context` hierarchy per specification #888