docs: update wf-stateless-design.md to reflect new/resume semantics

Refs #101
2026-06-05 09:37:52 +00:00
50 changed files with 967 additions and 837 deletions
@@ -0,0 +1,9 @@
+---
+"@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.
@@ -0,0 +1,247 @@
+name: "solve-issue"
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
+roles:
+  planner:
+    description: "Analyzes issue and outputs a TDD test spec"
+    goal: "You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: |
+      On first run (no previous steps):
+      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
+      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md, .cursor/rules/) in the repo
+      3. Assess whether the issue has enough information to produce a test spec
+      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info
+      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
+
+      On subsequent runs (bounced back by tester with fix_spec):
+      1. Read the tester's output from the previous step to understand what's wrong with the spec
+      2. Revise the test spec accordingly
+
+      After producing the test spec:
+      1. The test spec is stored in CAS automatically by the uwf pipeline (agents do not need to call `ocas put` directly)
+      2. Put the plan hash in frontmatter.plan (required when $status=ready)
+      3. Set repoPath to the absolute path of the repository root
+
+      IMPORTANT: Extract the repo remote (owner/repo) from git:
+      ```bash
+      git remote get-url origin | sed 's|.*[:/]\([^/]*/[^.]*\).*|\1|'
+      ```
+      Store the result as repoRemote in your frontmatter output so downstream roles can use it for tea/API calls.
+    output: "Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+            repoRemote: { type: string }
+          required: [$status, plan, repoPath, repoRemote]
+        - properties:
+            $status: { const: "insufficient_info" }
+            reason: { type: string }
+          required: [$status, reason]
+  developer:
+    description: "TDD implementation per test spec"
+    goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
+    capabilities:
+      - coding
+    procedure: |
+      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+      The repo path and other details are provided in your task prompt.
+
+      Before starting any work, set up an isolated worktree:
+      1. cd into the repo path provided in your task prompt
+      2. `git fetch origin` to get latest refs
+      3. First time (no existing branch):
+         - `git worktree add .worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
+         - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`
+      4. If bounced back from reviewer or tester (branch already exists):
+         - cd into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`
+         - `git fetch origin && git rebase origin/main`
+      5. ALL subsequent work must happen inside the worktree directory.
+
+      Then implement TDD:
+      6. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner's output in your task prompt)
+      7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt
+      8. Write tests first based on the spec
+      9. Implement the code to make tests pass
+      10. Ensure `bun run build` passes with no errors
+      11. Run `bun test` to verify all tests pass
+          - If tests fail on first run:
+            * Read the test output carefully for missing imports or setup issues
+            * Check if you're running tests from the correct working directory (package root vs workspace root)
+            * Fix the immediate issue and rerun ONCE
+            * If tests still fail after 2 attempts: check the test spec for ambiguities
+            * If stuck after 3 test cycles: set $status=failed with detailed error report rather than continuing blind retries
+      12. MANDATORY VERIFICATION before reporting done:
+          - Run `git branch --show-current` and confirm branch name matches expected
+          - Run `git status` and verify changed files exist
+          - Run `ls -la <key-implementation-files>` to verify they exist on disk
+          - If ANY verification fails: retry the implementation, do NOT report done
+
+      If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,
+      or repeated attempts fail), set $status=failed with a reason.
+    output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "done" }
+            branch: { type: string }
+            worktree: { type: string }
+            repoRemote: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "failed" }
+            reason: { type: string }
+          required: [$status, reason]
+  reviewer:
+    description: "Code standards compliance check"
+    goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      CRITICAL: You MUST execute every verification command below. Do NOT report results without running the actual commands. Do NOT rely on prior context or assumptions.
+
+      Before reviewing, verify the worktree and branch exist:
+      0. Run `cd <worktree-path> && pwd` to confirm the path is accessible
+         - If the cd fails: the worktree truly doesn't exist, reject with that reason
+         - If the cd succeeds: proceed with step 1 below
+      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
+      2. If the branch doesn't correspond to the issue, flag it in your output and reject
+
+      Then perform code review:
+      Hard checks (must all pass):
+      3. `bun run build` — no build errors
+      4. `bunx biome check` — no lint violations
+      5. TypeScript strict mode — no type errors
+
+      Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist):
+      - Naming conventions, module boundaries, code style
+      - No `console.log` in production code
+      - No dynamic imports in production code
+
+      Only review standards compliance. Do NOT test functionality.
+      If rejecting, you MUST explain the specific reason in your output.
+    output: "Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "approved" }
+            branch: { type: string }
+            worktree: { type: string }
+            repoRemote: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "rejected" }
+            comments: { type: string }
+            worktree: { type: string }
+            repoRemote: { type: string }
+          required: [$status, comments, worktree]
+  tester:
+    description: "Functional correctness verification"
+    goal: "You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec."
+    capabilities:
+      - testing
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      1. Run `bun test` for automated test verification
+      2. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner step in the thread history)
+      3. Verify each scenario in the spec is covered and passing
+      4. Determine outcome:
+         - passed: all scenarios verified, tests pass
+         - fix_code: tests fail or implementation doesn't match spec → send back to developer
+         - fix_spec: the spec itself is wrong or incomplete → send back to planner
+    output: "Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "passed" }
+            branch: { type: string }
+            worktree: { type: string }
+            repoRemote: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "fix_code" }
+            report: { type: string }
+            repoRemote: { type: string }
+            worktree: { type: string }
+            branch: { type: string }
+          required: [$status, report]
+        - properties:
+            $status: { const: "fix_spec" }
+            report: { type: string }
+            repoRemote: { type: string }
+            worktree: { type: string }
+            branch: { type: string }
+          required: [$status, report]
+  committer:
+    description: "Commits and creates PR"
+    goal: "You are a committer agent. You create a clean commit and push a PR linking the original issue."
+    capabilities: []
+    procedure: |
+      The worktree path, branch name, and repo remote (owner/repo) are provided in your task prompt.
+      cd into the worktree first.
+
+      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
+      1. Check `git status` — if working tree is clean and branch is ahead of origin, skip to step 3 (push).
+      2. If there are unstaged/uncommitted changes: `git add -A` then `git commit -m "type: description\n\nFixes #N"`
+      3. Push the branch: `git push -u origin <branch-name>`
+      4. **Verify push succeeded** — run `git ls-remote origin <branch-name>` and confirm it prints a commit hash.
+         - If no output or push failed: capture the error, mark hook_failed
+      5. Create a PR using the Gitea API (do NOT use `tea pr create` — it fails in worktrees):
+         ```bash
+         GITEA_TOKEN=$(cfg get GITEA_TOKEN)
+         curl -s -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
+           "https://git.shazhou.work/api/v1/repos/<owner>/<repo>/pulls" \
+           -d '{"title":"...","body":"...","head":"<branch>","base":"main"}'
+         ```
+         - The repo remote (owner/repo format, e.g. "shazhou/united-workforce") is given in your task prompt — use it directly.
+         - PR body must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+      6. **Verify PR was created** — parse the curl response JSON: it must contain a `"number"` field. Print the PR URL.
+         - If curl returns an error or no number field: capture the response, mark hook_failed
+      7. After PR creation, clean up the worktree:
+         - cd to the repo root (parent of .worktrees)
+         - `git worktree remove <worktree-path>`
+    output: "Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "committed" }
+            prUrl: { type: string }
+            repoRemote: { type: string }
+            worktree: { type: string }
+            branch: { type: string }
+          required: [$status, prUrl]
+        - properties:
+            $status: { const: "hook_failed" }
+            error: { type: string }
+            repoRemote: { type: string }
+            worktree: { type: string }
+            branch: { type: string }
+          required: [$status, error]
+graph:
+  $START:
+    new: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+    resume: { role: "planner", prompt: "Review the previous run output and continue the work." }
+  planner:
+    insufficient_info: { role: "$SUSPEND", prompt: "信息不足，需要补充：{{{reason}}}" }
+    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}." }
+  developer:
+    done: { role: "reviewer", prompt: "Review branch {{{branch}}} at {{{worktree}}} for code standards compliance. Repo remote: {{{repoRemote}}}." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
+  reviewer:
+    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
+    approved: { role: "tester", prompt: "Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
+  tester:
+    fix_code: { role: "developer", prompt: "Tests found code issues: {{{report}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
+    fix_spec: { role: "planner", prompt: "Tests found spec issues: {{{report}}}. Revise the test spec. Repo remote: {{{repoRemote}}}." }
+    passed: { role: "committer", prompt: "All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}. Repo remote (owner/repo): {{{repoRemote}}}." }
+  committer:
+    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
+    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow complete." }
@@ -23,7 +23,7 @@ roles:
      type: object
      properties:
        $status:
-          const: done
+          enum: ["done"]
        thesis:
          type: string
        keyPoints:
@@ -1,131 +1,63 @@
-name: debate
-description: "Multi-role structured debate with critical thinking framework and host summary."
-
-# Shared frontmatter schema for debater roles (YAML anchor)
-x-debater-frontmatter: &debater-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]
-
+name: "debate"
+description: "Structured debate between two sides. Tests cross-process session resume."
 roles:
-  proponent:
-    description: "Argues FOR the proposition"
-    goal: "Build a compelling case for the proposition through logical reasoning and evidence"
-    capabilities: []
+  against:
+    description: "Argues against the proposition"
+    goal: |
+      You are a skilled debater arguing AGAINST 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: |
-      You are an experienced scholar arguing FOR the proposition.
-
-      ## Critical Thinking Framework (execute before every speech)
-
-      ### A. Pre-speech reflection (internal, do not output)
-      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
-      - 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?
-      - Should I go on offense or defense this round?
-
-      ### 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: *debater-frontmatter
-
-  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 (execute before every speech)
-
-      ### A. Pre-speech reflection (internal, do not output)
-      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
-      - 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?
-      - Should I go on offense or defense this round?
-
-      ### 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: *debater-frontmatter
-
-  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"
+      1. If this is the opening, present your strongest argument against 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.
+    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: { const: done }
-        summary: { type: string }
-        highlights: { type: string }
-        verdict: { type: string }
-      required: [$status, summary, highlights, verdict]
-
+        $status:
+          enum: ["continue", "conceded"]
+        argument:
+          type: string
+      required: [$status, argument]
+  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: proponent, prompt: "The debate begins. You are arguing FOR the proposition. Present your opening argument." }
-    resume: { role: proponent, prompt: "The debate continues." }
-
-  proponent:
-    speak: { role: opponent, prompt: "Proponent argues:\n\n{{{argument}}}\n\nYou are the opponent. Counter this argument." }
-    conceded: { role: host, prompt: "The proponent conceded: {{{reason}}}\n\nPlease summarize the debate." }
-    final: { role: opponent, prompt: "Proponent's closing statement:\n\n{{{closing}}}\n\nYou are the opponent. Deliver your final response." }
-
-  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." }
+    new: { role: "against", prompt: "Present your opening argument against the proposition." }
+    resume: { role: "against", prompt: "Review the previous debate output and continue the argument against the proposition." }
+  against:
+    conceded: { role: "$END", prompt: "The against side conceded. Debate over." }
+    continue: { role: "for", prompt: "Counter the opposing argument: {{{argument}}}" }
+  for:
+    conceded: { role: "$END", prompt: "The for side conceded. Debate over." }
+    continue: { role: "against", prompt: "Counter the opposing argument: {{{argument}}}" }
@@ -18,7 +18,8 @@ roles:
      type: object
      properties:
        $status:
-          const: done
+          type: string
+          enum: [done]
        summary:
          type: string
      required: [$status, summary]
@@ -1,5 +1,5 @@
 name: "solve-issue"
-description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds. Uses pnpm."
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
 roles:
  planner:
    description: "Analyzes issue and outputs a TDD test spec"
@@ -80,7 +80,7 @@ roles:
      2. `git fetch origin` to get latest refs
      3. First time (no existing branch):
         - `git worktree add .worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
-         - `cd .worktrees/fix/<issue-number>-<short-slug> && pnpm install`
+         - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`
      4. If continuing on existing branch (prompt says "Continue work on existing branch" or provides a worktree path):
         - cd directly into the worktree path provided in the prompt
         - `git fetch origin && git rebase origin/main`
@@ -95,20 +95,8 @@ roles:
      7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt
      8. Write tests first based on the spec
      9. Implement the code to make tests pass
-      10. Ensure `pnpm run build` passes with no errors
-      11. Run `pnpm test` to verify all tests pass
-
-      After implementation, before reporting done:
-      12. Add a changeset file (`.changeset/<short-slug>.md`) with correct bump type:
-          - `patch` for bug fixes, internal refactors, test-only changes
-          - `minor` for new features, new CLI commands, new API surfaces
-          - `major` for breaking changes
-          List every affected package in the changeset frontmatter.
-      13. Update documentation if the change affects user-facing behavior:
-          - `README.md` — usage examples, feature descriptions
-          - `.cards/` — architecture decision records (if applicable)
-          - CLI prompt subcommand output (if CLI help text changes)
-          - CLI `--help` text (if flags/commands are added or changed)
+      10. Ensure `bun run build` passes with no errors
+      11. Run `bun test` to verify all tests pass

      If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,
      or repeated attempts fail), set $status=failed with a reason.
@@ -139,8 +127,8 @@ roles:

      Then perform code review:
      Hard checks (must all pass):
-      3. `pnpm run build` — no build errors
-      4. `pnpm run check` — no lint violations
+      3. `bun run build` — no build errors
+      4. `bunx biome check` — no lint violations
      5. TypeScript strict mode — no type errors

      Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist):
@@ -148,14 +136,6 @@ roles:
      - No `console.log` in production code
      - No dynamic imports in production code

-      Documentation & changeset checks:
-      6. Changeset exists in `.changeset/` with correct bump type (`patch`/`minor`/`major`) and lists all affected packages
-      7. If the change is user-facing, documentation is updated:
-         - `README.md` reflects new/changed behavior
-         - `.cards/` architecture cards updated if design decisions changed
-         - CLI prompt subcommand output updated (if it generates skill/reference content)
-         - CLI `--help` text matches new flags/commands
-
      Only review standards compliance. Do NOT test functionality.
      If rejecting, you MUST explain the specific reason in your output.
    output: "Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments)."
@@ -179,7 +159,7 @@ roles:
    procedure: |
      The worktree path is provided in your task prompt. cd into it first.

-      1. Run `pnpm test` for automated test verification
+      1. Run `bun test` for automated test verification
      2. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner step in the thread history)
      3. Verify each scenario in the spec is covered and passing
      4. Determine outcome:
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-builtin",
-  "version": "0.1.2",
+  "version": "0.1.1",
  "files": [
    "src",
    "dist",
@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+#!/usr/bin/env node

 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-claude-code",
-  "version": "0.1.3",
+  "version": "0.1.1",
  "files": [
    "src",
    "dist",
@@ -7,7 +7,6 @@ import {
  type AgentRunResult,
  buildContinuationPrompt,
  buildRolePrompt,
-  buildThreadProgress,
  createAgent,
  getCachedSessionId,
  setCachedSessionId,
@@ -28,10 +27,6 @@ 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) {
@@ -176,12 +171,8 @@ async function runClaudeCode(ctx: AgentContext, model: string | null): Promise<A

  log("K7R2M4N8", `prompt for role=${ctx.role} (length=${fullPrompt.length}):\n${fullPrompt}`);

-  // Try resuming a cached session.  This covers both normal re-entry
-  // (e.g. reviewer reject → developer re-entry) AND the case where a
-  // previous run completed but frontmatter validation failed — the step
-  // was never written to CAS so isFirstVisit is still true, but the
-  // session cache holds a valid session we should resume.
-  {
+  // Try resuming a cached session for re-entry scenarios (e.g. reviewer reject → developer re-entry).
+  if (!ctx.isFirstVisit) {
    const cachedSessionId = await getCachedSessionId(
      "claude-code",
      ctx.threadId,
@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+#!/usr/bin/env node

 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
@@ -15,8 +15,7 @@ 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")).toBe(true);
-    expect(content).toContain("node");
+    expect(content.startsWith("#!/usr/bin/env node")).toBe(true);
  });

  test("README.md explains uwf-hermes is an adapter", () => {
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-hermes",
-  "version": "0.1.4",
+  "version": "0.1.2",
  "files": [
    "src",
    "dist",
@@ -12,11 +12,7 @@ const OWN_VERSION = (
  }
 ).version;

-/** Resolve hermes binary: `UWF_HERMES_BIN` override → default `"hermes"` via PATH. */
-function resolveHermesCommand(): string {
-  const override = process.env.UWF_HERMES_BIN;
-  return override !== undefined && override !== "" ? override : "hermes";
-}
+const HERMES_COMMAND = "hermes";
 const PROTOCOL_VERSION = 1;

 type JsonRpcResponse = {
@@ -275,8 +271,7 @@ export class HermesAcpClient {
      return;
    }

-    const hermesCommand = resolveHermesCommand();
-    const child = spawn(hermesCommand, ["acp"], {
+    const child = spawn(HERMES_COMMAND, ["acp"], {
      env: process.env,
      shell: false,
      stdio: ["pipe", "pipe", "pipe"],
@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+#!/usr/bin/env node

 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
@@ -6,7 +6,6 @@ import {
  type AgentRunResult,
  buildContinuationPrompt,
  buildRolePrompt,
-  buildThreadProgress,
  createAgent,
 } from "@united-workforce/util-agent";
 import type { AcpUsage } from "./acp-client.js";
@@ -61,9 +60,6 @@ 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));
@@ -110,15 +106,11 @@ async function prepareSession(
  cwd: string,
  resumeDisabled: boolean,
 ): Promise<PromptAttempt> {
-  if (resumeDisabled) {
+  if (ctx.isFirstVisit || resumeDisabled) {
    await client.connect(cwd);
    return { useContinuation: false, resumed: false };
  }

-  // Check session cache regardless of isFirstVisit.  A previous run may
-  // have completed and cached its session but failed frontmatter
-  // validation — the step never got written to CAS so isFirstVisit is
-  // still true, yet we should resume the existing session.
  const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role, ctx.storageRoot);
  if (cachedSessionId === null) {
    log("6RWK3N8Q", `no cached session for ${ctx.threadId}:${ctx.role}, starting new session`);
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/agent-mock",
-  "version": "0.1.2",
+  "version": "0.1.1",
  "files": [
    "src",
    "dist",
@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+#!/usr/bin/env node

 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/cli",
-  "version": "0.3.0",
+  "version": "0.1.1",
  "files": [
    "src",
    "dist",
@@ -28,13 +28,9 @@ 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
@@ -46,7 +42,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "done" }
+        $status: { type: string, enum: ["done"] }
 graph:
  $START:
    new:
@@ -86,13 +82,9 @@ 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
@@ -104,7 +96,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "done" }
+        $status: { type: string, enum: ["done"] }
  roleC:
    description: Fail role
    goal: Do C
@@ -116,7 +108,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "done" }
+        $status: { type: string, enum: ["done"] }
 graph:
  $START:
    new:
@@ -163,7 +155,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "done" }
+        $status: { type: string, enum: ["done"] }
 graph:
  $START:
    new:
@@ -71,22 +71,12 @@ 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/");
@@ -21,11 +21,11 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
    "..",
    "..",
    "..",
-    "examples",
+    ".workflows",
    "solve-issue.yaml",
  );

-  test("committer procedure should create PR via tea pr create", async () => {
+  test("committer procedure should use curl API instead of tea pr create", async () => {
    const yamlContent = await readFile(workflowPath, "utf-8");
    const workflow = parse(yamlContent) as WorkflowPayload;

@@ -33,22 +33,25 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
    const committerProcedure = workflow.roles.committer?.procedure;
    expect(committerProcedure).toBeDefined();

-    // Verify the procedure uses tea pr create for PR creation
-    expect(committerProcedure).toContain("tea pr create");
-    expect(committerProcedure).toContain("git push");
-    expect(committerProcedure).toContain("Fixes #N");
+    // Verify the procedure uses curl API, not tea pr create
+    expect(committerProcedure).toContain("curl");
+    expect(committerProcedure).toContain("api/v1/repos");
+    expect(committerProcedure).toContain("/pulls");
+
+    // Verify it explicitly warns against tea pr create
+    expect(committerProcedure).toMatch(/do NOT use.*tea pr create/i);
  });

-  test("committer procedure should extract owner/repo from git remote", async () => {
+  test("committer procedure should reference repoRemote from task prompt", async () => {
    const yamlContent = await readFile(workflowPath, "utf-8");
    const workflow = parse(yamlContent) as WorkflowPayload;

    const committerProcedure = workflow.roles.committer?.procedure;
    expect(committerProcedure).toBeDefined();

-    // Verify the procedure extracts owner/repo from remote
-    expect(committerProcedure).toContain("git remote get-url origin");
-    expect(committerProcedure).toContain("hook_failed");
+    // Verify the procedure mentions repoRemote is provided in task prompt
+    expect(committerProcedure).toMatch(/repo remote.*provided.*task prompt/i);
+    expect(committerProcedure).toMatch(/owner\/repo/i);
  });

  test("committer procedure should include error handling for curl failures", async () => {
@@ -97,42 +100,45 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
    expect(committedVariant.required).toContain("$status");
  });

-  test("developer procedure should include worktree setup", async () => {
+  test("developer procedure should include mandatory verification step", async () => {
    const yamlContent = await readFile(workflowPath, "utf-8");
    const workflow = parse(yamlContent) as WorkflowPayload;

    const developerProcedure = workflow.roles.developer?.procedure;
    expect(developerProcedure).toBeDefined();

-    // Verify the procedure includes worktree setup
-    expect(developerProcedure).toContain("IMPORTANT");
-    expect(developerProcedure).toContain("git worktree add");
-    expect(developerProcedure).toContain("pnpm install");
+    // Verify the procedure includes mandatory verification step
+    expect(developerProcedure).toContain("MANDATORY VERIFICATION");
+    expect(developerProcedure).toContain("git branch --show-current");
+    expect(developerProcedure).toContain("git status");
+    expect(developerProcedure).toMatch(/ls -la|verify.*exist/i);
  });

-  test("reviewer procedure should verify branch and run checks", async () => {
+  test("reviewer procedure should enforce worktree path verification", async () => {
    const yamlContent = await readFile(workflowPath, "utf-8");
    const workflow = parse(yamlContent) as WorkflowPayload;

    const reviewerProcedure = workflow.roles.reviewer?.procedure;
    expect(reviewerProcedure).toBeDefined();

-    // Verify the procedure includes branch verification and build checks
-    expect(reviewerProcedure).toContain("git branch --show-current");
-    expect(reviewerProcedure).toContain("pnpm run build");
-    expect(reviewerProcedure).toContain("pnpm run check");
+    // Verify the procedure includes critical enforcement
+    expect(reviewerProcedure).toContain("CRITICAL");
+    expect(reviewerProcedure).toMatch(/cd.*pwd/);
+    expect(reviewerProcedure).toContain(
+      "Do NOT report results without running the actual commands",
+    );
  });

-  test("developer procedure should include changeset and failure handling", async () => {
+  test("developer procedure should include test debugging escalation", async () => {
    const yamlContent = await readFile(workflowPath, "utf-8");
    const workflow = parse(yamlContent) as WorkflowPayload;

    const developerProcedure = workflow.roles.developer?.procedure;
    expect(developerProcedure).toBeDefined();

-    // Verify the procedure includes changeset requirement and failure path
-    expect(developerProcedure).toContain(".changeset/");
+    // Verify the procedure includes test failure guidance
+    expect(developerProcedure).toMatch(/tests fail.*first run/i);
+    expect(developerProcedure).toMatch(/3 test cycles|after 3 attempts/i);
    expect(developerProcedure).toContain("$status=failed");
-    expect(developerProcedure).toContain("pnpm test");
  });
 });
@@ -54,7 +54,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "ready" }
+        $status: { type: string, enum: ["ready"] }
 graph:
  $START:
    new:
@@ -114,7 +114,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "ready" }
+        $status: { type: string, enum: ["ready"] }
 graph:
  $START:
    new:
@@ -161,7 +161,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "ready" }
+        $status: { type: string, enum: ["ready"] }
 graph:
  $START:
    new:
@@ -31,7 +31,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "ready" }
+        $status: { type: string, enum: ["ready"] }
 graph:
  $START:
    new:
@@ -54,7 +54,7 @@ roles:
      type: object
      required: ["$status"]
      properties:
-        $status: { const: "ready" }
+        $status: { type: string, enum: ["ready"] }
 graph:
  $START:
    new:
@@ -17,7 +17,7 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
        frontmatter: {
          type: "object",
          properties: {
-            $status: { const: "done" },
+            $status: { enum: ["done"] },
            plan: { type: "string" },
          },
          required: ["$status", "plan"],
@@ -85,7 +85,7 @@ describe("Suite 1: Role Reference Integrity", () => {
      output: "None",
      frontmatter: {
        type: "object",
-        properties: { $status: { const: "done" } },
+        properties: { $status: { enum: ["done"] } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -187,7 +187,7 @@ describe("Suite 2: Graph Structure", () => {
      output: "Isolated",
      frontmatter: {
        type: "object",
-        properties: { $status: { const: "done" } },
+        properties: { $status: { enum: ["done"] } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -272,8 +272,8 @@ describe("Suite 3: Status-Edge Consistency", () => {
  });
 });

-describe("Suite 3b: Enum-Based $status is Rejected", () => {
-  test("3b.1 enum multi-exit is rejected (must use oneOf + const)", () => {
+describe("Suite 3b: Enum-Based Multi-Exit", () => {
+  test("3b.1 enum multi-exit passes with matching graph keys", () => {
    const wf = makeWorkflow();
    wf.roles.reviewer = {
      ...wf.roles.reviewer,
@@ -291,10 +291,52 @@ describe("Suite 3b: Enum-Based $status is Rejected", () => {
      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
    };
    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
+    expect(errors).toEqual([]);
  });

-  test("3b.2 enum single-exit is rejected (must use const)", () => {
+  test("3b.2 enum multi-exit with extra 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 },
+      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,
@@ -309,71 +351,28 @@ describe("Suite 3b: Enum-Based $status is Rejected", () => {
    };
    wf.graph.writer = { ready: { role: "reviewer", prompt: "Review: {{{plan}}}", location: null } };
    const errors = validateWorkflow(wf);
-    expect(errors.some((e) => e.includes("must define") && e.includes("const"))).toBe(true);
-  });
-});
-
-describe("Suite 3c: Const-Based Flat Schema", () => {
-  test("3c.1 flat schema with const $status passes validation", () => {
-    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,
-    };
-    const errors = validateWorkflow(wf);
    expect(errors).toEqual([]);
  });

-  test("3c.2 flat schema with const $status detects extra graph key", () => {
+  test("3b.5 enum multi-exit mustache var not in frontmatter", () => {
    const wf = makeWorkflow();
-    wf.roles.writer = {
-      ...wf.roles.writer,
+    wf.roles.reviewer = {
+      ...wf.roles.reviewer,
      frontmatter: {
        type: "object",
        properties: {
-          $status: { const: "done" },
-          plan: { type: "string" },
+          $status: { enum: ["approved", "rejected"] },
+          comments: { type: "string" },
        },
-        required: ["$status", "plan"],
+        required: ["$status", "comments"],
      } as unknown as string,
    };
-    wf.graph.writer = {
-      done: { role: "reviewer", prompt: "Review.", location: null },
-      extra: { role: "$END", prompt: "Nope.", location: null },
+    wf.graph.reviewer = {
+      approved: { role: "$END", prompt: "Done: {{{nonexistent}}}", location: null },
+      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
    };
    const errors = validateWorkflow(wf);
-    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);
+    expect(errors.some((e) => e.includes("nonexistent") && e.includes("not found"))).toBe(true);
  });
 });

@@ -481,7 +480,7 @@ describe("Suite 6: Multiple Errors Collection", () => {
      output: "None",
      frontmatter: {
        type: "object",
-        properties: { $status: { const: "done" } },
+        properties: { $status: { enum: ["done"] } },
        required: ["$status"],
      } as unknown as string,
    };
@@ -31,7 +31,7 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
        frontmatter: {
          type: "object",
          properties: {
-            $status: { const: "done" },
+            $status: { type: "string", enum: ["done"] },
          },
          required: ["$status"],
        } as unknown as CasRef,
@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
+#!/usr/bin/env node

 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, resolvePresetBaseUrl } from "./commands/setup.js";
+import { cmdSetup, cmdSetupInteractive } 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. Run without options for interactive wizard.")
+  .description("Configure provider, model, and agent")
  .option("--provider <name>", "Provider name")
  .option("--base-url <url>", "OpenAI-compatible API base URL")
  .option("--api-key <key>", "API key")
@@ -558,14 +558,10 @@ program
    }) => {
      const storageRoot = resolveStorageRoot();
      runAction(async () => {
-        // 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) {
+        if (opts.provider && opts.baseUrl && opts.apiKey && opts.model) {
          const result = await cmdSetup({
            provider: opts.provider,
-            baseUrl: resolvedBaseUrl,
+            baseUrl: opts.baseUrl,
            apiKey: opts.apiKey,
            model: opts.model,
            agent: opts.agent ?? undefined,
@@ -576,7 +572,7 @@ program
          await cmdSetupInteractive(storageRoot);
        } else {
          throw new Error(
-            "Non-interactive setup requires: --provider, --api-key, --model (--base-url is optional for preset providers)",
+            "Non-interactive setup requires all of: --provider, --base-url, --api-key, --model",
          );
        }
      });
@@ -1,35 +1,10 @@
-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,
@@ -47,275 +22,33 @@ export function cmdPromptList(): ReadonlyArray<string> {
 }

 export function cmdPromptBootstrap(): string {
-  return `# uwf Bootstrap
+  return `# uwf Skill Bootstrap

-Set up or upgrade uwf (United Workforce) — from zero to running your first workflow.
+Install or update the uwf (United Workforce) skills for your agent.

-## 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.
+## Steps

+1. **Check if uwf CLI is installed:**
   \`\`\`bash
-# 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"
+   uwf --help
   \`\`\`
+   If not installed: \`npm install -g @united-workforce/cli\`
+   Current version: ${VERSION}

-**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.
+2. **Install the skills** by running each command below and creating a skill from its output:
+   - 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\`

-### Step 1 — Discover agents and install adapter
+   Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them.

-**First, detect which supported agents are already installed on the user's machine:**
+3. **Verify** the skills are loadable by your agent framework.

-\`\`\`bash
-# Check for Hermes Agent
-which hermes 2>/dev/null && hermes --version
+## Updating

-# 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
-
-# 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>
-\`\`\`
+When \`uwf\` is upgraded, re-run \`uwf prompt bootstrap\` and follow the steps again.
+The skill content is bundled with the CLI — always use \`uwf prompt <name>\` to get
+content matching your installed version.

 ## Available prompts

@@ -324,7 +57,6 @@ 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
 \`\`\`
 `;
 }
@@ -1,4 +1,3 @@
-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";
@@ -73,12 +72,6 @@ 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;
@@ -182,6 +175,7 @@ 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"],
@@ -397,37 +391,6 @@ 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.
 */
@@ -442,26 +405,15 @@ 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,
  };
 }

@@ -1004,12 +1004,6 @@ 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
        ? ""
@@ -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 const (flat schema form). */
-function hasStatusConst(fm: unknown): boolean {
+/** Check if a frontmatter schema declares "$status" as an enum (the required form for user roles). */
+function hasStatusEnum(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 typeof props.$status.const === "string";
+  return Array.isArray(props.$status.enum);
 }

-/** Extract status values from a const-based $status field. */
-function getConstStatuses(fm: SchemaObj): string[] {
+/** Extract status values from an enum-based $status field. */
+function getEnumStatuses(fm: SchemaObj): string[] {
  const props = fm.properties as Record<string, SchemaObj> | undefined;
  if (!props?.$status) return [];
  const statusDef = props.$status;
-  if (typeof statusDef.const === "string") return [statusDef.const];
-  return [];
+  if (!Array.isArray(statusDef.enum)) return [];
+  return statusDef.enum as string[];
 }

 /** 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 (hasStatusConst(fm)) {
-      const statuses = getConstStatuses(fm as SchemaObj);
+    } else if (hasStatusEnum(fm)) {
+      const statuses = getEnumStatuses(fm as SchemaObj);
      checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
-      // For const-based flat schemas, mustache vars come from the flat properties
-      checkFlatMustache(roleName, graphEntry, fm as SchemaObj, errors);
+      // For enum-based schemas, mustache vars come from the flat properties
+      checkEnumMustache(roleName, graphEntry, fm as SchemaObj, errors);
    } else {
      errors.push(
-        `role "${roleName}" must define "$status" as const (or oneOf with const) in frontmatter`,
+        `role "${roleName}" must define "$status" as an enum (or oneOf const) in frontmatter`,
      );
    }
  }
 }

 /** Check mustache vars in all edge prompts against flat schema properties. */
-function checkFlatMustache(
+function checkEnumMustache(
  roleName: string,
  graphEntry: Record<string, { role: string; prompt: string }>,
  fm: SchemaObj,
@@ -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}". Either rename the file to "${payload.name}.yaml" or change the YAML \`name\` field to "${expected}"`;
+    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
  }
  return null;
 }
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/eval",
-  "version": "0.1.5",
+  "version": "0.1.3",
  "private": false,
  "files": [
    "src",
@@ -6,7 +6,7 @@ import { formatList, selectEntries } from "./format.js";
 import { readEvalEntries } from "./read.js";

 const log = createLogger({ sink: { kind: "stderr" } });
-const LOG_LIST = "H5KX9R2B";
+const LOG_LIST = "L5KX9R2B";

 type ListCliOptions = {
  task: string | undefined;
@@ -143,7 +143,7 @@ describe("buildOutputFormatInstruction", () => {
        {
          type: "object",
          properties: {
-            $status: { const: "approved" },
+            $status: { type: "string", enum: ["approved"] },
            branch: { type: "string" },
          },
          required: ["$status"],
@@ -151,7 +151,7 @@ describe("buildOutputFormatInstruction", () => {
        {
          type: "object",
          properties: {
-            $status: { const: "rejected" },
+            $status: { type: "string", enum: ["rejected"] },
            comments: { type: "string" },
          },
          required: ["$status"],
@@ -225,34 +225,4 @@ describe("buildOutputFormatInstruction", () => {
    const result = buildOutputFormatInstruction({});
    expect(result).toContain("Focus exclusively on YOUR role");
  });
-
-  test("renders const value as literal in flat schema example", () => {
-    const schema = {
-      type: "object",
-      properties: {
-        $status: { type: "string", const: "greeted" },
-        message: { type: "string" },
-      },
-      required: ["$status", "message"],
-    };
-    const result = buildOutputFormatInstruction(schema);
-    expect(result).toContain("$status: greeted");
-    expect(result).toContain("fixed value");
-    expect(result).not.toContain("$status: <string>");
-  });
-
-  test("renders const value for non-string types", () => {
-    const schema = {
-      type: "object",
-      properties: {
-        count: { type: "number", const: 42 },
-        done: { type: "boolean", const: true },
-      },
-      required: ["count", "done"],
-    };
-    const result = buildOutputFormatInstruction(schema);
-    expect(result).toContain("count: 42");
-    expect(result).toContain("done: true");
-    expect(result).toContain("fixed value");
-  });
 });
@@ -1,59 +0,0 @@
-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");
-  });
-});
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/util-agent",
-  "version": "0.1.1",
+  "version": "0.1.0",
  "files": [
    "src",
    "dist",
@@ -74,10 +74,6 @@ function collectObjectSchemas(schema: JSONSchema): JSONSchema[] {
 }

 function resolvePropertySchema(prop: JSONSchema): JSONSchema {
-  if (prop.const !== undefined) {
-    return prop;
-  }
-
  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
    return prop;
  }
@@ -117,11 +113,6 @@ function buildPropertyExampleLine(prop: SchemaProperty): string {
    commentParts.push("required");
  }

-  if (resolved.const !== undefined) {
-    commentParts.push("fixed value");
-    return `${prop.name}: ${formatYamlScalar(resolved.const)}${buildPropertyComment(commentParts)}`;
-  }
-
  if (Array.isArray(resolved.enum) && resolved.enum.length > 0) {
    const enumValues = resolved.enum.map((v) => String(v));
    commentParts.push(...enumValues);
@@ -1,27 +0,0 @@
-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");
-}
@@ -1,7 +1,6 @@
 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";
@@ -1,6 +1,6 @@
 {
  "name": "@united-workforce/util",
-  "version": "0.1.4",
+  "version": "0.1.1",
  "files": [
    "src",
    "dist",
@@ -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,3 +35,4 @@ 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";
@@ -0,0 +1,57 @@
+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
+`;
+}
@@ -140,18 +140,5 @@ 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
-\`\`\`
 `;
 }
@@ -28,7 +28,6 @@ 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" }
@@ -72,13 +71,10 @@ 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.
-
-**Multi-exit (oneOf)** — use \`const\` to constrain each variant:
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:

 \`\`\`yaml
 frontmatter:
-  type: object
  oneOf:
    - properties:
        $status: { const: "done" }
@@ -90,26 +86,22 @@ frontmatter:
      required: [$status, error]
 \`\`\`

-**Single-exit (flat schema)** — same syntax, just no \`oneOf\` wrapper:
+### Custom Fields
+
+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:
@@ -0,0 +1,83 @@
+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}}}."\`
+`;
+}
@@ -0,0 +1,329 @@
+name: solve-issue
+description: TDD-driven issue resolution adapted for the workflow monorepo with bun + vitest
+roles:
+  planner:
+    description: Analyzes issue and outputs a TDD test spec
+    goal: You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify.
+    capabilities:
+    - issue-analysis
+    - planning
+    procedure: 'On first run (no previous steps):
+
+      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
+
+      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md) in the repo
+
+      3. Assess whether the issue has enough information to produce a test spec
+
+      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info
+
+      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
+
+
+      On subsequent runs (bounced back by tester with fix_spec):
+
+      1. Read the tester''s output from the previous step to understand what''s wrong with the spec
+
+      2. Revise the test spec accordingly
+
+
+      After producing the test spec:
+
+      1. The test spec is stored in CAS automatically by the uwf pipeline (agents do not need to call `ocas put` directly)
+
+      2. Put the hash in frontmatter.plan (required when $status=ready)
+
+      3. Set repoPath to the absolute path of the repository root
+
+
+
+      IMPORTANT: Extract the repo remote (owner/repo) from git:
+
+      ```bash
+
+      git remote get-url origin | sed ''s|.*[:/]\([^/]*/[^.]*\).*|\1|''
+
+      ```
+
+      Store the result as repoRemote in your frontmatter output so downstream roles can use it for tea/API calls.'
+    output: Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info.
+    frontmatter:
+      oneOf:
+      - properties:
+          $status:
+            const: ready
+          plan:
+            type: string
+          repoPath:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - plan
+        - repoPath
+      - properties:
+          $status:
+            const: insufficient_info
+          reason:
+            type: string
+        required:
+        - $status
+        - reason
+  developer:
+    description: TDD implementation per test spec
+    goal: You are a developer agent. You implement code changes following TDD — write tests first, then implementation.
+    capabilities:
+    - coding
+    procedure: "IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.\nThe repo path and other details are provided in your task prompt.\n\nBefore starting any work,\
+      \ set up an isolated worktree:\n1. cd into the repo path provided in your task prompt\n2. `git fetch origin` to get latest refs\n3. First time (no existing branch):\n   - `git worktree add .worktrees/fix/<issue-number>-<short-slug>\
+      \ -b fix/<issue-number>-<short-slug> origin/main`\n   - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`\n4. If bounced back from reviewer or tester (branch already exists):\n   - cd\
+      \ into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`\n   - `git fetch origin && git rebase origin/main`\n5. ALL subsequent work must happen inside the worktree directory.\n\
+      \nThen implement TDD:\n6. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner's output in your task prompt)\n7. If bounced back from reviewer or tester: read the\
+      \ previous role's feedback in your task prompt\n8. Write tests first based on the spec (use vitest)\n9. Implement the code to make tests pass\n10. Ensure `bun run build` passes with no errors\n11.\
+      \ Run `bun test` to verify all tests pass\n\nIf you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,\nor repeated attempts fail), set $status=failed\
+      \ with a reason.\n"
+    output: List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason).
+    frontmatter:
+      oneOf:
+      - properties:
+          $status:
+            const: done
+          branch:
+            type: string
+          worktree:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - branch
+        - worktree
+      - properties:
+          $status:
+            const: failed
+          reason:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - reason
+  reviewer:
+    description: Code standards compliance check
+    goal: You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job).
+    capabilities:
+    - code-review
+    - static-analysis
+    procedure: 'The worktree path is provided in your task prompt. cd into it first.
+
+
+      Before reviewing, verify the git branch:
+
+      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
+
+      2. If the branch doesn''t correspond to the issue, flag it in your output and reject
+
+
+      Then perform code review:
+
+      Hard checks (must all pass):
+
+      3. `bun run build` — no build errors
+
+      4. `bunx biome check` — no lint violations
+
+      5. TypeScript strict mode — no type errors
+
+
+      Soft checks (review against project conventions from CLAUDE.md):
+
+      - Functional-first: functions + types, no classes (except for errors or third-party requirements)
+
+      - Named exports only, no default exports
+
+      - No optional properties (use `T | null` instead of `?:`)
+
+      - Folder module discipline: index.ts only re-exports, types in types.ts
+
+      - Crockford Base32 log tags (8-char, unique per call site)
+
+      - No `console.log` in production code (use createLogger from @united-workforce/util)
+
+      - No dynamic imports in production code
+
+
+      Only review standards compliance. Do NOT test functionality.
+
+      If rejecting, you MUST explain the specific reason in your output.
+
+      '
+    output: Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments).
+    frontmatter:
+      oneOf:
+      - properties:
+          $status:
+            const: approved
+          branch:
+            type: string
+          worktree:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - branch
+        - worktree
+      - properties:
+          $status:
+            const: rejected
+          comments:
+            type: string
+          worktree:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - comments
+        - worktree
+  tester:
+    description: Functional correctness verification
+    goal: You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec.
+    capabilities:
+    - testing
+    procedure: "The worktree path is provided in your task prompt. cd into it first.\n\n1. Run `bun test` for automated test verification\n2. Read the test spec from CAS: `ocas get <plan hash>` (find\
+      \ the hash from the planner step in the thread history)\n3. Verify each scenario in the spec is covered and passing\n4. Determine outcome:\n   - passed: all scenarios verified, tests pass\n   - fix_code:\
+      \ tests fail or implementation doesn't match spec → send back to developer\n   - fix_spec: the spec itself is wrong or incomplete → send back to planner\n"
+    output: Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report).
+    frontmatter:
+      oneOf:
+      - properties:
+          $status:
+            const: passed
+          branch:
+            type: string
+          worktree:
+            type: string
+          repoRemote:
+            type: string
+        required:
+        - $status
+        - branch
+        - worktree
+      - properties:
+          $status:
+            const: fix_code
+          report:
+            type: string
+          repoRemote:
+            type: string
+          worktree:
+            type: string
+          branch:
+            type: string
+        required:
+        - $status
+        - report
+      - properties:
+          $status:
+            const: fix_spec
+          report:
+            type: string
+          repoRemote:
+            type: string
+          worktree:
+            type: string
+          branch:
+            type: string
+        required:
+        - $status
+        - report
+  committer:
+    description: Commits and creates PR
+    goal: You are a committer agent. You create a clean commit and push a PR linking the original issue.
+    capabilities: []
+    procedure: "The worktree path, branch name, and repo remote (owner/repo) are provided in your task prompt.\ncd into the worktree first.\n\nNote: You inherit the developer's worktree and branch. Do NOT\
+      \ create a new branch.\n1. Stage all changes: `git add -A`\n2. Commit with a descriptive message referencing the issue: `git commit -m \"type: description\\n\\nFixes #N\"`\n3. Push the branch: `git\
+      \ push -u origin <branch-name>`\n4. **Verify push succeeded** — run `git ls-remote origin <branch-name>` and confirm it prints a commit hash.\n   - If no output or push failed: capture the error, mark hook_failed\n\
+      5. Create a PR using the Gitea API (do NOT use `tea pr create` — it fails in worktrees):\n   ```bash\n   GITEA_TOKEN=$(cfg get GITEA_TOKEN)\n   curl -s -X POST -H \"Authorization: token $GITEA_TOKEN\" -H \"Content-Type: application/json\" \\\n\
+      \     \"https://git.shazhou.work/api/v1/repos/<owner>/<repo>/pulls\" \\\n     -d '{\"title\":\"...\",\"body\":\"...\",\"head\":\"<branch>\",\"base\":\"main\"}'\n   ```\n   - The repo remote (owner/repo format, e.g. \"shazhou/united-workforce\") is given in your task prompt — use it directly.\n\
+      \   - PR body must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref\n6. **Verify PR was created** — parse the curl response JSON: it must contain a `\"number\"` field. Print the PR URL.\n\
+      \   - If curl returns an error or no number field: capture the response, mark hook_failed\n7. After PR creation, clean up the worktree:\n   - cd to the repo root (parent of .worktrees)\n   - `git worktree remove <worktree-path>`"
+    output: Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error).
+    frontmatter:
+      oneOf:
+      - properties:
+          $status:
+            const: committed
+          prUrl:
+            type: string
+          repoRemote:
+            type: string
+          worktree:
+            type: string
+          branch:
+            type: string
+        required:
+        - $status
+        - prUrl
+      - properties:
+          $status:
+            const: hook_failed
+          error:
+            type: string
+          repoRemote:
+            type: string
+          worktree:
+            type: string
+          branch:
+            type: string
+        required:
+        - $status
+        - error
+graph:
+  $START:
+    new:
+      role: planner
+      prompt: Analyze the issue and produce an implementation plan.
+    resume:
+      role: planner
+      prompt: Review the previous run output and continue the work.
+  planner:
+    insufficient_info:
+      role: $SUSPEND
+      prompt: "信息不足，需要补充：{{{reason}}}"
+    ready:
+      role: developer
+      prompt: 'Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}.'
+  developer:
+    done:
+      role: reviewer
+      prompt: 'Review branch {{{branch}}} at {{{worktree}}} for code standards compliance. Repo remote: {{{repoRemote}}}.'
+    failed:
+      role: $END
+      prompt: 'Developer failed: {{{reason}}}. Ending workflow.'
+  reviewer:
+    rejected:
+      role: developer
+      prompt: 'Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
+    approved:
+      role: tester
+      prompt: 'Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
+  tester:
+    fix_code:
+      role: developer
+      prompt: 'Tests found code issues: {{{report}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
+    fix_spec:
+      role: planner
+      prompt: 'Tests found spec issues: {{{report}}}. Revise the test spec. Repo remote: {{{repoRemote}}}.'
+    passed:
+      role: committer
+      prompt: 'All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}. Repo remote (owner/repo): {{{repoRemote}}}.'
+  committer:
+    hook_failed:
+      role: developer
+      prompt: 'Push hook failed: {{{error}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
+    committed:
+      role: $END
+      prompt: 'PR created: {{{prUrl}}}. Workflow complete.'