workflow-worlds

Custom World implementations for the Workflow DevKit.

Workflow 4.1 Status

This repository now targets the Workflow 4.1 world contract (@workflow/world@4.1.x).

• World implementations now use event-sourced state transitions via storage.events.create(...).
• Legacy runs are still supported with guarded compatibility behavior.
• Turso requires running migrations before use and after upgrades (pnpm exec workflow-turso-setup).

See Workflow 4.1 Migration Guide for upgrade steps and rollout checks.

What is a World?

A World provides the infrastructure layer for Workflow DevKit, handling:

• Storage: Persisting workflow runs, steps, events, and hooks
• Queue: Message passing for async execution
• Streamer: Real-time output streaming

Quick Start

Using the Starter Template

1. Copy the starter package:

   cp -r packages/starter my-world
   cd my-world

2. Update package.json with your package name

3. Install dependencies and verify tests pass:

   pnpm install
   pnpm build
   pnpm test

4. Replace the in-memory implementations with your backend

Packages

Package	Description	Status
@workflow-worlds/starter	In-memory World template for building custom implementations	✅ Ready
@workflow-worlds/mongodb	MongoDB World using native driver	✅ Ready
@workflow-worlds/redis	Redis World using BullMQ for queues, Redis Streams for output	✅ Ready
@workflow-worlds/turso	Turso/libSQL World for embedded or remote SQLite databases	✅ Ready

Documentation

• Introduction - What is a World and why it exists
• Interface Reference - Complete API documentation
• Implementation Guide - Step-by-step tutorial
• Patterns & Practices - Key patterns and gotchas
• Testing - Running the test suite
• Production Checklist - Production readiness
• Release Guide - Stable and beta release workflows
• Workflow 4.1 Migration Guide - Safe upgrade and legacy-run strategy

AI/LLM Resources

This repository is optimized for AI-assisted development:

• CLAUDE.md - Quick reference for AI agents
• llm/AGENTS.md - Detailed agent instructions
• llm/PROMPTS.md - Ready-to-use prompts
• llm/world-builder-agent.md - Comprehensive guide

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

License

MIT