xiaoju
031c3aa632
Complete the CLI refactoring with deprecation error handlers, updated help text, and comprehensive migration guide. ## Changes ### Deprecation Handlers Add error handlers for all removed commands with helpful migration messages: - `workflow put` → suggests `workflow add` - `thread step` → suggests `thread exec` - `thread steps` → suggests `step list` - `thread step-details` → suggests `step show` - `thread fork` → suggests `step fork` - `thread kill` → suggests `thread stop` or `thread cancel` - `thread running` → suggests `thread list --status running` Error messages follow the format: ``` Error: Command 'X' has been removed. Use 'Y' instead. For more information, see: uwf help Y ``` ### Help Documentation Updated CLI help text to explain four-layer architecture: - Main help shows architecture diagram with Chinese labels - Command group descriptions reference layers: - `workflow` → "Workflow definitions (layer 1: templates)" - `thread` → "Thread execution (layer 2: instances)" - `step` → "Step results (layer 3: single cycle)" - Deprecated commands appear in help with [DEPRECATED] tag ### README Updates Comprehensive documentation updates: - Added "Four-Layer Architecture" section with diagram - Updated all command tables with new command names - Added complete migration guide with: - Renamed commands table - Merged commands table - Split commands table - Moved commands table - Example deprecation error output - Updated "Internal Structure" to show new step.ts module ## Testing - ✅ All 124 tests pass - ✅ Build completes successfully - ✅ Deprecation handlers tested manually - ✅ Help output verified for main, thread, and step commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@uncaged/workflow
A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, JSONata routing conditions, and a directed graph. Threads are immutable CAS-linked chains — each uwf thread step runs one moderator→agent→extract cycle and exits.
Overview
This monorepo implements uwf, a workflow engine with no long-running daemon. You register YAML workflow definitions in a content-addressed store (CAS), start a thread with an initial prompt, then invoke uwf thread step repeatedly until the moderator routes to $END. Each step is a complete process: the moderator evaluates JSONata conditions to pick the next role, an external agent CLI produces frontmatter markdown output, and an extract pipeline validates or structures that output against the role's JSON Schema.
Workflow state lives entirely on disk under ~/.uncaged/workflow/: CAS nodes for definitions and step payloads, registry.yaml for workflow name→hash mappings, and threads.yaml for active thread head pointers. Completed threads are archived to history.jsonl. Because there is no server process, workflows are easy to debug, fork, and inspect with ordinary CLI tools.
Agents are pluggable CLI binaries (uwf-hermes, uwf-builtin, uwf-claude-code, or custom commands). The engine spawns the configured agent with <thread-id> and <role>, sets UWF_EDGE_PROMPT from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay.
Architecture
Dependency layers (lower layers have no dependency on higher layers):
Layer 0 — Contract
workflow-protocol Shared types and JSON Schema definitions
Layer 1 — Shared infra
workflow-util Encoding, IDs, logging, frontmatter, paths
workflow-moderator JSONata graph evaluator
Layer 2 — Agent framework
workflow-agent-kit createAgent factory, context builder, extract pipeline
Layer 3 — Agent implementations
workflow-agent-hermes Hermes ACP agent (uwf-hermes)
workflow-agent-builtin Built-in LLM + tools agent (uwf-builtin)
workflow-agent-claude-code Claude Code agent (uwf-claude-code)
Layer 4 — CLI
cli-workflow uwf binary — thread lifecycle, registry, CAS, setup
App (uses protocol; not in the runtime engine stack)
workflow-dashboard Web UI for visual workflow editing
External CAS: @uncaged/json-cas (store API, hashing, schema validation) + @uncaged/json-cas-fs (filesystem backend).
See docs/architecture.md for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
Packages
| Package | npm | Description | Type | README |
|---|---|---|---|---|
cli-workflow |
@uncaged/cli-workflow |
uwf CLI — thread lifecycle, workflow registry, CAS inspection, setup |
cli | README |
workflow-protocol |
@uncaged/workflow-protocol |
Shared TypeScript types and JSON Schema constants | lib | README |
workflow-moderator |
@uncaged/workflow-moderator |
JSONata graph evaluator — next role or $END |
lib | README |
workflow-agent-kit |
@uncaged/workflow-agent-kit |
createAgent factory, context builder, extract pipeline |
lib | README |
workflow-util |
@uncaged/workflow-util |
Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | README |
workflow-agent-hermes |
@uncaged/workflow-agent-hermes |
uwf-hermes — spawns Hermes chat via ACP |
agent | README |
workflow-agent-builtin |
@uncaged/workflow-agent-builtin |
uwf-builtin — built-in LLM agent with file/shell tools |
agent | README |
workflow-agent-claude-code |
@uncaged/workflow-agent-claude-code |
uwf-claude-code — spawns Claude Code CLI |
agent | README |
workflow-dashboard |
@uncaged/workflow-dashboard |
Web graph editor for workflow YAML (private, alpha) | app | README |
Quick Start
# 1. Configure provider, model, and default agent
uwf setup
# 2. Register a workflow from YAML
uwf workflow put examples/solve-issue.yaml
# 3. Start a thread (creates head pointer; does not execute)
uwf thread start solve-issue -p "Fix the login redirect bug"
# 4. Execute steps (one at a time, until done)
uwf thread step <thread-id>
Use -c, --count <number> on thread step to run multiple steps in one invocation. Override the agent with --agent <cmd>.
CLI Reference
Global options: -V, --version, --format <json|yaml>, -h, --help.
| Group | Commands |
|---|---|
| thread | start, step, show, list, kill, steps, read, fork, step-details |
| workflow | put, show, list |
| cas | get, put, put-text, has, refs, walk, reindex, schema list, schema get |
| setup | Interactive or --provider, --base-url, --api-key, --model, --agent |
| skill | cli — print markdown reference of all uwf commands |
| log | list, show, clean — process-level debug logs |
Config is stored in ~/.uncaged/workflow/config.yaml. API keys go in ~/.uncaged/workflow/.env.
Detailed command usage, options, and examples: packages/cli-workflow/README.md.
Development
bun install --no-cache # Install dependencies
bun run build # tsc --build (all packages)
bun run check # tsc + biome + lint-log-tags
bun run format # Auto-format with Biome
bun test # Run all tests
Managed with bun workspace. See CLAUDE.md for coding conventions.