Context is Everything logo

Workflow Editor POC — Design Document

Problem

Sasha's task system has grown organically: "prompt files" are hidden configuration, "schedules" and "tasks" mean the same thing, execution history lives in two tables, and there's no way to chain, branch, or compose work. Meanwhile, we've published the Agent Flow spec (github.com/context-is-everything/sasha-workflow) defining a layered format for agentic workflows — but have no UI to author or run them.

Goal

Build a proof-of-concept workflow editor inside Sasha Studio that:

  1. Makes Workflow the first-class concept (replacing the prompt/schedule/task confusion)
  2. Provides a visual editor (React Flow canvas + CodeMirror) for authoring Agent Flow workflows
  3. Ships with two working examples: Report Publisher pipeline and Transcript-to-Report
  4. Integrates with existing scheduler, execution logging, and API infrastructure
  5. Offers three template models as best-practice starting points

Core Concepts

Two concepts, not three:

Concept What it is Where it lives
Workflow Definition of work AND how it's triggered .md file with Agent Flow frontmatter
Execution A single run of a workflow executions table

The trigger config (cron, manual, API) lives in the workflow frontmatter — no separate "task" or "schedule" record needed. The database stores a workflows table as a metadata cache synced from files on startup.

Frontmatter with Triggers

---
name: transcript-to-report
kind: agent-flow/workflow
version: 1.0.0
description: Process meeting transcript into structured report

triggers:
  schedule: "0 6 * * 1"
  timezone: UTC
  manual: true
  api: true

budgets:
  max_tokens: 40000
  deadline_seconds: 300
---

Architecture

Storage

all-project-files/
├── scheduled-prompts/        # existing, unchanged
├── workflows/                # NEW
│   ├── report-publisher-pipeline.md
│   ├── transcript-to-report.md
│   └── document-creation.md

Database

  • workflows table: name, file_path, enabled, description, kind, version, triggers (JSON), last_synced_at
  • executions table: existing unified table, execution_type = 'workflow'
  • Legacy execution_history continues for existing prompts, no migration

Server

  • GET/POST/PUT/DELETE /api/v1/workflows — CRUD for workflows
  • POST /api/v1/workflows/:name/run — trigger execution
  • GET /api/v1/workflows/:name/executions — execution history
  • Server scans workflows/ on startup, syncs workflows table
  • Scheduler reads trigger config from workflow frontmatter

Parser

  • Parses .md file → typed AST (frontmatter + step/agent/bundle/runtime/observability blocks)
  • Validates against Agent Flow schema
  • Shared between server and client (isomorphic JS module)

UI Design

Workflow Manager

Launched from the Workflows tab (replaces Tasks tab). Lists workflows with:

  • Name, version, status badge (draft/active)
  • Step count, layer indicator
  • Trigger summary (schedule, manual, API)
  • Last execution status and time
  • [Edit] [Run Now] [Schedule] buttons

Legacy prompts appear in a separate "Legacy Prompts" section with "Convert to Workflow" option.

Recent executions shown at the bottom.

Workflow Editor

Full-screen overlay (same pattern as CodeEditor). Three view modes:

  • Canvas: React Flow only (business users)
  • Code: CodeMirror only (technical users)
  • Split: Both side by side (default)

Layout:

┌──────────────────────────────────────────────────┐
│  ← Back   [name] [version] [status]   [Save] [Run]│
├──────────────────────────────────────────────────┤
│  [Canvas] [Code] [Split]       [Triggers] [Settings]│
├──────────────────────┬───────────────────────────┤
│  React Flow Canvas   │  CodeMirror (MD view)     │
│  (interactive nodes) │  (read-only for POC)      │
├──────────────────────┴───────────────────────────┤
│  Inspector Panel (selected node properties)      │
└──────────────────────────────────────────────────┘

Custom Node Types

Step Type Shape Color Icon
transform Rounded rect Blue Funnel
skill Rounded rect Purple Lightning
tool Rounded rect Green Wrench
decision Diamond Orange GitBranch
gate Octagon Red ShieldCheck
parallel Double-border rect Teal ArrowsSplit
end Circle Gray Flag

Inspector Panel

Bottom panel when a node is selected. Form fields for step properties: type, description, reads, writes, error handling, expected output. Agent and bundle config shown inline for relevant step types.

Triggers Panel

Slide-out panel: cron builder, manual toggle, API toggle with endpoint URL and curl example, timezone picker.

Settings Panel

Slide-out panel: budgets, tool allowlist/denylist, risk profile, I/O schema editor, observability config.

Template Models

Three templates offered when creating a new workflow:

1. Simple Pipeline

validate → process → output

Linear steps, no agents. For scheduled reports, data extraction, single-task automation.

2. Agentic Workflow

validate → specialist work → QA gate → assemble output

Agent definitions with roles/goals, critic gate for quality. For analysis, content creation, research.

3. Parallel Fan-out

validate → fan-out to workers → merge → confirmation gate → output

Multiple specialists in parallel, merge with conflict handling, confirmation before proceeding. For multi-perspective analysis, document processing.

Each template generates a complete workflow file with best-practice budgets, reason codes, and observability pre-configured.

Working Examples

1. Report Publisher Pipeline

Maps the existing report-publisher stages:

validate_input → load_design_pack → plan_layouts → render_charts
→ solve_fit → repair_overflow → export (parallel: pptx, pdf, html, web)

Layer 2 workflow (parallel export). All tool/transform steps — no LLM agents. Demonstrates the spec works for deterministic pipelines.

2. Transcript-to-Report

validate → extract (parallel: actions, risks, themes) → QA gate → assemble

Layer 2 with agents, parallel bundle, critic gate. The core agentic non-determinism story.

Integration with Existing Systems

Existing System Integration
Scheduler service Reads trigger config from workflow frontmatter, creates CronJobs
Execution logging Workflow runs use existing executions table with type='workflow'
API key auth Workflows triggered via /api/v1/workflows/:name/run use existing auth
Idempotency Deterministic execution IDs for scheduled runs (same pattern)
Crash recovery Stale workflow executions marked on startup

Spec Repo Sync

The public spec at github.com/context-is-everything/sasha-workflow needs updates:

  1. Add triggers: frontmatter section to SPEC.md
  2. Document the Workflow + Execution model (simplified from three concepts)
  3. Add the three template models as recommended patterns
  4. Add Report Publisher example (non-agentic pipeline)
  5. Simplify any over-engineering identified during POC

POC Scope

In scope

  • Workflow file parser (frontmatter + fenced blocks → AST)
  • Workflow Manager UI (list, create from template, edit, run)
  • Workflow Editor with React Flow canvas + CodeMirror
  • Inspector panel for node editing
  • Two working example workflows
  • Integration with existing scheduler and execution logging
  • Spec repo updates

Out of scope (fast follow)

  • Bidirectional code↔canvas sync (POC is visual→code only)
  • Actual workflow execution engine (POC generates files, doesn't run multi-step)
  • Drag-and-drop node creation on canvas
  • Undo/redo
  • Collaborative editing
  • Workflow versioning / diff view

Technology

  • React Flow — node-based graph editor (new dependency)
  • CodeMirror 6 — code editor (already in project)
  • Tailwind CSS — styling (already in project)
  • Phosphor Icons — icons (already in project)