docs: upgrade debate example — 3 roles, oneOf routing, bounded termination

Based on xiaonuo's battle-tested debate workflow. Changes:
- 3 roles (proponent/opponent/host) instead of 2
- oneOf + const schema (speak/conceded/final) instead of enum
- Bounded: 3rd speech forces final statement
- Host role delivers summary/highlights/verdict
- Critical thinking framework in procedure
- Edge prompts pass structured data via {{{argument}}}/{{{closing}}}

.changeset/inject-thread-progress.md

@@ -0,0 +1,12 @@
+---
+"@united-workforce/agent-hermes": patch
+"@united-workforce/agent-claude-code": patch
+"@united-workforce/util-agent": patch
+---
+
+feat: inject thread progress into agent prompt (#127)
+
+Agents now receive a "Thread Progress" section in their prompt showing the
+current step number and how many times the current role has spoken before.
+This eliminates the need for agents to make tool calls (terminal, delegate_task)
+just to count their own turn history.

.changeset/start-new-resume.md

@@ -1,9 +0,0 @@
----
-"@united-workforce/cli": minor
-"@united-workforce/util": patch
----
-
-feat: replace $START `_` status with `new`/`resume` semantics
-
-BREAKING: All workflow YAML files must update `$START._` to `$START.new` + `$START.resume`.
-The `resume` edge prompt replaces the previously hardcoded resume message in the CLI.

docs/wf-stateless-design.md

@@ -200,7 +200,7 @@ payload:
 
 - `roles` — 内联定义，每个 role 的 `meta` 是独立的 ocas_ref（指向 ocas 内置 JSON Schema 节点）
 - `graph` — `Record<Role | "$START", Record<Status, Target>>`，每个 Target = `{ role, prompt }`
-- Status 来自上一个 role 输出的 `status` 字段，`$START` 用 `_` 作为初始 status
+- Status 来自上一个 role 输出的 `$status` 字段，`$START` 使用 `new`（首次启动）和 `resume`（恢复已完成的 thread）作为 status
 - Prompt 模板使用 Mustache 渲染，变量来自 lastOutput
 - 不含 agent binding — agent 配置在 `~/.uwf/config.yaml` 中管理
 
@@ -208,7 +208,7 @@ Moderator 的求值逻辑：
 
 ```typescript
 evaluate(graph, lastRole, lastOutput) → { role, prompt }
-// 1. status = lastRole === "$START" ? "_" : lastOutput.status
+// 1. status = lastOutput.$status (e.g. "new" for $START first run, "resume" for completed thread resume)
 // 2. target = graph[lastRole][status]
 // 3. prompt = mustache.render(target.prompt, lastOutput)
 ```
@@ -422,8 +422,8 @@ type StepNodePayload = StepRecord & {
 Moderator 使用 `evaluate(graph, lastRole, lastOutput)` 进行同步 status-based routing：
 
 ```typescript
-// graph[lastRole][lastOutput.status] → Target { role, prompt }
+// graph[lastRole][lastOutput.$status] → Target { role, prompt }
-// $START 角色使用 "_" 作为初始 status
+// $START 使用 "new"（首次启动）和 "resume"（恢复已完成 thread）作为 status
 // prompt 通过 Mustache 模板渲染，变量来自 lastOutput
 ```
 

examples/debate.yaml

@@ -1,63 +1,140 @@
-name: "debate"
+name: debate
-description: "Structured debate between two sides. Tests cross-process session resume."
+description: "Structured two-side debate with host summary. Demonstrates multi-role coordination, oneOf output routing, and bounded termination."
+
 roles:
-  against:
+  proponent:
-    description: "Argues against the proposition"
+    description: "Argues FOR the proposition"
-    goal: |
+    goal: "Build a compelling case for the proposition through logical reasoning and evidence"
-      You are a skilled debater arguing AGAINST the proposition.
+    capabilities: []
-      Be logical, cite evidence, and directly address your opponent's points.
-      Keep each argument concise (under 200 words).
-    capabilities:
-      - argumentation
-      - critical-thinking
     procedure: |
-      1. If this is the opening, present your strongest argument against the proposition.
+      You are an experienced scholar arguing FOR the proposition.
-      2. If responding to the other side, directly counter their points with evidence and logic.
+
-      3. If you find yourself genuinely convinced by the other side, you may concede.
+      ## Critical Thinking Framework (apply before every response)
-    output: |
+
-      Provide your argument in the frontmatter.
+      ### A. Pre-response reflection (internal, do not output)
-      Set status to "conceded" ONLY if you are genuinely convinced and wish to stop debating.
+      - Does every step in my argument chain hold? Any hidden assumptions?
-      Otherwise set status to "continue".
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, you MUST output $status: final (closing statement).
+      3. If genuinely convinced by the opponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the opponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter:
+      type: object
+      oneOf:
+        - properties:
+            $status: { const: speak }
+            argument: { type: string }
+          required: [$status, argument]
+        - properties:
+            $status: { const: conceded }
+            reason: { type: string }
+          required: [$status, reason]
+        - properties:
+            $status: { const: final }
+            closing: { type: string }
+          required: [$status, closing]
+
+  opponent:
+    description: "Argues AGAINST the proposition"
+    goal: "Build a compelling case against the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing AGAINST the proposition.
+
+      ## Critical Thinking Framework (apply before every response)
+
+      ### A. Pre-response reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, or when the proponent has issued a final statement, you MUST output $status: final.
+      3. If genuinely convinced by the proponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the proponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter:
+      type: object
+      oneOf:
+        - properties:
+            $status: { const: speak }
+            argument: { type: string }
+          required: [$status, argument]
+        - properties:
+            $status: { const: conceded }
+            reason: { type: string }
+          required: [$status, reason]
+        - properties:
+            $status: { const: final }
+            closing: { type: string }
+          required: [$status, closing]
+
+  host:
+    description: "Debate moderator — delivers impartial summary and verdict"
+    goal: "Objectively review the debate, analyze both sides, and deliver a verdict"
+    capabilities: []
+    procedure: |
+      You are an experienced academic debate moderator.
+
+      ## Task
+      1. Outline each side's core arguments
+      2. Evaluate reasoning quality and evidence use
+      3. Highlight the most impactful exchanges
+      4. Analyze the deeper significance of the topic
+      5. Deliver an overall verdict
+
+      ## Style
+      - Impartial but with independent judgment
+      - Substantive, not superficial
+    output: "Debate summary report"
     frontmatter:
       type: object
       properties:
-        $status:
+        $status: { const: done }
-          enum: ["continue", "conceded"]
+        summary: { type: string }
-        argument:
+        highlights: { type: string }
-          type: string
+        verdict: { type: string }
-      required: [$status, argument]
+      required: [$status, summary, highlights, verdict]
-  for:
+
-    description: "Argues for the proposition"
-    goal: |
-      You are a skilled debater arguing FOR the proposition.
-      Be logical, cite evidence, and directly address your opponent's points.
-      Keep each argument concise (under 200 words).
-    capabilities:
-      - argumentation
-      - critical-thinking
-    procedure: |
-      1. Read the opposing side's latest argument carefully.
-      2. Counter their points with evidence and logic.
-      3. If you find yourself genuinely convinced by the other side, you may concede.
-    output: |
-      Provide your argument in the frontmatter.
-      Set status to "conceded" ONLY if you are genuinely convinced and wish to stop debating.
-      Otherwise set status to "continue".
-    frontmatter:
-      type: object
-      properties:
-        $status:
-          enum: ["continue", "conceded"]
-        argument:
-          type: string
-      required: [$status, argument]
 graph:
   $START:
-    new: { role: "against", prompt: "Present your opening argument against the proposition." }
+    new: { role: proponent, prompt: "The debate begins. You are arguing FOR the proposition. Present your opening argument." }
-    resume: { role: "against", prompt: "Review the previous debate output and continue the argument against the proposition." }
+    resume: { role: proponent, prompt: "The debate continues." }
-  against:
+
-    conceded: { role: "$END", prompt: "The against side conceded. Debate over." }
+  proponent:
-    continue: { role: "for", prompt: "Counter the opposing argument: {{{argument}}}" }
+    speak: { role: opponent, prompt: "Proponent argues:\n\n{{{argument}}}\n\nYou are the opponent. Counter this argument." }
-  for:
+    conceded: { role: host, prompt: "The proponent conceded: {{{reason}}}\n\nPlease summarize the debate." }
-    conceded: { role: "$END", prompt: "The for side conceded. Debate over." }
+    final: { role: opponent, prompt: "Proponent's closing statement:\n\n{{{closing}}}\n\nYou are the opponent. Deliver your final response." }
-    continue: { role: "against", prompt: "Counter the opposing argument: {{{argument}}}" }
+
+  opponent:
+    speak: { role: proponent, prompt: "Opponent argues:\n\n{{{argument}}}\n\nYou are the proponent. Counter this argument." }
+    conceded: { role: host, prompt: "The opponent conceded: {{{reason}}}\n\nPlease summarize the debate." }
+    final: { role: host, prompt: "Opponent's closing statement:\n\n{{{closing}}}\n\nThe debate is over. Please summarize." }
+
+  host:
+    done: { role: "$END", prompt: "Summary complete." }

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/claude-code.ts

@@ -7,6 +7,7 @@ import {
   type AgentRunResult,
   buildContinuationPrompt,
   buildRolePrompt,
+  buildThreadProgress,
   createAgent,
   getCachedSessionId,
   setCachedSessionId,
@@ -27,6 +28,10 @@ export function buildClaudeCodePrompt(ctx: AgentContext): string {
   if (ctx.outputFormatInstruction !== undefined && ctx.outputFormatInstruction !== "") {
     parts.push(ctx.outputFormatInstruction, "");
   }
+
+  // Inject thread progress so the agent knows step count and role visit count
+  parts.push(buildThreadProgress(ctx.steps, ctx.role), "");
+
   parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
 
   if (!ctx.isFirstVisit) {

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-hermes/src/hermes.ts

@@ -6,6 +6,7 @@ import {
   type AgentRunResult,
   buildContinuationPrompt,
   buildRolePrompt,
+  buildThreadProgress,
   createAgent,
 } from "@united-workforce/util-agent";
 import type { AcpUsage } from "./acp-client.js";
@@ -60,6 +61,9 @@ export function buildHermesPrompt(ctx: AgentContext): string {
     parts.push(ctx.outputFormatInstruction, "");
   }
 
+  // Inject thread progress so the agent knows step count and role visit count
+  parts.push(buildThreadProgress(ctx.steps, ctx.role), "");
+
   if (!ctx.isFirstVisit) {
     // Re-entry: show only steps since last visit, meta only
     parts.push(buildContinuationPrompt(ctx.steps, ctx.role, ctx.edgePrompt));

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.1.1",
+  "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__/prompt.test.ts

@@ -71,12 +71,22 @@ describe("prompt commands", () => {
   test("prompt bootstrap returns framework-agnostic setup instructions", () => {
     const result = cmdPromptBootstrap();
     expect(typeof result).toBe("string");
+    // Skills installation
     expect(result).toContain("uwf prompt usage");
     expect(result).toContain("uwf prompt workflow-authoring");
     expect(result).toContain("uwf prompt adapter-developing");
     expect(result).toContain("uwf-usage");
     expect(result).toContain("uwf-workflow-authoring");
     expect(result).toContain("uwf-adapter-developing");
+    // Fresh install scenario
+    expect(result).toContain("Fresh Install");
+    expect(result).toContain("uwf setup");
+    expect(result).toContain("--provider");
+    expect(result).toContain("--api-key");
+    expect(result).toContain("agent adapter");
+    // Upgrade scenario
+    expect(result).toContain("Upgrade");
+    expect(result).toContain("Migrate");
     // Should NOT contain Hermes-specific paths
     expect(result).not.toContain("~/.hermes/skills/");
     expect(result).not.toContain("> ~/.hermes/");

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";
@@ -11,7 +11,7 @@ import {
   cmdPromptUsage,
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
-import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdSetup, cmdSetupInteractive, resolvePresetBaseUrl } from "./commands/setup.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
@@ -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")
@@ -558,10 +558,14 @@ program
     }) => {
       const storageRoot = resolveStorageRoot();
       runAction(async () => {
-        if (opts.provider && opts.baseUrl && opts.apiKey && opts.model) {
+        // Resolve preset base-url when provider is known but --base-url is omitted
+        const resolvedBaseUrl =
+          opts.baseUrl ??
+          (opts.provider !== undefined ? resolvePresetBaseUrl(opts.provider) : null);
+        if (opts.provider && resolvedBaseUrl && opts.apiKey && opts.model) {
           const result = await cmdSetup({
             provider: opts.provider,
-            baseUrl: opts.baseUrl,
+            baseUrl: resolvedBaseUrl,
             apiKey: opts.apiKey,
             model: opts.model,
             agent: opts.agent ?? undefined,
@@ -572,7 +576,7 @@ program
           await cmdSetupInteractive(storageRoot);
         } else {
           throw new Error(
-            "Non-interactive setup requires all of: --provider, --base-url, --api-key, --model",
+            "Non-interactive setup requires: --provider, --api-key, --model (--base-url is optional for preset providers)",
           );
         }
       });

packages/cli/src/commands/prompt.ts

@@ -1,10 +1,35 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   generateAdapterDevelopingReference,
   generateUsageReference,
   generateWorkflowAuthoringReference,
-  VERSION,
 } from "@united-workforce/util";
 
+// CLI package version (for bootstrap prompt — uwf --version prints this)
+// Walk up from __dirname to find the nearest package.json (works from both src/ and dist/)
+function _findCliVersion(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as {
+        name?: string;
+        version?: string;
+      };
+      if (pkg.name === "@united-workforce/cli") {
+        return pkg.version ?? "0.0.0";
+      }
+    } catch {
+      // not found, keep walking
+    }
+    dir = dirname(dir);
+  }
+  return "0.0.0";
+}
+const CLI_VERSION = _findCliVersion();
+
 export {
   generateAdapterDevelopingReference as cmdPromptAdapterDeveloping,
   generateUsageReference as cmdPromptUsage,
@@ -22,33 +47,275 @@ export function cmdPromptList(): ReadonlyArray<string> {
 }
 
 export function cmdPromptBootstrap(): string {
-  return `# uwf Skill Bootstrap
+  return `# uwf Bootstrap
 
-Install or update the uwf (United Workforce) skills for your agent.
+Set up or upgrade uwf (United Workforce) — from zero to running your first workflow.
 
-## Steps
+## Scenario A: Fresh Install
+
+### Step 0 — Environment pre-flight check
+
+Run ALL checks below BEFORE installing anything. If any check fails, fix it first — do NOT skip ahead.
 
-1. **Check if uwf CLI is installed:**
 \`\`\`bash
-   uwf --help
+# 1. Node.js
+node --version   # need v20+
+# FIX: install via nvm (https://github.com/nvm-sh/nvm) or your OS package manager
+
+# 2. Package manager — pnpm (preferred) or npm
+pnpm --version || npm --version
+# FIX for pnpm: corepack enable pnpm   (Node 20+)
+#   or: npm install -g pnpm
+# If pnpm is not an option, npm works too — adjust install commands below
+
+# 3. Global bin directory is in PATH
+# For pnpm:
+pnpm bin -g       # prints the global bin directory
+# For npm:
+npm prefix -g     # global prefix; bin is <prefix>/bin
+# The directory printed above MUST be in your PATH.
+# Test: echo \\$PATH | tr ':' '\\\\n'
+# 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"
 \`\`\`
-   If not installed: \`npm install -g @united-workforce/cli\`
-   Current version: ${VERSION}
 
-2. **Install the skills** by running each command below and creating a skill from its output:
+**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.
-   - Run \`uwf prompt usage\` → create a skill named \`uwf-usage\`
-   - Run \`uwf prompt workflow-authoring\` → create a skill named \`uwf-workflow-authoring\`
-   - Run \`uwf prompt adapter-developing\` → create a skill named \`uwf-adapter-developing\`
 
-   Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them.
+### Step 1 — Discover agents and install adapter
 
-3. **Verify** the skills are loadable by your agent framework.
+**First, detect which supported agents are already installed on the user's machine:**
 
-## Updating
+\`\`\`bash
+# Check for Hermes Agent
+which hermes 2>/dev/null && hermes --version
 
-When \`uwf\` is upgraded, re-run \`uwf prompt bootstrap\` and follow the steps again.
+# Check for Claude Code
-The skill content is bundled with the CLI — always use \`uwf prompt <name>\` to get
+which claude 2>/dev/null && claude --version   # should show "X.Y.Z (Claude Code)"
-content matching your installed version.
+\`\`\`
+
+**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
+
+# 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
+\`\`\`
+
+**⚠ Adapter versions are independent from CLI versions.** Do NOT try to match adapter version to CLI version. Just install \`@latest\` (the default).
+
+**After installing, verify that \`uwf\` and the adapter are available in PATH:**
+
+\`\`\`bash
+uwf --version          # should print ${CLI_VERSION}
+uwf-hermes --version   # or: uwf-claude-code --version
+\`\`\`
+
+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> --api-key <key> --model <model> --agent <adapter-command>
+\`\`\`
+
+**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name.
+
+**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
+uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes
+\`\`\`
+
+If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default.
+
+Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`.
+
+### Step 3 — Install skills
+
+Run each command and create a skill from its output:
+
+\`\`\`bash
+uwf prompt usage               # → save as skill "uwf-usage"
+uwf prompt workflow-authoring  # → save as skill "uwf-workflow-authoring"
+uwf prompt adapter-developing  # → save as skill "uwf-adapter-developing"
+\`\`\`
+
+Each command outputs a complete SKILL.md with YAML frontmatter. Use your agent framework's skill creation API to save them (e.g. \`skill_manage(action='create', name='uwf-usage', content=<output>)\`).
+
+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:
+
+\`\`\`bash
+cat > /tmp/hello.yaml << 'YAML'
+name: hello
+description: Minimal smoke test
+roles:
+  greeter:
+    description: "Greet the user"
+    goal: "Respond with a friendly greeting"
+    capabilities: []
+    procedure: "Write a short greeting based on the prompt."
+    output: "A greeting message."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        message: { type: string }
+      required: [$status, message]
+graph:
+  $START:
+    new: { role: greeter, prompt: "Say hello to the user." }
+    resume: { role: greeter, prompt: "Greet the user again." }
+  greeter:
+    done: { role: "$END", prompt: "Done." }
+YAML
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+uwf thread start /tmp/hello.yaml -p "Hello, world!"
+uwf thread exec <thread-id>
+uwf thread show <thread-id>
+\`\`\`
+
+If the thread reaches \`$END\` with status \`completed\`, the setup is working.
+
+## Scenario B: Upgrade from Previous Version
+
+### Step 1 — Update packages
+
+\`\`\`bash
+# Using pnpm
+pnpm add -g @united-workforce/cli@latest
+
+# 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
+
+Skill content is bundled with the CLI — always regenerate after upgrading:
+
+\`\`\`bash
+uwf prompt usage               # → update skill "uwf-usage"
+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:
+
+- **v0.2.0**: \`$START._\` → \`$START.new\` + \`$START.resume\`. All workflow YAML files must be updated:
+  \`\`\`yaml
+  # Before (v0.1.x)
+  $START:
+    _: { role: planner, prompt: "..." }
+
+  # After (v0.2.0+)
+  $START:
+    new: { role: planner, prompt: "..." }
+    resume: { role: planner, prompt: "Review previous run and continue." }
+  \`\`\`
+
+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
+uwf thread start <your-workflow> -p "upgrade test"
+uwf thread exec <thread-id>
+\`\`\`
 
 ## Available prompts
 
@@ -57,6 +324,7 @@ uwf prompt list                # list available prompt names
 uwf prompt usage               # CLI usage guide
 uwf prompt workflow-authoring  # workflow YAML design guide
 uwf prompt adapter-developing  # building agent adapters
+uwf prompt bootstrap           # this guide
 \`\`\`
 `;
 }

packages/cli/src/commands/setup.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
@@ -72,6 +73,12 @@ const PRESET_PROVIDERS = [
   { name: "ollama", label: "Ollama (local)", baseUrl: "http://localhost:11434/v1" },
 ] as const;
 
+/** Look up the base URL for a preset provider name. Returns null if not a preset. */
+export function resolvePresetBaseUrl(providerName: string): string | null {
+  const preset = PRESET_PROVIDERS.find((p) => p.name === providerName);
+  return preset !== undefined ? preset.baseUrl : null;
+}
+
 type SetupArgs = {
   provider: string;
   baseUrl: string;
@@ -175,7 +182,6 @@ export async function _discoverAgents(): Promise<string[]> {
 
 async function _tryWhichDiscovery(): Promise<string[] | null> {
   try {
-    const { execFileSync } = await import("node:child_process");
     const text = execFileSync("which", ["-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -391,6 +397,37 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
   };
 }
 
+/**
+ * Check if the configured adapter binary (and its dependencies) are in PATH.
+ * Returns warnings array — empty means all good.
+ */
+export function _checkAdapterAvailability(agentName: string): string[] {
+  const warnings: string[] = [];
+  const binary = `uwf-${agentName}`;
+
+  try {
+    execFileSync("which", [binary], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    warnings.push(
+      `${binary} not found in PATH. Install it: pnpm add -g @united-workforce/agent-${agentName}`,
+    );
+    return warnings; // skip dependency check if adapter itself is missing
+  }
+
+  // uwf-hermes depends on hermes CLI
+  if (agentName === "hermes") {
+    try {
+      execFileSync("which", ["hermes"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+    } catch {
+      warnings.push(
+        'hermes CLI not found in PATH (required by uwf-hermes). Fix: export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"',
+      );
+    }
+  }
+
+  return warnings;
+}
+
 /**
  * Non-interactive setup. All required args provided via CLI flags.
  */
@@ -405,15 +442,26 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
 
   writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");
 
+  // Print config path to stderr (stdout is reserved for JSON output)
+  console.error(`Config saved to ${configPath} ✓`);
+
   // Validate model connectivity
   const validation = await validateModel(args.baseUrl, args.apiKey, args.model);
 
+  // Check adapter availability
+  const agentName = _agentNameFromBinary(args.agent ?? "hermes");
+  const adapterWarnings = _checkAdapterAvailability(agentName);
+  for (const w of adapterWarnings) {
+    console.error(`⚠ ${w}`);
+  }
+
   return {
     configPath,
     provider: args.provider,
     model: args.model,
     defaultAgent: merged.defaultAgent,
     validation,
+    adapterWarnings,
   };
 }
 

packages/cli/src/commands/thread.ts

@@ -1004,6 +1004,12 @@ function spawnAgent(
     });
   } catch (e) {
     const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
+    if (err.code === "ENOENT") {
+      failStep(
+        plog,
+        `"${agent.command}" not found in PATH. Install it or check your PATH config. Run: which ${agent.command}`,
+      );
+    }
     const stderr =
       err.stderr == null
         ? ""

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/cli/src/validate.ts

@@ -99,7 +99,7 @@ export function checkWorkflowFilenameConsistency(
 ): string | null {
   const expected = workflowNameFromPath(filePath);
   if (payload.name !== expected) {
-    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
+    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}". Either rename the file to "${payload.name}.yaml" or change the YAML \`name\` field to "${expected}"`;
   }
   return null;
 }

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-agent/__tests__/build-thread-progress.test.ts

@@ -0,0 +1,59 @@
+import type { StepContext } from "@united-workforce/protocol";
+import { describe, expect, test } from "vitest";
+import { buildThreadProgress } from "../src/build-thread-progress.js";
+
+function makeStep(role: string): StepContext {
+  return {
+    role,
+    output: {},
+    detail: "0000000000000" as string,
+    agent: "uwf-mock",
+    edgePrompt: "",
+    startedAtMs: 0,
+    completedAtMs: 0,
+    cwd: "",
+    assembledPrompt: null,
+    usage: null,
+    content: null,
+  };
+}
+
+describe("buildThreadProgress", () => {
+  test("first step of thread", () => {
+    const result = buildThreadProgress([], "proponent");
+    expect(result).toContain("## Thread Progress");
+    expect(result).toContain("first step");
+    expect(result).toContain("first time");
+    expect(result).toContain("proponent");
+  });
+
+  test("second step, role not seen before", () => {
+    const steps = [makeStep("opponent")];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 2");
+    expect(result).toContain("spoken 0 times");
+  });
+
+  test("role has spoken once before", () => {
+    const steps = [makeStep("proponent"), makeStep("opponent")];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 3");
+    expect(result).toContain("spoken 1 time before");
+    // singular "time" not "times"
+    expect(result).not.toContain("1 times");
+  });
+
+  test("role has spoken multiple times", () => {
+    const steps = [
+      makeStep("proponent"),
+      makeStep("opponent"),
+      makeStep("proponent"),
+      makeStep("opponent"),
+      makeStep("proponent"),
+      makeStep("opponent"),
+    ];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 7");
+    expect(result).toContain("spoken 3 times");
+  });
+});

packages/util-agent/src/build-thread-progress.ts

@@ -0,0 +1,27 @@
+import type { StepContext } from "@united-workforce/protocol";
+
+/**
+ * Build a compact thread-progress summary so the agent knows where it is
+ * in the conversation without making tool calls to count steps.
+ *
+ * Example output:
+ *   ## Thread Progress
+ *   Thread step 6. You (proponent) have spoken 2 times before this turn.
+ */
+export function buildThreadProgress(steps: StepContext[], role: string): string {
+  const totalSteps = steps.length;
+  const roleVisits = steps.filter((s) => s.role === role).length;
+
+  const parts = [`## Thread Progress`];
+  if (totalSteps === 0) {
+    parts.push(
+      `This is the first step of the thread. You (${role}) are speaking for the first time.`,
+    );
+  } else {
+    parts.push(
+      `Thread step ${totalSteps + 1}. You (${role}) have spoken ${roleVisits} time${roleVisits === 1 ? "" : "s"} before this turn.`,
+    );
+  }
+
+  return parts.join("\n");
+}

packages/util-agent/src/index.ts

@@ -1,6 +1,7 @@
 export { buildContinuationPrompt } from "./build-continuation-prompt.js";
 export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
 export { buildRolePrompt } from "./build-role-prompt.js";
+export { buildThreadProgress } from "./build-thread-progress.js";
 export type { BuildContextMeta } from "./context.js";
 export { buildContext, buildContextWithMeta } from "./context.js";
 export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";

packages/util/package.json

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

packages/util/src/index.ts

@@ -15,7 +15,7 @@ export {
   validateFrontmatter,
 } from "./frontmatter-markdown/index.js";
 export { createLogger } from "./logger.js";
-export { generateModeratorReference } from "./moderator-reference.js";
+
 export type {
   CreateProcessLoggerOptions,
   ProcessLogFn,
@@ -35,4 +35,3 @@ export { extractUlidTimestamp, generateUlid } from "./ulid.js";
 export { generateUsageReference } from "./usage-reference.js";
 export { VERSION } from "./version.js";
 export { generateWorkflowAuthoringReference } from "./workflow-authoring-reference.js";
-export { generateYamlReference } from "./yaml-reference.js";

packages/util/src/moderator-reference.ts

@@ -1,57 +0,0 @@
-export function generateModeratorReference(): string {
-  return `# Moderator Reference
-
-## Overview
-
-The moderator is the workflow engine's routing component. It evaluates the directed graph defined in the workflow YAML to determine the next role (or \`$END\`) after each step — with zero LLM cost.
-
-## Status-Based Routing
-
-The moderator uses **status-based routing**: it inspects the previous step's extracted output (specifically the \`$status\` field) and looks up the corresponding edge in the graph.
-
-### Graph Structure
-
-The graph is a nested map: \`Record<Role | "$START", Record<Status, Target>>\`. Each role maps its possible \`$status\` values to a target with a \`role\` and \`prompt\`:
-
-\`\`\`yaml
-graph:
-  $START:
-    new: { role: planner, prompt: "Analyze the issue." }
-    resume: { role: planner, prompt: "Review the previous run output and continue." }
-  planner:
-    ready: { role: developer, prompt: "Implement the plan (CAS hash: {{{plan}}})." }
-    insufficient_info: { role: $END, prompt: "Not enough info." }
-  developer:
-    done: { role: reviewer, prompt: "Review branch {{{branch}}} at {{{worktree}}}." }
-    failed: { role: $END, prompt: "Developer failed: {{{reason}}}." }
-  reviewer:
-    approved: { role: tester, prompt: "Run tests on {{{branch}}} at {{{worktree}}}." }
-    rejected: { role: developer, prompt: "Fix issues: {{{comments}}}." }
-\`\`\`
-
-### Routing Algorithm
-
-1. Look up \`graph[lastRole]\` to get the status map for the current role
-2. Look up \`statusMap[lastOutput.$status]\` to get the target
-3. If target role is \`$END\`, mark thread as completed
-4. Otherwise, render the edge prompt (Mustache templates with \`{{{field}}}\` from output) and spawn the next agent
-
-### Edge Prompts and Mustache Templates
-
-Edge prompts use triple-brace Mustache syntax (\`{{{field}}}\`) to interpolate values from the previous step's output into the next agent's task prompt. This passes structured data (branch names, file paths, CAS hashes) between roles without manual wiring.
-
-## Special Nodes
-
-- \`$START\` — entry point; uses status keys \`new\` (first start) and \`resume\` (resuming a completed thread)
-- \`$END\` — terminal node; thread completes when reached and is moved to history
-
-## Integration with Steps
-
-Each \`uwf thread exec\` cycle:
-1. Moderator reads the thread's head step output
-2. Looks up \`graph[lastRole][output.$status]\` to pick the next role
-3. If next is \`$END\`, marks thread as completed
-4. Otherwise, renders the edge prompt and spawns the agent for the selected role
-5. Extract pipeline parses agent output → new step node → append to CAS chain
-`;
-}

packages/util/src/usage-reference.ts

@@ -140,5 +140,18 @@ For specific scenarios, run the corresponding \`uwf prompt\` command:
 |----------|---------|-------------|
 | Writing workflow YAML | \`uwf prompt workflow-authoring\` | Designing roles, conditions, graphs, and edge prompts |
 | Building a new agent adapter | \`uwf prompt adapter-developing\` | Creating a new \`uwf-<name>\` CLI adapter |
+
+## Upgrading
+
+\`\`\`bash
+# Install the latest version
+pnpm add -g @united-workforce/cli@latest @united-workforce/agent-hermes@latest
+# or: npm install -g @united-workforce/cli@latest @united-workforce/agent-hermes@latest
+
+# Verify
+uwf --version
+
+# Then run uwf prompt bootstrap and follow the upgrade instructions
+\`\`\`
 `;
 }

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,22 +90,26 @@ 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:
 
 \`\`\`yaml
 frontmatter:
+  type: object
   properties:
     $status: { const: "done" }
     summary: { type: string }
   required: [$status, summary]
 \`\`\`
 
+**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
 
 The graph maps each role's \`$status\` values to the next role:

packages/util/src/yaml-reference.ts

@@ -1,83 +0,0 @@
-export function generateYamlReference(): string {
-  return `# Workflow YAML Schema Reference
-
-## Top-Level Structure
-
-A workflow YAML file defines the complete workflow specification:
-
-\`\`\`yaml
-name: solve-issue          # verb-first kebab-case identifier
-description: "..."         # human-readable description
-
-roles:                     # named actors in the workflow
-  planner:
-    description: "Analyzes issue and outputs a plan"
-    goal: "You are a planning agent."
-    capabilities:
-      - issue-analysis
-      - planning
-    procedure: |
-      1. Read the issue
-      2. Produce a test spec
-    output: "Output the plan summary. Set $status to ready or insufficient_info."
-    frontmatter:           # JSON Schema for structured output (drives routing)
-      oneOf:
-        - properties:
-            $status: { const: ready }
-            plan: { type: string }
-          required: [$status, plan]
-        - properties:
-            $status: { const: insufficient_info }
-          required: [$status]
-
-graph:                     # status-based routing (nested map)
-  $START:
-    new: { role: planner, prompt: "Analyze the issue." }
-    resume: { role: planner, prompt: "Review the previous run output and continue." }
-  planner:
-    ready: { role: developer, prompt: "Implement plan {{{plan}}}." }
-    insufficient_info: { role: $END, prompt: "Not enough info." }
-\`\`\`
-
-## roles
-
-Each role defines an actor in the workflow:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| \`description\` | string | Short description of the role's purpose |
-| \`goal\` | string | System-level goal statement for the agent |
-| \`capabilities\` | string[] | Tags describing what the role can do |
-| \`procedure\` | string | Step-by-step instructions for the agent |
-| \`output\` | string | Description of expected output format |
-| \`frontmatter\` | JSON Schema | Defines the structured output the agent must produce |
-
-### frontmatter
-
-The \`frontmatter\` field is a standard JSON Schema object. The extract pipeline validates agent output against it. Key conventions:
-- \`$status\` field drives routing decisions in the graph
-- Use \`const\` or \`enum\` to constrain status values
-- Use \`oneOf\` to define multiple valid output shapes (one per status)
-- All \`required\` fields must appear in the agent's frontmatter output
-
-## graph
-
-The graph is a nested map defining status-based routing:
-
-\`\`\`
-Record<Role | "$START", Record<Status, { role: string, prompt: string }>>
-\`\`\`
-
-| Level | Key | Value |
-|-------|-----|-------|
-| Outer | Role name or \`$START\` | Status map for that role |
-| Inner | \`$status\` value | Target: \`{ role, prompt }\` |
-
-### Special Nodes
-- \`$START\` — entry point; uses status keys \`new\` (first start) and \`resume\` (resuming a completed thread)
-- \`$END\` — terminal node; thread completes when reached
-
-### Edge Prompts
-Prompts use triple-brace Mustache templates (\`{{{field}}}\`) to interpolate values from the previous step's output. Example: \`"Implement plan {{{plan}}} in repo {{{repoPath}}}."\`
-`;
-}