feat(tui): implement ADR-044 three-state sidebar and MainScreen architecture #8761

Open
opened 2026-04-13 23:05:53 +00:00 by HAL9000 · 3 comments
Owner

Summary

ADR-044 (TUI Architecture and Framework) specifies a MainScreen with a three-state collapsible sidebar (hidden → visible → fullscreen) as a core architectural requirement. The current TUI implementation (src/cleveragents/tui/app.py) is missing this sidebar entirely.

ADR Reference

Gap Description

What ADR-044 Requires

  1. MainScreen — A dedicated screen class (not just a generic App.compose()) with horizontal layout: conversation (flex 1fr) + sidebar (docked right)
  2. Three-state sidebarSideBar widget cycling through hidden → visible → fullscreen via shift+tab
  3. SidebarFullScreen screen pushed when sidebar enters fullscreen state
  4. PlansPanel and ProjectsPanel — collapsible panels inside the sidebar
  5. SessionTabs — multi-session tab bar (auto-shown when >=2 sessions)
  6. TuiMaterializerMaterializationStrategy implementation mapping ElementHandle events to Textual widgets
  7. Escape-cascading navigationescape always moves toward main screen
  8. Throbber — rainbow gradient animated bar at top (height: 1, visible when actor is processing)

What Currently Exists

The current app.py implements a minimal CleverAgentsTuiApp with:

  • A single #main-column vertical layout
  • A Static widget for conversation (no streaming, no block types)
  • No sidebar widget at all
  • No MainScreen class
  • No SidebarFullScreen, PlanDetailModal, ProjectDetailModal, PersonaEditorModal, SettingsScreen, SessionsScreen, or PermissionsScreen
  • No TuiMaterializer
  • No SessionTabs
  • No PlansPanel or ProjectsPanel
  • No throbber

The CSS (cleveragents.tcss) has no sidebar rules, no horizontal layout, and no three-state sidebar styling.

Impact

The TUI cannot fulfill its architectural role as a Presentation-layer surface. Without the sidebar and MainScreen, users cannot:

  • Monitor plan progress in real-time
  • Navigate between plans and projects
  • Use the fullscreen sidebar for persona/plan management

Metadata

  • Commit message: feat(tui): implement ADR-044 three-state sidebar and MainScreen architecture
  • Branch name: feat/tui-adr044-mainscreen-sidebar

Background and Context

ADR-044 was accepted on 2026-03-10 and defines the canonical TUI architecture for the CleverAgents project. The current app.py was scaffolded as a minimal placeholder and has not been updated to reflect the accepted ADR. This gap means the TUI milestone (v3.7.0) cannot be completed without implementing the full MainScreen + sidebar architecture as specified.

Expected Behavior

The TUI launches into a MainScreen with a horizontal layout. The sidebar is hidden by default. Pressing shift+tab cycles through hidden → visible → fullscreen. In fullscreen, the sidebar is pushed as a dedicated screen. escape cascades back toward the main screen. PlansPanel and ProjectsPanel are visible inside the sidebar when it is in the visible or fullscreen state. A throbber animates at the top when the actor is processing.

Acceptance Criteria

  • MainScreen class exists in src/cleveragents/tui/ with horizontal layout (conversation + sidebar)
  • SideBar widget has three states: hidden, visible, fullscreen
  • shift+tab cycles sidebar states as specified in ADR-044
  • escape from fullscreen returns to visible; second escape returns to hidden
  • PlansPanel and ProjectsPanel render inside the visible sidebar
  • SidebarFullScreen screen is pushed when sidebar enters fullscreen
  • TuiMaterializer handles all 9 ElementHandle types from ADR-044 Table
  • Throbber animates at 15fps when actor is processing
  • All pilot tests pass
  • nox passes with coverage >= 97%

Subtasks

  • Create MainScreen class with horizontal layout (conversation + sidebar)
  • Implement SideBar widget with three states: hidden, visible, fullscreen
  • Add shift+tab binding to cycle sidebar states
  • Implement PlansPanel and ProjectsPanel collapsible widgets inside sidebar
  • Implement SidebarFullScreen screen (pushed when sidebar enters fullscreen)
  • Implement SessionTabs widget (auto-shown when >=2 sessions)
  • Implement TuiMaterializer as a MaterializationStrategy for all ElementHandle types
  • Add throbber widget (rainbow gradient, height 1, visible when actor is processing)
  • Add escape-cascading navigation (escape always moves toward main screen)
  • Update cleveragents.tcss with sidebar layout rules and three-state styling
  • Add pilot tests for sidebar state transitions
  • Add pilot tests for shift+tab cycling behavior

Definition of Done

  • MainScreen class exists in src/cleveragents/tui/ with horizontal layout
  • SideBar widget has three states: hidden, visible, fullscreen
  • shift+tab cycles sidebar states as specified in ADR-044
  • escape from fullscreen returns to visible; second escape returns to hidden
  • PlansPanel and ProjectsPanel render inside the visible sidebar
  • SidebarFullScreen screen is pushed when sidebar enters fullscreen
  • TuiMaterializer handles all 9 ElementHandle types from ADR-044 Table
  • Throbber animates at 15fps when actor is processing
  • All pilot tests pass
  • nox passes with coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor
Worker: [AUTO-UAT-14]


Automated by CleverAgents Bot
Agent: new-issue-creator

## Summary ADR-044 (TUI Architecture and Framework) specifies a `MainScreen` with a **three-state collapsible sidebar** (hidden → visible → fullscreen) as a core architectural requirement. The current TUI implementation (`src/cleveragents/tui/app.py`) is missing this sidebar entirely. ## ADR Reference - **ADR:** [ADR-044 TUI Architecture and Framework](docs/adr/ADR-044-tui-architecture-and-framework.md) - **Status:** Accepted (2026-03-10) - **Milestone:** v3.7.0 (M8: TUI Implementation) ## Gap Description ### What ADR-044 Requires 1. **`MainScreen`** — A dedicated screen class (not just a generic `App.compose()`) with horizontal layout: conversation (flex 1fr) + sidebar (docked right) 2. **Three-state sidebar** — `SideBar` widget cycling through `hidden → visible → fullscreen` via `shift+tab` 3. **`SidebarFullScreen`** screen pushed when sidebar enters fullscreen state 4. **`PlansPanel`** and **`ProjectsPanel`** — collapsible panels inside the sidebar 5. **`SessionTabs`** — multi-session tab bar (auto-shown when >=2 sessions) 6. **`TuiMaterializer`** — `MaterializationStrategy` implementation mapping `ElementHandle` events to Textual widgets 7. **Escape-cascading navigation** — `escape` always moves toward main screen 8. **Throbber** — rainbow gradient animated bar at top (height: 1, visible when actor is processing) ### What Currently Exists The current `app.py` implements a minimal `CleverAgentsTuiApp` with: - A single `#main-column` vertical layout - A `Static` widget for conversation (no streaming, no block types) - No sidebar widget at all - No `MainScreen` class - No `SidebarFullScreen`, `PlanDetailModal`, `ProjectDetailModal`, `PersonaEditorModal`, `SettingsScreen`, `SessionsScreen`, or `PermissionsScreen` - No `TuiMaterializer` - No `SessionTabs` - No `PlansPanel` or `ProjectsPanel` - No throbber The CSS (`cleveragents.tcss`) has no sidebar rules, no horizontal layout, and no three-state sidebar styling. ### Impact The TUI cannot fulfill its architectural role as a Presentation-layer surface. Without the sidebar and `MainScreen`, users cannot: - Monitor plan progress in real-time - Navigate between plans and projects - Use the fullscreen sidebar for persona/plan management ## Metadata - **Commit message:** `feat(tui): implement ADR-044 three-state sidebar and MainScreen architecture` - **Branch name:** `feat/tui-adr044-mainscreen-sidebar` ## Background and Context ADR-044 was accepted on 2026-03-10 and defines the canonical TUI architecture for the CleverAgents project. The current `app.py` was scaffolded as a minimal placeholder and has not been updated to reflect the accepted ADR. This gap means the TUI milestone (v3.7.0) cannot be completed without implementing the full `MainScreen` + sidebar architecture as specified. ## Expected Behavior The TUI launches into a `MainScreen` with a horizontal layout. The sidebar is hidden by default. Pressing `shift+tab` cycles through `hidden → visible → fullscreen`. In fullscreen, the sidebar is pushed as a dedicated screen. `escape` cascades back toward the main screen. `PlansPanel` and `ProjectsPanel` are visible inside the sidebar when it is in the `visible` or `fullscreen` state. A throbber animates at the top when the actor is processing. ## Acceptance Criteria - `MainScreen` class exists in `src/cleveragents/tui/` with horizontal layout (conversation + sidebar) - `SideBar` widget has three states: `hidden`, `visible`, `fullscreen` - `shift+tab` cycles sidebar states as specified in ADR-044 - `escape` from fullscreen returns to visible; second `escape` returns to hidden - `PlansPanel` and `ProjectsPanel` render inside the visible sidebar - `SidebarFullScreen` screen is pushed when sidebar enters fullscreen - `TuiMaterializer` handles all 9 `ElementHandle` types from ADR-044 Table - Throbber animates at 15fps when actor is processing - All pilot tests pass - `nox` passes with coverage >= 97% ## Subtasks - [ ] Create `MainScreen` class with horizontal layout (conversation + sidebar) - [ ] Implement `SideBar` widget with three states: `hidden`, `visible`, `fullscreen` - [ ] Add `shift+tab` binding to cycle sidebar states - [ ] Implement `PlansPanel` and `ProjectsPanel` collapsible widgets inside sidebar - [ ] Implement `SidebarFullScreen` screen (pushed when sidebar enters fullscreen) - [ ] Implement `SessionTabs` widget (auto-shown when >=2 sessions) - [ ] Implement `TuiMaterializer` as a `MaterializationStrategy` for all `ElementHandle` types - [ ] Add throbber widget (rainbow gradient, height 1, visible when actor is processing) - [ ] Add escape-cascading navigation (escape always moves toward main screen) - [ ] Update `cleveragents.tcss` with sidebar layout rules and three-state styling - [ ] Add pilot tests for sidebar state transitions - [ ] Add pilot tests for `shift+tab` cycling behavior ## Definition of Done - [ ] `MainScreen` class exists in `src/cleveragents/tui/` with horizontal layout - [ ] `SideBar` widget has three states: `hidden`, `visible`, `fullscreen` - [ ] `shift+tab` cycles sidebar states as specified in ADR-044 - [ ] `escape` from fullscreen returns to visible; second `escape` returns to hidden - [ ] `PlansPanel` and `ProjectsPanel` render inside the visible sidebar - [ ] `SidebarFullScreen` screen is pushed when sidebar enters fullscreen - [ ] `TuiMaterializer` handles all 9 `ElementHandle` types from ADR-044 Table - [ ] Throbber animates at 15fps when actor is processing - [ ] All pilot tests pass - [ ] `nox` passes with coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor Worker: [AUTO-UAT-14] --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.7.0 milestone 2026-04-13 23:05:56 +00:00
Author
Owner

[AUTO-OWNR] Triage Decision (Cycle 18)

Status: Verified

MoSCoW: Must Have
Priority: Critical
Milestone: v3.7.0

Rationale: This is the foundational TUI architecture issue. ADR-044 defines the canonical TUI structure (MainScreen + three-state sidebar + TuiMaterializer) and the current implementation is a minimal placeholder that doesn't implement any of it. This is a comprehensive implementation task that covers the core TUI architecture. Without this, the entire v3.7.0 milestone cannot be completed.

Note: This issue covers the same scope as several previously filed issues (#8589 MainScreen, #8590 sidebar, #8442 TuiMaterializer). Implementation workers should coordinate to avoid duplicate work.

Next Steps: Implementation worker should pick this up as the primary v3.7.0 TUI architecture task.


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

## [AUTO-OWNR] Triage Decision (Cycle 18) **Status**: ✅ Verified **MoSCoW**: Must Have **Priority**: Critical **Milestone**: v3.7.0 **Rationale**: This is the foundational TUI architecture issue. ADR-044 defines the canonical TUI structure (MainScreen + three-state sidebar + TuiMaterializer) and the current implementation is a minimal placeholder that doesn't implement any of it. This is a comprehensive implementation task that covers the core TUI architecture. Without this, the entire v3.7.0 milestone cannot be completed. **Note**: This issue covers the same scope as several previously filed issues (#8589 MainScreen, #8590 sidebar, #8442 TuiMaterializer). Implementation workers should coordinate to avoid duplicate work. **Next Steps**: Implementation worker should pick this up as the primary v3.7.0 TUI architecture task. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

[AUTO-EPIC] Epic Assignment

This issue has been identified as a child issue of Epic #8086: TUI MainScreen & Sidebar State Management (M8) (v3.7.0).

This comprehensive implementation issue covers the full ADR-044 MainScreen + sidebar architecture, which is the core deliverable of Epic #8086.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

## [AUTO-EPIC] Epic Assignment This issue has been identified as a child issue of **Epic #8086: TUI MainScreen & Sidebar State Management (M8) (v3.7.0)**. This comprehensive implementation issue covers the full ADR-044 MainScreen + sidebar architecture, which is the core deliverable of Epic #8086. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Author
Owner

Epic Assignment [AUTO-EPIC-1]

This issue has been confirmed as a child of parent Epic #8086 (Epic: TUI MainScreen & Sidebar State Management) as part of the v3.7.0 TUI Implementation milestone.

Dependency Direction: This issue BLOCKS Epic #8086 (child blocks parent per project conventions).

Milestone: v3.7.0

This issue was created by [AUTO-UAT-14] and covers the full ADR-044 MainScreen + three-state sidebar architecture. It is the highest-priority item in Epic #8086.


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

**Epic Assignment [AUTO-EPIC-1]** This issue has been confirmed as a child of parent Epic #8086 (Epic: TUI MainScreen & Sidebar State Management) as part of the v3.7.0 TUI Implementation milestone. **Dependency Direction:** This issue BLOCKS Epic #8086 (child blocks parent per project conventions). **Milestone:** v3.7.0 ✅ This issue was created by [AUTO-UAT-14] and covers the full ADR-044 MainScreen + three-state sidebar architecture. It is the highest-priority item in Epic #8086. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#8761
No description provided.