T3 fork: Integrate workflow authoring, execution and attention into the client #3

Problem Statement

I want workflows to feel like part of T3 Code rather than a separate dashboard attached to it. A graph engine alone would still leave me switching between workflow definitions, agent conversations and status lists to understand what is running, which review is incomplete and what needs my attention.

The workflow UI needs to make sequences, report-driven decisions, bounded rework and parallel review understandable in one editor. During execution it must show the backend's recorded decisions and connect them to native threads, tool history, diffs, approvals and questions. It must remain coherent when connected to a remote environment, after restart or when the client and server have different plugin capabilities.

Solution

Implement workflow pages as the workflow plugin's client module, using the generic plugin host contribution points. Integrate a workflow library, one graph editor, Run workflow actions, a run view and an actionable attention list into the existing application shell. Associate ordinary T3 threads with their workflow context and retain their native conversation, tools, diffs and input handling.

The backend owns definition validity, execution state, accepted reports, selected routes and available actions. The client presents that state and submits explicit commands. The same graph presentation supports editing and read-only run history, with an accessible route list alongside the visual flow.

User Stories

1. As a user, I want to reach Workflows from the normal project navigation, so that I can find them without leaving the application.
2. As a user connected to several environments, I want the workflow page to show its environment and project, so that I know where work will run.
3. As a user, I want a library of saved and packaged workflows with search, so that I can reuse the process that fits my task.
4. As a user, I want invalid definitions to remain visible with their reason, so that I can repair them rather than wonder where they went.
5. As a workflow author, I want to create one Workflow without choosing a simple or advanced type, so that I can grow a sequence into a richer process.
6. As a workflow author, I want installed skills listed by their actual names for the selected environment/provider, so that my choices correspond to runnable capabilities.
7. As a workflow author, I want an inspector for agent instructions, provider, permissions, inputs and report fields, so that I can configure each step precisely.
8. As a workflow author, I want typed condition controls and a plain-language explanation, so that I can understand a route without writing expressions.
9. As a workflow author, I want ordered All/Any condition groups and an explicit Otherwise route, so that the editor represents the engine's actual decision rules.
10. As a workflow author, I want a Repeat a previous step action with Maximum repeats and At limit, so that bounded rework has an obvious direction and stop condition.
11. As a workflow author, I want repeat labels to distinguish the initial visit from repeats, so that Repeat once means exactly two total visits.
12. As a workflow author, I want parallel reviewer lanes with stable branch identities, so that separate instances of the same skill remain distinguishable.
13. As a workflow author, I want a visible Wait for all join and frozen review input, so that I understand what must finish before the decision.
14. As a workflow author, I want validation errors linked to their offending control, so that I can fix a graph without searching through YAML.
15. As a workflow author, I want import/export using the canonical backend format, so that visual and file-based authoring remain interchangeable.
16. As a workflow author, I want failed saves and version conflicts to preserve my draft, so that a connection problem does not erase my edits.
17. As a keyboard or touch user, I want to add, edit, connect and remove steps without dragging, so that the editor is usable with my input method.
18. As a user, I want to start a workflow from the project and workflow library, so that reusable execution is available where I already work.
19. As a user, I want to review the selected workflow revision, workspace and inputs before starting, so that the execution target is clear.
20. As a user, I want the same workflow selectable in scheduling controls, so that recurring work uses the same process as manual runs.
21. As a user, I want a run overview that summarizes current steps, branches and attention, so that I do not inspect every thread to understand progress.
22. As a user, I want to open a step's ordinary T3 thread, so that I can inspect native tools, messages, diffs and approvals in their existing views.
23. As a user, I want a thread to link back to its workflow run and attempt, so that I retain context while investigating agent work.
24. As a user, I want accepted reports distinguished from completed executions, so that an early report cannot look like a finished review.
25. As a user, I want partial parallel progress and every required branch visible, so that I can see why a join is still waiting.
26. As a user, I want route history to show accepted evidence, evaluated rules, selected edges and repeat counters, so that I can explain the actual path taken.
27. As a user, I want human gates and unresolved runs collected in an attention list, so that the next action is obvious.
28. As a user, I want native questions and approvals accessible from workflow attention, so that I resolve them through the correct existing controls.
29. As a user, I want stale review input and missing-report failures explained with relevant actions, so that I can recover deliberately.
30. As a user, I want cancel, resume, retry and gate decisions to reflect authoritative allowed actions, so that the UI cannot offer unsafe transitions.
31. As a user, I want page reloads, reconnects and server restarts to restore the same run trace and attention, so that my client is not the source of execution truth.
32. As a user, I want unread and snooze preferences separated from unresolved workflow decisions, so that acknowledging a thread does not approve the process.
33. As a user, I want clear unavailable/unsupported states when a plugin or environment is missing, so that cached UI cannot act on another server or an unsupported API.
34. As a user with many threads and runs, I want bounded lists and scoped live updates, so that workflows do not make the normal client sluggish.
35. As a fork maintainer, I want workflow UI components isolated from core client stores and navigation internals, so that upstream UI improvements remain practical to pull.

Implementation Decisions

• Dependencies and ownership: implement the client module of the workflow plugin after the plugin host and canonical backend contract exist. Consume only plugin APIs and host client/navigation/design interfaces. Register generic page, navigation, project run action, scheduling target, thread context/action and attention contributions. Core components must not import workflow domain code or contain special workflow rendering branches.
• Environment scope: every library, editor, start dialog, run view and action has an explicit environment and project target obtained through the host. Show that context in the normal shell. Preserve it in deep links, including run/node/attempt references. Verify plugin/API capabilities from that environment before querying or acting. An unavailable target shows its connection recovery state; it never falls back to another project, server or client-local filesystem.
• Library: show workflow name, description, concise step/review summary, saved revision and packaged/read-only status. Provide New workflow, Import YAML, search, Edit, Run and export actions where allowed. Packaged examples may be cloned for editing. Invalid catalog entries remain visible with their server parser/validation reason and an appropriate repair/import action. Provide useful empty, loading, load-error and Retry states without inventing runs or usage counts.
• One editor: New workflow asks for a name and opens one graph editor with Add a step. A simple sequence uses the same representation as decisions, repeats and parallel groups. At desktop widths use a step palette, flow and selected-item inspector. At narrow widths the palette and inspector become labeled sheets. Keep an always-available Route list with the same nodes, edges, direction and conditions in reading order. Pointer dragging is optional, not the only way to author the graph.
• Palette and agent inspector: offer Agent step, Check, Decision, Parallel group, Join, Human gate and End only when advertised by the backend. Agent controls cover label, provider/model, runtime mode, installed skill, instructions, input bindings, deadline and declared report fields. Every graph agent requires a structured report. Use actual environment/provider skill names and capabilities. Missing skills and unsupported reporting providers have actionable messages and block runnable save/start as the server contract dictates; no free-text skill name is treated as verified installation.
• Report fields and checks: edit boolean, string, finite number and enum fields with required/optional status and enum values. Field pickers for later decisions come from declared upstream report/check/join contracts. Do not derive fields from prose or arbitrary command output. Check controls expose command, intended workspace, timeout and declared retry behavior; check-result conditions use only the backend's published result fields.
• Decisions: ordered route cards have Match all/Match any, Add condition, Add group, typed field/operator/value and destination. Show a concise Reads as explanation of the actual predicate. The final card is Otherwise with a required destination. Only backend-supported comparisons appear; incompatible values are identified inline. Editing rule order changes first-match order visibly. No free-form expression editor or client-side choice of ordinary execution edges.
• Repeats: Add route includes Repeat a previous step. The inspector requires Return to, Maximum repeats and At limit, and explains that one repeat means one additional execution after the initial visit. Draw the return direction and label in the flow and route list. Removing a target exposes the dangling route as an error. Show the configured limit destination alongside the route; do not hide it behind a generic retry setting.
• Parallel authoring: add independently labeled reviewer branches, each with a stable identity, skill, focus/instructions, provider, declared inputs/report and review permission policy. Two branches can use the same skill. Display All N reviewers required and Join policy: Wait for all. Reference one frozen committed PR head for the group and show how isolated reviewer workspaces will be prepared. Branch removal must expose/repair any predicates referencing it. Do not add workflow budgeting or a new maximum-concurrency setting.
• Human gates and ends: Human gate configures the recorded user decision and its permitted approve/changes destinations. End configures an outcome from the backend contract. Human review is an actionable persisted state, not an invented successful terminal label. The example development workflow makes its final human gate visible. The UI has no auto-merge action.
• Validation: client validation provides timely feedback using the shared schema; server validation remains authoritative for publish/save and start. A Problems to fix list links each error to its node, route or inspector control. Cover missing target/fallback, unknown field/type, unsafe/unbounded cycle, missing repeat limit destination, dangling branch references, unsupported capability, invalid frozen input and unreachable end. Preserve server paths/reasons and distinguish warnings from blocking errors. Retain an invalid local draft while blocking its publication as runnable.
• Drafts, saving and files: show Unsaved changes, Saving and Saved revision. Protect unsaved navigation with Keep editing/Discard choices. Keep a recoverable local draft keyed by environment/project/workflow identity; it is editing state, not execution state. Save with the expected server revision, retain edits on request failure and offer reload/compare after a conflict rather than silently overwriting. Import parses into a candidate draft and must not replace the current draft on error. Export the canonical definition. Presentation/layout preferences cannot affect graph semantics or routing.
• Starting: offer Run workflow through the project and library contributions, with the same start dialog and service operation. Choose the saved definition/revision, task inputs and normal host workspace/provider options. For development runs default to a new primary worktree; review branches always follow the backend's frozen isolated workspace rule. Show a concise execution summary and current capability/validation problems. Persist a command ID for retries of one start request; a double click, lost response or reconnect opens the existing run. Starting again intentionally creates a new command/run. Do not change the normal chat composer into a workflow-only entry point.
• Schedules: let the existing schedule controls select the workflow plugin's registered target and required inputs. Show that a schedule dispatch starts a workflow and link each occurrence to its run. Distinguish dispatched from workflow completed/failed/awaiting review. Enable/pause/run-now use the host's existing schedule semantics. The client does not own timing, create another clock or pretend schedules run only while it is open.
• Run view: present the persisted definition snapshot in read-only flow mode. Replace the palette with Run steps and show the selected node/attempt's evidence in the inspector. The overview includes current state, start source, definition revision, workspace, active attempts, required reviews and next user action. For every visit show attempt identity, related thread, accepted-report status, execution status and stop reason. Avoid ambiguous percentages across optional branches; display concrete completed steps and required review counts.
• Native thread integration: a contributed context strip/badge on an owned thread identifies workflow, run, node/branch and attempt, with Open workflow run and View route actions. Run-step links open the existing thread view for its messages, native tools, diffs, checkpoints and input controls. Keep ordinary thread statuses, unread handling and native controls intact. A thread can retain its historical association after the workflow settles; a later manual message does not mutate the old workflow attempt.
• Report and route evidence: render bounded, redacted accepted report data as Agent report and check outputs as separate execution evidence. Show the persisted predicates considered, selected edge, repeat number/maximum, limit route and input references. Report acceptance is not a passed-tests badge. Never reconstruct route decisions from final prose or run the predicate evaluator in the client. A missing report states that no accepted report was received and routing stopped, with Open thread and allowed recovery actions.
• Join presentation: show each required branch as pending launch, running, reported/awaiting settlement, completed, failed, canceled, unresolved or stale according to server state. Show accepted-report count separately from settled-branch count. At 2/3 reports the decision remains pending. At 3/3 reports with one still-running execution it also remains pending. Only the persisted join result unlocks its next action/edge. Display frozen head, reviewer focus, child thread links, deadlines and the reason for an unsuccessful aggregate. An early changes verdict does not visually imply that remaining reviewers were canceled.
• Attention: provide a workflow attention view and a concise navigation count through the generic host slot. Group actionable items by workflow run with clear reasons such as Needs review, Needs input, Interrupted, Missing report or Review is stale. Link to the exact gate, attempt or native request. Count distinct runs requiring action; multiple branch requests remain visible within their run. Ordinary active work has progress but is not labeled as requiring a user decision. Attention is server-owned and remains after reload/restart until its underlying condition resolves.
• Attention actions: native approval/input cards open the existing thread controls, not a duplicate approval protocol. Human gates offer the backend's allowed Approve/request-changes actions against the displayed gate revision and frozen review reference. Unresolved attempts offer eligible Resume or Retry; a stale review offers rerun on the new verified head. Cancel names the affected run and its active attempts. Disable a submitted action until its idempotent result/reconciliation is known. Stale-action responses refresh state and explain the change while preserving user input.
• Unread and snooze: viewing the run, marking a thread read or snoozing its thread changes client/thread presentation only. It cannot accept a report, resolve a native request, approve a human gate or clear server-owned workflow attention. Preserve T3's existing native attention priorities and clearly distinguish unread information from an outstanding workflow decision.
• Connections and capability states: handle loading, empty results, permission denial, missing plugin, incompatible API, unavailable skill/provider, disconnected environment and server errors explicitly. Retain drafts and the last read snapshot with a visible stale/disconnected state. Mutation controls remain unavailable until connected and reconciled. A removed/downgraded plugin cannot leave cached actions callable. Other clients that cannot render plugin pages keep ordinary threads usable and provide only navigation/unsupported behavior covered by the host contract.
• Performance and accessibility: use bounded/paginated list queries and view-scoped run subscriptions. Share one attention controller per connected environment while needed, release it when no consumer needs it and avoid fetching all thread histories for counts. Coalesce updates using existing client mechanisms; no perpetual progress animation. Provide visible focus, semantic labels, textual status and direction, keyboard add/select/connect/reorder/remove actions and touch targets. Color and graph geometry cannot be the sole explanation of a route.
• Acceptance walkthrough: author implementation, checks, code/security/UX reviewers, Wait for all, a changes condition, Repeat implementation once and At limit: human review. Start it, inspect native threads, observe 2/3 and reported-but-running states, see the durable repeat decision, reach a human gate and resolve it. Repeat the walkthrough over an authenticated remote connection, including reload/reconnect, a changed PR head and an unresolved branch. Every displayed decision must match the backend trace.

Testing Decisions

• The primary seam is user behavior in the hosted workflow route and contributed entry points against the real workflow backend. Assert saves, start results, related native threads, persisted route evidence and attention/gate changes. Component-prop snapshots and tests that merely verify callback wiring are insufficient.
• Use the real registered plugin API, authorization, persistence and graph services. Provider processes/network and external systems may use deterministic replay; the client must read the resulting production-shaped state. Use server milestones and drainable workers for execution progress.
• Exercise one integrated authoring flow from an empty workflow through agent/skill selection, typed decision, All/Any nesting, Otherwise, repeat/limit destination and three reviewer branches. Test invalid targets/fields, removed branch references, unsupported capabilities, invalid YAML and expected-revision conflicts with retained drafts.
• Verify keyboard and touch-friendly route-list authoring can complete the same graph without dragging. Before committing to a canvas library, test whether a user can identify the direction of Repeat implementation once and explain the limit destination without coaching. Simplify the controls if this fails; do not conceal the problem with explanatory prose alone.
• Run an end-to-end deterministic workflow with real accepted reports. Assert the same library/project start behavior, one run after a repeated start request, native-thread backlinks, actual saved revision and persisted route history after refresh. Check presentation distinguishes accepted claims from check evidence and runtime settlement.
• Cover all join presentation boundaries: 2/3 reports, 3/3 with one execution still active, early changes verdict, successful wait-for-all, failed/missing/timed-out branch and changed/unverifiable PR head. Verify no premature decision or hidden sibling cancellation is implied.
• Test native approval/input navigation, human approval/changes, stale gate commands, cancel racing completion, eligible resume/retry and review rerun. Marking read or snoozing must leave unresolved workflow attention present; resolving the underlying state must clear the correct stable item.
• Test authenticated remote web and desktop-web behavior, two environments with similarly named projects, reconnect/server restart, capability downgrade and unavailable plugin. Assert deep links/actions remain target-bound and no mutation occurs on a fallback environment.
• Verify subscription cleanup and bounded attention/list behavior with representative multiple runs and threads. Reuse client-runtime connection/compatibility and sidebar attention prior art; add a real-client verification pass for the integrated flow rather than a separate browser test for every component. Use focused checks for changed scopes, with broader checks left to normal CI.

Out of Scope

• Implementing or duplicating the reporting, predicate, loop, recovery, scheduling-clock or join engine. Missing backend capabilities must be delivered by the backend spec before their controls are enabled.
• Redesigning the ordinary T3 conversation, tools, diffs, native approvals, settings or global sidebar behavior beyond the finite plugin contribution points.
• Full mobile graph editing or native React Native plugin pages in this first delivery. Responsive web and the desktop web shell are included.
• New budgeting/concurrency settings, automatic PR merge, free-form executable conditions or a model that guesses which route to show.
• A skills marketplace/installer and automatic conversion of Cezar's legacy workflow files or run history.
• Clearing workflow decisions through unread, snooze or client-local status inference.

Further Notes

This is specification 3 of 3. It depends on both the plugin-system spec and workflow backend spec. The backend schema and capability descriptor are authoritative; the UI must not introduce another graph model.

The interaction requirements adapt unified workflow builder #12 to T3's environment/project/thread vocabulary and plugin interface. The earlier Cezar issue remains unchanged. T3's existing thread sidebar behavior, composer skills, remote architecture and client capability negotiation are the surrounding behavior to preserve.

Deliver authoring/start/native-thread links and persisted run trace first, then parallel authoring/join evidence and the integrated attention/gate experience. Controls are enabled only when their backend capabilities exist. This sequence is implementation ordering within one coherent system, not separate workflow types for users.