@united-workforce/cli 0.1.1 → 0.2.1-rc.0

package/src/__tests__/thread-location.test.ts

@@ -57,10 +57,14 @@ roles:
         $status: { type: string, enum: ["ready"] }
 graph:
   $START:
-    _:
+    new:
       role: planner
       prompt: "Plan the work"
       location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
   planner:
     ready:
       role: $END
@@ -113,10 +117,14 @@ roles:
         $status: { type: string, enum: ["ready"] }
 graph:
   $START:
-    _:
+    new:
       role: planner
       prompt: "Plan"
       location: null
+    resume:
+      role: planner
+      prompt: "Resume"
+      location: null
   planner:
     ready:
       role: $END
@@ -156,10 +164,14 @@ roles:
         $status: { type: string, enum: ["ready"] }
 graph:
   $START:
-    _:
+    new:
       role: planner
       prompt: "Plan"
       location: null
+    resume:
+      role: planner
+      prompt: "Resume"
+      location: null
   planner:
     ready:
       role: $END

package/src/__tests__/thread-resume.test.ts

@@ -70,7 +70,10 @@ async function setupSuspendedThread(mode: MockAgentMode): Promise<{
       },
     },
     graph: {
-      $START: { _: { role: "worker", prompt: "Start work", location: null } },
+      $START: {
+        new: { role: "worker", prompt: "Start work", location: null },
+        resume: { role: "worker", prompt: "Resume the work", location: null },
+      },
       worker: {
         needs_input: {
           role: "$SUSPEND",
@@ -233,7 +236,10 @@ describe("uwf thread resume", () => {
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
         worker: { done: { role: "$END", prompt: "Done", location: null } },
       },
     });
@@ -479,7 +485,10 @@ describe("uwf thread resume - completed threads", () => {
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "Start work", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start work", location: null },
+          resume: { role: "worker", prompt: "Resume the work", location: null },
+        },
         worker: { done: { role: "reviewer", prompt: "Review the work", location: null } },
         reviewer: { done: { role: "$END", prompt: "Done", location: null } },
       },
@@ -610,7 +619,7 @@ echo '${adapterJson}'
     expect(cliOutput.done).toBe(false);
 
     const capturedPrompt = await readFile(promptCapturePath, "utf8");
-    expect(capturedPrompt).toContain("Previous run completed");
+    expect(capturedPrompt).toContain("Resume the work");
     expect(capturedPrompt).toContain("Additional context");
 
     const storeModule = await import("../store.js");
@@ -640,7 +649,10 @@ echo '${adapterJson}'
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
         worker: { done: { role: "$END", prompt: "Done", location: null } },
       },
     });
@@ -688,7 +700,10 @@ echo '${adapterJson}'
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "Start", location: null } },
+        $START: {
+          new: { role: "worker", prompt: "Start", location: null },
+          resume: { role: "worker", prompt: "Resume", location: null },
+        },
         worker: { done: { role: "$END", prompt: "Done", location: null } },
       },
     });

package/src/__tests__/thread-show-status.test.ts

@@ -34,10 +34,14 @@ roles:
         $status: { type: string, enum: ["ready"] }
 graph:
   $START:
-    _:
+    new:
       role: planner
       prompt: "Plan the work"
       location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
   planner:
     ready:
       role: $END
@@ -66,10 +70,14 @@ roles:
             question: { type: string }
 graph:
   $START:
-    _:
+    new:
       role: worker
       prompt: "Start work"
       location: null
+    resume:
+      role: worker
+      prompt: "Resume work"
+      location: null
   worker:
     needs_input:
       role: $SUSPEND

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

@@ -57,10 +57,14 @@ roles:
         $status: { type: string, enum: ["ready"] }
 graph:
   $START:
-    _:
+    new:
       role: planner
       prompt: "Plan the work"
       location: null
+    resume:
+      role: planner
+      prompt: "Resume the work"
+      location: null
   planner:
     ready:
       role: $END

package/src/__tests__/thread-suspend-step.test.ts

@@ -58,7 +58,10 @@ describe("suspend step CAS chain and threads.yaml metadata", () => {
           },
         },
         graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
           worker: {
             needs_input: {
               role: "$SUSPEND",

package/src/__tests__/thread-suspended-display.test.ts

@@ -55,7 +55,10 @@ describe("suspended thread display", () => {
           },
         },
         graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
           worker: {
             needs_input: {
               role: "$SUSPEND",
@@ -162,7 +165,10 @@ describe("suspended thread display", () => {
           },
         },
         graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
           worker: {
             needs_input: {
               role: "$SUSPEND",
@@ -248,7 +254,10 @@ describe("suspended thread display", () => {
           },
         },
         graph: {
-          $START: { _: { role: "worker", prompt: "Start work", location: null } },
+          $START: {
+            new: { role: "worker", prompt: "Start work", location: null },
+            resume: { role: "worker", prompt: "Resume work", location: null },
+          },
         },
       });
 

package/src/__tests__/validate-semantic.test.ts

@@ -51,7 +51,10 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
       },
     },
     graph: {
-      $START: { _: { role: "writer", prompt: "Begin writing", location: null } },
+      $START: {
+        new: { role: "writer", prompt: "Begin writing", location: null },
+        resume: { role: "writer", prompt: "Review previous output and continue", location: null },
+      },
       writer: { done: { role: "reviewer", prompt: "Review this: {{{plan}}}", location: null } },
       reviewer: {
         approved: { role: "$END", prompt: "Done: {{{summary}}}", location: null },
@@ -135,27 +138,38 @@ describe("Suite 2: Graph Structure", () => {
     expect(errors.some((e) => e.includes("$START must be defined in graph"))).toBe(true);
   });
 
-  test("2.2 $START has multiple status keys", () => {
+  test("2.2 $START missing resume edge", () => {
     const wf = makeWorkflow();
     wf.graph.$START = {
-      _: { role: "writer", prompt: "Begin", location: null },
-      other: { role: "reviewer", prompt: "Also", location: null },
+      new: { role: "writer", prompt: "Begin", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
-      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+      errors.some((e) => e.includes('$START must have edges with statuses "new" and "resume"')),
     ).toBe(true);
   });
 
-  test("2.3 $START edge uses non-_ status", () => {
+  test("2.3 $START missing new edge", () => {
     const wf = makeWorkflow();
-    wf.graph.$START = { ready: { role: "writer", prompt: "Begin", location: null } };
+    wf.graph.$START = {
+      resume: { role: "writer", prompt: "Resume", location: null },
+    };
     const errors = validateWorkflow(wf);
     expect(
-      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+      errors.some((e) => e.includes('$START must have edges with statuses "new" and "resume"')),
     ).toBe(true);
   });
 
+  test("2.3b $START with new and resume passes", () => {
+    const wf = makeWorkflow();
+    wf.graph.$START = {
+      new: { role: "writer", prompt: "Begin", location: null },
+      resume: { role: "writer", prompt: "Resume", location: null },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("$START must have edges"))).toBe(false);
+  });
+
   test("2.4 $END has outgoing edges", () => {
     const wf = makeWorkflow();
     wf.graph.$END = { _: { role: "writer", prompt: "Loop", location: null } };
@@ -193,15 +207,18 @@ describe("Suite 2: Graph Structure", () => {
 });
 
 describe("Suite 3: Status-Edge Consistency", () => {
-  test("3.1 user role using _ graph key is rejected", () => {
+  test("3.1 user role using _ graph key is treated as an unknown status", () => {
+    // "_" is no longer special-cased — it's just a status key that does not
+    // match the role's $status enum, so it surfaces as extra/missing keys.
     const wf = makeWorkflow();
     wf.graph.writer = { _: { role: "reviewer", prompt: "Review", location: null } };
     const errors = validateWorkflow(wf);
-    expect(
-      errors.some((e) =>
-        e.includes('role "writer" must use explicit $status keys in graph, not "_"'),
-      ),
-    ).toBe(true);
+    expect(errors.some((e) => e.includes('role "writer" graph has extra status keys: _'))).toBe(
+      true,
+    );
+    expect(errors.some((e) => e.includes('role "writer" graph is missing status keys: done'))).toBe(
+      true,
+    );
   });
 
   test("3.2 user role graph key not matching $status enum", () => {
@@ -240,13 +257,16 @@ describe("Suite 3: Status-Edge Consistency", () => {
     ).toBe(true);
   });
 
-  test("3.5 multi-exit role with _ key", () => {
+  test("3.5 multi-exit role with _ key is treated as an unknown status", () => {
     const wf = makeWorkflow();
     wf.graph.reviewer = { _: { role: "$END", prompt: "Done", location: null } };
     const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('role "reviewer" graph has extra status keys: _'))).toBe(
+      true,
+    );
     expect(
       errors.some((e) =>
-        e.includes('role "reviewer" must use explicit $status keys in graph, not "_"'),
+        e.includes('role "reviewer" graph is missing status keys: approved, rejected'),
       ),
     ).toBe(true);
   });

package/src/__tests__/workflow-resolution.test.ts

@@ -38,7 +38,10 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
       },
     },
     graph: {
-      $START: { _: { role: "worker", prompt: "start working", location: null } },
+      $START: {
+        new: { role: "worker", prompt: "start working", location: null },
+        resume: { role: "worker", prompt: "resume working", location: null },
+      },
       worker: { done: { role: "$END", prompt: "done", location: null } },
     },
   };

package/src/cli.ts

@@ -8,9 +8,7 @@ import {
   cmdPromptAdapterDeveloping,
   cmdPromptBootstrap,
   cmdPromptList,
-  cmdPromptSetup,
   cmdPromptUsage,
-  cmdPromptUsageReference,
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
@@ -509,23 +507,16 @@ prompt.addHelpCommand(false);
 
 prompt
   .command("usage")
-  .description("Print the complete skill content (all references combined)")
+  .description("Print the usage reference (CLI guide + typical workflows)")
   .action(() => {
     console.log(cmdPromptUsage());
   });
 
 prompt
-  .command("setup")
-  .description("Print setup instructions for installing the uwf skill")
-  .action(() => {
-    console.log(cmdPromptSetup());
-  });
-
-prompt
-  .command("usage-reference")
-  .description("Print the usage reference (CLI guide + typical workflows)")
+  .command("bootstrap")
+  .description("Print setup instructions for installing uwf skills")
   .action(() => {
-    console.log(cmdPromptUsageReference());
+    console.log(cmdPromptBootstrap());
   });
 
 prompt
@@ -542,13 +533,6 @@ prompt
     console.log(cmdPromptAdapterDeveloping());
   });
 
-prompt
-  .command("bootstrap")
-  .description("Print the bootstrap skill YAML for Hermes agents")
-  .action(() => {
-    console.log(cmdPromptBootstrap());
-  });
-
 prompt
   .command("list")
   .description("List all available prompt names")

package/src/commands/prompt.ts

@@ -1,14 +1,13 @@
 import {
   generateAdapterDevelopingReference,
-  generateBootstrapReference,
   generateUsageReference,
   generateWorkflowAuthoringReference,
+  VERSION,
 } from "@united-workforce/util";
 
 export {
   generateAdapterDevelopingReference as cmdPromptAdapterDeveloping,
-  generateBootstrapReference as cmdPromptBootstrap,
-  generateUsageReference as cmdPromptUsageReference,
+  generateUsageReference as cmdPromptUsage,
   generateWorkflowAuthoringReference as cmdPromptWorkflowAuthoring,
 };
 
@@ -16,66 +15,142 @@ const PROMPT_ENTRIES: ReadonlyArray<{ name: string; generate: () => string }> =
   { name: "usage", generate: generateUsageReference },
   { name: "workflow-authoring", generate: generateWorkflowAuthoringReference },
   { name: "adapter-developing", generate: generateAdapterDevelopingReference },
-  { name: "bootstrap", generate: generateBootstrapReference },
 ];
 
 export function cmdPromptList(): ReadonlyArray<string> {
   return PROMPT_ENTRIES.map((e) => e.name);
 }
 
-export function cmdPromptUsage(): string {
-  return PROMPT_ENTRIES.filter((e) => e.name !== "bootstrap")
-    .map((e) => e.generate())
-    .join("\n\n---\n\n");
-}
+export function cmdPromptBootstrap(): string {
+  return `# uwf Bootstrap
+
+Set up or upgrade uwf (United Workforce) — from zero to running your first workflow.
+
+## Scenario A: Fresh Install
+
+### Step 1 — Install CLI and agent adapter
+
+\`\`\`bash
+npm install -g @united-workforce/cli
+uwf --version   # should print ${VERSION}
+\`\`\`
+
+Install an agent adapter (at least one is required):
+
+| Adapter | Install | When to use |
+|---------|---------|-------------|
+| uwf-hermes | \`npm install -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent |
+| uwf-claude-code | \`npm install -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
+| uwf-builtin | \`npm install -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
+
+Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).
+
+### 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>]
+\`\`\`
+
+Preset providers (base-url is auto-filled when using a preset name):
+openai, xai, openrouter, venice, dashscope, deepseek, siliconflow, volcengine, kimi, glm, stepfun, minimax, ollama
+
+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:
 
-export function cmdPromptSetup(): string {
-  return `# uwf Skill Setup
+\`\`\`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.
+
+### Step 4 — Verify end-to-end
+
+Run a quick smoke test with the built-in eval workflow:
 
-You are being asked to install or update the uwf (United Workforce) skill
-so that you know how to use the \`uwf\` CLI for workflow orchestration.
+\`\`\`bash
+# Start a thread with the example workflow
+uwf thread start examples/eval-simple.yaml -p "Hello, test run"
+
+# Execute one step
+uwf thread exec <thread-id>
+
+# Check result
+uwf thread show <thread-id>
+\`\`\`
 
-## Steps
+If the thread reaches \`$END\` or produces output, the setup is working.
 
-1. **Check if uwf CLI is installed:**
-   \`\`\`bash
-   uwf --help
-   \`\`\`
-   If not installed: \`npm install -g @united-workforce/cli\`
+## Scenario B: Upgrade from Previous Version
 
-2. **Clean up old versions of the skill** (if any exist):
-   - Look for any existing uwf/workflow skill files in your skill directories
-     (e.g. \`~/.hermes/skills/uwf/SKILL.md\` or similar paths).
-   - If a skill exists, read its \`version\` from the YAML frontmatter.
-   - If the version matches the current CLI version (\`uwf --version\`), you're done — no update needed.
-   - If the version is older, **delete the old skill file** before proceeding.
+### Step 1 — Update packages
 
-3. **Install the bootstrap skill:**
-   \`\`\`bash
-   uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md
-   \`\`\`
-   The bootstrap prompt already includes complete YAML frontmatter — no editing needed.
+\`\`\`bash
+npm install -g @united-workforce/cli@latest
+uwf --version   # should print ${VERSION}
 
-4. **Verify** the skill is loadable by your agent framework.
+# Also update your adapter(s)
+npm install -g @united-workforce/agent-hermes@latest
+\`\`\`
 
-## Individual prompts
+### Step 2 — Regenerate skills
 
-Each prompt outputs a complete SKILL.md with frontmatter — pipe directly to a file:
+Skill content is bundled with the CLI — always regenerate after upgrading:
 
 \`\`\`bash
-uwf prompt list                                              # list available prompt names
-uwf prompt usage > ~/.hermes/skills/uwf-usage/SKILL.md      # CLI usage guide
-uwf prompt workflow-authoring > ~/.hermes/skills/uwf-workflow-authoring/SKILL.md
-uwf prompt adapter-developing > ~/.hermes/skills/uwf-adapter-developing/SKILL.md
-uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md        # bootstrap skill
+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"
 \`\`\`
 
-## Notes
+### Step 3 — Migrate workflow YAML files (if needed)
 
-- The skill content is bundled with the CLI and versioned with it — always use
-  \`uwf prompt usage\` to get the content matching your installed version.
-- Do NOT hand-edit the skill body. If the CLI is updated, re-run \`uwf prompt setup\`
-  and follow the steps again.
-- When upgrading, always delete the old skill first to avoid stale instructions.
+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.
+
+### Step 4 — Verify
+
+\`\`\`bash
+uwf thread start <your-workflow> -p "upgrade test"
+uwf thread exec <thread-id>
+\`\`\`
+
+## Available prompts
+
+\`\`\`bash
+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
+\`\`\`
 `;
 }

package/src/commands/thread.ts

@@ -911,7 +911,7 @@ function resolveEvaluateArgs(
   chain: ChainState,
 ): { lastRole: string; lastOutput: EvaluateLastOutput } {
   if (chain.headIsStart) {
-    return { lastRole: START_ROLE, lastOutput: { [STATUS_KEY]: "_" } };
+    return { lastRole: START_ROLE, lastOutput: { [STATUS_KEY]: "new" } };
   }
 
   const lastStep = chain.stepsNewestFirst[0];
@@ -1037,7 +1037,6 @@ function archiveThread(uwf: UwfStore, threadId: ThreadId, _workflow: CasRef, _he
   completeThread(uwf.varStore, threadId, "completed");
 }
 
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: orchestration function with inherent branching
 export async function cmdThreadResume(
   storageRoot: string,
   threadId: ThreadId,
@@ -1101,7 +1100,7 @@ export async function cmdThreadResume(
 
   // status === "completed"
   const workflow = loadWorkflowPayload(uwf, workflowHash);
-  const startResult = evaluate(workflow.graph, START_ROLE, {});
+  const startResult = evaluate(workflow.graph, START_ROLE, { [STATUS_KEY]: "resume" });
   if (!startResult.ok) {
     fail(`failed to evaluate $START: ${startResult.error.message}`);
   }
@@ -1113,11 +1112,7 @@ export async function cmdThreadResume(
   }
 
   const startRole = startResult.value.role;
-  const completedPromptPrefix = "Previous run completed. Resuming with additional context.";
-  const completedResumePrompt =
-    supplement !== null && supplement !== ""
-      ? `${completedPromptPrefix}\n\n${supplement}`
-      : completedPromptPrefix;
+  const completedResumePrompt = buildResumePrompt(startResult.value.prompt, supplement);
 
   const updatedEntry = { ...entry, status: "idle" as const, completedAt: null };
   setThread(uwf.varStore, threadId, updatedEntry);