cleveragents/cleveragents-core

Fork 3

UAT: TUI `SlashCommandOverlay` displays command names only — spec requires descriptions alongside each command #3437

New issue

Closed

opened 2026-04-05 16:50:06 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 16:50:06 +00:00

Owner

Metadata

Branch: fix/tui-slash-overlay-show-descriptions
Commit Message: fix(tui): show command descriptions in SlashCommandOverlay alongside command names
Milestone: None (backlog)
Parent Epic: #868

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.

Summary

Per ADR-046, the Slash Command overlay must display each command with its description alongside it. Currently, SlashCommandOverlay.set_commands() only renders command names — descriptions from SLASH_COMMAND_SPECS are never passed to or displayed by the overlay.

Expected display (per ADR-046):

┌─ Commands ───────────────────────────────────────────────────┐
│ /se                                                          │
│ ──────────────────────────────────────────────────────────── │
│  /session:create       Create a new session tab              │
│  /session:list         Show all sessions                     │
│  /session:show         Show session details                  │
│  /session:switch       Switch to session by ID               │
│  /session:close        Close current session                 │
│  /session:delete       Delete a saved session                │
│  /session:rename       Rename current session                │
│  /session:export       Export session to file                │
│  /session:import       Import session from file              │
│  /settings             Open settings screen                  │
│                                                              │
│ enter Execute │ tab Complete │ escape Dismiss                │
└──────────────────────────────────────────────────────────────┘

Actual display:

│  /session:create
│  /session:list
│  ...

Root Cause

Three locations require changes:

src/cleveragents/tui/widgets/slash_command_overlay.py lines 25–35 — set_commands() accepts list[str] (names only) and formats lines without descriptions:

def set_commands(self, query: str, commands: list[str]) -> None:
    ...
    for command in filtered[:12]:
        lines.append(f"  /{command}")   # ← no description

src/cleveragents/tui/app.py line 133 — calls set_commands with names only:
```
slash.set_commands("", slash_command_names())  # ← names only
```
src/cleveragents/tui/slash_catalog.py lines 17–88 — SLASH_COMMAND_SPECS contains descriptions but they are not forwarded to the overlay.

Subtasks

Update set_commands() signature to accept list[SlashCommandSpec] (or equivalent typed structure with name + description)
Update the line-formatting logic in set_commands() to render /command-name Description text with aligned columns
Update app.py to pass full SlashCommandSpec objects (not just names) when initialising and updating the overlay
Update any other call sites that invoke set_commands() to pass specs instead of bare names
Tests (Behave): Add/update BDD scenarios covering description rendering in the overlay
Tests (Behave): Add TDD issue-capture test (@tdd_expected_fail) demonstrating the missing-description bug before fixing it
Tests (Robot): Add/update integration test verifying descriptions appear in the rendered overlay
Verify nox -e typecheck passes (Pyright — no # type: ignore suppressions)
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.
The slash command overlay renders each command with its description alongside it, matching the ADR-046 wireframe layout.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(tui): show command descriptions in SlashCommandOverlay alongside command names), followed by a blank line, then additional lines providing relevant details about the implementation, and a footer ISSUES CLOSED: #<this issue number>.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/tui-slash-overlay-show-descriptions).
The commit is submitted as a pull request to master, reviewed by at least two non-author contributors, and merged before this issue is marked done.
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/tui-slash-overlay-show-descriptions` - **Commit Message**: `fix(tui): show command descriptions in SlashCommandOverlay alongside command names` - **Milestone**: None (backlog) - **Parent Epic**: #868 > **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. ## Summary Per ADR-046, the Slash Command overlay must display each command with its description alongside it. Currently, `SlashCommandOverlay.set_commands()` only renders command names — descriptions from `SLASH_COMMAND_SPECS` are never passed to or displayed by the overlay. **Expected display (per ADR-046):** ``` ┌─ Commands ───────────────────────────────────────────────────┐ │ /se │ │ ──────────────────────────────────────────────────────────── │ │ /session:create Create a new session tab │ │ /session:list Show all sessions │ │ /session:show Show session details │ │ /session:switch Switch to session by ID │ │ /session:close Close current session │ │ /session:delete Delete a saved session │ │ /session:rename Rename current session │ │ /session:export Export session to file │ │ /session:import Import session from file │ │ /settings Open settings screen │ │ │ │ enter Execute │ tab Complete │ escape Dismiss │ └──────────────────────────────────────────────────────────────┘ ``` **Actual display:** ``` │ /session:create │ /session:list │ ... ``` ## Root Cause Three locations require changes: 1. **`src/cleveragents/tui/widgets/slash_command_overlay.py` lines 25–35** — `set_commands()` accepts `list[str]` (names only) and formats lines without descriptions: ```python def set_commands(self, query: str, commands: list[str]) -> None: ... for command in filtered[:12]: lines.append(f" /{command}") # ← no description ``` 2. **`src/cleveragents/tui/app.py` line 133** — calls `set_commands` with names only: ```python slash.set_commands("", slash_command_names()) # ← names only ``` 3. **`src/cleveragents/tui/slash_catalog.py` lines 17–88** — `SLASH_COMMAND_SPECS` contains descriptions but they are not forwarded to the overlay. ## Subtasks - [ ] Update `set_commands()` signature to accept `list[SlashCommandSpec]` (or equivalent typed structure with name + description) - [ ] Update the line-formatting logic in `set_commands()` to render ` /command-name Description text` with aligned columns - [ ] Update `app.py` to pass full `SlashCommandSpec` objects (not just names) when initialising and updating the overlay - [ ] Update any other call sites that invoke `set_commands()` to pass specs instead of bare names - [ ] Tests (Behave): Add/update BDD scenarios covering description rendering in the overlay - [ ] Tests (Behave): Add TDD issue-capture test (`@tdd_expected_fail`) demonstrating the missing-description bug before fixing it - [ ] Tests (Robot): Add/update integration test verifying descriptions appear in the rendered overlay - [ ] Verify `nox -e typecheck` passes (Pyright — no `# type: ignore` suppressions) - [ ] 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. - The slash command overlay renders each command with its description alongside it, matching the ADR-046 wireframe layout. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(tui): show command descriptions in SlashCommandOverlay alongside command names`), followed by a blank line, then additional lines providing relevant details about the implementation, and a footer `ISSUES CLOSED: #<this issue number>`. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/tui-slash-overlay-show-descriptions`). - The commit is submitted as a **pull request** to `master`, reviewed by at least two non-author contributors, and **merged** before this issue is marked done. - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-05 16:50:23 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo added this to the v3.7.0 milestone

2026-04-05 17:06:15 +00:00

freemo commented

2026-04-05 17:06:38 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Backlog (confirmed) — Slash command overlay shows names without descriptions. UX polish.
Milestone: v3.7.0 (TUI Implementation)
Story Points: 2 (S) — Update set_commands() signature and formatting logic
MoSCoW: Could Have — The overlay is functional, just missing descriptions alongside command names.
Parent Epic: #868 (TUI Interface, Modals and Persona System)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (confirmed) — Slash command overlay shows names without descriptions. UX polish. - **Milestone**: v3.7.0 (TUI Implementation) - **Story Points**: 2 (S) — Update `set_commands()` signature and formatting logic - **MoSCoW**: Could Have — The overlay is functional, just missing descriptions alongside command names. - **Parent Epic**: #868 (TUI Interface, Modals and Persona System) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

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

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

freemo referenced this issue from a commit

2026-04-05 17:51:01 +00:00

fix(tui): show command descriptions in SlashCommandOverlay alongside command names

freemo referenced this issue

2026-04-05 17:51:13 +00:00

fix(tui): show command descriptions in SlashCommandOverlay alongside command names #3457

freemo commented

2026-04-05 17:51:25 +00:00

Author

Owner

PR #3457 created on branch fix/tui-slash-overlay-show-descriptions. I will monitor and handle all review feedback until merged.

Implementation summary:

Updated SlashCommandOverlay.set_commands() to accept list[SlashCommandSpec] instead of list[str]
Renders each command as /command-name Description text with 28-char aligned name column
Added slash_command_specs() helper to slash_catalog.py
Updated app.py to pass full spec objects to the overlay
Added/updated Behave BDD tests and Robot Framework integration test

Quality gates: lint ✅ | typecheck ✅ (0 errors) | dead_code ✅

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

PR #3457 created on branch `fix/tui-slash-overlay-show-descriptions`. I will monitor and handle all review feedback until merged. **Implementation summary:** - Updated `SlashCommandOverlay.set_commands()` to accept `list[SlashCommandSpec]` instead of `list[str]` - Renders each command as ` /command-name Description text` with 28-char aligned name column - Added `slash_command_specs()` helper to `slash_catalog.py` - Updated `app.py` to pass full spec objects to the overlay - Added/updated Behave BDD tests and Robot Framework integration test **Quality gates:** lint ✅ | typecheck ✅ (0 errors) | dead_code ✅ --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo referenced this issue

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

fix(tui): show command descriptions in SlashCommandOverlay alongside command names #3457

freemo closed this issue

2026-04-05 21:12:11 +00:00

freemo referenced this issue from a commit

2026-04-05 21:12:11 +00:00

fix(tui): show command descriptions in SlashCommandOverlay alongside command names

freemo referenced this issue

2026-04-05 21:15:18 +00:00

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