Workflow boards: kanban state machines that drive coding agents

[ccdwyer]

Workflow Boards

Per-project kanban boards as event-sourced state machines that drive coding agents. Lanes hold pipelines of steps (agent / script / approval / merge); routing between lanes is decided by step outcomes, JSONLogic predicates over captured output, lane fallbacks, manual actions, or external webhook events. Every ticket gets its own git worktree, every move is audited and explained.

All screenshots below are from a live run on a mock project ("Snackbase"): the board's agent steps run GPT-5.5 at different reasoning levels per lane (planning = low, implementation = medium with escalation to extra-high on retry, review = high ×3 reviewers), and the "Fix off-by-one" ticket was driven through the pipeline by real agents.

The board

Lanes with per-lane colors and WIP limits, tickets with status stripes, dependency badges ("waiting on 1 dependency"), token budgets ("0 tok / 250k"), and usage roll-ups.

Creating a ticket: description, blocked-by dependencies, and an optional token budget that halts agent steps once spent.

Intake: braindump → tickets

Paste a braindump, pick the agent (provider/model + reasoning effort), and it proposes structured tickets — including dependency edges ("After #1") — which you edit and approve before anything is created. These proposals came from a real GPT-5.5 run.

The workflow editor

Canvas view: lanes as cards, steps typed and colored, routing edges colored by outcome (success/failure/blocked), numbered transitions, dotted action edges, routing-precedence legend. Edits are drag-to-connect or via the inspector; explicit Save lints and writes the board file (.t3/boards/*.json is the source of truth).

Selecting a lane dims every edge that doesn't touch it, so dense graphs stay readable:

Agent steps, fully configurable

The implement step: GPT-5.5 · Medium reasoning, 2 retry attempts, and "Escalate on retry" to GPT-5.5 · Extra High — a failed attempt automatically reruns on the stronger configuration.

The review step: GPT-5.5 · High, captured output (the agent ends with a fenced JSON verdict that routing predicates can read), and a 3-reviewer panel — three independent sessions vote, strict majority wins.

Lane form: merge steps, routing, external events

The Land lane in form view: a merge step (commits the ticket worktree and merges it into the checked-out branch; conflicts block instead of failing), lane success/failure/blocked routes, and external event matchers — a ci.passed webhook with a payload predicate moves the ticket to Done.

Dry run

Simulate a hypothetical ticket through the definition you're editing (unsaved changes included) under all-succeed / all-fail / all-block scenarios. It mirrors the engine's exact routing semantics and explains every hop — here it correctly flags that the success path stalls in Review unless a verdict transition matches.

Version history

Every save is snapshotted per board with diffs and non-destructive revert.

External events

Each board gets a webhook endpoint with a rotating token (shown exactly once) and a copyable curl example. CI, PR automation, or cron can move correlated tickets (by ticketId or workflow/<id> branch) through their lane's event matchers, with delivery dedupe.

The board reports to you

A digest of the last 24h: shipped/created counts, tokens spent, agent time, and which tickets are waiting on a human.

Living with a ticket

The drawer: "Why is this ticket here?" route explainability (every hop with the rule that caused it), a discussion thread whose comments reach the next agent step as context, per-step status/duration/token usage, and one-click lane actions ("Retry build", "Back to backlog").

Script steps are gated by per-project trust — the first node --test run blocks until you allow it:

Every ticket has a case file (.t3/ticket/<id>/) the agents write into — here the PLAN.md the planning agent produced — plus the script output and reviewer sessions:

And any agent step's full session is one click away, read-only:

Boards live in the sidebar with hover rename/delete (delete cascades tickets, events, versions, worktrees, and webhook tokens):

Not shown but included

Durable restart recovery (pipelines, retries, merges, approvals resume safely), WIP queueing with FIFO auto-admission, dependency auto-release, terminal-lane retention TTL with full state cleanup, aging badges and waiting-on-you toasts, ticket search, multi-environment boards, and an event-sourced audit trail under everything.

Notes

• The engine is a new bounded context under apps/server/src/workflow/** (Effect TS, event-sourced over SQLite) with contracts in packages/contracts/src/workflow.ts and the web UI under apps/web/src/components/board/**.
• Every batch on this branch went through adversarial review (security findings like webhook token hashing, prototype-pollution sanitization, and stale-event fencing came out of those rounds) plus live Playwright verification.
• docs/workflow-demo/ (these screenshots) is demo material and can be dropped before merge.

🤖 Generated with Claude Code

Note

Add workflow boards — a kanban-based state machine system for driving coding agents

• Introduces a full event-sourced workflow engine (WorkflowEngine) with per-board kanban lanes, agent/script/merge step types, WIP limits, conditional routing via JSONLogic predicates, and ticket dependency tracking
• Adds 22 database migrations (033–054) for event store, projection tables, worktree leases, dispatch outbox, setup runs, checkpoints, webhook delivery, and version history
• Implements durable execution with a provider dispatch outbox, worktree leases with fencing tokens, crash recovery, and a terminal retention sweeper for expired tickets
• Exposes a comprehensive WebSocket RPC surface (30+ methods) gated by new workflow:read and workflow:operate auth scopes, wired through the existing environment auth layer
• Adds a full web UI: board view with drag-and-drop (BoardView), ticket drawer with step activity feed and diffs, an Intake dialog for proposing tickets from a braindump, a visual canvas editor with SVG edge routing, and version history with JSON diff preview
• Adds per-board webhook ingestion (POST /hooks/workflow/:boardId) with token verification, payload sanitization, and delivery deduplication
• Hides workflow-internal orchestration threads from user-facing snapshots and agent awareness relay by propagating a hidden flag through the thread schema and projection queries
• Risk: large schema and runtime surface introduced in a single PR; recovery paths, retention sweeper, and worktree janitor run at startup and may interact with existing orchestration under concurrent workloads

^{Macroscope summarized 5002be8.}

---

Note

High Risk
Very large new subsystem touching auth scopes, webhooks, worktree leasing, dispatch/outbox recovery, and orchestration visibility; correctness and security depend on many interacting durable paths.

Overview
Adds per-project workflow boards (.t3/boards/*.json) backed by a new event-sourced engine under apps/server/src/workflow/**: lane pipelines (agent / script / approval / merge), ticket moves via step outcomes, JSONLogic routing (json-logic-js), WIP queues, dependencies, token budgets, worktree leases, a dispatch outbox into orchestration, crash recovery, terminal retention, and board webhooks (hashed tokens + delivery dedupe). 22 SQLite migrations (033–054) create workflow events, projections, and supporting tables.

The server wires WorkflowServerRuntimeLive into startup (recovery + retention sweeper), exposes workflowHooksRouteLayer, and extends OAuth token exchange with workflow:read / workflow:operate (tests/assertions now use shared AuthStandardClientScopes / AuthAdministrativeScopes).

Orchestration gains hidden threads for internal workflow agent runs: they are projected but stripped from public snapshots/lists, gated by isThreadHidden, and skipped by the agent-awareness relay. thread.create can mark hidden; terminal manager adds attachHistoryStream so script steps can stream persisted output without opening a shell.

Also ships a sample Standard delivery board definition and ignores .superpowers/ in git.

^{Reviewed by Cursor Bugbot for commit 5002be8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3c9e9787-59ad-4b9a-aca6-09293aedb682

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ccdwyer]

Addressed all 6 Macroscope findings in 87db8cc:

• ApprovalGate race (Medium): getOrCreate now registers the deferred atomically via Ref.modify — concurrent callers always share one deferred.
• TurnStateReader interrupted (Medium): completed now includes interrupted, matching toTurnState's terminal classification.
• workflowFile status path (Low): steps.<key>.status.<extra> is now rejected, same as exitCode.
• TicketCard failed badge (Low): label fixed to "failed".
• CanvasView record equality (Low): key presence checked explicitly instead of ?? 0 masking.
• VersionHistoryPanel race (Low): stale async version loads are invalidated by a request counter.

Same commit also hardens review-panel verdict capture (found during the live demo run): captured output now falls back to earlier assistant messages in the turn when the final message lacks the fenced json block, and the auto-appended captureOutput suffix explicitly overrides skill-driven output formats.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}