xingyue
e7f733c393
What: Replace ELK layout engine with a hand-written spine layout that topologically sorts nodes into a vertical main path with feedback edges routed to the right side. Why: ELK's layered algorithm spreads the graph too wide when handling feedback (back) edges, causing fitView to shrink nodes until text is unreadable. Our workflow graphs are predominantly linear pipelines with feedback loops — a custom layout handles this topology much better. Changes: - packages/workflow-dashboard/src/components/workflow-graph/use-layout.ts: rewrite from async ELK to synchronous spine layout — topo-sort extracts main path, nodes stack vertically, feedback edges get right-side routing - packages/workflow-dashboard/src/components/workflow-graph/condition-edge.tsx: add custom SVG path for feedback edges (right-side arc with Q curves), use typed isFeedback/isSelfLoop fields from ConditionEdgeData - packages/workflow-dashboard/src/components/workflow-graph/types.ts: rename elkLabelX/Y to labelX/Y, add isFeedback and isSelfLoop fields - packages/workflow-dashboard/src/components/workflow-graph/workflow-graph.tsx: remove ReactFlowProvider/useReactFlow/useEffect fitView workaround (no longer needed — layout is synchronous), simplify component - packages/workflow-dashboard/package.json: remove elkjs and dagre deps
@uncaged/workflow
A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained .esm.js file identified by its XXH64 hash (Crockford Base32).
Core Concepts
| Concept | Description |
|---|---|
| Workflow | A single-file ESM module exporting run (workflow function) and descriptor (metadata). Identified by its XXH64 hash. |
| Bundle | The physical .esm.js file stored in ~/.uncaged/workflow/bundles/. |
| Thread | A single execution of a workflow, identified by a ULID. CAS-backed chain plus threads.json / history/*.jsonl; .info.jsonl for debug logs. |
| Role | A named actor within a workflow. Each role produces output with typed meta. Roles live inside template packages (src/roles/). |
| Registry | workflow.yaml — maps workflow names to current/historical bundle hashes. |
| CAS | Content-Addressed Storage — bundles are immutable and addressed by hash. |
Monorepo Packages
packages/
workflow/ # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
cli-workflow/ # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
workflow-template-develop/ # @uncaged/workflow-template-develop — develop workflow template (includes roles)
workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
workflow-agent-hermes/ # @uncaged/workflow-agent-hermes — Hermes agent adapter
workflow-agent-cursor/ # @uncaged/workflow-agent-cursor — Cursor agent adapter
workflow-agent-llm/ # @uncaged/workflow-agent-llm — LLM agent adapter
workflow-util-agent/ # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
Managed with bun workspace using the workspace:* protocol.
Quick Start
# Install dependencies
bun install
# Build all packages
bun run build
# Register a workflow bundle
uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
# Run a workflow
uncaged-workflow run solve-issue --prompt "Fix bug #42"
CLI Usage
uncaged-workflow # Print full command usage (exits with status 1)
uncaged-workflow workflow list # List registered workflows
uncaged-workflow run <name> # Start a workflow thread
uncaged-workflow thread list # List all threads
uncaged-workflow thread show <id> # Inspect a thread
uncaged-workflow skill # Agent-consumable reference docs
Run uncaged-workflow with no arguments to print usage, or uncaged-workflow skill cli for the full CLI skill reference.
Development
bun run check # Biome lint + format check
bun run format # Auto-format with Biome
bun test # Run tests
Architecture
See docs/architecture.md for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.