Workflow Studio

1. The Situation

Running multiple coding agents (Claude, Codex, Antigravity) across active worktrees creates constant branch drift, overlapping file edits, and untracked task states.

2. The Constraint & Tension

The engine originally lived coupled inside a VS Code extension, making it impossible to drive from CLI scripts, CI test suites, or headless worker sessions without booting a full editor instance.

3. The Architecture Decision

Decoupled runtime logic into an isolated headless Node.js core engine (@workflow-studio/core) backed by an explicit SQLite task DAG using strict compile-time tsconfig boundaries. Implemented Kahn's algorithm for topological task ordering with strict cycle detection, and distributed task leases with monotonic fencing tokens to reject stale writes.

4. System Architecture

5. Verbatim Code Evidence

export function topologicalSort(def: WorkflowDefinition): string[] {
  const adj = new Map<string, string[]>();
  const inDeg = new Map<string, number>();

if (order.length !== def.nodes.length) {
    throw new Error('Workflow contains a cycle — not a valid DAG');
  }

export function isFenceCurrent(store: TaskLeaseStore, taskId: string, epoch: number): boolean {
  const lease = store.leases[normalizeTaskId(taskId)];
  if (!lease) return false;
  return leaseEpochFor(lease) === epoch;
}

6. Trade-offs & What's Left

Extracting the core required duplicating some interface shims between VS Code tree views and CLI output formatters. Maintaining the strict Node-only tsconfig boundary requires careful re-export barrels in packages/core/src/index.ts.