Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
da93ad5
ui(plans): phased plans, build specs, and review ledger for the workf…
looksystems Aug 26, 2026
eb6ad7c
ui(design): components-and-layouts spec with intent traceability
looksystems Aug 26, 2026
e844378
ui(design): fold the round-5 design review into the components spec
looksystems Aug 26, 2026
0f27da2
ui(phase-0): monorepo, shared schemas, bridge core — engine adapter, …
looksystems Aug 26, 2026
42d9638
ui(phase-0): replay engine, fixture converter, CI skeleton, packaging…
looksystems Aug 26, 2026
a62ad43
ui(phase-0): mid-discussion fixture (recorded), goldens, and the defe…
looksystems Aug 26, 2026
3177a22
ui(phase-0): fold the round-6 adversarial review — six defects fixed,…
looksystems Aug 26, 2026
953935a
ui(phase-1): the mirror — read-only API layer + SPA (lobby, channel, …
looksystems Aug 26, 2026
8444946
ui(phase-1): fold the round-7 adversarial review — five defects fixed…
looksystems Aug 26, 2026
46c93ed
ui(phase-2): SDK spike results + the gate parser with its adversarial…
looksystems Aug 26, 2026
14a09e5
ui(phase-2): session manager, journal projections, lease, trust bound…
looksystems Aug 26, 2026
7b5e2df
ui(phase-2): the gate UI — GateCard, queue (S2), thread (S4), session…
looksystems Aug 26, 2026
48cf5d4
ui(phase-2): done-means run — the permission stack measured into shap…
looksystems Aug 27, 2026
4bb2f8b
ui(phase-2): fold the round-8 adversarial review — security stack har…
looksystems Aug 27, 2026
8d00ac4
ui(phase-3): the attention system — policy, notifier, escalation, dig…
looksystems Aug 27, 2026
37ffd92
ui(phase-3): SPA attention surfaces — DigestCard, EscalationChip, TOD…
looksystems Aug 27, 2026
3f40934
ui(phase-3): the fixture-day done-means as a deterministic test
looksystems Aug 27, 2026
e0c9b4b
ui(phase-3): fold the round-9 review — the coordinator wiring overhau…
looksystems Aug 27, 2026
108113b
ui(phase-4): bridge structure extractors + history lens + roadmap route
looksystems Aug 27, 2026
412a3ce
ui(phase-4): the SPA lenses — LensTabs, per-type rails, claim chips, …
looksystems Aug 27, 2026
551692c
ui(phase-4): epic topic derivation for structure — the spec sign-off …
looksystems Aug 27, 2026
b16b85b
ui(phase-4): history hardening + fold the round-10 review — 6 defects…
looksystems Aug 27, 2026
83354c4
ui(phase-5): telemetry source inventory + manifest-sourced loop telem…
looksystems Aug 27, 2026
11da935
ui(phase-5): SPA delivery surfaces — TelemetrySurface, ConsolidationC…
looksystems Aug 27, 2026
cb2bdd3
ui(phase-5): fix the staging shape — the real field is staging.{cycle…
looksystems Aug 27, 2026
049995c
ui(phase-5): fold round-11 review — topic-scoped plan format, phase-s…
looksystems Aug 27, 2026
bb68c34
ui(phase-6): multiplayer — auth, gate ownership, capture gesture, pre…
looksystems Aug 27, 2026
7db8f43
ui(phase-6): fold round-12 review — membership gating, resolver sound…
looksystems Aug 27, 2026
edbbfda
ui(phase-7): MCP Apps distribution — workflow MCP server, card/queue …
looksystems Aug 27, 2026
0a6d830
ui(phase-7): fold round-13 review — widget interactivity, stdio cap, …
looksystems Aug 27, 2026
afb1552
ui(fix): SessionThread hooks-order crash (React #310) — found via bro…
looksystems Aug 27, 2026
99d11cd
ui(fix): capture popover clipped off-screen + palette missing Queue/R…
looksystems Aug 27, 2026
835a9f2
ui(feat): shared ChatInput component + file attachments (materialize …
looksystems Aug 27, 2026
72e05e7
ui(fix): fold attachment upload security review — membership gate, re…
looksystems Aug 27, 2026
b55c539
ui(feat): calm working indicator while an answered turn is in flight
looksystems Aug 27, 2026
3130f70
ui(fix): resume affordance for an interrupted (dead, no-gate) session
looksystems Aug 27, 2026
adc8206
chore(ui): gitignore the local ui/demo test-harness project
looksystems Aug 27, 2026
81bcb45
Merge branch 'leeovery:main' into ui-pr
looksystems Aug 27, 2026
ea6d936
docs(ui): bring the README up to date (phases 0–7)
looksystems Aug 27, 2026
83b2ba3
docs(ui): add design artefacts + reference them in the README
looksystems Aug 27, 2026
a48470e
ui(fix): render the thread conversation as markdown
looksystems Aug 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .github/workflows/ui.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# UI test lanes — phase-0 §7 (CI skeleton). Runs on every commit touching
# ui/**; never touches the product's own npm test gates.
name: ui

on:
push:
paths:
- 'ui/**'
- '.github/workflows/ui.yml'
pull_request:
paths:
- 'ui/**'
- '.github/workflows/ui.yml'

jobs:
test:
runs-on: ubuntu-latest
defaults:
run:
working-directory: ui
steps:
- uses: actions/checkout@v4
with:
# The version handshake and spine tests read git history/tags.
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- uses: pnpm/action-setup@v4
with:
version: 10
- run: pnpm install --frozen-lockfile
- run: pnpm typecheck
- run: pnpm test
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,6 @@
node_modules/
.npm-cache/
.workflows/.knowledge/store.msp

# Local test-harness workflow project (not part of the UI deliverable)
/ui/demo/
5 changes: 5 additions & 0 deletions ui/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
node_modules/
dist/
bridge-state/
*.tsbuildinfo
.tmp/
149 changes: 149 additions & 0 deletions ui/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Workflow Bridge UI

The web UI for the agentic-workflows process — a read-only-first veneer over a
project's `.workflows/`, git, and the engine's in-process `lib.cjs`. It adds no
new workflow state: everything renders from the engine, gates are never guessed,
and never-auto gates require a typed confirm. Plans and specs live in
[`plans/`](plans/) — start at [`plans/README.md`](plans/README.md) (the intent
baseline); the phase-by-phase review history is in
[`plans/REVIEW.md`](plans/REVIEW.md).

Implemented across phases 0–7: **rails** (event model, spine, watcher, version
handshake) · **mirror** (the read-only SPA) · **gates** (sessions, the needs-you
queue, threads) · **attention** (escalation, digests) · **artifact lenses**
(Read/Structure/History) · **delivery telemetry** · **multiplayer** (auth,
ownership, capture, presence, comments) · **MCP Apps** (the gate card inside
Claude).

## Design artefacts

Self-contained HTML design/presentation pages (open directly in a browser) —
snapshots of the visual language and screen designs the build follows:

- [`artefacts/the-workflow-bridge.html`](artefacts/the-workflow-bridge.html) —
the overview: what the bridge is and the design intent behind it.
- [`artefacts/workflow-bridge-screens.html`](artefacts/workflow-bridge-screens.html)
— the screen mockups (lobby, channel, queue, thread, lenses, and the rest).
- [`artefacts/agentic-workflows-field-guide.html`](artefacts/agentic-workflows-field-guide.html)
— a field guide to the workflow system the bridge surfaces.

## Layout

- `bridge/` — the bridge daemon: turns the project's existing surfaces (engine
`lib.cjs`, manifests, git, presence, the agent store) into a typed event
stream, drives headless workflow sessions, serves the SPA, and hosts the MCP
server (`bridge mcp`).
- `app/` — the SPA (React + Vite): lobby, channels, the needs-you queue, session
threads, artifact lenses, delivery telemetry, and the multiplayer surfaces
(identity, gate ownership, the capture gesture, presence, comments).
- `shared/` — the gate-card schema and event vocabulary as zod schemas, frozen
at the end of Phase 2.
- `fixtures/` — replay fixtures per `plans/specs/fixture-format.md`. Recorded
through the harness, never hand-edited (the authored `fixtures/adversarial/`
corpus is the one carve-out).

## Running

Prototype distribution is a repo checkout. Build once so the bridge can serve
the SPA, then run it against a project:

```sh
cd ui && pnpm install && pnpm build # build the SPA + packages

# Live mode — stream a real project's domain events and serve the app:
pnpm bridge -- --project /path/to/project

# Replay mode — stream a recorded fixture:
pnpm bridge -- --replay fixtures/mid-discussion

# Convert a terminal-driven session into a fixture (spec 4, Phase 0 form):
pnpm --filter @workflow-ui/bridge exec tsx src/cli.ts convert \
--session ~/.claude/projects/<proj>/<session>.jsonl \
--out ../fixtures/my-fixture --world-from /path/to/project
```

Open **http://127.0.0.1:4870/** for the app (it follows live over SSE); the
observability console is at `/debug`. During UI development, `pnpm --filter app
dev` runs Vite with HMR against a running bridge.

- **Engine discovery**: `<project>/.claude/skills/workflow-engine/scripts/`
(dev-repo fallback: `<project>/skills/workflow-engine/scripts/`). Override
with `--engine <path>`.
- **Width pin**: every engine invocation pins `WORKFLOWS_DISPLAY_WIDTH=65` —
renders are terminal-width-sensitive; unpinned output encodes whatever width
was detected.
- **Config file**: `~/.config/workflow-bridge/config.json` (override with
`--config <path>`), schema in `shared/src/config.ts` — projects, width pin,
notification settings (quiet hours, escalation, roll-up, stuck/grace), auth
mode, port, daily budget warning. Argv flags override per run.
- **Bridge state**: UI-native SQLite lives OUT of tree at
`~/.cache/workflow-bridge/<project>-<hash>/` (override with `--state-dir`).
The bridge never writes into `.workflows/` — the one exception is a chat
attachment, materialized into the gitignored `.workflows/.cache/` so the
session's Read tool can pick it up (transient user-input-in-transit, not
bridge state).
- **Debug console**: `http://127.0.0.1:4870/debug` — health/banner, event stream
(live vs durable), structured logs, cost counters. `/health`, `/events` (SSE,
`?since=<seq>`), `/costs`, `/logs` are named surfaces the SPA is built on.

### Sessions and API keys (Phase 2+)

The bridge drives headless workflow sessions — answering gates, the capture
gesture, resuming an interrupted session — one SDK query per human turn, with a
programmatic permission policy (allowlisted Bash, project-confined file writes,
non-Anthropic secrets redacted). The Anthropic API key resolves from the
environment (`ANTHROPIC_API_KEY`) or the OS keychain — **never the browser,
never this repo** — following the product's own credentials doctrine
(`~/.config/workflows/credentials.json`, mode 0600; keys never transit chat or
argv).

### Auth (Phase 6)

Single-user mode is **zero-config** — every request is the sentinel human
("You"), and the per-install bearer token is the whole trust boundary. Multi-user
mode (`auth.mode: "github"` in the config, with `auth.repo`) authenticates via a
GitHub login and treats **push access to the origin repo as membership**, checked
at login and cached per auth session. Gate ownership, comments, and capture are
**UI-side routing, never process authority** — the engine enforces none of it,
and a terminal answer bypasses the UI entirely (resolving the card as "answered
outside the UI"). The OAuth redirect flow is deployment wiring; the prototype
ships the identity + member-check contract it wraps (see `plans/REVIEW.md`).

### MCP server (Phase 7)

`bridge mcp` exposes the gate card and the needs-you queue to an MCP host (Claude
web/desktop) as a **third client of a running bridge** — no second card
implementation, the frozen `shared/` schema rendered as `ui://` resources:

```sh
WORKFLOW_BRIDGE_TOKEN=<install token from GET /api/token> \
pnpm --filter @workflow-ui/bridge exec tsx src/cli.ts mcp \
--bridge-url http://127.0.0.1:4870
```

In github mode also set `WORKFLOW_BRIDGE_COOKIE` (a per-user auth cookie).
Typed-confirm (never-auto) gates require a UI-origin gesture and render read-only
in the MCP widget with a deep link to the SPA — a plain model tool call answering
one is rejected at the bridge.

### Version handshake

The bridge reads the installed product's version from its git tag and declares a
supported range; outside it — or on a repo with pending migrations (diff of
`.workflows/.state/migrations` against the install's migrations directory) — it
degrades to **read-only raw-embed mode with a banner and no events**. The bridge
never runs migrations; that is `workflow-start`'s boot, in a session. Both
detection mechanisms are fragile by design and are replaced when the proposed
read-only currency verb lands (`plans/UPSTREAM.md` #2). Shallow/grafted clones
degrade to live-only mode (no durable spine).

## Tests

```sh
pnpm test # all packages (vitest)
pnpm typecheck # tsc --noEmit
pnpm build # shared + the SPA
```

UI tests are self-contained — they never touch the product's `npm test` gates.
CI runs `.github/workflows/ui.yml` on every commit touching `ui/`.
12 changes: 12 additions & 0 deletions ui/app/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>workflow bridge</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
38 changes: 38 additions & 0 deletions ui/app/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
{
"name": "@workflow-ui/app",
"private": true,
"version": "0.0.0",
"description": "The SPA — Phase 1: the read-only mirror.",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"test": "vitest run",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@workflow-ui/shared": "workspace:*",
"clsx": "^2.1.0",
"cmdk": "^1.0.4",
"mermaid": "^11.4.0",
"react": "^18.3.0",
"react-dom": "^18.3.0",
"react-markdown": "^9.0.0",
"react-router-dom": "^6.28.0",
"remark-gfm": "^4.0.0",
"shiki": "^1.24.0"
},
"devDependencies": {
"@testing-library/react": "^16.1.0",
"@types/react": "^18.3.0",
"@types/react-dom": "^18.3.0",
"@vitejs/plugin-react": "^4.3.0",
"autoprefixer": "^10.4.20",
"jsdom": "^25.0.0",
"postcss": "^8.4.49",
"tailwindcss": "^3.4.15",
"typescript": "^5.6.0",
"vite": "^6.0.0",
"vitest": "^2.1.0"
}
}
6 changes: 6 additions & 0 deletions ui/app/postcss.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
export default {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
};
Loading