xiaoju
4a925b98af
- Create root README.md with project intro, concepts, packages, quickstart - Remove workflow-role-* references from docs/architecture.md - Roles now live inside template packages (src/roles/) - Clean up untracked dist/packages/workflow-role-* remnants Fixes #88
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# @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. Persisted as `.data.jsonl` + `.info.jsonl`. |
|
|
| **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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Build all packages
|
|
bun run build
|
|
|
|
# Register a workflow bundle
|
|
uncaged-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
|
|
|
|
```bash
|
|
uncaged-workflow help # Show all commands
|
|
uncaged-workflow list # List registered workflows
|
|
uncaged-workflow run <name> # Start a workflow thread
|
|
uncaged-workflow threads # List all threads
|
|
uncaged-workflow thread <id> # Inspect a thread
|
|
uncaged-workflow skill # Show workflow skill info
|
|
```
|
|
|
|
See `uncaged-workflow --help` for the full command reference.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
bun run check # Biome lint + format check
|
|
bun run format # Auto-format with Biome
|
|
bun test # Run tests
|
|
```
|
|
|
|
## Architecture
|
|
|
|
See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.
|