orchestra/orchestra-ui-spec.md

orchestra web control ui

status: mockup specification app: orchestra shared design system: ethos accent: signal violet #8F7AE5 motif: routing fork primary operator: single infrastructure operator

1. purpose

orchestra's web ui is an operator console for understanding and steering agent work without reconstructing state from logs, tmux sessions, gitea, or the event stream.

it has three jobs:

1. show what needs the operator now.
2. show what orchestra believes and what an agent is actually doing.
3. expose intervention and forensic detail without making the default screens noisy.

it is not a generic project-management product, an analytics dashboard, or a chat-first interface.

2. ethos application

orchestra inherits the ethos shell and neutral system unchanged.

fingerprint

• accent: signal violet #8F7AE5
• motif: routing fork
• accent use: active navigation, focus, selected phase, primary operator action, routing/transition marks
• motif use: app mark, phase transitions, routing state, empty states, one hero/detail moment

suggested token block:

[data-app="orchestra"] {
  --accent:      #8F7AE5;
  --accent-hi:   #A291EC;
  --accent-dim:  rgba(143, 122, 229, 0.14);
  --accent-line: rgba(143, 122, 229, 0.32);
  --accent-glow: rgba(143, 122, 229, 0.22);
}

type

• geist sans: labels, task names, explanations, buttons, headings, operator-authored prose
• geist mono: task ids, epochs, worker ids, pane ids, timestamps, percentages, context counts, revisions, paths, refs, sha values, lease durations
• machine values must never silently use sans for visual convenience

surfaces

• page room: --bg-0
• normal panel: --bg-1
• selected/raised content: --bg-2
• hover: --bg-3
• borders: 1px --line, --line-hi only where selection or risk needs stronger separation
• no blur or glass
• accent never washes a whole content panel

motion

all ui transitions use ethos mechanical motion: 130–170 ms, cubic-bezier(0.2, 0, 0, 1), no spring or bounce.

3. shared shell

desktop

• 64px vertical icon rail
• 56px top bar
• main content fills remaining viewport
• global cmd+k command/search surface in the top bar
• right side of top bar shows only high-value machine state: orchestra revision, live state, current time

primary navigation:

1. dashboard
2. tasks
3. decisions
4. workers
5. projects
6. review
7. settings

terminal is entered from a task or worker and does not need permanent primary navigation.

mobile

• rail becomes bottom navigation with no more than five primary items
• secondary pages move behind task/project drill-down or header menus
• machine readouts relocate into detail screens rather than disappearing
• terminal remains a dedicated full-screen view

4. information hierarchy

orchestra should visually distinguish five classes of information.

class	meaning	treatment
operator authority	human decision, correction, constraint	high prominence, accent signal
verified orchestra state	lifecycle, lease, phase, review, refs	neutral surfaces, machine values in mono
agent claims	proposed plan, handoff text, self-reported risk	visibly labeled as agent-supplied
historical/superseded	stale plan, previous handoff, old decision	muted, never visually dominant
fault/attention	blocked, refused, stale, mismatch	status color + explicit reason

raw events and implementation details are drill-down evidence, not default-page content.

5. dashboard

mockup: final/01-dashboard.png

purpose: answer "what needs me, what is running, and is the system healthy?"

layout

three primary regions only:

1. needs your attention

   • trajectory gate
   • blocking human decision
   • pr awaiting review
   • closed-without-merge/operator-required state
   • one line explaining why each item needs the operator

2. running tasks

   • task name/id
   • current phase
   • worker/harness
   • last real progress
   • context occupancy
   • lease timing
   • compact routing-fork phase indicator

3. system state and capacity

   • workers online/available
   • quota status
   • active leases
   • router queue/rejection state
   • source reconciliation
   • herdr health

rules

• no disk, cpu, ram, or generic host-monitor metrics unless they directly block orchestration
• no vanity charts
• health should show actual counts/times, not vague "running" indicators
• dashboard actions should navigate to the relevant task/review/worker rather than becoming an operator-control surface itself

6. tasks list

mockup: final/04-tasks.png

purpose: browse all work under orchestra and locate a task quickly.

groups

• needs attention
• running
• waiting/queued
• completed
• failed

row fields

• task title/id
• project
• current phase
• compact routing-fork phase path
• worker/harness when assigned
• last update/progress
• context occupancy for active sessions
• status

filters

• project
• phase
• worker/harness
• status
• attention state

avoid turning this into a kanban board. orchestra's lifecycle is stateful and event-backed; the list should expose state, not encourage arbitrary drag-and-drop mutation.

7. task detail

mockup: final/02-task-detail.png

purpose: provide one calm page answering "what are we doing?", "what is happening?", and "where are we in the workflow?"

top area

• title
• task id
• project
• current phase
• steer/correct primary action
• secondary actions menu

what we're doing

show only:

• goal
• acceptance summary
• latest effective human decisions when present
• active constraints when present

full contract, all decisions, and historical versions open in drill-down views.

live execution

show only:

• worker/harness
• pane
• lease remaining
• context occupancy
• last progress
• one-line current activity

links:

• open live pane
• worker logs
• launch context
• git diff

workflow

render the ace-fca path visibly:

frame → research → plan → implement → review → pr → merged

completed phases are quiet green, current phase uses the orchestra accent, future phases remain neutral.

phase detail, artifacts, refusal history, and raw events belong in drill-downs rather than the default task screen.

8. live pane / terminal

mockup: final/03-terminal-live-pane.png

purpose: show the actual tmux/herdr pane, not a reconstructed log view.

behavior

• read-only by default
• exact pane dimensions and terminal rendering preserved when possible
• fit mode may scale visually but must not alter the underlying pane
• scrollback inspection must not disturb the live cursor
• take control explicitly enables keyboard forwarding
• strong visual state when control is captured
• escape or a fixed shortcut releases control

why this screen exists

it must reveal real tui state such as:

• input still sitting in the editor
• queued input
• paste placeholders
• permission/approval dialogs
• /clear
• @HANDOFF.md
• agent busy/idle presentation
• tmux status line and pane identity

surrounding chrome

keep it minimal:

• worker/pane identity
• read-only/control state
• fit/copy/scrollback controls
• lease epoch/timing
• context occupancy
• last verified progress
• pane/worker health
• small live event strip for orchestra-originated interactions and confirmations

when a pane is lost, preserve the last captured frame and state the exact loss time and lease consequence.

9. decisions list

mockup: final/05-decisions.png

purpose: inspect durable human authority and approvals across tasks.

this is not the human attention queue; that is review.

list fields

• decision id
• short decision text
• task
• phase
• source/provenance
• requested/recorded time
• status: active, superseded, waiting, approved, rejected, auto
• operator/actor

filters

• active/superseded
• kind: decision, correction, constraint, answer, scope change
• project
• task
• actor/source

detail

opening a decision should show:

• exact value
• subject
• provenance
• supersedes/superseded-by links
• event sequence
• effective authority impact

machine provenance is mono; the human decision text remains sans.

10. workers

mockup: final/06-workers.png

purpose: answer "where can work run and is that execution machinery usable?"

worker list fields

• worker/harness identity
• online/idle/busy/offline/degraded
• harness type
• current task when leased
• phase
• lease or heartbeat age

intentionally omit generic infrastructure metrics such as disk, memory, cpu, and uptime unless orchestra directly uses them for eligibility.

worker detail

• current session/task
• pane id
• lease epoch/remaining
• last verified progress
• worker revision
• herdr status
• last heartbeat
• projects declared by the worker
• declared capabilities if orchestra actually consumes them

capabilities

capabilities must come from worker registration/project configuration, never be guessed from host inspection.

the ui labels them declared capabilities and can expose registration provenance.

registration

registration is worker-driven:

1. worker starts with coordinator credentials/configuration
2. worker announces identity, revision, harnesses, projects, capacity and declared capabilities
3. coordinator records it and heartbeat updates liveness

add worker should therefore be a registration guide/bootstrap flow, not a magical browser-side creation of a remote process.

11. projects

mockup: final/07-projects.png

purpose: group long-running repository/workflow configuration and its active work.

project list

• project name
• short description
• state
• active/total task count
• attention/decision count
• last meaningful activity

avoid aggregate artifact counts or infrastructure metrics unless they help choose an action.

project detail

• description
• source/repository identity
• configured worker/harness affinity
• workflow phases
• trajectory-gate policy
• quality gate
• human reconcile source
• safe-operation policy
• active tasks
• recent meaningful events

configuration edits belong in the project detail, while global defaults remain in settings.

12. review

mockup: final/08-review.png

purpose: the operator inbox: what needs me to look at something and judge?

workers show machinery. review shows human attention.

review item types

• trajectory decision
• human blocker / decision request
• code/pr review
• ai review requiring operator override
• operator-required lifecycle state
• closed pr without merge
• information/fyi, optionally hidden by default

list fields

• type
• task/item
• why it is here
• project
• priority
• age

worker/pane is secondary metadata, not a primary column.

detail drawer/page

show the minimum evidence needed to act:

• why this needs the operator
• effective task goal/constraints relevant to the decision
• proposed options when applicable
• relevant plan/diff/review evidence
• provenance and age
• comments/context drill-down

primary action names must match the lifecycle action: make decision, answer blocker, review pr, request changes, retry, etc.

snooze/defer may exist for attention management but must not silently mutate underlying task truth.

13. settings

mockup: final/09-settings.png

purpose: configure orchestra itself, project-independent defaults, integrations, policies, and operator/security settings.

tabs

1. general
2. appearance
3. notifications
4. access & security
5. integrations
6. agents & tools
7. policies
8. advanced

general

• instance name/environment
• locale/time display
• default task preferences
• default workflow policy
• event/artifact retention
• storage/backup state only if orchestra owns it

appearance

• theme: system/dark/light
• ethos remains fixed; no arbitrary shell redesign controls
• accessibility and reduced motion

access & security

• surface tokens/status
• trusted review actors
• ignored actors
• operator sessions
• agent-surface auth
• secret/config source status without exposing secret values

integrations

• gitea
• vikunja
• notification sinks
• source reconciliation state

show endpoint/identity and last successful interaction in mono.

agents & tools

• harness definitions
• adapter/runtime configuration
• tmux/herdr ownership
• default launch behavior
• context occupancy thresholds

policies

• work phase defaults
• trajectory gate
• bounded decision request budget
• retry policy
• reconcile failure handoff threshold
• quality/review/submission policy

advanced

• event-store diagnostics
• snapshots/replay
• raw configuration
• migration/status information
• destructive operator actions in a visually separated danger zone

14. global command surface

cmd+k is the shared ethos command surface and should handle navigation plus safe operator actions.

examples:

• open task by id/title
• open worker/pane
• show decisions for task
• steer/correct active task
• answer current blocker
• retry failed task
• open review item

high-risk lifecycle actions require explicit confirmation and should not be the first fuzzy-search result for ordinary text.

15. status grammar

status is compact and consistent across screens.

recommended semantic colors:

• green: verified healthy/completed/accepted
• violet: current/selected/orchestra-controlled active state
• amber: waiting/degraded/operator attention
• red: failed/refused/danger
• gray: idle/unknown/historical

color never carries the entire meaning; every state also has text/iconography.

16. evidence drill-down

any important derived claim should be traceable without ssh.

from relevant detail screens the operator should be able to reach:

• event(s) that established the state
• exact generated launch context
• sealed research/plan/review/submission artifact refs
• git sha/ref
• worker journal observations
• input confirmation receipt
• pane capture/terminal
• source comment/review provenance

raw evidence is accessible but not visible by default.

17. copy rules

• labels describe what the operator controls, not implementation class names
• machine values remain exact and honest
• errors state what failed and what consequence follows
• no "something went wrong"
• no spinner where a queue depth, heartbeat age, poll timestamp, retry time, or progress value exists

examples:

• source reconcile failed · retry at 14:06:00
• worker heartbeat 42s old · ineligible after 60s
• phase request refused · next phase is research
• pane lost at 13:42:18 · lease expires in 09:14

18. responsive behavior

tablet/mobile priorities

keep visible:

1. attention state
2. task title/phase
3. latest human authority
4. live execution state
5. primary action

collapse or drill down:

• long acceptance lists
• complete workflow history
• detailed lease metadata
• worker journal
• raw events
• project configuration

terminal becomes its own full-screen route and should not be squeezed into a card.

19. implementation order

recommended web-ui build order:

1. ethos shell + orchestra tokens/motif
2. dashboard
3. tasks list
4. task detail
5. live pane
6. review inbox
7. decisions list/detail
8. workers
9. projects
10. settings
11. global command surface
12. evidence/raw-event drill-down

build each screen against real orchestra api data rather than static ui-only state as early as practical.

20. verification

for every screen:

• render and visually inspect pixels
• check desktop and <=640px mobile layout
• assert no horizontal overflow
• verify mono/sans split visibly
• verify accent is signal-only
• verify no blur/backdrop-filter exists
• verify empty/error/loading states show real machine state
• compare implemented screen against the corresponding mockup as direction, not pixel-perfect contract

mockups communicate hierarchy, density, and interaction intent. orchestra state and the ethos design laws are the actual specification.