chore: release cli@0.3.0 util@0.1.3 agent-hermes@0.1.3 agent-claude-code@0.1.2 agent-builtin@0.1.2 agent-mock@0.1.2

- Step 3 (fresh install): warn skills not active until new session
- Step 2 (upgrade): same reminder after regenerating skills
- Step 3 (upgrade): add v0.2.1 migration note for enum → const

Refs #123

.changeset/bootstrap-ux-3.md

@@ -0,0 +1,14 @@
+---
+"@united-workforce/cli": patch
+---
+
+fix: improve bootstrap docs — agent discovery, pnpm/npm parity, preset provider table (#118, #120)
+
+- Step 1: detect installed agents (hermes/claude) before choosing adapter
+- Step 1: clarify adapter versions are independent from CLI — install @latest
+- Step 1: show pnpm and npm side-by-side
+- Step 1: add "adapter must be installed before `uwf setup --agent`" note
+- Step 1: add ACP verification step (hermes acp --help)
+- Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package
+- Step 2: preset providers listed as a table with names and default base URLs
+- Remove uwf-builtin from supported adapters (not ready yet)

.changeset/setup-ux-2.md

@@ -0,0 +1,14 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/agent-hermes": patch
+"@united-workforce/agent-claude-code": patch
+"@united-workforce/agent-builtin": patch
+"@united-workforce/agent-mock": patch
+---
+
+fix: suppress ExperimentalWarning, PEP 668 pip guidance, setup help (#116)
+
+- All CLI bins use shebang `#!/usr/bin/env -S node --disable-warning=ExperimentalWarning`
+- Remove NODE_OPTIONS injection from spawn (shebang handles it)
+- Bootstrap pip install guidance covers venv/pipx/source options for PEP 668 systems
+- `uwf setup --help` mentions interactive wizard mode

.changeset/workflow-authoring-docs.md

@@ -0,0 +1,15 @@
+---
+"@united-workforce/cli": patch
+"@united-workforce/util": patch
+---
+
+fix: unify $status to const-only, drop enum support (#123)
+
+Breaking: `$status` in frontmatter now requires `const` everywhere.
+`enum` is no longer accepted and will be rejected by the validator.
+
+- Validator: `hasStatusConst()` / `getConstStatuses()` replace enum-based checks
+- Error message: "must define $status as const (or oneOf with const)"
+- workflow-authoring docs: all examples use `const`, enum explicitly noted as unsupported
+- bootstrap hello.yaml: `$status: { const: done }`
+- All test fixtures migrated from enum to const/oneOf

packages/agent-builtin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-builtin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "files": [
     "src",
     "dist",

packages/agent-builtin/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });

packages/agent-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-claude-code",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "files": [
     "src",
     "dist",

packages/agent-claude-code/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });

packages/agent-hermes/__tests__/issue-551.test.ts

@@ -15,7 +15,8 @@ describe("Issue #551 — bin entry & engines", () => {
     const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
     const binPath = pkg.bin["uwf-hermes"];
     const content = readFileSync(join(PKG_ROOT, binPath), "utf-8");
-    expect(content.startsWith("#!/usr/bin/env node")).toBe(true);
+    expect(content.startsWith("#!/usr/bin/env")).toBe(true);
+    expect(content).toContain("node");
   });
 
   test("README.md explains uwf-hermes is an adapter", () => {

packages/agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-hermes",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "files": [
     "src",
     "dist",

packages/agent-hermes/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });

packages/agent-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-mock",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "files": [
     "src",
     "dist",

packages/agent-mock/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "files": [
     "src",
     "dist",

packages/cli/src/__tests__/current-role.test.ts

@@ -28,9 +28,13 @@ roles:
       $status: "ready"
     frontmatter:
       type: object
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+          required: ["$status"]
+        - properties:
+            $status: { const: "not-ready" }
           required: ["$status"]
-      properties:
-        $status: { type: string, enum: ["ready", "not-ready"] }
   roleB:
     description: Second role
     goal: Do B
@@ -42,7 +46,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
   $START:
     new:
@@ -82,9 +86,13 @@ roles:
       $status: "pass"
     frontmatter:
       type: object
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+          required: ["$status"]
+        - properties:
+            $status: { const: "fail" }
           required: ["$status"]
-      properties:
-        $status: { type: string, enum: ["pass", "fail"] }
   roleB:
     description: Pass role
     goal: Do B
@@ -96,7 +104,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
   roleC:
     description: Fail role
     goal: Do C
@@ -108,7 +116,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
   $START:
     new:
@@ -155,7 +163,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["done"] }
+        $status: { const: "done" }
 graph:
   $START:
     new:

packages/cli/src/__tests__/thread-location.test.ts

@@ -54,7 +54,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
   $START:
     new:
@@ -114,7 +114,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
   $START:
     new:
@@ -161,7 +161,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
   $START:
     new:

packages/cli/src/__tests__/thread-show-status.test.ts

@@ -31,7 +31,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
   $START:
     new:

packages/cli/src/__tests__/thread-start-cwd-cli.test.ts

@@ -54,7 +54,7 @@ roles:
       type: object
       required: ["$status"]
       properties:
-        $status: { type: string, enum: ["ready"] }
+        $status: { const: "ready" }
 graph:
   $START:
     new:

packages/cli/src/__tests__/validate-semantic.test.ts

@@ -17,7 +17,7 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
         frontmatter: {
           type: "object",
           properties: {
-            $status: { enum: ["done"] },
+            $status: { const: "done" },
             plan: { type: "string" },
           },
           required: ["$status", "plan"],
@@ -85,7 +85,7 @@ describe("Suite 1: Role Reference Integrity", () => {
       output: "None",
       frontmatter: {
         type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
         required: ["$status"],
       } as unknown as string,
     };
@@ -187,7 +187,7 @@ describe("Suite 2: Graph Structure", () => {
       output: "Isolated",
       frontmatter: {
         type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
         required: ["$status"],
       } as unknown as string,
     };
@@ -272,8 +272,8 @@ describe("Suite 3: Status-Edge Consistency", () => {
   });
 });
 
-describe("Suite 3b: Enum-Based Multi-Exit", () => {
+describe("Suite 3b: Enum-Based $status is Rejected", () => {
-  test("3b.1 enum multi-exit passes with matching graph keys", () => {
+  test("3b.1 enum multi-exit is rejected (must use oneOf + const)", () => {
     const wf = makeWorkflow();
     wf.roles.reviewer = {
       ...wf.roles.reviewer,
@@ -291,52 +291,10 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
       rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
     };
     const errors = validateWorkflow(wf);
-    expect(errors).toEqual([]);
+    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
   });
 
-  test("3b.2 enum multi-exit with extra graph key", () => {
+  test("3b.2 enum single-exit is rejected (must use const)", () => {
-    const wf = makeWorkflow();
-    wf.roles.reviewer = {
-      ...wf.roles.reviewer,
-      frontmatter: {
-        type: "object",
-        properties: {
-          $status: { enum: ["approved", "rejected"] },
-          comments: { type: "string" },
-        },
-        required: ["$status", "comments"],
-      } as unknown as string,
-    };
-    wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done", location: null },
-      rejected: { role: "writer", prompt: "Fix", location: null },
-      timeout: { role: "$END", prompt: "Timed out", location: null },
-    };
-    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("extra status keys: timeout"))).toBe(true);
-  });
-
-  test("3b.3 enum multi-exit with missing graph key", () => {
-    const wf = makeWorkflow();
-    wf.roles.reviewer = {
-      ...wf.roles.reviewer,
-      frontmatter: {
-        type: "object",
-        properties: {
-          $status: { enum: ["approved", "rejected"] },
-          comments: { type: "string" },
-        },
-        required: ["$status", "comments"],
-      } as unknown as string,
-    };
-    wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done", location: null },
-    };
-    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("missing status keys: rejected"))).toBe(true);
-  });
-
-  test("3b.4 enum with single explicit value passes", () => {
     const wf = makeWorkflow();
     wf.roles.writer = {
       ...wf.roles.writer,
@@ -351,28 +309,71 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
     };
     wf.graph.writer = { ready: { role: "reviewer", prompt: "Review: {{{plan}}}", location: null } };
     const errors = validateWorkflow(wf);
-    expect(errors).toEqual([]);
+    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
   });
+});
 
-  test("3b.5 enum multi-exit mustache var not in frontmatter", () => {
+describe("Suite 3c: Const-Based Flat Schema", () => {
+  test("3c.1 flat schema with const $status passes validation", () => {
     const wf = makeWorkflow();
-    wf.roles.reviewer = {
+    wf.roles.writer = {
-      ...wf.roles.reviewer,
+      ...wf.roles.writer,
       frontmatter: {
         type: "object",
         properties: {
-          $status: { enum: ["approved", "rejected"] },
+          $status: { const: "done" },
-          comments: { type: "string" },
+          plan: { type: "string" },
         },
-        required: ["$status", "comments"],
+        required: ["$status", "plan"],
       } as unknown as string,
     };
-    wf.graph.reviewer = {
+    const errors = validateWorkflow(wf);
-      approved: { role: "$END", prompt: "Done: {{{nonexistent}}}", location: null },
+    expect(errors).toEqual([]);
-      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
+  });
+
+  test("3c.2 flat schema with const $status detects extra graph key", () => {
+    const wf = makeWorkflow();
+    wf.roles.writer = {
+      ...wf.roles.writer,
+      frontmatter: {
+        type: "object",
+        properties: {
+          $status: { const: "done" },
+          plan: { type: "string" },
+        },
+        required: ["$status", "plan"],
+      } as unknown as string,
+    };
+    wf.graph.writer = {
+      done: { role: "reviewer", prompt: "Review.", location: null },
+      extra: { role: "$END", prompt: "Nope.", location: null },
     };
     const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("nonexistent") && e.includes("not found"))).toBe(true);
+    expect(errors.some((e) => e.includes("extra status keys") && e.includes("extra"))).toBe(true);
+  });
+
+  test("3c.3 flat schema with const $status validates mustache vars", () => {
+    const wf = makeWorkflow();
+    wf.roles.writer = {
+      ...wf.roles.writer,
+      frontmatter: {
+        type: "object",
+        properties: {
+          $status: { const: "done" },
+          plan: { type: "string" },
+        },
+        required: ["$status", "plan"],
+      } as unknown as string,
+    };
+    wf.graph.writer = {
+      done: { role: "reviewer", prompt: "Review: {{{nonexistent}}}", location: null },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some(
+        (e) => e.includes('prompt variable "nonexistent"') && e.includes('role "writer"'),
+      ),
+    ).toBe(true);
   });
 });
 
@@ -480,7 +481,7 @@ describe("Suite 6: Multiple Errors Collection", () => {
       output: "None",
       frontmatter: {
         type: "object",
-        properties: { $status: { enum: ["done"] } },
+        properties: { $status: { const: "done" } },
         required: ["$status"],
       } as unknown as string,
     };

packages/cli/src/__tests__/workflow-resolution.test.ts

@@ -31,7 +31,7 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
         frontmatter: {
           type: "object",
           properties: {
-            $status: { type: "string", enum: ["done"] },
+            $status: { const: "done" },
           },
           required: ["$status"],
         } as unknown as CasRef,

packages/cli/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
@@ -542,7 +542,7 @@ prompt
 
 program
   .command("setup")
-  .description("Configure provider, model, and agent")
+  .description("Configure provider, model, and agent. Run without options for interactive wizard.")
   .option("--provider <name>", "Provider name")
   .option("--base-url <url>", "OpenAI-compatible API base URL")
   .option("--api-key <key>", "API key")

packages/cli/src/commands/prompt.ts

@@ -78,48 +78,105 @@ npm prefix -g     # global prefix; bin is <prefix>/bin
 # FIX: add the missing directory to your shell's startup file
 #   (e.g. ~/.bashrc, ~/.zshrc, ~/.profile, or fish config):
 #   export PATH="<global-bin-dir>:$PATH"
-
-# 4. (uwf-hermes only) hermes CLI
-which hermes
-# FIX: if hermes is in a virtualenv, add it to PATH:
-#   export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"
-#   or create a symlink: ln -s ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes
 \`\`\`
 
 **All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your shell config.
 
-### Step 1 — Install CLI and agent adapter
+### Step 1 — Discover agents and install adapter
+
+**First, detect which supported agents are already installed on the user's machine:**
 
 \`\`\`bash
+# Check for Hermes Agent
+which hermes 2>/dev/null && hermes --version
+
+# Check for Claude Code
+which claude 2>/dev/null && claude --version   # should show "X.Y.Z (Claude Code)"
+\`\`\`
+
+**Based on the results:**
+
+- **Only hermes found** → install \`uwf-hermes\` adapter
+- **Only claude found** → install \`uwf-claude-code\` adapter
+- **Both found** → ask the user which agent they want uwf to use as default
+- **Neither found** → the user must install at least one agent first:
+  - Hermes Agent: https://hermes-agent.nousresearch.com/docs
+  - Claude Code: \`npm install -g @anthropic-ai/claude-code\`
+
+**Install the uwf CLI and the chosen adapter** using pnpm or npm:
+
+\`\`\`bash
+# CLI (required)
 pnpm add -g @united-workforce/cli       # or: npm install -g @united-workforce/cli
-uwf --version   # should print ${CLI_VERSION}
+
+# Adapter — install the one matching the detected agent:
+pnpm add -g @united-workforce/agent-hermes       # or: npm i -g @united-workforce/agent-hermes
+pnpm add -g @united-workforce/agent-claude-code   # or: npm i -g @united-workforce/agent-claude-code
 \`\`\`
 
-Install an agent adapter (at least one is required):
+**⚠ Adapter versions are independent from CLI versions.** Do NOT try to match adapter version to CLI version. Just install \`@latest\` (the default).
 
-| Adapter | Install | When to use |
+**After installing, verify that \`uwf\` and the adapter are available in PATH:**
-|---------|---------|-------------|
-| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent |
-| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
-| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
 
-**uwf-hermes** also requires the Hermes ACP plugin. After installing \`hermes-agent\`, run:
 \`\`\`bash
-pip install hermes-agent[acp]   # or: pip install -e .[acp] if installed from source
+uwf --version          # should print ${CLI_VERSION}
+uwf-hermes --version   # or: uwf-claude-code --version
 \`\`\`
 
-Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).
+If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:**
+
+1. Find where the binary was installed:
+   \`\`\`bash
+   find ~/.local ~/.hermes /usr/local -name uwf -type f 2>/dev/null
+   npm prefix -g    # global prefix — bin is <prefix>/bin
+   \`\`\`
+2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config):
+   \`\`\`bash
+   export PATH="<global-bin-dir>:$PATH"
+   \`\`\`
+3. Source the updated config or open a new shell, then re-verify the commands work.
+
+**uwf-hermes** also requires the Hermes ACP plugin. Verify with \`hermes acp --help\`. If not available, install it:
+\`\`\`bash
+# Option A: install into hermes venv (recommended)
+source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp]
+
+# Option B: pipx
+pipx install 'hermes-agent[acp]'
+
+# Option C: if installed from source
+pip install -e '.[acp]'
+\`\`\`
 
 ### Step 2 — Configure provider and model
 
 uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run:
 
 \`\`\`bash
-uwf setup --provider <name> --base-url <url> --api-key <key> --model <model> [--agent <adapter>]
+uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
 \`\`\`
 
-Preset providers (base-url is auto-filled when using a preset name):
+**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name.
-openai, xai, openrouter, venice, dashscope, deepseek, siliconflow, volcengine, kimi, glm, stepfun, minimax, ollama
+
+**Preset providers** — when using a preset name, \`--base-url\` is auto-filled and can be omitted:
+
+| Provider | Name | Default base URL |
+|----------|------|-----------------|
+| OpenAI | \`openai\` | https://api.openai.com/v1 |
+| xAI | \`xai\` | https://api.x.ai/v1 |
+| OpenRouter | \`openrouter\` | https://openrouter.ai/api/v1 |
+| Venice | \`venice\` | https://api.venice.ai/api/v1 |
+| Dashscope | \`dashscope\` | https://dashscope.aliyuncs.com/compatible-mode/v1 |
+| DeepSeek | \`deepseek\` | https://api.deepseek.com/v1 |
+| SiliconFlow | \`siliconflow\` | https://api.siliconflow.cn/v1 |
+| VolcEngine | \`volcengine\` | https://ark.cn-beijing.volces.com/api/v3 |
+| Kimi (Moonshot) | \`kimi\` | https://api.moonshot.cn/v1 |
+| GLM (Zhipu AI) | \`glm\` | https://open.bigmodel.cn/api/paas/v4 |
+| StepFun | \`stepfun\` | https://api.stepfun.com/v1 |
+| MiniMax | \`minimax\` | https://api.minimax.io/v1 |
+| Ollama (local) | \`ollama\` | http://localhost:11434/v1 |
+
+For **non-preset providers**, you must specify \`--base-url\` manually.
 
 Example:
 \`\`\`bash
@@ -144,6 +201,8 @@ Each command outputs a complete SKILL.md with YAML frontmatter. Use your agent f
 
 Verify skills are installed by listing them (e.g. \`skills_list()\`) and confirming all three appear.
 
+**⚠ After saving all skills, start a new session** so the agent loads the updated skill content. Skills saved in the current session are not active until the next session.
+
 ### Step 4 — Verify end-to-end
 
 Create a minimal workflow file to test your setup:
@@ -162,7 +221,7 @@ roles:
     frontmatter:
       type: object
       properties:
-        $status: { enum: [done] }
+        $status: { const: done }
         message: { type: string }
       required: [$status, message]
 graph:
@@ -189,11 +248,25 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working.
 ### Step 1 — Update packages
 
 \`\`\`bash
-pnpm add -g @united-workforce/cli@latest    # or: npm install -g @united-workforce/cli@latest
+# Using pnpm
-uwf --version   # should print ${CLI_VERSION}
+pnpm add -g @united-workforce/cli@latest
 
-# Also update your adapter(s)
+# Using npm
+npm install -g @united-workforce/cli@latest
+\`\`\`
+
+\`\`\`bash
+uwf --version   # should print ${CLI_VERSION}
+\`\`\`
+
+Also update your adapter(s):
+
+\`\`\`bash
+# pnpm
 pnpm add -g @united-workforce/agent-hermes@latest
+
+# npm
+npm install -g @united-workforce/agent-hermes@latest
 \`\`\`
 
 ### Step 2 — Regenerate skills
@@ -206,6 +279,8 @@ uwf prompt workflow-authoring  # → update skill "uwf-workflow-authoring"
 uwf prompt adapter-developing  # → update skill "uwf-adapter-developing"
 \`\`\`
 
+**⚠ After updating skills, start a new session** to load the new skill content.
+
 ### Step 3 — Migrate workflow YAML files (if needed)
 
 Check the changelog for breaking changes. Known migrations:
@@ -224,6 +299,17 @@ Check the changelog for breaking changes. Known migrations:
 
 Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax.
 
+- **v0.2.1**: \`$status: { enum: [value] }\` → \`$status: { const: "value" }\`. The validator no longer accepts \`enum\` for \`$status\`. Update all workflow YAML files:
+  \`\`\`yaml
+  # Before (v0.2.0)
+  $status: { enum: [done] }
+  $status: { type: string, enum: ["ready", "failed"] }
+
+  # After (v0.2.1+)
+  $status: { const: "done" }
+  # For multi-exit, use oneOf with const (unchanged)
+  \`\`\`
+
 ### Step 4 — Verify
 
 \`\`\`bash

packages/cli/src/commands/thread.ts

@@ -1001,12 +1001,6 @@ function spawnAgent(
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
       cwd,
-      env: {
-        ...process.env,
-        NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
-          .filter(Boolean)
-          .join(" "),
-      },
     });
   } catch (e) {
     const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
@@ -1254,12 +1248,6 @@ async function cmdThreadStepBackground(
   const child = spawn(scriptPath, args, {
     detached: true,
     stdio: "ignore",
-    env: {
-      ...process.env,
-      NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
-        .filter(Boolean)
-        .join(" "),
-    },
   });
 
   child.unref();

packages/cli/src/validate-semantic.ts

@@ -24,22 +24,22 @@ function isOneOfSchema(fm: unknown): fm is SchemaObj & { oneOf: SchemaObj[] } {
   return Array.isArray(obj.oneOf);
 }
 
-/** Check if a frontmatter schema declares "$status" as an enum (the required form for user roles). */
+/** Check if a frontmatter schema declares "$status" as const (flat schema form). */
-function hasStatusEnum(fm: unknown): boolean {
+function hasStatusConst(fm: unknown): boolean {
   if (typeof fm !== "object" || fm === null) return false;
   const obj = fm as SchemaObj;
   const props = obj.properties as Record<string, SchemaObj> | undefined;
   if (!props?.$status) return false;
-  return Array.isArray(props.$status.enum);
+  return typeof props.$status.const === "string";
 }
 
-/** Extract status values from an enum-based $status field. */
+/** Extract status values from a const-based $status field. */
-function getEnumStatuses(fm: SchemaObj): string[] {
+function getConstStatuses(fm: SchemaObj): string[] {
   const props = fm.properties as Record<string, SchemaObj> | undefined;
   if (!props?.$status) return [];
   const statusDef = props.$status;
-  if (!Array.isArray(statusDef.enum)) return [];
+  if (typeof statusDef.const === "string") return [statusDef.const];
-  return statusDef.enum as string[];
+  return [];
 }
 
 /** Get property names from a schema object. */
@@ -248,21 +248,21 @@ function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void
       checkOneOfDiscriminant(roleName, variants, statuses, errors);
       checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
       checkMultiExitMustache(roleName, graphEntry, variants, errors);
-    } else if (hasStatusEnum(fm)) {
+    } else if (hasStatusConst(fm)) {
-      const statuses = getEnumStatuses(fm as SchemaObj);
+      const statuses = getConstStatuses(fm as SchemaObj);
       checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
-      // For enum-based schemas, mustache vars come from the flat properties
+      // For const-based flat schemas, mustache vars come from the flat properties
-      checkEnumMustache(roleName, graphEntry, fm as SchemaObj, errors);
+      checkFlatMustache(roleName, graphEntry, fm as SchemaObj, errors);
     } else {
       errors.push(
-        `role "${roleName}" must define "$status" as an enum (or oneOf const) in frontmatter`,
+        `role "${roleName}" must define "$status" as const (or oneOf with const) in frontmatter`,
       );
     }
   }
 }
 
 /** Check mustache vars in all edge prompts against flat schema properties. */
-function checkEnumMustache(
+function checkFlatMustache(
   roleName: string,
   graphEntry: Record<string, { role: string; prompt: string }>,
   fm: SchemaObj,

packages/util-agent/__tests__/build-output-format-instruction.test.ts

@@ -143,7 +143,7 @@ describe("buildOutputFormatInstruction", () => {
         {
           type: "object",
           properties: {
-            $status: { type: "string", enum: ["approved"] },
+            $status: { const: "approved" },
             branch: { type: "string" },
           },
           required: ["$status"],
@@ -151,7 +151,7 @@ describe("buildOutputFormatInstruction", () => {
         {
           type: "object",
           properties: {
-            $status: { type: "string", enum: ["rejected"] },
+            $status: { const: "rejected" },
             comments: { type: "string" },
           },
           required: ["$status"],

packages/util/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/util",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "files": [
     "src",
     "dist",

packages/util/src/workflow-authoring-reference.ts

@@ -28,6 +28,7 @@ roles:                         # named actors
       2. Do that
     output: "..."              # what the agent should produce
     frontmatter:               # JSON Schema for structured output
+      type: object
       oneOf:
         - properties:
             $status: { const: "ready" }
@@ -71,10 +72,13 @@ The \`frontmatter\` field is a standard JSON Schema. It defines the structured f
 
 ### \`$status\` Field
 
-\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows.
+
+**Multi-exit (oneOf)** — use \`const\` to constrain each variant:
 
 \`\`\`yaml
 frontmatter:
+  type: object
   oneOf:
     - properties:
         $status: { const: "done" }
@@ -86,26 +90,25 @@ frontmatter:
       required: [$status, error]
 \`\`\`
 
-### Custom Fields
+**Single-exit (flat schema)** — same syntax, just no \`oneOf\` wrapper:
-
-Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
-
-### Flat Schema (Single Status)
-
-When a role has only one outcome, use \`enum\` with a single value:
 
 \`\`\`yaml
 frontmatter:
   type: object
   properties:
-    $status:
+    $status: { const: "done" }
-      type: string
-      enum: [done]
     summary: { type: string }
   required: [$status, summary]
 \`\`\`
 
-Note: \`$status: { const: "done" }\` is **not** valid in flat schemas — the validator requires \`enum\` or \`oneOf\` with \`const\`. Use \`const\` only inside \`oneOf\` variants.
+**Important rules:**
+- \`type: object\` is **required** at the top level of frontmatter (both flat and oneOf)
+- \`$status\` always uses \`const: "value"\` — simple and consistent
+- \`enum\` is **not supported** for \`$status\` — the validator will reject it
+
+### Custom Fields
+
+Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
 
 ## Graph Routing