UWF Bootstrap Guide

This guide helps any AI agent set up uwf (Uncaged Workflow) from scratch.

Prerequisites

bun — uwf is built with bun. Install: curl -fsSL https://bun.sh/install | bash
Network access — to install npm packages

1. Install uwf CLI

bun install -g @uncaged/cli-workflow

Verify:

uwf --version

2. Install Agent Adapter

Install the adapter that matches your agent runtime. Pick one:

Agent	Package	Binary
Hermes	`@uncaged/workflow-agent-hermes`	`uwf-hermes`

# Example: Hermes agent
bun install -g @uncaged/workflow-agent-hermes

3. Setup

Run the interactive wizard:

uwf setup

Or configure non-interactively:

uwf setup \
  --provider <name> \
  --base-url <url> \
  --api-key <key> \
  --model <model-name> \
  --agent hermes

This creates ~/.uncaged/workflow/config.yaml with your provider, model, and default agent.

Config Structure

providers:
  my-provider:
    baseUrl: https://api.example.com/v1
    apiKey: sk-xxx
models:
  default:
    provider: my-provider
    name: my-model
agents:
  hermes:
    command: uwf-hermes
    args: []
defaultAgent: hermes
defaultModel: default

4. Verify Installation

# List workflows (should return empty or existing ones)
uwf workflow list

# Check built-in help
uwf skill user     # usage guide
uwf skill author   # workflow authoring guide

5. Add the uwf Skill

Copy the skill file from this repo into your agent's skill library:

# For Hermes agents with skills at ~/.hermes/skills/
mkdir -p ~/.hermes/skills/devops/uwf
cp skills/uwf-skill.md ~/.hermes/skills/devops/uwf/SKILL.md

The skill teaches the agent to use uwf skill user and uwf skill author for detailed reference, keeping the skill itself minimal.

6. Quick Smoke Test

# Register an example workflow
uwf workflow add examples/analyze-topic.yaml

# Start a thread
uwf thread start analyze-topic -p "Analyze the concept of technical debt"

# Execute it (runs one moderator → agent → extract cycle)
uwf thread exec <thread-id>

Done

The agent now has uwf + agent adapter installed, configured, and a skill to guide future usage. For workflow authoring details, run uwf skill author.

2.3 KiB Raw Blame History