@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.