feat(workflows): browse, author, and save workflows in one editor

[Igloczek]

Closes #25 · Parent spec #3 · Stack layer 1/5 (base: main)

Problem

Workflows had a durable backend and plugin host but no client: no way to find, author, save, repair, or exchange workflow definitions from T3 Code.

Maintainer redesign (after browser review)

The maintainer reviewed the first version in a browser and rejected it. The flow was a numbered list padded with explanatory prose instead of a graph, and none of the pages looked like part of T3 Code. Commits 4133b84ffd and a0ee50612e redo the UI (1378313b15/fd28b30446 before the rebase):

• Graph editor: React Flow (@xyflow/react) with a top-to-bottom dagre layout. Steps are nodes, and every route is a labelled edge. A repeat route is a backward edge labelled repeat ×N, and its At-limit destination is a dashed at limit edge. Parallel reviewers are sibling nodes between the fork and the join. A route to a missing step points at a dashed "missing" card. The graph lays out again only when the structure changes, not on every keystroke, and it refits when the canvas is resized. It is lazy-loaded with the editor page.
• Editor layout: an Add-step palette, the canvas, and an inspector panel. A Graph | Routes | YAML switch keeps the keyboard Route list and the canonical YAML available.
• Native chrome: the page header has the breadcrumb [project ▾] / Workflows / {title}, one primary action and a … menu. The library uses settings-style card rows, and empty and error states use the app's components. Explanatory prose was removed.
• Navigation: plugin navigation is a sidebar icon button beside Settings, Pull Requests and Usage. It opens in the current project, and its active state comes from the route. Plugin chat-header actions are icon buttons.
• Generic host contract additions: PageHeader/breadcrumb, ListGroup/ListRow, Menu, SegmentedControl, Alert, Empty, Icon, a fixed host icon set for navigation and actions, and the row button size.

What this adds

• Library (sidebar navigation + project header action): target-bound environment/project, search and paging across the whole catalog, step/review summary, saved revision, packaged/read-only status, invalid/duplicate entries with their authoritative reason and Repair / Import replacement.
• One editor: name prompt → palette / flow / inspector with an always-available Route list; keyboard (no-drag) create, select, connect, reorder (Alt+Arrow), remove (Delete) for reported Agent and End steps; canonical entry, whole-run visit bound and At limit. Narrow widths use labeled host sheets. Later-ticket node kinds stay visible and read-only.
• Agent inspector: provider/model/options from the selected environment's discovery and reporting matrix, runtime/interaction mode, installed skill select (no free-text claims), instructions, deadlines, typed upstream bindings, declared report fields.
• Canonical authoring path: authorized read/save/replace/export; protected (redacted) values become fingerprint-bound placeholders that cannot overwrite the original; staged YAML import; fingerprint-bound repair; ID-collision conflicts that point at the ID field.
• Drafts and validation: bounded per-environment/project/workflow local drafts (listed in the library, flushed on pagehide, quota-safe), Keep editing / Discard guard, conflict reload/compare, structured server problems with severity and control focus, truthful loading/disconnected/unsupported/catalog-unavailable states with Retry.
• Generic host facilities only (verified through the plugin fixture): bounded page-link state, draft store, navigation guard, design/discovery interfaces, lazy plugin pages; core navigation/stores contain no workflow branches. Authoring discovery uses cached (non-fresh) skill snapshots; save/start still rescans.

Validation

Rebased onto main (55df74e33b) on 2026-10-10. 5e79aeb23a adds scrollbar-gutter-both to the centered plugin scrollers, which main's new require-centered-scroll-gutter lint rule requires. After the rebase, vp fmt --check, vp run lint, the t3... typecheck, the CI smoke tests and vp run --filter t3 build all pass. The plugin-workflows and apps/web/src/plugins unit tests pass 40/40. Five WorkflowsMissingReportTime tests (expected 'running' to be 'launching') also fail on plain main, so this PR doesn't cause them.

Earlier runs (before the rebase):

• Server (Bun): WorkflowsAuthoring, WorkflowsAuthoringDiscovery, WorkflowsAuthoringRedaction, WorkflowsCatalog*, Workflows, WorkflowsValidation, … — all pass.
• Web integration (Bun, real servers, authenticated WebSocket, two similarly named environments): 5/5 files pass, incl. WorkflowAuthoring.integration.test.tsx and fixture PluginPage.integration.test.tsx.
• Unit: plugin-workflows/src/web + apps/web/src/plugins 22/22 after the redesign (includes flowGraph.test.ts); earlier apps/web/src/plugins 13/13, plugin-host-adapter 12/12.
• Typecheck clean for touched packages; lint/fmt clean on changed files.

Independent review

Rounds 6–7 reviewed the redesign. Round 6 approved 1378313b15 with four minor findings:

• a relayout on every keystroke;
• a decodeURIComponent crash on malformed URLs;
• the projects-error Retry lost when a project is selected;
• the narrow breadcrumb.

All four were fixed. Round 7 then gave APPROVED fd28b304466fbd44771863a9295f53c8629606b7. The approved code is unchanged, now a0ee50612e after the rebase onto main, plus the lint-only commit 5e79aeb23a. One nit remains: a mouse focus on a step at the canvas edge also pans to it.

Rounds 1–5 by a separate Claude Opus 5.5 reviewer: All BLOCKER/MAJOR findings were fixed: duplicate-ID dead end, unrecoverable new drafts, fresh provider refresh while typing, plugin Tailwind classes not compiled, and stale status labels. Those rounds approved d80dcd1153 (pre-redesign). Two non-material NITs remain (draft-index rollback edge case; wording of the "plugin missing from catalog" message).

UI evidence (real browser, isolated dev state)

The redesign was checked in a real browser (agent-browser, isolated dev server) on the library, the editor graph, step selection, the narrow 390 px layout, dark mode and the sidebar entry from a thread. Before/after screenshots are being attached separately.

Earlier pass:
Verified in the T3 Browser panel against an isolated dev server and a scratch project:

• library
• new workflow → editor
• narrow Inspector sheet with real provider discovery
• Base UI provider select showing which providers can't report
• save writing canonical YAML to .t3code/workflows/browser-check-flow.yaml

The pass found the desktop three-column layout collapsing. Cause: Tailwind @source globs don't expand plugin packages. Fixed in f02a23f and confirmed by compiling the CSS: the rule is emitted, 19 plugin files are scanned. Screenshots are being attached separately. The post-fix desktop screenshot is still pending because the preview host was unavailable.

Limitations

• The canonical schema has no description field, so the library shows the name and step summary.
• Compare is two YAML panes side by side, not a structured diff.
• Library/read/save re-scan the catalog per call (no cache).
• A new plugin package needs its own @source line in apps/web/src/index.css.

Implemented by Claude Opus 5.5 implementation agents and reviewed by an independent Claude Opus 5.5 agent (gilfoyle), orchestrated in Claude Code running in T3 Code.

🤖 Generated with Claude Code

[Igloczek]

UI evidence for #25, captured by the primary agent in the native T3 Browser against isolated development state.

Before: origin/main fc7f811de9, without the Workflows library/editor.

After: the workflow library on the proposed authoring layer. Native still captures are 640×400.

Pending Save verification (4450d43e9b): inputs, palette and keyboard removal stay frozen until the actual backend request settles.

iglo-pr30-save-freeze-4450d43e9b.mp4

Delayed Reload verification (9a920ce2a4): typing remains available; releasing the actual read request preserves the newer displayed and recovered draft. A later unsuperseded Reload succeeds.

iglo-pr30-reload-guard-9a920ce2a4.mp4

These are local proposed-head checks; they do not claim remote/tunnel coverage or approval of the current remote head. Temporary browser instrumentation was removed and the primary agent’s fixtures were deleted. Independent review confirmed the product race fixes; the remaining authoring walkthrough test-fixture correction is in progress.

Primary verification and evidence upload: GPT-6.1-Sol, Codex harness in T3 Code.