boocode/openspec/changes/archived/2026-06-07-hybrid-workflow-engine/proposal.md at c9356877257cb482fbcdc9a4d2aa83dd510c3c2d

Files

indifferentketchup c935687725 chore(openspec): drop 9 superseded proposals + 11 stub archive files

Drop 9 batch proposals that are superseded by the boocode-lift-analysis
(boocontext-audit, conductor upgrades, self-healing/verify-gate skills):
add-3tier-memory, import-llm-evaluator, import-pregel-engine, plugin-platform,
conductor-evolution, code-intelligence-upgrade, dev-workflow, ui-overhaul,
agent-reliability.

Delete 11 stub archive files (49-66B each, 'Status: Shipped. Archived.' only)
that provide zero documentation value over the existing CHANGELOG.md + git tags.

2026-06-07 22:15:38 +00:00

3.4 KiB

Raw Blame History

Why

Current workflow engines force a tradeoff between simplicity and durability. Archon has a clean DAG-based YAML format but no crash recovery. Vercel Workflow has bulletproof deterministic replay but requires a Rust compiler plugin and 24-36 weeks to build. Agent SOP proves that human-readable markdown workflows work, but lacks structured execution. There is no portable workflow engine that combines a simple DAG format, human-readable definitions, and durable event-sourced execution in a single, buildable package.

What Changes

Introduce Ion — a portable hybrid workflow engine that combines the three approaches:

Archon-style YAML DAG format with nodes:, depends_on:, and trigger rules as the primary workflow definition
Agent SOP-style .sop.md markdown as a secondary human-readable format, auto-converted to the DAG representation
Vercel-style event log for deterministic replay and crash recovery, but simplified — no SWC plugin, no VM sandbox, no compile-time transforms
Multi-backend storage (filesystem for dev, SQLite/Postgres for production)
CLI + library dual distribution: use as a CLI tool or embed as a library
No Rust compiler plugins, no SWC, no VM sandbox — pure TypeScript/JavaScript, zero compile-time transforms

Capabilities

New Capabilities

dag-engine: DAG execution engine with topological ordering, concurrent layers, trigger rules (all_success, one_success, all_done, none_failed_min_one_success), and when: condition evaluation
yaml-format: Workflow definition in YAML with 7 node types (command, prompt, bash, script, loop, approval, cancel) plus depends_on, trigger_rule, output_format, retry, timeout
markdown-format: .sop.md human-readable workflow format with RFC 2119 constraint keywords, auto-converted to DAG nodes
event-sourcing: Append-only event log for workflow runs with deterministic replay for crash recovery — simplified (no SWC, no VM sandbox)
variable-substitution: $nodeId.output, $nodeId.output.field, $ARGUMENTS, $ARTIFACTS_DIR, $WORKFLOW_ID, $LOOP_PREV_OUTPUT, $REJECTION_REASON with strict field access
script-execution: Script node type running TypeScript (bun/node) and Python (uv/python3) with deps: support and timeout:
human-approval: Approval gate nodes that pause execution for human review with capture_response and on_reject retry support
storage-backends: Pluggable storage — filesystem (dev), SQLite, Postgres — with IWorkflowStore interface
workflow-lifecycle: Run states pending → running → paused/completed/failed/cancelled, resume skipping completed nodes, event-driven observability
cli-tool: Command-line interface for listing, running, approving, rejecting, resuming, and cleaning up workflow runs
library-api: Programmatic API for embedding the engine in other applications

Modified Capabilities

Impact

Greenfield project — no existing code to modify, all new artifacts under ion/ or equivalent package path
Dependencies: Zod (schema validation), nanoid/ulid (ID generation), js-yaml (YAML parsing), chokidar (file watching for dev mode)
Optional dependencies: better-sqlite3 / postgres.js (production storage backends), bun (fast script runtime), highlight.js (markdown rendering)
No Rust, SWC, wasm, or compile-time transforms in the core engine

3.4 KiB Raw Blame History

Why