ed/manual_slop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

conductor: Refine GUI UX track with full codebase knowledge, add doc references

Browse Source 
Rewrites comprehensive_gui_ux_20260228 spec and plan using deep analysis of
the actual gui_2.py implementation (3078 lines). The previous spec asked to
implement features that already exist (Track Browser, DAG tree, epic planning,
approval dialogs, token table, performance monitor). The new spec:

- Documents 15 already-implemented features with exact line references
- Identifies 8 actual gaps (tier stream panels, DAG editing, cost tracking,
  conductor lifecycle forms, track-scoped discussions, approval indicators,
  track proposal editing, stream scrollability)
- Rewrites all 5 phases with surgical task descriptions referencing exact
  gui_2.py line ranges, function names, and data structures
- Each task specifies the precise imgui API calls to use
- References docs/guide_architecture.md for threading constraints
- References docs/guide_mma.md for Ticket/Track data structures

Also adds architecture documentation fallback references to:
- conductor/workflow.md (new principle #9)
- conductor/product.md (new Architecture Reference section)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Edward R. Gonzalez
2026-03-01 09:51:37 -05:00
parent 08e003a137
commit d93f650c3a
5 changed files with 146 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
conductor/tracks/comprehensive_gui_ux_20260228/spec.md
View File

@@ -1,36 +1,99 @@
# Track Specification: Comprehensive Conductor & MMA GUI UX
## Overview
This track aims to implement a comprehensive, high-density, and tactile GUI for controlling all aspects of the Conductor orchestration and the 4-Tier Hierarchical Multi-Model Architecture (MMA). The focus is on providing the user with explicit, granular control over the entire lifecycle of a track, from initialization to task execution, with a "Manual First" philosophy.
This track enhances the existing MMA orchestration GUI from its current functional-but-minimal state to a production-quality control surface. The existing implementation already has a working Track Browser, DAG tree visualizer, epic planning flow, approval dialogs, and token usage table. This track focuses on the **gaps**: dedicated tier stream panels, DAG editing, track-scoped discussions, conductor lifecycle GUI forms, cost tracking, and visual polish.
## Current State Audit (as of 08e003a)
### Already Implemented (DO NOT re-implement)
- **Track Browser table** (`_render_mma_dashboard`, lines 2633-2660): Title, status, progress bar, Load button per track.
- **Epic Planning** (`_render_projects_panel`, lines 1968-1983 + `_cb_plan_epic`): Input field + "Plan Epic (Tier 1)" button, background thread orchestration.
- **Track Proposal Modal** (`_render_track_proposal_modal`, lines 2146-2173): Shows proposed tracks, Start/Accept/Cancel.
- **Step Mode toggle**: Checkbox for "Step Mode (HITL)" with `self.mma_step_mode`.
- **Active Track Info**: Description + ticket progress bar.
- **Token Usage Table**: Per-tier input/output display in a 3-column ImGui table.
- **Tier 1 Strategy Stream**: `mma_streams.get("Tier 1")` rendered as read-only multiline (150px).
- **Task DAG Tree** (`_render_ticket_dag_node`, lines 2726-2785): Recursive tree with color-coded status (gray/yellow/green/red/orange), tooltips showing ID/target/description/dependencies/worker-stream, Retry/Skip buttons.
- **Spawn Interceptor** (`MMASpawnApprovalDialog`): Editable prompt, context_md, abort capability.
- **MMA Step Approval** (`MMAApprovalDialog`): Editable payload, approve/reject.
- **Script Confirmation** (`ConfirmDialog`): Editable script, approve/reject.
- **Comms History Panel** (`_render_comms_history_panel`, lines 2859-2984).
- **Tool Calls Panel** (`_render_tool_calls_panel`, lines 2787-2857).
- **Performance Monitor**: FPS, Frame Time, CPU, Input Lag via `perf_monitor`.
### Gaps to Fill (This Track's Scope)
1. **Tier Stream Panels**: Only Tier 1 gets a dedicated text box. Tier 2/3/4 streams exist in `mma_streams` dict but have no dedicated UI. Tier 3 output is tooltip-only on DAG nodes. No Tier 2 (Tech Lead) or Tier 4 (QA) visibility at all.
2. **DAG Editing**: Can Retry/Skip tickets but cannot reorder, insert, or delete tasks from the GUI.
3. **Conductor Lifecycle Forms**: `/conductor:setup` and `/conductor:newTrack` have no GUI equivalents — they're CLI-only. Users must use slash commands or the epic planning flow.
4. **Track-Scoped Discussion**: Discussions are global. When a track is active, the discussion panel should optionally isolate to that track's context. `project_manager.load_track_history()` exists but isn't wired to the GUI.
5. **Cost Estimation**: Token counts are displayed but not converted to estimated cost per tier or per track.
6. **Approval State Indicators**: The dashboard doesn't visually indicate when a spawn/step/tool approval is pending. `pending_mma_spawn_approval`, `pending_mma_step_approval`, `pending_tool_approval` are tracked but not rendered.
7. **Track Proposal Editing**: The modal shows proposed tracks read-only. No ability to edit track titles, goals, or remove unwanted tracks before accepting.
8. **Stream Scrollability**: Tier 1 stream is a 150px non-scrolling text box. Needs proper scrollable, resizable panels for all tier streams.
## Goals
1. **Conductor Lifecycle Management:** Implement UI components for `/conductor:setup`, `/conductor:newTrack`, and a robust Track Browser.
2. **MMA Orchestration Dashboard:** Create a multi-viewport modular system for monitoring and managing the 4-Tier hierarchy.
3. **Task DAG Management:** Implement an interactive DAG visualizer that allows the user to reorder, insert, and delete tasks/tickets incrementally.
4. **Tier-Specific Discussion History:** Provide dedicated visual panels for each tier agent's (Orchestrator, Tech Lead, Worker, QA) discussion history and streaming output.
5. **Manual Execution Control:** Ensure every event, task transition, and sub-agent spawn requires manual user acceptance by default, with opt-in automation.
6. **Metrics & Observability:** Integrate real-time telemetry, token usage, and cost tracking for each tier and track.
1. **Tier Stream Visibility**: Dedicated, scrollable panels for all 4 tier output streams (Tier 1 Strategy, Tier 2 Tech Lead, Tier 3 Worker, Tier 4 QA) with auto-scroll and copy support.
2. **DAG Manipulation**: Add/remove tickets from the active track's DAG via the GUI, with dependency validation.
3. **Conductor GUI Forms**: Setup and track creation forms that invoke the same logic as the CLI slash commands.
4. **Track-Scoped Discussions**: Switch the discussion panel to track-specific history when a track is active.
5. **Cost Tracking**: Per-tier and per-track cost estimation based on model pricing.
6. **Approval Indicators**: Clear visual cues (blinking, color changes) when any approval gate is pending.
7. **Track Proposal Editing**: Allow editing/removing proposed tracks before acceptance.
8. **Polish & Density**: Make the dashboard information-dense and responsive to the MMA engine's state.
## Functional Requirements
- **Track Browser:** A central hub for viewing, selecting, and managing implementation tracks.
- **Interactive Task DAG:** A node-based UI (using Dear PyGui) for visualizing task dependencies. Users can manually manipulate the graph (reorder, add, remove nodes).
- **Tier History Panels:** Separate viewing modes for the logs/discussions of each tier agent.
- **Execution Clutch:** A global toggle for "Step Mode" vs. "Auto-Queue", with the default being manual step-through.
- **Spawn Interceptor:** An improved modal for reviewing and editing worker prompts/context before they are dispatched.
- **Observability Widgets:** High-density monitors for FPS, CPU, and API metrics (latency, token burn, cost).
### Tier Stream Panels
- Four collapsible/expandable text regions in the MMA dashboard, one per tier.
- Auto-scroll to bottom on new content. Toggle for manual scroll lock.
- Each stream populated from `self.mma_streams` keyed by tier prefix.
- Tier 3 streams: aggregate all `"Tier 3: T-xxx"` keyed entries, render with ticket ID headers.
### DAG Editing
- "Add Ticket" button: opens an inline form (ID, description, target_file, depends_on dropdown).
- "Remove Ticket" button on each DAG node (with confirmation).
- Changes must update `self.active_tickets`, rebuild the ConductorEngine's `TrackDAG`, and push state via `_push_state`.
### Conductor Lifecycle Forms
- "Setup Conductor" button that reads `conductor/workflow.md`, `conductor/tech-stack.md`, `conductor/product.md` and displays a readiness summary.
- "New Track" form: name, description, type dropdown. Creates the track directory structure under `conductor/tracks/`.
### Track-Scoped Discussion
- When `self.active_track` is set, add a toggle "Track Discussion" that switches to `project_manager.load_track_history(track_id)`.
- Saving flushes to the track's history file instead of the project's.
### Cost Tracking
- Model pricing table (configurable or hardcoded initial version).
- Compute `cost = (input_tokens / 1M) * input_price + (output_tokens / 1M) * output_price` per tier.
- Display as additional column in the existing token usage table.
### Approval Indicators
- When `_pending_mma_spawn` is not None: flash the "MMA Dashboard" tab header or show a blinking indicator.
- When `_pending_mma_approval` is not None: similar.
- When `_pending_ask_dialog` is True: similar.
- Use `imgui.push_style_color` to tint the relevant UI region.
### Track Proposal Editing
- Make track titles and goals editable in the proposal modal.
- Add a "Remove" button per proposed track.
- Edited data flows back to `self.proposed_tracks` before acceptance.
## Non-Functional Requirements
- **Arcade Aesthetics:** Use blinking notifications, visceral color-coded feedback (Ready, Running, Blocked, Done), and high-contrast visuals (USA Graphics style).
- **Asynchronous Responsibility:** The UI must remain responsive during multi-model generation using the `AsyncEventQueue`.
- **Modular Layout:** Support for docking, floating, and rearranging all Conductor/MMA windows.
- **Thread Safety**: All new data mutations from background threads must go through `_pending_gui_tasks`. No direct GUI state writes from non-main threads.
- **No New Dependencies**: Use only existing Dear PyGui / imgui-bundle APIs.
- **Performance**: New panels must not degrade FPS below 30 under normal operation. Verify via `get_ui_performance`.
## Acceptance Criteria
- Users can initialize and manage tracks entirely through the GUI.
- The Task DAG accurately reflects the state of the active track and allows manual editing.
- Each tier agent's history is viewable in a dedicated panel.
- The "Manual Acceptance" flow is enforced for all MMA actions by default.
- API metrics and telemetry are visible and update in real-time.
## Architecture Reference
- Threading model and `_process_pending_gui_tasks` action catalog: [docs/guide_architecture.md](../../docs/guide_architecture.md)
- MMA data structures (Ticket, Track, WorkerContext): [docs/guide_mma.md](../../docs/guide_mma.md)
- Hook API for testing: [docs/guide_tools.md](../../docs/guide_tools.md)
- Simulation patterns: [docs/guide_simulations.md](../../docs/guide_simulations.md)
## Out of Scope
- Automated "Auto-Fix" loops without user intervention.
- Remote management via web browser (staying local GUI for now).
- Automated "Auto-Fix" loops without user intervention.
- Remote management via web browser.
- Visual diagram generation (Dear PyGui node editor for DAG — future track).
- Docking/floating multi-viewport layout (requires imgui docking branch investigation — future track).