PRD: Symphony Console as the primary native operator surface

[gannonh]

Problem Statement

Kata is moving toward a model where the CLI is an i/o and skills layer that can work with any agent harness, while Symphony owns orchestration across tracker-backed work. The current product shape splits that operator experience across the Symphony Rust TUI and the Electron Desktop Kanban/dashboard surface. That split creates duplicated product energy and pushes rich orchestration workflows toward a web-style UI even though the real documents and project records already live in Linear, GitHub, and future backends such as Asana and Jira.

Users need a satisfying, keyboard-native, terminal-based way to monitor, steer, recover, and understand Symphony runs without relying on Desktop as the primary surface. They also need this work to preserve future frontend flexibility for Kata Cloud, web dashboards, or a native desktop shell by defining clean domain and application boundaries rather than coupling the TUI directly to orchestration internals.

Solution

Evolve the current Symphony TUI into Symphony Console: the primary native operator surface for Kata orchestration. Symphony Console should provide terminal-based agent chat, rich live monitoring, workflow board views, run drilldowns, escalation handling, artifact visibility, harness health, and recovery actions.

The Console should consume an explicit Symphony operator API rather than reaching directly into orchestration internals. The same API should be suitable for future frontends, including Kata Cloud, a web dashboard, or a desktop shell. Desktop can remain available during transition, but the next product investment should prioritize Symphony Console first and decide later whether Desktop still needs to exist.

User Stories

1. As a Kata operator, I want Symphony Console to be the primary place I monitor active runs, so that I can manage agent work without opening Desktop.
2. As a Kata operator, I want a keyboard-native run board, so that I can scan work by workflow state quickly.
3. As a Kata operator, I want to see Todo, In Progress, Agent Review, Human Review, Merging, Rework, Done, and terminal states in one console, so that the orchestration lifecycle is visible at a glance.
4. As a Kata operator, I want to filter runs by tracker backend, state, label, assignee, harness, and project, so that I can focus on the work that needs intervention.
5. As a Kata operator, I want to drill into a selected run, so that I can see its prompt, current status, recent events, artifacts, and last error.
6. As a Kata operator, I want live event streaming in the Console, so that I can understand what agents are doing in real time.
7. As a Kata operator, I want token and event throughput indicators, so that I can tell whether the system is active, stalled, or overloaded.
8. As a Kata operator, I want stale-run detection, so that I can intervene before work silently hangs.
9. As a Kata operator, I want to respond to escalations from the Console, so that agents can continue without switching tools.
10. As a Kata operator, I want to steer an active run from the Console, so that I can redirect work without restarting it.
11. As a Kata operator, I want retry and recovery actions in the Console, so that I can quickly handle transient failures.
12. As a Kata operator, I want to pause and resume workers, so that I can control concurrency during incidents or high-priority work.
13. As a Kata operator, I want to inspect worker health, so that I can diagnose capacity, harness, or environment issues.
14. As a Kata operator, I want to inspect harness health for pi, Claude Code, Codex, and future harnesses, so that I can identify whether a failure is orchestration-related or harness-related.
15. As a Kata operator, I want the Console to support the pi default harness cleanly, so that the current direction of the CLI and skills layer is reflected in the operator surface.
16. As a Kata operator, I want third-party harnesses to appear through the same run and event model, so that switching harnesses does not fragment the UI.
17. As a Kata operator, I want artifact links surfaced in run detail, so that I can open PRs, tracker issues, comments, and generated plans from the terminal.
18. As a Kata operator, I want copied artifact URLs and identifiers to be easy to access, so that I can paste them into external systems.
19. As a Kata operator, I want a compact command palette, so that common actions are discoverable without memorizing every keybinding.
20. As a Kata operator, I want a terminal-based agent chat area, so that I can converse with the harness while staying inside the Console.
21. As a Kata operator, I want chat and run monitoring to coexist, so that I can ask for help while watching execution state.
22. As a Kata operator, I want Console state to update from the same event stream as any other frontend, so that the TUI is not a special case.
23. As a Kata Cloud developer, I want Symphony to expose a frontend-neutral operator API, so that a cloud UI can be built later without rewriting orchestration logic.
24. As a Desktop maintainer, I want Desktop to consume the same operator API if it remains, so that Desktop does not duplicate Symphony behavior.
25. As a Symphony maintainer, I want orchestration logic separated from presentation logic, so that Console features can be tested without terminal rendering.
26. As a Symphony maintainer, I want read models for run lists and run details, so that UI clients can query stable shapes instead of reconstructing state from raw internals.
27. As a Symphony maintainer, I want commands such as steer, retry, pause, resume, and respond to escalation represented as application actions, so that all frontends share the same behavior.
28. As a backend adapter developer, I want Linear, GitHub, Asana, and Jira to map into the same domain concepts, so that Console behavior does not depend on a specific tracker.
29. As a harness adapter developer, I want pi, Claude Code, Codex, and future harnesses to map into the same session/event model, so that Console behavior does not depend on a specific CLI.
30. As a user working over SSH, I want the Console to remain fully useful in a terminal, so that I can operate Kata from remote environments.
31. As a user who prefers native tools, I want Symphony Console to feel polished and intentional, so that Kata has a distinctive terminal-native product identity.
32. As a team lead, I want to monitor multiple active agents from one terminal view, so that I can coordinate work without visiting every tracker issue.
33. As a team lead, I want to see bottlenecks and blocked work, so that I can unblock agents and humans faster.
34. As a release owner, I want Merging and Agent Review states to be prominent, so that completion and review work does not get lost.
35. As a user, I want the Console to degrade gracefully in small terminals, so that it remains usable in constrained environments.
36. As a user, I want sensible defaults and keyboard hints, so that the Console is usable without reading documentation first.
37. As a user, I want errors to show actionable recovery options, so that failures do not become terminal dead ends.
38. As a user, I want Console state to survive refreshes and reconnects where possible, so that transient terminal or server interruptions do not lose context.
39. As a future web frontend developer, I want the operator API documented and stable, so that Kata Cloud can build on it confidently.
40. As a product maintainer, I want Desktop investment to pause until Symphony Console proves the core interaction model, so that effort is concentrated on the native operator experience first.

Implementation Decisions

• Treat Symphony Console as a first-class bounded context for the operator experience, not as incidental TUI rendering near the orchestrator.
• Keep Symphony as the source of truth for orchestration, worker lifecycle, tracker polling, harness execution, escalations, artifacts, and event streams.
• Define a frontend-neutral operator API with read/query operations and command/action operations. Candidate operations include list runs, get run detail, stream events, respond to escalation, steer run, retry run, pause worker, resume worker, open artifact, set workflow state, and inspect harness.
• Introduce stable read models for run summaries, run details, worker summaries, queue state, escalation inbox, artifact references, harness health, reliability signals, and throughput metrics.
• Make the Ratatui Console consume the operator API rather than directly coupling to orchestration structs, except for short-lived migration adapters during early development.
• Preserve frontend flexibility by ensuring Desktop, Kata Cloud, and future web/native clients can consume the same API contracts as the Console.
• Keep Linear and GitHub as existing document/workflow backends, and design backend adapter boundaries so Asana, Jira, and future trackers can map into the same domain model.
• Keep the CLI/skills layer harness-agnostic: pi is the default harness, but Claude Code, Codex, and future harnesses should map into the same session, event, artifact, and health abstractions.
• Prioritize Console workflows that are hard to perform from tracker UIs: live monitoring, intervention, recovery, harness inspection, and orchestration health.
• Treat external trackers as the durable document and collaboration systems. Symphony Console should link to and summarize those documents rather than becoming a rich document editor.
• Defer major Desktop feature work until Symphony Console validates whether Desktop is still needed.
• Avoid modeling the Console as a web UI inside a terminal. Optimize for keyboard-first terminal workflows, dense information layout, modal command flows, and focused drilldowns.
• Extract deep modules around operator read models, operator actions, event projection, harness health normalization, and tracker-agnostic workflow mapping so they can be tested independently of Ratatui rendering.

Testing Decisions

• Good tests should verify externally observable behavior: operator API responses, command outcomes, event projection, state transitions, filtering, escalation handling, and harness/backend normalization. Tests should not assert Ratatui layout implementation details unless rendering behavior itself is the user-visible contract.
• Test the operator read model projector with representative orchestration snapshots, worker states, event streams, escalations, artifacts, stale runs, and completed runs.
• Test the operator action service for steer, retry, pause, resume, escalation response, refresh, and workflow-state mutation behavior using fake orchestration ports.
• Test backend adapter normalization for Linear and GitHub, and add contract tests that future Asana/Jira adapters must pass.
• Test harness normalization for pi, Claude Code, Codex, and any future harnesses using fixture event streams and known failure cases.
• Test Console interaction state separately from terminal rendering: selected run, filters, command palette actions, detail pane mode, escalation drafts, and reconnect behavior.
• Add focused Ratatui snapshot/render tests only for stable, high-value views such as the run board, selected-run detail, escalation inbox, and status bar.
• Reuse prior art from Symphony’s current TUI tests for throughput, status coloring, stale-session presentation, and dashboard truncation.
• Reuse prior art from Desktop’s Kanban/dashboard tests for workflow board normalization, summary stats, escalation responses, and reliability surfacing.
• Add integration tests for the operator API over HTTP/WebSocket so non-TUI clients can rely on the same contracts.

Out of Scope

• Rebuilding Desktop in this phase.
• Building Kata Cloud or a web dashboard in this phase.
• Creating a rich document editor for Linear, GitHub, Asana, or Jira content.
• Replacing external trackers as the durable source of truth for issues, project documents, comments, or PRs.
• Committing to Warp as the foundation for the next Desktop version.
• Implementing every future tracker backend during the initial Symphony Console work.
• Implementing every third-party harness integration before the Console API and interaction model are proven.
• Perfect visual parity between the Console and the existing Electron Desktop Kanban/dashboard.

Further Notes

This PRD follows the product direction discussed in planning: finish the new CLI/skills work, update Symphony for the new tools and third-party harnesses, then invest heavily in Symphony Console before bringing Desktop along. The intended product identity is a terminal-native agent operations system: rich enough to be satisfying and powerful in Rust/Ratatui, but abstracted cleanly enough that Kata Cloud or another frontend can reuse the same domain/application API later.

[coderabbitai]

🔗 Related PRs

#97 - [kata/M001/S06] M001/S06: Orchestrator Core [merged]
#143 - feat: add Symphony Ratatui terminal dashboard (--tui) [merged]
#274 - docs(online-docs): finalize Kata Desktop docs language for shipped M001–M004 scope [merged]
#299 - Desktop v0.2.0 — Windows & Linux platform support [merged]
#333 - KAT-2705: align Symphony GitHub execution contract with CLI semantics [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!