feat: AEE Workbench GUI (specsmith gui)

Full PySide6 Qt6 desktop application launching via 'specsmith gui'.
Deep navy/teal/amber epistemic engineering aesthetic.

src/specsmith/gui/
  app.py          - QApplication bootstrap + launch() entry point
  main_window.py  - QMainWindow: tabbed sessions, new session dialog,
                    status bar (version + epistemic strip + update notif),
                    menu bar (Ctrl+T new tab, Ctrl+W close, Ctrl+Q quit)
  session_tab.py  - per-tab widget: tool panel + provider bar + chat +
                    token meter + input bar; optimize banner at 70% fill
  worker.py       - GUIAgentRunner(AgentRunner): routes output to Qt signals
                    instead of stdout; AgentWorker(QThread) runs turns off-UI
  theme.py        - QSS stylesheet (BG #0d1117, teal #0d9488, amber #d97706)
  widgets/
    chat_view.py      - HTML-rendered messages: user/assistant/tool/system/error
    input_bar.py      - multi-line input + Send + File + URL + drag-drop
    token_meter.py    - context fill bar (green/amber/red) + cost label
    tool_panel.py     - 12 specsmith tool buttons with pass/fail indicators
    provider_bar.py   - provider + model dropdowns, hot-swappable per tab
    update_checker.py - background QThread: silently upgrades dev versions

pyproject.toml:
  gui = ['PySide6>=6.6'] optional extra

cli.py:
  specsmith gui [--project-dir] [--provider] [--model]

docs/:
  REQ-GUI-001 through REQ-GUI-013 added to REQUIREMENTS.md
  GUI Workbench section added to architecture.md
  TEST-GUI-001 through TEST-GUI-013 added to TEST_SPEC.md

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

docs/REQUIREMENTS.md

@@ -305,3 +305,19 @@
 - **REQ-SCF-EPI-001**: `specsmith init` for epistemic project types renders 4 epistemic governance templates
 - **REQ-SCF-EPI-002**: `enable_epistemic=true` adds epistemic governance to any project type
 - **REQ-SCF-EPI-003**: Epistemic project types get domain-specific directory structures
+
+## GUI Workbench
+
+- **REQ-GUI-001**: `specsmith gui` launches a cross-platform Qt6 desktop workbench (Windows, Linux, macOS)
+- **REQ-GUI-002**: Workbench supports multiple independent agent sessions as tabs, each with its own project directory, provider, model, and conversation history
+- **REQ-GUI-003**: Chat view renders user, assistant, tool call, and system messages in visually distinct styles
+- **REQ-GUI-004**: Token meter displays context window fill percentage, input/output token counts, and estimated cost in real time
+- **REQ-GUI-005**: Optimization banner appears at 70% context fill with actionable suggestions (clear history, compress ledger, summarize session)
+- **REQ-GUI-006**: Tool panel provides one-click access to all specsmith tools (audit, validate, doctor, stress-test, epistemic-audit, belief-graph, export, trace-verify, req-list, req-gaps) with pass/fail indicators
+- **REQ-GUI-007**: File upload injects text files as inline context; images and PDFs are routed through Mistral OCR
+- **REQ-GUI-008**: URL injection fetches page content and injects it as context prefix
+- **REQ-GUI-009**: Background update checker silently installs newer specsmith versions on startup and shows a status bar notification
+- **REQ-GUI-010**: Provider and model can be switched per tab without restarting the session
+- **REQ-GUI-011**: Agent calls run in a background QThread so the UI never blocks
+- **REQ-GUI-012**: Epistemic status strip shows current certainty score, last audit result, and last validate result
+- **REQ-GUI-013**: Input bar supports keyboard shortcut (Ctrl+Enter) to send and drag-and-drop of files

docs/TEST_SPEC.md

@@ -538,3 +538,32 @@
   Covers: REQ-WFL-007
 - **TEST-WFL-010**: `specsmith session-end` reports unpushed commits and dirty files
   Covers: REQ-WFL-008
+
+### GUI Workbench
+
+- **TEST-GUI-001**: `specsmith gui` command is registered and exits cleanly when PySide6 not installed
+  Covers: REQ-GUI-001
+- **TEST-GUI-002**: `SessionTab` initialises a `GUIAgentRunner` with correct project dir and provider
+  Covers: REQ-GUI-002
+- **TEST-GUI-003**: `ChatView.append_user()`, `append_assistant()`, `append_tool()` produce distinct HTML
+  Covers: REQ-GUI-003
+- **TEST-GUI-004**: `TokenMeter.update()` updates bar value, token counts, and cost label
+  Covers: REQ-GUI-004
+- **TEST-GUI-005**: `TokenMeter` emits `optimize_suggested` signal when fill exceeds 70%
+  Covers: REQ-GUI-005
+- **TEST-GUI-006**: `ToolPanel` contains buttons for audit, validate, doctor, stress-test, and epistemic-audit
+  Covers: REQ-GUI-006
+- **TEST-GUI-007**: `InputBar.inject_file()` reads a text file and prepends content to input
+  Covers: REQ-GUI-007
+- **TEST-GUI-008**: `InputBar.inject_url()` fetches URL and prepends content to input
+  Covers: REQ-GUI-008
+- **TEST-GUI-009**: `UpdateChecker` emits `updated` signal when a newer version is detected
+  Covers: REQ-GUI-009
+- **TEST-GUI-010**: `ProviderBar` emits `provider_changed` and `model_changed` signals on selection
+  Covers: REQ-GUI-010
+- **TEST-GUI-011**: `AgentWorker` runs on a separate QThread and does not block the main thread
+  Covers: REQ-GUI-011
+- **TEST-GUI-012**: Status bar updates with epistemic score after each completed agent turn
+  Covers: REQ-GUI-012
+- **TEST-GUI-013**: Ctrl+Enter in `InputBar` triggers `send_requested` signal
+  Covers: REQ-GUI-013

docs/architecture.md

@@ -60,6 +60,22 @@ Re-exports all symbols from `epistemic`. Allows `from specsmith.epistemic import
 - **`runner.py`** — REPL loop, tool execution, streaming, session state, model routing
 - **`profiles/`** — Built-in skill profiles: planner, verifier, epistemic-auditor
 
+## GUI Workbench (`src/specsmith/gui/`)
+
+PySide6 (Qt6) desktop application launched via `specsmith gui` (see REQ-GUI-001 through REQ-GUI-013).
+
+- **`app.py`** — `QApplication` bootstrap, dark AEE theme (deep-navy/teal/amber), `launch()` entry point
+- **`main_window.py`** — `MainWindow`: `QTabWidget` with new-session dialog, global status bar, menu bar
+- **`session_tab.py`** — per-tab widget: assembles chat view, input bar, token meter, tool panel, provider bar
+- **`worker.py`** — `GUIAgentRunner(AgentRunner)` overrides `_print`/`_call_provider`/`_execute_tool_calls` to emit Qt signals; `AgentWorker(QThread)` runs agent turns off the UI thread
+- **`theme.py`** — QSS stylesheet: `#0d1117` background, teal accents, amber warnings
+- **`widgets/chat_view.py`** — `QTextBrowser` with HTML message rendering per role
+- **`widgets/input_bar.py`** — `QPlainTextEdit` + Send/File/URL buttons + drag-drop accept
+- **`widgets/token_meter.py`** — `QProgressBar` (green→yellow→red at 70%/90%) + cost label
+- **`widgets/tool_panel.py`** — collapsible sidebar with `QToolButton`s per specsmith tool
+- **`widgets/provider_bar.py`** — `QComboBox` for provider and model selection
+- **`widgets/update_checker.py`** — `QThread` that checks PyPI on startup and silently upgrades
+
 ## Verification Tools
 
 **Lint:** ruff check

pyproject.toml

@@ -59,6 +59,7 @@ anthropic = ["anthropic>=0.56"]
 openai = ["openai>=1.0"]
 gemini = ["google-generativeai>=0.8"]
 mistral = ["openai>=1.0"]  # Mistral uses the openai SDK pointed at api.mistral.ai
+gui = ["PySide6>=6.6"]
 # Install all optional LLM providers
 agent = ["anthropic>=0.56", "openai>=1.0"]
 # Convenience bundle: everything

src/specsmith/cli.py

@@ -2920,5 +2920,45 @@ def credits_check_cmd(project_dir: str) -> None:
         console.print(f"  [yellow]\u26a0[/yellow] {alert}")
 
 
+# ---------------------------------------------------------------------------
+# GUI Workbench
+# ---------------------------------------------------------------------------
+
+
+@main.command(name="gui")
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True),
+    default=".",
+    help="Project root to open as the first tab.",
+)
+@click.option(
+    "--provider",
+    "provider_name",
+    default=None,
+    help="Default LLM provider for new sessions.",
+)
+@click.option("--model", default=None, help="Default model for new sessions.")
+def gui_cmd(project_dir: str, provider_name: str | None, model: str | None) -> None:
+    """Launch the AEE Workbench — multi-tab epistemic engineering GUI.
+
+    Requires: pip install specsmith[gui]
+    """
+    try:
+        from specsmith.gui.app import launch
+    except ImportError:
+        console.print(
+            "[red]PySide6 is required for the GUI.[/red]\n"
+            "Install it: [bold]pip install specsmith[gui][/bold]"
+        )
+        raise SystemExit(1) from None
+
+    launch(
+        project_dir=str(Path(project_dir).resolve()),
+        provider_name=provider_name,
+        model=model,
+    )
+
+
 if __name__ == "__main__":
     main()

src/specsmith/gui/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""specsmith GUI — AEE Workbench.
+
+Launch with: specsmith gui
+Or programmatically: from specsmith.gui.app import launch; launch()
+
+Requires: pip install specsmith[gui]
+"""

src/specsmith/gui/app.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""specsmith GUI bootstrap — QApplication setup and launch() entry point."""
+
+from __future__ import annotations
+
+import sys
+
+
+def launch(
+    project_dir: str = ".",
+    provider_name: str | None = None,
+    model: str | None = None,
+) -> None:
+    """Launch the AEE Workbench.
+
+    Called by `specsmith gui` CLI command.
+    Blocks until the window is closed.
+    """
+    from PySide6.QtGui import QFont, QFontDatabase
+    from PySide6.QtWidgets import QApplication
+
+    from specsmith.gui.main_window import MainWindow
+    from specsmith.gui.theme import qss
+
+    app = QApplication.instance() or QApplication(sys.argv)
+    app.setApplicationName("specsmith AEE Workbench")
+    app.setOrganizationName("BitConcepts")
+
+    # Fusion style as the base (cross-platform, neutral widgets)
+    app.setStyle("Fusion")
+
+    # Apply AEE dark theme
+    app.setStyleSheet(qss())
+
+    # Font: prefer Inter/Segoe UI; fall back to system default
+    preferred_fonts = ["Segoe UI", "Inter", "SF Pro Text", "Helvetica Neue", "Arial"]
+    for font_name in preferred_fonts:
+        if font_name in QFontDatabase.families():
+            app.setFont(QFont(font_name, 12))
+            break
+
+    window = MainWindow(
+        project_dir=project_dir,
+        provider_name=provider_name,
+        model=model,
+    )
+    window.show()
+
+    sys.exit(app.exec())