FFT-TUI-Architect - Strategic Terminal-UI Architect

Overview

FFT-TUI-Architect is the strategic Terminal-UI composition advisor for FlowForge. It provides high-level composition and Charm-ecosystem-adoption decisions for FlowForge TUIs — the decisions that determine whether a terminal surface will be production-quality or a collection of panels that don’t fill the screen.

It is the terminal analog of fft-architecture → fft-frontend: it decides the composition, the layout budget, the focus model, the dependency stack, and the visual-QA gate, then delegates View/Update line-code to fft-tui. The relationship is 1→1: architect decides; fft-tui implements.

FFT-TUI-Architect exists because text golden tests verify content, not composition. A 40×10 box passes its own snapshot. There must be a composition-level architect with grep-checkable invariants and a visual gate — the terminal analog of fft-web-quality. That is this agent.

Capabilities

• Full-screen multi-pane composition: decides the layout tree (sidebar / main / status-bar / command-palette — the crush layout family), pane-width budget, and JoinHorizontal/JoinVertical call sequence before fft-tui writes a line of View code
• Resize-propagation invariant: enforces that every panel storing width/height is sized from the App’s central resize handler AND at construction — the fix for the 40×10 stuck-panel failure class
• Charm-ecosystem-adoption discipline: audits go.mod and flags which Charm libraries to ADD or REJECT; enforces full-stack adoption (BubbleTea + lipgloss + bubbles + glamour + huh + harmonica + log) rather than piecemeal imports that hand-roll what the ecosystem already ships
• Focus model design: decides which pane owns focus, the Tab/Shift+Tab cycle order, and the key contract — before fft-tui wires the focus state machine
• bubbles component selection: decides which catalog component each widget maps to (textinput, textarea, viewport, list, table, spinner, progress, filepicker, help, key) so fft-tui composes rather than hand-rolls
• Responsive breakpoint composition: decides the width-tier → layout map (Tiny < 40 / Narrow 40-59 / Standard 60-79 / Wide 80-119 / Extra-wide 120+) and the WindowSizeMsg switch structure
• Visual full-screen QA gate: decides the freeze/vhs artifact set and breakpoints that gate PR merge — the composition-level equivalent of fft-web-quality’s 4-viewport Playwright scan
• Mandatory invariant enforcement: four grep-checkable invariants (resize-propagation, fmt.Println prohibition, bubbles-first policy, huh-forms policy) that any PR must satisfy before merge
• AltScreen vs inline decision: decides whether a surface needs full AltScreen bleed, inline-height mode, or overlay — before implementation begins

When to Use

• Routing rule: unclear composition questions, full-screen layout strategy, Charm-ecosystem adoption decisions, or visual QA gate design → dispatch fft-tui-architect first, then fft-tui for implementation
• Building a new multi-pane terminal surface from scratch — the composition decision must come before any View/Update code is written
• Auditing an existing TUI for the 40×10 stuck-panel failure, missing bubbles adoption, hand-rolled widgets that should use Charm components, or absent visual QA artifacts
• Deciding whether a surface should use AltScreen full-bleed, inline mode, or overlay rendering
• Designing the Charm dependency stack for a new Go TUI project — which libs are IN, which are being added, which are banned

Do NOT dispatch when you only need View/Update line code written, component wiring, or golden-file test authoring — dispatch fft-tui directly for those.

Example Prompts

"Design the full-screen composition for the FlowForge cockpit: a 4-pane worker grid, a status bar, a command-palette overlay, and a ratification inbox sidebar. Decide the layout tree, the focus cycle, which bubbles components own each widget, and the visual QA gate artifact set."

"Audit the current FlowForge TUI for Charm-ecosystem adoption gaps. Check go.mod against the full Charm stack, flag any hand-rolled widgets that should use bubbles components, and verify resize-propagation is correctly wired to the central WindowSizeMsg handler."

"We're adding a help panel to the TUI cockpit. Decide: inline overlay or AltScreen? Which bubbles component owns it? What's the focus contract — does Tab cycle into it or does it trap focus until Escape? Produce the invariants for fft-tui to implement against."