docs: add BOOTSTRAP.md and uwf skill for agent onboarding

2026-05-28 09:42:28 +00:00
parent 3a927de63f
commit b4919aa921
2 changed files with 149 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 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
+
+```bash
+bun install -g @uncaged/cli-workflow
+```
+
+Verify:
+
+```bash
+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` |
+
+```bash
+# Example: Hermes agent
+bun install -g @uncaged/workflow-agent-hermes
+```
+
+## 3. Setup
+
+Run the interactive wizard:
+
+```bash
+uwf setup
+```
+
+Or configure non-interactively:
+
+```bash
+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
+
+```yaml
+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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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`.