united-workforce/BOOTSTRAP.md

UWF Bootstrap Guide

This guide helps any AI agent set up uwf (Uncaged Workflow) from scratch — or self-check and upgrade an existing installation.

Prerequisites

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

Already have uwf? Jump to Self-Check & Upgrade.

---

Fresh Install

1. Install uwf CLI

bun install -g @uncaged/cli

✅ Check: uwf --version prints a version number (e.g. 0.5.1).

2. Install Agent Adapter

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

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

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

✅ Check: uwf-hermes --version prints a version number.

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

✅ Check: cat ~/.uncaged/workflow/config.yaml shows valid provider, model, and agent config.

4. Verify Installation

uwf workflow list    # should return empty array or existing workflows
uwf skill user       # prints usage guide
uwf skill author     # prints workflow authoring guide

✅ Check: All three commands run without errors.

5. Add the uwf Skill

mkdir -p ~/.hermes/skills/devops/uwf
uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md

✅ Check: cat ~/.hermes/skills/devops/uwf/SKILL.md shows the skill content with triggers uwf, workflow, 工作流.

6. 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 (one moderator → agent → extract cycle)
uwf thread exec <thread-id>

✅ Check: Thread reaches completed status. Verify with uwf thread list.

---

Self-Check & Upgrade

Already have uwf installed? Run through this checklist to verify and upgrade.

Version Check

uwf --version
uwf-hermes --version   # or your agent adapter

Compare with latest published versions:

bun pm ls -g | grep -E "cli|workflow-agent"
npm info @uncaged/cli version
npm info @uncaged/agent-hermes version

If local version < published version, upgrade:

bun install -g @uncaged/cli@latest
bun install -g @uncaged/agent-hermes@latest

✅ Check: uwf --version matches npm info @uncaged/cli version.

Config Check

cat ~/.uncaged/workflow/config.yaml

Verify:

• providers has at least one entry with valid baseUrl and apiKey
• models.default references an existing provider
• agents has your adapter configured
• defaultAgent and defaultModel are set

Skill Check

cat ~/.hermes/skills/devops/uwf/SKILL.md

Verify the skill is up to date:

uwf skill bootstrap | diff - ~/.hermes/skills/devops/uwf/SKILL.md

If diff produces any output, the local skill is outdated. Update:

uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md

Functional Check

uwf workflow list      # should not error
uwf skill user         # should print usage guide
uwf skill author       # should print authoring guide

✅ All green? You're good to go.