feat(tui): implement TUI /-mode slash command system with autocomplete #9342

New issue

Open

opened 2026-04-14 15:15:03 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-14 15:15:03 +00:00

Owner

Metadata

Branch: feat/tui-slash-command-system
Commit Message: feat(tui): implement TUI /-mode slash command system with autocomplete
Milestone: v3.7.0

Background and Context

The v3.7.0 milestone (M8: TUI Implementation) explicitly includes a "Reference and command input system (@, /, ! modes)" as part of its scope, governed by ADR-046 (Reference/Command System). The /-mode slash command system is the primary mechanism by which users invoke structured TUI commands — such as managing sessions, switching personas, executing plans, and accessing help — directly from the prompt input without leaving the TUI.

Currently, the TUI prompt input accepts free-form text only. There is no mechanism to invoke structured commands inline. Without /-mode, users cannot perform session management, persona switching, plan operations, or access help from within the TUI. This creates a significant usability gap and blocks the full ADR-046 command input system from being functional.

The slash command system must be extensible so that plugins can register new commands at runtime, and must provide a discoverable autocomplete overlay so users can explore available commands without prior knowledge.

Expected Behavior

When a user types / at the start of the prompt input:

An autocomplete overlay appears above the prompt, listing all available slash commands organized by category.
Typing additional characters after / filters the list in real-time (e.g., /ses shows only session-related commands).
Arrow keys navigate the filtered list; Enter executes the highlighted command.
Commands that accept arguments display a parameter hint in the overlay (e.g., /session:switch <name>).
Pressing Escape dismisses the overlay and returns to normal input mode.
/help displays all available commands with their descriptions and argument signatures.
The command registry is extensible: plugins can register new slash commands at runtime.

Command categories and key commands:

Category	Commands
Help	`/help`
Session	`/clear`, `/session:create`, `/session:list`, `/session:switch <name>`
Plan	`/plan:use <id>`, `/plan:status`, `/plan:execute`
Actor	`/actor:list`
Settings	`/settings`
Persona	`/persona:list`, `/persona:switch <name>`

Acceptance Criteria

Typing / at the start of the prompt input activates /-mode and shows the autocomplete overlay
The autocomplete overlay lists all registered slash commands organized by category
Typing characters after / filters the command list in real-time (case-insensitive prefix match)
Arrow keys (↑/↓) navigate the filtered command list
Enter executes the currently highlighted command
Escape dismisses the overlay and returns to normal input mode without executing a command
Commands with required arguments display a parameter hint (e.g., <name>) in the overlay
/help outputs all available commands with descriptions and argument signatures to the conversation area
/clear clears the current conversation area
/settings opens the Settings screen
/session:create creates a new session
/session:list lists all available sessions in the conversation area
/session:switch <name> switches to the named session
/plan:use <id> sets the active plan by ID
/plan:status displays the current plan status
/plan:execute triggers plan execution
/actor:list lists all available actors in the conversation area
/persona:list lists all available personas in the conversation area
/persona:switch <name> switches to the named persona
The command registry exposes a public API for plugins to register new slash commands
Registered plugin commands appear in the autocomplete overlay and /help output
Unit tests achieve >= 97% coverage for all new modules
Widget tests verify overlay rendering, keyboard navigation, and real-time filtering
All existing TUI tests continue to pass (no regressions)

Subtasks

Design and implement SlashCommandRegistry — a singleton registry that holds all registered SlashCommand descriptors (name, category, description, argument signature, handler)
Implement built-in command registrations for all key commands: /help, /clear, /settings, /session:create, /session:list, /session:switch, /plan:use, /plan:status, /plan:execute, /actor:list, /persona:list, /persona:switch
Implement SlashCommandOverlay Textual widget — renders the filtered command list with category grouping, highlights the selected item, and shows parameter hints
Wire /-mode activation into the TUI PromptInput widget: detect / as the first character and activate the overlay
Implement real-time filtering logic: as the user types after /, filter the registry by prefix match and update the overlay
Implement keyboard navigation in the overlay: ↑/↓ to move selection, Enter to execute, Escape to dismiss
Implement command dispatch: on Enter, resolve the selected command from the registry and invoke its handler with any parsed arguments
Implement /help handler: format and display all registered commands (grouped by category) in the conversation area
Implement /clear handler: clear the conversation area
Implement /settings handler: open the Settings screen
Implement session command handlers (/session:create, /session:list, /session:switch) wired to the A2A session service
Implement plan command handlers (/plan:use, /plan:status, /plan:execute) wired to the A2A plan service
Implement actor/persona command handlers (/actor:list, /persona:list, /persona:switch) wired to the A2A actor/persona service
Expose plugin registration API: SlashCommandRegistry.register(command: SlashCommand) callable from plugin entry points
Write unit tests for SlashCommandRegistry (registration, deduplication, filtering, plugin registration)
Write widget tests for SlashCommandOverlay (rendering, keyboard navigation, real-time filtering, parameter hints)
Write integration tests for end-to-end slash command dispatch (input → overlay → execution → conversation output)
Update docs/reference/tui.md with the slash command system documentation

Definition of Done

This issue should be closed when:

All acceptance criteria checkboxes above are checked.
The SlashCommandRegistry, SlashCommandOverlay, and all built-in command handlers are implemented and merged to the feat/tui-slash-command-system branch.
The plugin registration API is documented and tested.
Unit, widget, and integration test coverage is >= 97% for all new code.
nox passes with no regressions on the full test suite.
The TUI /-mode slash command system is fully functional end-to-end in a running TUI session.
docs/reference/tui.md is updated to document the slash command system.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch**: `feat/tui-slash-command-system` - **Commit Message**: `feat(tui): implement TUI /-mode slash command system with autocomplete` - **Milestone**: v3.7.0 --- ## Background and Context The v3.7.0 milestone (M8: TUI Implementation) explicitly includes a "Reference and command input system (@, /, ! modes)" as part of its scope, governed by ADR-046 (Reference/Command System). The `/-mode` slash command system is the primary mechanism by which users invoke structured TUI commands — such as managing sessions, switching personas, executing plans, and accessing help — directly from the prompt input without leaving the TUI. Currently, the TUI prompt input accepts free-form text only. There is no mechanism to invoke structured commands inline. Without `/-mode`, users cannot perform session management, persona switching, plan operations, or access help from within the TUI. This creates a significant usability gap and blocks the full ADR-046 command input system from being functional. The slash command system must be extensible so that plugins can register new commands at runtime, and must provide a discoverable autocomplete overlay so users can explore available commands without prior knowledge. --- ## Expected Behavior When a user types `/` at the start of the prompt input: 1. An autocomplete overlay appears above the prompt, listing all available slash commands organized by category. 2. Typing additional characters after `/` filters the list in real-time (e.g., `/ses` shows only session-related commands). 3. Arrow keys navigate the filtered list; `Enter` executes the highlighted command. 4. Commands that accept arguments display a parameter hint in the overlay (e.g., `/session:switch <name>`). 5. Pressing `Escape` dismisses the overlay and returns to normal input mode. 6. `/help` displays all available commands with their descriptions and argument signatures. 7. The command registry is extensible: plugins can register new slash commands at runtime. **Command categories and key commands:** | Category | Commands | |----------|----------| | **Help** | `/help` | | **Session** | `/clear`, `/session:create`, `/session:list`, `/session:switch <name>` | | **Plan** | `/plan:use <id>`, `/plan:status`, `/plan:execute` | | **Actor** | `/actor:list` | | **Settings** | `/settings` | | **Persona** | `/persona:list`, `/persona:switch <name>` | --- ## Acceptance Criteria - [ ] Typing `/` at the start of the prompt input activates `/-mode` and shows the autocomplete overlay - [ ] The autocomplete overlay lists all registered slash commands organized by category - [ ] Typing characters after `/` filters the command list in real-time (case-insensitive prefix match) - [ ] Arrow keys (`↑`/`↓`) navigate the filtered command list - [ ] `Enter` executes the currently highlighted command - [ ] `Escape` dismisses the overlay and returns to normal input mode without executing a command - [ ] Commands with required arguments display a parameter hint (e.g., `<name>`) in the overlay - [ ] `/help` outputs all available commands with descriptions and argument signatures to the conversation area - [ ] `/clear` clears the current conversation area - [ ] `/settings` opens the Settings screen - [ ] `/session:create` creates a new session - [ ] `/session:list` lists all available sessions in the conversation area - [ ] `/session:switch <name>` switches to the named session - [ ] `/plan:use <id>` sets the active plan by ID - [ ] `/plan:status` displays the current plan status - [ ] `/plan:execute` triggers plan execution - [ ] `/actor:list` lists all available actors in the conversation area - [ ] `/persona:list` lists all available personas in the conversation area - [ ] `/persona:switch <name>` switches to the named persona - [ ] The command registry exposes a public API for plugins to register new slash commands - [ ] Registered plugin commands appear in the autocomplete overlay and `/help` output - [ ] Unit tests achieve >= 97% coverage for all new modules - [ ] Widget tests verify overlay rendering, keyboard navigation, and real-time filtering - [ ] All existing TUI tests continue to pass (no regressions) --- ## Subtasks - [ ] Design and implement `SlashCommandRegistry` — a singleton registry that holds all registered `SlashCommand` descriptors (name, category, description, argument signature, handler) - [ ] Implement built-in command registrations for all key commands: `/help`, `/clear`, `/settings`, `/session:create`, `/session:list`, `/session:switch`, `/plan:use`, `/plan:status`, `/plan:execute`, `/actor:list`, `/persona:list`, `/persona:switch` - [ ] Implement `SlashCommandOverlay` Textual widget — renders the filtered command list with category grouping, highlights the selected item, and shows parameter hints - [ ] Wire `/-mode` activation into the TUI `PromptInput` widget: detect `/` as the first character and activate the overlay - [ ] Implement real-time filtering logic: as the user types after `/`, filter the registry by prefix match and update the overlay - [ ] Implement keyboard navigation in the overlay: `↑`/`↓` to move selection, `Enter` to execute, `Escape` to dismiss - [ ] Implement command dispatch: on `Enter`, resolve the selected command from the registry and invoke its handler with any parsed arguments - [ ] Implement `/help` handler: format and display all registered commands (grouped by category) in the conversation area - [ ] Implement `/clear` handler: clear the conversation area - [ ] Implement `/settings` handler: open the Settings screen - [ ] Implement session command handlers (`/session:create`, `/session:list`, `/session:switch`) wired to the A2A session service - [ ] Implement plan command handlers (`/plan:use`, `/plan:status`, `/plan:execute`) wired to the A2A plan service - [ ] Implement actor/persona command handlers (`/actor:list`, `/persona:list`, `/persona:switch`) wired to the A2A actor/persona service - [ ] Expose plugin registration API: `SlashCommandRegistry.register(command: SlashCommand)` callable from plugin entry points - [ ] Write unit tests for `SlashCommandRegistry` (registration, deduplication, filtering, plugin registration) - [ ] Write widget tests for `SlashCommandOverlay` (rendering, keyboard navigation, real-time filtering, parameter hints) - [ ] Write integration tests for end-to-end slash command dispatch (input → overlay → execution → conversation output) - [ ] Update `docs/reference/tui.md` with the slash command system documentation --- ## Definition of Done This issue should be closed when: 1. All acceptance criteria checkboxes above are checked. 2. The `SlashCommandRegistry`, `SlashCommandOverlay`, and all built-in command handlers are implemented and merged to the `feat/tui-slash-command-system` branch. 3. The plugin registration API is documented and tested. 4. Unit, widget, and integration test coverage is >= 97% for all new code. 5. `nox` passes with no regressions on the full test suite. 6. The TUI `/-mode` slash command system is fully functional end-to-end in a running TUI session. 7. `docs/reference/tui.md` is updated to document the slash command system. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 15:16:17 +00:00

HAL9000 added this to the v3.7.0 milestone