fix: add workflow-agent-claude-code to publish order

小橘 <xiaoju@shazhou.work>

.changeset/env-api-unify.md

@@ -1,5 +0,0 @@
----
-"@uncaged/workflow-util": patch
----
-
-Replace optionalEnv/requireEnv with unified env(name, fallback) API

.changeset/fix-internal-deps.md

@@ -1,5 +0,0 @@
----
-"@uncaged/workflow-protocol": patch
----
-
-fix: correct internal dependency versions for prerelease

.changeset/fix-publish-src.md

@@ -1,5 +0,0 @@
----
-"@uncaged/workflow-util-agent": patch
----
-
-fix: include create-agent-adapter.ts in published src

.changeset/fix-workspace-deps.md

@@ -1,5 +0,0 @@
----
-"@uncaged/workflow-protocol": patch
----
-
-fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)

.changeset/pre.json

@@ -1,30 +0,0 @@
-{
-  "mode": "pre",
-  "tag": "alpha",
-  "initialVersions": {
-    "@uncaged/cli-workflow": "0.4.5",
-    "@uncaged/workflow-agent-cursor": "0.4.5",
-    "@uncaged/workflow-agent-hermes": "0.4.5",
-    "@uncaged/workflow-agent-llm": "0.4.5",
-    "@uncaged/workflow-agent-react": "0.4.5",
-    "@uncaged/workflow-cas": "0.4.5",
-    "@uncaged/workflow-dashboard": "0.1.0",
-    "@uncaged/workflow-execute": "0.4.5",
-    "@uncaged/workflow-gateway": "0.4.5",
-    "@uncaged/workflow-protocol": "0.4.5",
-    "@uncaged/workflow-reactor": "0.4.5",
-    "@uncaged/workflow-register": "0.4.5",
-    "@uncaged/workflow-runtime": "0.4.5",
-    "@uncaged/workflow-template-develop": "0.4.5",
-    "@uncaged/workflow-template-solve-issue": "0.4.5",
-    "@uncaged/workflow-util": "0.4.5",
-    "@uncaged/workflow-util-agent": "0.4.5"
-  },
-  "changesets": [
-    "env-api-unify",
-    "fix-internal-deps",
-    "fix-publish-src",
-    "fix-workspace-deps",
-    "rfc-252-agent-fn"
-  ]
-}

.changeset/rfc-252-agent-fn.md

@@ -1,5 +0,0 @@
----
-"@uncaged/workflow-protocol": minor
----
-
-feat: AgentFn<Opt> type boundary and createAgentAdapter bridging function (RFC #252)

.gitea/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: ['*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Check
+        run: bun run check
+
+      - name: Test
+        run: bun run test:ci

.gitignore

@@ -12,4 +12,5 @@ packages/workflow-template-develop/develop.esm.js
 .DS_Store
 *.py
 .claude
-tmp
+tmp.worktrees/
+.worktrees/

.plan/335-setup-validate.md

@@ -1,83 +0,0 @@
-# Test Spec: uwf setup model connectivity validation (#335)
-
-## Context
-
-File: `packages/cli-workflow/src/commands/setup.ts`
-Test file: `packages/cli-workflow/src/__tests__/setup-validate.test.ts`
-
-After `cmdSetup` writes config, it should send a test chat completion request to verify the configured model is reachable. If validation fails, warn the user (don't abort — config is already saved).
-
-## Implementation Notes
-
-- Add a `validateModel(baseUrl, apiKey, model)` function that sends a minimal chat completion request (`POST /chat/completions` with `messages: [{role:"user",content:"hi"}]`, `max_tokens: 1`)
-- Returns `Result<void, string>` — ok if 2xx response, error with reason string otherwise
-- Use `AbortSignal.timeout(15_000)` for the request
-- Both `cmdSetup` and `cmdSetupInteractive` should call it after saving config
-- `cmdSetup` returns validation result in its return object: `{ ...existing, validation: { ok: true } | { ok: false, error: string } }`
-- `cmdSetupInteractive` prints a warning to console if validation fails, success message if it passes
-- Use the project logger (`createLogger`) — no raw `console.log` except in interactive CLI output (per CLAUDE.md)
-
-## Test Cases (vitest)
-
-### 1. `validateModel` — success path
-- Mock `fetch` to return `{ status: 200, ok: true, json: () => ({}) }`
-- Call `validateModel(baseUrl, apiKey, model)`
-- Assert returns `{ ok: true, value: undefined }`
-- Assert fetch was called with correct URL (`${baseUrl}/chat/completions`), correct headers (`Authorization: Bearer ${apiKey}`), correct body (model, messages, max_tokens: 1)
-
-### 2. `validateModel` — HTTP error (401 unauthorized)
-- Mock `fetch` to return `{ status: 401, ok: false, statusText: "Unauthorized" }`
-- Call `validateModel(baseUrl, apiKey, model)`
-- Assert returns `{ ok: false, error: <string containing "401"> }`
-
-### 3. `validateModel` — HTTP error (404 model not found)
-- Mock `fetch` to return `{ status: 404, ok: false, statusText: "Not Found" }`
-- Assert returns `{ ok: false, error: <string containing "404"> }`
-
-### 4. `validateModel` — network timeout
-- Mock `fetch` to throw `DOMException` with name `AbortError`
-- Assert returns `{ ok: false, error: <string containing "timeout" or "unreachable"> }`
-
-### 5. `validateModel` — network error (DNS failure, connection refused)
-- Mock `fetch` to throw `TypeError("fetch failed")`
-- Assert returns `{ ok: false, error: <string mentioning connectivity> }`
-
-### 6. `cmdSetup` — includes validation result on success
-- Mock global `fetch` for `/chat/completions` to succeed
-- Call `cmdSetup({ provider, baseUrl, apiKey, model, storageRoot })`
-- Assert returned object has `validation: { ok: true, value: undefined }`
-- Assert config files are still written (existing behavior preserved)
-
-### 7. `cmdSetup` — includes validation result on failure (config still saved)
-- Mock global `fetch` for `/chat/completions` to return 401
-- Call `cmdSetup({ ... })`
-- Assert returned object has `validation: { ok: false, error: ... }`
-- Assert `config.yaml` and `.env` are still written (validation failure doesn't prevent saving)
-
-### 8. `cmdSetupInteractive` — prints success message on validation pass
-- Mock `fetch` for both `/models` and `/chat/completions` to succeed
-- Mock stdin to provide valid selections
-- Capture console output
-- Assert output contains a success message like "Model verified" or "✓"
-
-### 9. `cmdSetupInteractive` — prints warning on validation failure
-- Mock `fetch`: `/models` succeeds, `/chat/completions` returns 401
-- Mock stdin for valid selections
-- Capture console output
-- Assert output contains a warning about model not being reachable and suggests trying a different model
-
-### 10. `validateModel` — request body correctness
-- Mock `fetch` to capture the request body
-- Call `validateModel(baseUrl, apiKey, "test-model")`
-- Assert body is `{ model: "test-model", messages: [{role: "user", content: "hi"}], max_tokens: 1 }`
-
-## Export Requirements
-
-- `validateModel` must be exported (for direct unit testing)
-- Signature: `async function validateModel(baseUrl: string, apiKey: string, model: string): Promise<Result<void, string>>`
-- `Result` type: `{ ok: true; value: T } | { ok: false; error: E }` (project convention)
-
-## Files to Create/Modify
-
-- **New**: `packages/cli-workflow/src/__tests__/setup-validate.test.ts` — all test cases above
-- **Modify**: `packages/cli-workflow/src/commands/setup.ts` — add `validateModel`, integrate into `cmdSetup` and `cmdSetupInteractive`

.workflows/e2e-walkthrough.yaml

@@ -0,0 +1,269 @@
+name: "e2e-walkthrough"
+description: "End-to-end walkthrough of uwf CLI. Dogfooding: uwf tests uwf. Each role validates a phase of the CLI surface inside an isolated Docker container."
+roles:
+  bootstrap:
+    description: "Start Docker container with isolated storage, verify uwf is runnable"
+    goal: "You are an E2E test runner. Set up an isolated Docker environment and verify basic uwf functionality."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      1. Start a Docker container with isolated storage:
+         ```
+         docker run -d --name uwf-e2e-$$ \
+           -v $HOME:$HOME \
+           -e HOME=$HOME \
+           -e UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage \
+           -w ~/repos/workflow \
+           node:22-bookworm \
+           sleep infinity
+         ```
+      2. Inside the container, install bun, install deps, then `bun link` all packages
+         so that `uwf`, `uwf-hermes`, `uwf-builtin` are on PATH (from source):
+         ```
+         docker exec uwf-e2e-$$ bash -c '
+           # Install bun
+           curl -fsSL https://bun.sh/install | bash
+           export PATH="$HOME/.bun/bin:$PATH"
+
+           # Isolated storage
+           mkdir -p $UNCAGED_WORKFLOW_STORAGE_ROOT
+
+           # Install workspace deps
+           cd ~/repos/workflow && bun install --frozen-lockfile
+
+           # bun link each package that has a bin entry
+           cd packages/cli-workflow && bun link && cd ../..
+           cd packages/workflow-agent-hermes && bun link && cd ../..
+           cd packages/workflow-agent-builtin && bun link && cd ../..
+         '
+         ```
+      3. Verify all three commands are available inside the container:
+         ```
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf --version'
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf-hermes --help'
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf-builtin --help'
+         ```
+      4. Copy host config if it exists:
+         ```
+         docker exec uwf-e2e-$$ bash -c '
+           if [ -f $HOME/.uncaged/workflow/config.yaml ]; then
+             cp $HOME/.uncaged/workflow/config.yaml $UNCAGED_WORKFLOW_STORAGE_ROOT/config.yaml
+           fi
+         '
+         ```
+
+      Report the container name and confirm uwf + agents are working.
+      Set containerName to the Docker container name for subsequent roles.
+    output: "Report uwf version and container readiness. Set $status to pass with containerName, or fail with error."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            containerName: { type: string }
+          required: [$status, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+          required: [$status, error]
+
+  config-and-registry:
+    description: "Validate uwf config commands and workflow registration"
+    goal: "You are an E2E test runner. Validate uwf config operations and workflow registration inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container from the previous step (containerName is in your prompt).
+      All commands run via: `docker exec <containerName> bash -c '...'`
+      All commands use `uwf` (installed via `bun link` inside the container).
+      Remember to set env vars in each exec:
+        export PATH="$HOME/.bun/bin:$PATH"
+        export UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Config tests:
+      1. `uwf config list` — verify it returns valid JSON
+      2. `uwf config set models.test.name test-model` — set a test key
+      3. `uwf config get models.test.name` — verify it returns "test-model"
+
+      Workflow registration tests:
+      4. `uwf workflow add ~/repos/workflow/examples/solve-issue.yaml` — register workflow
+      5. Verify the output contains a hash
+      6. `uwf workflow list` — verify non-empty array
+      7. Capture the workflow name from the list
+      8. `uwf workflow show <name>` — verify it returns roles
+
+      Report all test results with pass/fail counts.
+    output: "Report test results. Set $status to pass (with workflowName and containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  thread-ops:
+    description: "Test thread start, list, show, and exec"
+    goal: "You are an E2E test runner. Validate thread creation and execution inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container (containerName) and workflow (workflowName) from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      1. `uwf thread start <workflowName> -p 'E2E test: what is 2+2?'` — capture thread ID from JSON output
+      2. `uwf thread list` — verify the thread appears in the list
+      3. `uwf thread show <threadId>` — verify head pointer exists
+      4. `uwf thread exec <threadId> --agent uwf-builtin` — execute one step
+      5. Verify exec returns JSON with a head field
+
+      Report results. Pass threadId and containerName forward.
+    output: "Report test results. Set $status to pass (with threadId, workflowName, containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            threadId: { type: string }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, threadId, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  inspect:
+    description: "Test step list/show, thread read, and CAS operations"
+    goal: "You are an E2E test runner. Validate read and inspect operations inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container (containerName) and threadId from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Step inspection:
+      1. `uwf step list <threadId>` — verify steps array has length > 1
+      2. Capture the last step hash from the output
+      3. `uwf step show <lastStepHash>` — verify it returns a role field
+
+      Thread read:
+      4. `uwf thread read <threadId>` — verify non-empty output
+
+      CAS operations:
+      5. `uwf cas get <lastStepHash>` — verify returns a type field
+      6. `uwf cas has <lastStepHash>` — verify exits 0
+      7. `uwf cas refs <lastStepHash>` — list refs (may be empty)
+      8. `uwf cas walk <lastStepHash>` — verify returns non-empty array
+
+      Report results. Pass threadId, lastStepHash, workflowName, containerName forward.
+    output: "Report test results. Set $status to pass (with threadId, lastStepHash, workflowName, containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            threadId: { type: string }
+            lastStepHash: { type: string }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, threadId, lastStepHash, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  cancel-and-fork:
+    description: "Test thread cancel, step fork, and log inspection"
+    goal: "You are an E2E test runner. Validate cancel, fork, and log operations inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use containerName, threadId, lastStepHash, and workflowName from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Cancel:
+      1. Start a second thread: `uwf thread start <workflowName> -p 'E2E cancel test'`
+      2. Cancel it: `uwf thread cancel <secondThreadId>`
+      3. Verify it appears in completed list: `uwf thread list --status completed`
+
+      Fork:
+      4. Fork from the first thread's last step: `uwf step fork <lastStepHash>`
+      5. Verify fork creates a new thread with a different ID
+
+      Logs:
+      6. `uwf log list` — verify output (may be empty)
+      7. `uwf log show --thread <threadId>` — verify runs without error
+
+      Report results with summary.
+    output: "Report test results with summary. Set $status to pass or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            containerName: { type: string }
+            summary: { type: string }
+          required: [$status, containerName, summary]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  cleanup:
+    description: "Remove Docker container"
+    goal: "You are an E2E test runner. Clean up the Docker container used for testing."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Remove the Docker container (containerName is in your prompt):
+      1. `docker rm -f <containerName>`
+      2. Verify the container is gone: `docker ps -a --filter name=<containerName> --format '{{.Names}}'` should return empty
+
+      Report cleanup result.
+    output: "Report cleanup result. Set $status to pass or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            summary: { type: string }
+          required: [$status, summary]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+          required: [$status, error]
+
+graph:
+  $START:
+    _: { role: "bootstrap", prompt: "Set up the Docker container and verify uwf is runnable." }
+  bootstrap:
+    pass: { role: "config-and-registry", prompt: "Container {{{containerName}}} is ready. Validate config and workflow registration." }
+    fail: { role: "$END", prompt: "Bootstrap failed: {{{error}}}. No container was created." }
+  config-and-registry:
+    pass: { role: "thread-ops", prompt: "Config and registry OK. Workflow '{{{workflowName}}}' registered. Container: {{{containerName}}}. Now test thread operations." }
+    fail: { role: "cleanup", prompt: "Config/registry failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  thread-ops:
+    pass: { role: "inspect", prompt: "Thread ops OK. threadId={{{threadId}}}, workflowName={{{workflowName}}}, containerName={{{containerName}}}. Now test inspect operations." }
+    fail: { role: "cleanup", prompt: "Thread ops failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  inspect:
+    pass: { role: "cancel-and-fork", prompt: "Inspect OK. threadId={{{threadId}}}, lastStepHash={{{lastStepHash}}}, workflowName={{{workflowName}}}, containerName={{{containerName}}}. Now test cancel, fork, and logs." }
+    fail: { role: "cleanup", prompt: "Inspect failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  cancel-and-fork:
+    pass: { role: "cleanup", prompt: "All tests passed! {{{summary}}}. Clean up container {{{containerName}}}." }
+    fail: { role: "cleanup", prompt: "Cancel/fork failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  cleanup:
+    pass: { role: "$END", prompt: "E2E walkthrough complete. {{{summary}}}" }
+    fail: { role: "$END", prompt: "Cleanup failed: {{{error}}}. Manual cleanup may be needed." }

CLAUDE.md

@@ -23,10 +23,9 @@ workflow/
   packages/
     workflow-protocol/    # @uncaged/workflow-protocol — shared types (WorkflowPayload, StepNodePayload, WorkflowConfig, etc.)
     workflow-util/        # @uncaged/workflow-util — Crockford Base32, ULID, logger, frontmatter parsing/validation
-    workflow-moderator/   # @uncaged/workflow-moderator — Status-based graph evaluator
-    workflow-agent-kit/   # @uncaged/workflow-agent-kit — createAgent factory, context builder, extract pipeline
+    workflow-util-agent/  # @uncaged/workflow-util-agent — createAgent factory, context builder, extract pipeline
     workflow-agent-hermes/ # @uncaged/workflow-agent-hermes — uwf-hermes CLI binary (spawns hermes chat)
-    cli-workflow/         # @uncaged/cli-workflow — uwf CLI binary
+    cli-workflow/         # @uncaged/cli-workflow — uwf CLI binary (includes status-based moderator in src/moderator/)
   legacy-packages/       # Archived packages (preserved for reference, not active)
   examples/              # Workflow YAML examples (solve-issue.yaml)
   docs/                  # Architecture docs
@@ -34,7 +33,7 @@ workflow/
   tsconfig.json          # root TypeScript config
 ```
 
-- Dependency layers: `workflow-protocol` → (`workflow-util`, `workflow-moderator`) → `workflow-agent-kit` → `workflow-agent-hermes` / `cli-workflow`
+- Dependency layers: `workflow-protocol` → `workflow-util` → `workflow-util-agent` → `workflow-agent-hermes` / `cli-workflow`
 - Packages use `workspace:^` protocol (resolves to `^x.y.z` on publish)
 - External CAS: `@uncaged/json-cas` (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend)
 

CONTRIBUTING.md

@@ -94,8 +94,7 @@ This creates a markdown file in `.changeset/` describing the change. It will be
 packages/
   workflow-protocol/      # Shared types and JSON Schema
   workflow-util/          # Encoding, IDs, logging, frontmatter
-  workflow-moderator/     # Status-based graph evaluator
-  workflow-agent-kit/     # createAgent factory, extract pipeline
+  workflow-util-agent/    # createAgent factory, extract pipeline
   workflow-agent-hermes/  # Hermes ACP agent
   workflow-agent-builtin/ # Built-in LLM agent
   workflow-agent-claude-code/ # Claude Code agent

README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/shazhou-ww/uncaged-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/shazhou-ww/uncaged-workflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@uncaged/cli-workflow?label=%40uncaged%2Fcli-workflow)](https://www.npmjs.com/package/@uncaged/cli-workflow)
 [![npm](https://img.shields.io/npm/v/@uncaged/workflow-protocol?label=%40uncaged%2Fworkflow-protocol)](https://www.npmjs.com/package/@uncaged/workflow-protocol)
-[![npm](https://img.shields.io/npm/v/@uncaged/workflow-agent-kit?label=%40uncaged%2Fworkflow-agent-kit)](https://www.npmjs.com/package/@uncaged/workflow-agent-kit)
+[![npm](https://img.shields.io/npm/v/@uncaged/workflow-util-agent?label=%40uncaged%2Fworkflow-util-agent)](https://www.npmjs.com/package/@uncaged/workflow-util-agent)
 
 A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, status-based routing, and a directed graph. Threads are immutable CAS-linked chains — each `uwf thread step` runs one moderator→agent→extract cycle and exits.
 
@@ -51,10 +51,9 @@ Layer 0 — Contract
 
 Layer 1 — Shared infra
   workflow-util              Encoding, IDs, logging, frontmatter, paths
-  workflow-moderator         Status-based graph evaluator
 
 Layer 2 — Agent framework
-  workflow-agent-kit         createAgent factory, context builder, extract pipeline
+  workflow-util-agent         createAgent factory, context builder, extract pipeline
 
 Layer 3 — Agent implementations
   workflow-agent-hermes      Hermes ACP agent (uwf-hermes)
@@ -62,7 +61,7 @@ Layer 3 — Agent implementations
   workflow-agent-claude-code Claude Code agent (uwf-claude-code)
 
 Layer 4 — CLI
-  cli-workflow               uwf binary — thread lifecycle, registry, CAS, setup
+  cli-workflow               uwf binary — thread lifecycle, registry, CAS, setup (includes status-based moderator)
 
 App (uses protocol; not in the runtime engine stack)
   workflow-dashboard         Web UI for visual workflow editing
@@ -78,8 +77,7 @@ See [docs/architecture.md](docs/architecture.md) for the full design — three-p
 |---------|-----|-------------|------|--------|
 | `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI — thread lifecycle, workflow registry, CAS inspection, setup | cli | [README](packages/cli-workflow/README.md) |
 | `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types and JSON Schema constants | lib | [README](packages/workflow-protocol/README.md) |
-| `workflow-moderator` | `@uncaged/workflow-moderator` | Status-based graph evaluator — next role or `$END` | lib | [README](packages/workflow-moderator/README.md) |
-| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-agent-kit/README.md) |
+| `workflow-util-agent` | `@uncaged/workflow-util-agent` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-util-agent/README.md) |
 | `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | [README](packages/workflow-util/README.md) |
 | `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` — spawns Hermes chat via ACP | agent | [README](packages/workflow-agent-hermes/README.md) |
 | `workflow-agent-builtin` | `@uncaged/workflow-agent-builtin` | `uwf-builtin` — built-in LLM agent with file/shell tools | agent | [README](packages/workflow-agent-builtin/README.md) |

biome.json

@@ -4,6 +4,7 @@
     "includes": [
       "**",
       "!**/dist",
+      "!.worktrees",
       "!**/node_modules",
       "!**/legacy-packages",
       "!scripts",

docs/architecture.md

@@ -8,7 +8,7 @@
 
 A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions stored as CAS nodes; threads are immutable chains of CAS-linked step nodes. No daemon — each `uwf thread step` invocation runs one moderator→agent→extract cycle and exits.
 
-The implementation lives in **6** active packages under `packages/`, plus two external CAS packages (`@uncaged/json-cas`, `@uncaged/json-cas-fs`). Legacy packages reside in `legacy-packages/` and are not part of the active stack.
+The implementation lives in **5** active packages under `packages/`, plus two external CAS packages (`@uncaged/json-cas`, `@uncaged/json-cas-fs`). Legacy packages reside in `legacy-packages/` and are not part of the active stack.
 
 ## Package map
 
@@ -16,10 +16,9 @@ The implementation lives in **6** active packages under `packages/`, plus two ex
 |-------|---------|---------------|
 | Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `ModeratorContext`, `WorkflowConfig`, etc.). No runtime deps beyond `@uncaged/json-cas-fs`. |
 | Shared infra | `@uncaged/workflow-util` → `workflow-util` | Crockford Base32, ULID generation, `createLogger`, frontmatter parsing/validation. |
-| Moderator | `@uncaged/workflow-moderator` → `workflow-moderator` | Status-based graph evaluator: given a routing graph, last role, and last output, returns the next role or `$END`. |
-| Agent framework | `@uncaged/workflow-agent-kit` → `workflow-agent-kit` | `createAgent` entrypoint factory, context builder, frontmatter fast-path extractor, LLM extract fallback, output format instruction builder. |
+| Agent framework | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `createAgent` entrypoint factory, context builder, frontmatter fast-path extractor, LLM extract fallback, output format instruction builder. |
 | Agent: Hermes | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `uwf-hermes` CLI binary — spawns `hermes chat`, pipes prompt, captures session detail. |
-| CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uwf` binary — thread lifecycle, workflow registry, CAS inspection, setup. |
+| CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uwf` binary — thread lifecycle, workflow registry, CAS inspection, setup. Includes status-based graph evaluator in `src/moderator/` (next role or `$END`). |
 
 ### External dependencies
 
@@ -27,7 +26,7 @@ The implementation lives in **6** active packages under `packages/`, plus two ex
 |---------|------|
 | `@uncaged/json-cas` | Content-addressed store API, XXH64 hashing, JSON Schema registration and validation. |
 | `@uncaged/json-cas-fs` | Filesystem backend for `json-cas`. |
-| `mustache` | Template renderer for edge prompts (used by `workflow-moderator`). |
+| `mustache` | Template renderer for edge prompts (used by `cli-workflow` moderator). |
 | `commander` | CLI argument parsing (used by `cli-workflow`). |
 | `dotenv` | Loads `.env` files for API keys. |
 | `yaml` | YAML parse/stringify. |
@@ -45,10 +44,9 @@ flowchart BT
   end
   subgraph L1["Layer 1 — shared"]
     util["@uncaged/workflow-util"]
-    moderator["@uncaged/workflow-moderator"]
   end
   subgraph L2["Layer 2 — agent framework"]
-    kit["@uncaged/workflow-agent-kit"]
+    kit["@uncaged/workflow-util-agent"]
   end
   subgraph L3["Layer 3 — agent implementations"]
     hermes["@uncaged/workflow-agent-hermes"]
@@ -58,7 +56,6 @@ flowchart BT
   end
   protocol --> jcasfs
   util --> protocol
-  moderator --> protocol
   kit --> protocol
   kit --> util
   kit --> jcas
@@ -68,7 +65,6 @@ flowchart BT
   cli --> protocol
   cli --> util
   cli --> kit
-  cli --> moderator
   cli --> jcas
   cli --> jcasfs
 ```
@@ -222,7 +218,7 @@ Each agent is an external command invoked by `uwf thread step`:
 Contract:
 1. `uwf thread step` determines the next role via the moderator
 2. Agent CLI is spawned with `(thread-id, role)` as positional args
-3. `workflow-agent-kit` (`createAgent`) handles the boilerplate:
+3. `workflow-util-agent` (`createAgent`) handles the boilerplate:
    - Parses argv
    - Loads `.env` from storage root
    - Builds `AgentContext` by walking the CAS chain from `threads.yaml` head
@@ -255,11 +251,11 @@ scope: role
 Fixed the login redirect by updating the auth middleware...
 ```
 
-The `outputFormatInstruction` (built by `buildOutputFormatInstruction` in `workflow-agent-kit`) is prepended to the role's system prompt, so the deliverable format is the first thing the agent sees. It lists the expected frontmatter fields derived from the role's `meta` JSON Schema.
+The `outputFormatInstruction` (built by `buildOutputFormatInstruction` in `workflow-util-agent`) is prepended to the role's system prompt, so the deliverable format is the first thing the agent sees. It lists the expected frontmatter fields derived from the role's `meta` JSON Schema.
 
 ## Two-layer extract
 
-Structured output extraction uses a two-layer strategy (`workflow-agent-kit`):
+Structured output extraction uses a two-layer strategy (`workflow-util-agent`):
 
 ### Layer 1: frontmatter fast path (`frontmatter.ts`)
 
@@ -283,7 +279,7 @@ If the fast path returns `null` (no frontmatter, invalid, or doesn't satisfy sch
 
 ## Prompt injection
 
-`workflow-agent-kit` prepends two pieces of context to the agent's system prompt:
+`workflow-util-agent` prepends two pieces of context to the agent's system prompt:
 
 1. **Deliverable format instruction** — generated from the role's `meta` schema, tells the agent exactly what frontmatter fields to produce and the expected format
 2. **Scope constraint** — "Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope."
@@ -395,7 +391,7 @@ Everything else is immutable CAS content.
 providers:
   openrouter:
     baseUrl: "https://openrouter.ai/api/v1"
-    apiKeyEnv: "OPENROUTER_API_KEY"
+    apiKey: "sk-..."
 
 models:
   sonnet:

docs/builtin-agent-research.md

@@ -78,9 +78,9 @@ Agent 解析优先级（`resolveAgentConfig`）：
 
 #### 环境变量：Storage Root
 
-文档中写的 `UWF_STORAGE_ROOT` **在当前代码中不存在**。实际优先级（`workflow-agent-kit` / `cli-workflow` 一致）：
+文档中写的 `UWF_STORAGE_ROOT` **在当前代码中不存在**。实际优先级（`workflow-util-agent` / `cli-workflow` 一致）：
 
-```33:43:packages/workflow-agent-kit/src/storage.ts
+```33:43:packages/workflow-util-agent/src/storage.ts
 export function resolveStorageRoot(): string {
   const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
   if (internal !== undefined && internal !== "") {
@@ -107,7 +107,7 @@ Agent 子进程通过继承的 `process.env` 与父 CLI 共享同一 storage roo
 
 ### Q2: createAgent 工厂
 
-workflow-agent-kit 的 `createAgent` 做了什么？它的完整生命周期是什么？
+workflow-util-agent 的 `createAgent` 做了什么？它的完整生命周期是什么？
 
 **调研要点：**
 - `AgentOptions` 类型的 `run` 和 `continue` 回调签名
@@ -119,7 +119,7 @@ workflow-agent-kit 的 `createAgent` 做了什么？它的完整生命周期是
 
 #### 类型定义
 
-```4:35:packages/workflow-agent-kit/src/types.ts
+```4:35:packages/workflow-util-agent/src/types.ts
 export type AgentContext = ModeratorContext & {
   threadId: ThreadId;
   role: string;
@@ -156,7 +156,7 @@ export type AgentOptions = {
 
 #### 生命周期（按执行顺序）
 
-```101:152:packages/workflow-agent-kit/src/run.ts
+```101:152:packages/workflow-util-agent/src/run.ts
 export function createAgent(options: AgentOptions): () => Promise<void> {
   return async function main(): Promise<void> {
     const { threadId, role } = parseArgv(process.argv);
@@ -197,7 +197,7 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
 
 #### StepNode 写入结构
 
-```44:68:packages/workflow-agent-kit/src/run.ts
+```44:68:packages/workflow-util-agent/src/run.ts
 async function writeStepNode(options: {
   store: AgentStore["store"];
   schemas: AgentStore["schemas"];
@@ -274,7 +274,7 @@ export type StepContext = Omit<StepRecord, "output"> & {
 
 `buildContextWithMeta` 还返回 `meta`：
 
-```148:154:packages/workflow-agent-kit/src/context.ts
+```148:154:packages/workflow-util-agent/src/context.ts
 export type BuildContextMeta = {
   storageRoot: string;
   store: Store;
@@ -337,7 +337,7 @@ async function resolveFrontmatterRef(..., frontmatter: unknown): Promise<CasRef>
 
 #### Frontmatter fast-path（createAgent 实际使用的路径）
 
-```148:195:packages/workflow-agent-kit/src/frontmatter.ts
+```148:195:packages/workflow-util-agent/src/frontmatter.ts
 export async function tryFrontmatterFastPath(
   raw: string,
   outputSchema: CasRef,
@@ -357,7 +357,7 @@ export async function tryFrontmatterFastPath(
 
 #### LLM extract fallback（已实现但未接入 createAgent）
 
-```135:181:packages/workflow-agent-kit/src/extract.ts
+```135:181:packages/workflow-util-agent/src/extract.ts
 export async function extract(
   rawOutput: string,
   outputSchema: CasRef,
@@ -374,7 +374,7 @@ export async function extract(
 
 #### Correction prompt（retry）
 
-```125:128:packages/workflow-agent-kit/src/run.ts
+```125:128:packages/workflow-util-agent/src/run.ts
 const correctionMessage =
   "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
   "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
@@ -402,7 +402,7 @@ workflow 怎么配置和使用 model？
 ```136:160:packages/workflow-protocol/src/types.ts
 export type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
 };
 
 export type ModelConfig = {
@@ -425,11 +425,11 @@ export type WorkflowConfig = {
 
 #### resolveModel
 
-```32:50:packages/workflow-agent-kit/src/extract.ts
+```32:50:packages/workflow-util-agent/src/extract.ts
 export function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider {
   const modelEntry = config.models[alias];
   const providerEntry = config.providers[modelEntry.provider];
-  const apiKey = process.env[providerEntry.apiKeyEnv];
+  const apiKey = providerEntry.apiKey;
   return { baseUrl: providerEntry.baseUrl, apiKey, model: modelEntry.name };
 }
 ```
@@ -438,7 +438,7 @@ export function resolveModel(config: WorkflowConfig, alias: ModelAlias): Resolve
 
 Extract 专用别名解析：
 
-```18:30:packages/workflow-agent-kit/src/extract.ts
+```18:30:packages/workflow-util-agent/src/extract.ts
 export function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias {
   return config.modelOverrides?.extract ?? (config.models.extract ? "extract" : config.models.default ? "default" : config.defaultModel);
 }
@@ -448,7 +448,7 @@ export function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias {
 
 #### chatCompletionText
 
-```87:124:packages/workflow-agent-kit/src/extract.ts
+```87:124:packages/workflow-util-agent/src/extract.ts
 async function chatCompletionText(
   provider: ResolvedLlmProvider,
   messages: Array<{ role: "system" | "user"; content: string }>,
@@ -463,7 +463,7 @@ async function chatCompletionText(
 | 多模态 | **无**（仅 text `content`） |
 | Extract 专用 | `response_format: { type: "json_object" }` |
 
-builtin agent 的 run loop 需要**新写**带 `tools` 的 completion 客户端（可放在 `workflow-agent-builtin` 或扩展 `workflow-agent-kit` 的 `llm/` 模块），不能复用当前 `chatCompletionText` 而不改。
+builtin agent 的 run loop 需要**新写**带 `tools` 的 completion 客户端（可放在 `workflow-agent-builtin` 或扩展 `workflow-util-agent` 的 `llm/` 模块），不能复用当前 `chatCompletionText` 而不改。
 
 ---
 
@@ -609,7 +609,7 @@ flowchart TB
     Loop --> Detail
   end
 
-  subgraph kit ["workflow-agent-kit"]
+  subgraph kit ["workflow-util-agent"]
     Ctx["buildContextWithMeta"]
     FM["tryFrontmatterFastPath"]
     Persist["persistStep"]
@@ -630,7 +630,7 @@ flowchart TB
   Spawn -->|"stdout: step hash"| Step
 ```
 
-**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-agent-kit`、`workflow-protocol`、`workflow-util`（可选 `@uncaged/json-cas` 写 detail schema）。
+**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-util-agent`、`workflow-protocol`、`workflow-util`（可选 `@uncaged/json-cas` 写 detail schema）。
 
 **分层**：
 

docs/wf-stateless-design.md

@@ -280,13 +280,13 @@ threads.yaml: { "01J7K9M2XNPQR5VWBCDF8G3H4T": "8FWKR3TN5V1QA" }
 providers:
   openai:
     baseUrl: "https://api.openai.com/v1"
-    apiKeyEnv: "OPENAI_API_KEY"
+    apiKey: "sk-..."
   anthropic:
     baseUrl: "https://api.anthropic.com/v1"
-    apiKeyEnv: "ANTHROPIC_API_KEY"
+    apiKey: "sk-ant-..."
   openrouter:
     baseUrl: "https://openrouter.ai/api/v1"
-    apiKeyEnv: "OPENROUTER_API_KEY"
+    apiKey: "sk-or-..."
 
 models:
   sonnet:
@@ -341,9 +341,8 @@ OPENROUTER_API_KEY=sk-or-...
 
 ```
 packages/
-├── cli-workflow/              # @uncaged/cli-workflow — uwf CLI（thread/workflow 命令）
-├── workflow-moderator/        # @uncaged/workflow-moderator — Status-based moderator 引擎
-├── workflow-agent-kit/        # @uncaged/workflow-agent-kit — Agent CLI 框架（含 extractor）
+├── cli-workflow/              # @uncaged/cli-workflow — uwf CLI（thread/workflow 命令，含 src/moderator/）
+├── workflow-util-agent/       # @uncaged/workflow-util-agent — Agent CLI 框架（含 extractor）
 ├── workflow-agent-hermes/     # @uncaged/workflow-agent-hermes — uwf-hermes CLI
 ├── workflow-agent-cursor/ # @uncaged/workflow-agent-cursor — uwf-cursor CLI
 └── workflow-protocol/         # @uncaged/workflow-protocol — 共享类型定义
@@ -466,7 +465,7 @@ type Scenario = string;              // e.g. "extract"
 
 type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;                 // env var name to read API key from
+  apiKey: string;                    // API key stored directly
 };
 
 type ModelConfig = {

examples/solve-issue.yaml

@@ -1,92 +1,198 @@
 name: "solve-issue"
-description: "End-to-end issue resolution"
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
 roles:
   planner:
-    description: "Creates implementation plan"
-    goal: "You are a planning agent. You analyze issues and create implementation plans grounded in the actual codebase."
+    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
-      - file-read
-      - shell
     procedure: |
-      1. Locate the code repository:
-         - Check if the current working directory is the repo (look for package.json, .git, etc.)
-         - If the task mentions a repo URL, clone it first.
-         - If this is a new project, create the repo and note the path.
-      2. Explore the codebase — read the relevant source files mentioned in the issue. Understand the current architecture, types, and conventions (check CLAUDE.md, CONTRIBUTING.md, .cursor/rules/).
-      3. Identify which files need changes and what the changes should be, with specific code references.
-      4. Output the plan with:
-         - `repoPath`: absolute path to the repository root
-         - `plan`: detailed implementation plan with file paths and code references
-         - `steps`: concrete action items for the developer
-    output: |
-      Provide repoPath, plan summary, and steps in the frontmatter.
-      The plan MUST reference actual file paths and code structures you found by reading the source.
-      Do NOT guess — if you haven't read a file, read it before referencing it.
+      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. Store it via `uwf cas put-text "<markdown content>"` and capture the returned hash
+      2. Put the hash in frontmatter.plan (required when $status=ready)
+      3. Set repoPath to the absolute path of the repository root
+    output: "Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info."
     frontmatter:
-      type: object
-      properties:
-        $status:
-          enum: ["_"]
-        repoPath:
-          type: string
-        plan:
-          type: string
-      required: [$status, repoPath, plan]
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+          required: [$status, plan, repoPath]
+        - properties:
+            $status: { const: "insufficient_info" }
+          required: [$status]
   developer:
-    description: "Implements code changes"
-    goal: "You are a developer agent. You implement code changes according to plans."
+    description: "TDD implementation per test spec"
+    goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
     capabilities:
-      - file-edit
-      - shell
-      - testing
+      - coding
     procedure: |
-      1. Read the planner's output to get the repoPath and implementation plan.
-      2. cd to the repoPath before making any changes.
-      3. Create a feature branch from the default branch.
-      4. Implement the plan — write code, tests, and ensure existing tests pass.
-      5. Run the project's lint/check command (e.g. `bun run check`, `npm run lint`) and fix ALL errors before proceeding. Build and lint must pass cleanly.
-      6. Commit your changes with a descriptive message referencing the issue.
-    output: "List all files changed and provide a summary of the implementation."
+      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: `uwf cas 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 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:
-      type: object
-      properties:
-        $status:
-          enum: ["_"]
-        filesChanged:
-          type: array
-          items:
-            type: string
-        summary:
-          type: string
-      required: [$status, filesChanged, summary]
+      oneOf:
+        - properties:
+            $status: { const: "done" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "failed" }
+            reason: { type: string }
+          required: [$status, reason]
   reviewer:
-    description: "Reviews code changes"
-    goal: "You are a code reviewer. You review implementations for correctness and quality."
+    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: |
-      1. Run hard checks first — build (`bun run build` or equivalent) and lint (`bunx biome check .` or equivalent) MUST pass with zero errors. If they fail, reject immediately.
-      2. Then review code quality: correctness, edge cases, naming, project conventions (CLAUDE.md), and test coverage.
-      3. Only reject for hard check failures or genuine correctness/security issues. Style suggestions alone should not block approval.
-    output: "Approve or reject with detailed comments explaining your decision."
+      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 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:
-      type: object
-      properties:
-        $status:
-          enum: ["approved", "rejected"]
-        comments:
-          type: string
-      required: [$status, comments]
+      oneOf:
+        - properties:
+            $status: { const: "approved" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "rejected" }
+            comments: { type: string }
+            worktree: { 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: `uwf cas 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 }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "fix_code" }
+            report: { type: string }
+          required: [$status, report]
+        - properties:
+            $status: { const: "fix_spec" }
+            report: { 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 info 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. Stage all changes: `git add -A`
+      2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
+      3. Push the branch: `git push -u origin <branch-name>`
+         - If push hook fails: capture the error log in your output, mark hook_failed
+      4. On push success: create a PR via `tea pr create --repo <owner/repo> --title "..." --description "..."`
+         - Extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
+         - PR description must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+         - On tea failure: capture stderr/stdout, include PR details for manual creation, mark hook_failed
+      5. 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 }
+          required: [$status, prUrl]
+        - properties:
+            $status: { const: "hook_failed" }
+            error: { type: string }
+          required: [$status, error]
 graph:
   $START:
-    _: { role: "planner", prompt: "Analyze the issue described in the task and produce a detailed implementation plan." }
+    _: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
   planner:
-    _: { role: "developer", prompt: "Implement the plan from the planner. Write code, tests, and ensure existing tests pass." }
+    insufficient_info: { role: "$END", prompt: "Insufficient information to proceed; end the workflow." }
+    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}." }
   developer:
-    _: { role: "reviewer", prompt: "Review the developer's implementation against the plan for correctness and quality." }
+    done: { role: "reviewer", prompt: "Review branch {{{branch}}} at {{{worktree}}} for code standards compliance." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
   reviewer:
-    approved: { role: "$END", prompt: "The review passed. Complete the workflow." }
-    rejected: { role: "developer", prompt: "The reviewer rejected your implementation. Read their feedback and fix the issues: {{{comments}}}" }
+    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}." }
+    approved: { role: "tester", prompt: "Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}." }
+  tester:
+    fix_code: { role: "developer", prompt: "Tests found code issues: {{{report}}}. Fix and re-submit." }
+    fix_spec: { role: "planner", prompt: "Tests found spec issues: {{{report}}}. Revise the test spec." }
+    passed: { role: "committer", prompt: "All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}." }
+  committer:
+    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit." }
+    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow complete." }

legacy-packages/workflow-moderator/package.json

@@ -32,7 +32,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
-    "directory": "packages/workflow-moderator"
+    "directory": "legacy-packages/workflow-moderator"
   },
   "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
   "bugs": {

package.json

@@ -14,7 +14,7 @@
     "test:ci": "bun run --filter './packages/*' test:ci",
     "changeset": "bunx changeset",
     "version": "bunx changeset version",
-    "release": "bun run build && bun test && node scripts/publish-all.mjs"
+    "release": "bun run build && bun run test && node scripts/publish-all.mjs"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.22.1",

packages/cli-workflow/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @uncaged/cli-workflow
+
+## 0.5.1
+
+### Patch Changes
+
+- Add 5 persona-based skills (actor, user, author, developer, adapter) and fix skill CLI description truncation
+- Updated dependencies
+  - @uncaged/workflow-util@0.5.1
+  - @uncaged/workflow-protocol@0.5.1
+  - @uncaged/workflow-util-agent@0.5.1

packages/cli-workflow/README.md

@@ -20,7 +20,7 @@ workflow → thread → step → turn
 
 This package has no library `src/index.ts` — it is consumed as a CLI binary only.
 
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-moderator`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `yaml`
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `mustache`, `yaml`
 
 ## Installation
 
@@ -119,7 +119,7 @@ uwf setup --provider openai --base-url https://api.openai.com/v1 \
   --api-key sk-... --model gpt-4o --agent hermes
 ```
 
-Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
+Config: `~/.uncaged/workflow/config.yaml` (includes API keys).
 
 ### Skill
 
@@ -190,6 +190,7 @@ src/
 ├── store.ts            CAS store + registry initialization
 ├── validate.ts         Workflow YAML validation
 ├── schemas.ts          CLI-local schema registration
+├── moderator/          Status-based graph evaluator (next role or $END)
 └── commands/
     ├── thread.ts       Thread lifecycle and exec
     ├── step.ts         Step operations (list/show/read/fork)

packages/cli-workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -8,17 +8,17 @@
   ],
   "type": "module",
   "bin": {
-    "uwf": "./src/cli.ts"
+    "uwf": "./dist/cli.js"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/json-cas-fs": "^0.5.2",
-    "@uncaged/workflow-agent-kit": "workspace:^",
-    "@uncaged/workflow-moderator": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/json-cas-fs": "^0.5.3",
     "@uncaged/workflow-protocol": "workspace:^",
     "@uncaged/workflow-util": "workspace:^",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "commander": "^14.0.3",
     "dotenv": "^16.6.1",
+    "mustache": "^4.2.0",
     "yaml": "^2.8.4"
   },
   "scripts": {
@@ -29,6 +29,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/mustache": "^4.2.6",
     "vitest": "^4.1.6"
   },
   "repository": {

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

@@ -0,0 +1,622 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  cmdConfigGet,
+  cmdConfigList,
+  cmdConfigSet,
+  getConfigPath,
+  getNestedValue,
+  maskApiKeys,
+  parseDotPath,
+  setNestedValue,
+} from "../commands/config.js";
+
+describe("config command", () => {
+  // Helper function to create a test config
+  function createTestConfig(tempDir: string, content: string): string {
+    const configPath = getConfigPath(tempDir);
+    writeFileSync(configPath, content, "utf8");
+    return configPath;
+  }
+
+  // Sample test config
+  const sampleConfig = `providers:
+  dashscope:
+    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+    apiKey: sk-test-dashscope-key
+  openai:
+    baseUrl: https://api.openai.com/v1
+    apiKey: sk-test-openai-key
+models:
+  default:
+    provider: dashscope
+    name: qwen-max
+  gpt4:
+    provider: openai
+    name: gpt-4
+agents:
+  hermes:
+    command: uwf-hermes
+    args:
+      - --provider
+      - dashscope
+  claude-code:
+    command: claude-code
+    args:
+      - --profile
+      - work
+defaultAgent: hermes
+defaultModel: default
+`;
+
+  describe("helper functions", () => {
+    describe("parseDotPath", () => {
+      test("splits dot notation correctly", () => {
+        expect(parseDotPath("a.b.c")).toEqual(["a", "b", "c"]);
+        expect(parseDotPath("defaultAgent")).toEqual(["defaultAgent"]);
+        expect(parseDotPath("providers.dashscope.baseUrl")).toEqual([
+          "providers",
+          "dashscope",
+          "baseUrl",
+        ]);
+      });
+    });
+
+    describe("getNestedValue", () => {
+      test("traverses nested objects", () => {
+        const obj = {
+          a: { b: { c: "value" } },
+          x: "simple",
+        };
+        expect(getNestedValue(obj, ["a", "b", "c"])).toBe("value");
+        expect(getNestedValue(obj, ["x"])).toBe("simple");
+      });
+
+      test("returns undefined for non-existent paths", () => {
+        const obj = { a: { b: "value" } };
+        expect(getNestedValue(obj, ["a", "c"])).toBeUndefined();
+        expect(getNestedValue(obj, ["x", "y"])).toBeUndefined();
+      });
+    });
+
+    describe("setNestedValue", () => {
+      test("creates intermediate objects and sets value", () => {
+        const obj: Record<string, unknown> = {};
+        setNestedValue(obj, ["a", "b", "c"], "value");
+        expect(obj).toEqual({ a: { b: { c: "value" } } });
+      });
+
+      test("preserves existing values", () => {
+        const obj: Record<string, unknown> = { a: { x: "keep" } };
+        setNestedValue(obj, ["a", "b"], "new");
+        expect(obj).toEqual({ a: { x: "keep", b: "new" } });
+      });
+
+      test("overwrites existing value at path", () => {
+        const obj: Record<string, unknown> = { a: { b: "old" } };
+        setNestedValue(obj, ["a", "b"], "new");
+        expect(obj).toEqual({ a: { b: "new" } });
+      });
+    });
+
+    describe("maskApiKeys", () => {
+      test("deep clones and masks all apiKey values in providers", () => {
+        const config = {
+          providers: {
+            dashscope: {
+              baseUrl: "https://example.com",
+              apiKey: "sk-test-key-12345",
+            },
+            openai: {
+              baseUrl: "https://api.openai.com",
+              apiKey: "sk-another-secret",
+            },
+          },
+          models: {
+            default: { provider: "dashscope" },
+          },
+        };
+        const masked = maskApiKeys(config);
+        expect(masked).toEqual({
+          providers: {
+            dashscope: {
+              baseUrl: "https://example.com",
+              apiKey: "***MASKED***",
+            },
+            openai: {
+              baseUrl: "https://api.openai.com",
+              apiKey: "***MASKED***",
+            },
+          },
+          models: {
+            default: { provider: "dashscope" },
+          },
+        });
+        // Ensure it's a deep clone
+        expect(masked).not.toBe(config);
+      });
+
+      test("handles config without providers", () => {
+        const config = { models: { default: { provider: "test" } } };
+        const masked = maskApiKeys(config);
+        expect(masked).toEqual(config);
+      });
+    });
+  });
+
+  describe("cmdConfigList", () => {
+    test("returns full config when file exists", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigList(tempDir);
+        expect(result).toBeDefined();
+        expect(typeof result).toBe("object");
+        expect(result).toHaveProperty("providers");
+        expect(result).toHaveProperty("models");
+        expect(result).toHaveProperty("agents");
+        expect(result).toHaveProperty("defaultAgent");
+        expect(result).toHaveProperty("defaultModel");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("masks all apiKey values in providers section", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = (await cmdConfigList(tempDir)) as Record<string, unknown>;
+        const providers = result.providers as Record<string, unknown>;
+        const dashscope = providers.dashscope as Record<string, unknown>;
+        const openai = providers.openai as Record<string, unknown>;
+        expect(dashscope.apiKey).toBe("***MASKED***");
+        expect(openai.apiKey).toBe("***MASKED***");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when config file doesn't exist", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        await expect(cmdConfigList(tempDir)).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("returns empty object when config file is empty", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, "");
+        const result = await cmdConfigList(tempDir);
+        expect(result).toEqual({});
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when config file is invalid YAML", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, "invalid: yaml: [broken");
+        await expect(cmdConfigList(tempDir)).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("cmdConfigGet", () => {
+    test("retrieves top-level string value (defaultAgent)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "defaultAgent");
+        expect(result).toBe("hermes");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("retrieves top-level string value (defaultModel)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "defaultModel");
+        expect(result).toBe("default");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("retrieves nested object (providers.dashscope)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "providers.dashscope");
+        expect(result).toEqual({
+          baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+          apiKey: "sk-test-dashscope-key",
+        });
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("retrieves deeply nested string (providers.dashscope.baseUrl)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "providers.dashscope.baseUrl");
+        expect(result).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("retrieves nested string in models (models.default.provider)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "models.default.provider");
+        expect(result).toBe("dashscope");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("retrieves array value (agents.hermes.args)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigGet(tempDir, "agents.hermes.args");
+        expect(result).toEqual(["--provider", "dashscope"]);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when key doesn't exist", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigGet(tempDir, "nonexistent.key")).rejects.toThrow(/Key not found/);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when config file doesn't exist", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        await expect(cmdConfigGet(tempDir, "defaultAgent")).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when accessing property on non-object", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigGet(tempDir, "defaultAgent.foo")).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("cmdConfigSet", () => {
+    test("sets top-level string value (defaultAgent)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigSet(tempDir, "defaultAgent", "claude-code");
+        expect(result).toEqual({ key: "defaultAgent", value: "claude-code" });
+        // Verify it was written
+        const updated = await cmdConfigGet(tempDir, "defaultAgent");
+        expect(updated).toBe("claude-code");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("sets nested string value (providers.dashscope.baseUrl)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const newUrl = "https://new-api.example.com/v1";
+        const result = await cmdConfigSet(tempDir, "providers.dashscope.baseUrl", newUrl);
+        expect(result).toEqual({
+          key: "providers.dashscope.baseUrl",
+          value: newUrl,
+        });
+        // Verify it was written
+        const updated = await cmdConfigGet(tempDir, "providers.dashscope.baseUrl");
+        expect(updated).toBe(newUrl);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("creates new nested path (providers.newprovider.baseUrl)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const newUrl = "https://new-provider.com/v1";
+        const result = await cmdConfigSet(tempDir, "providers.newprovider.baseUrl", newUrl);
+        expect(result).toEqual({
+          key: "providers.newprovider.baseUrl",
+          value: newUrl,
+        });
+        // Verify it was created
+        const updated = await cmdConfigGet(tempDir, "providers.newprovider.baseUrl");
+        expect(updated).toBe(newUrl);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("sets array value for args key with valid JSON array", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const newArgs = '["--new", "--flags"]';
+        const result = await cmdConfigSet(tempDir, "agents.hermes.args", newArgs);
+        expect(result).toEqual({
+          key: "agents.hermes.args",
+          value: ["--new", "--flags"],
+        });
+        // Verify it was written
+        const updated = await cmdConfigGet(tempDir, "agents.hermes.args");
+        expect(updated).toEqual(["--new", "--flags"]);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("preserves existing config values when updating one key", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "defaultAgent", "claude-code");
+        // Verify other values are preserved
+        const defaultModel = await cmdConfigGet(tempDir, "defaultModel");
+        expect(defaultModel).toBe("default");
+        const dashscopeUrl = await cmdConfigGet(tempDir, "providers.dashscope.baseUrl");
+        expect(dashscopeUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("creates config file if it doesn't exist", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        const result = await cmdConfigSet(tempDir, "defaultAgent", "hermes");
+        expect(result).toEqual({ key: "defaultAgent", value: "hermes" });
+        // Verify file was created
+        const configPath = getConfigPath(tempDir);
+        const content = readFileSync(configPath, "utf8");
+        expect(content).toContain("defaultAgent: hermes");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when setting property on non-object", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "defaultAgent.foo", "bar")).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("throws error when array value is invalid JSON for args key", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(
+          cmdConfigSet(tempDir, "agents.hermes.args", "[invalid json"),
+        ).rejects.toThrow();
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("sets deeply nested model config (models.gpt4.provider)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigSet(tempDir, "models.gpt4.provider", "new-provider");
+        expect(result).toEqual({
+          key: "models.gpt4.provider",
+          value: "new-provider",
+        });
+        // Verify it was written
+        const updated = await cmdConfigGet(tempDir, "models.gpt4.provider");
+        expect(updated).toBe("new-provider");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("sets agent command (agents.claude-code.command)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        const result = await cmdConfigSet(tempDir, "agents.claude-code.command", "new-command");
+        expect(result).toEqual({
+          key: "agents.claude-code.command",
+          value: "new-command",
+        });
+        // Verify it was written
+        const updated = await cmdConfigGet(tempDir, "agents.claude-code.command");
+        expect(updated).toBe("new-command");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("cmdConfigSet validation", () => {
+    test("rejects unknown top-level key", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "unknownKey", "value")).rejects.toThrow(
+          /Unknown config key.*unknownKey/,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects unknown nested key in providers", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(
+          cmdConfigSet(tempDir, "providers.myProvider.unknownField", "value"),
+        ).rejects.toThrow(/Unknown field.*unknownField.*providers/);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects unknown nested key in models", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "models.default.invalidField", "value")).rejects.toThrow(
+          /Unknown field.*invalidField.*models/,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects unknown nested key in agents", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "agents.hermes.badField", "value")).rejects.toThrow(
+          /Unknown field.*badField.*agents/,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects nested path on scalar key (defaultAgent)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "defaultAgent.foo", "value")).rejects.toThrow(
+          /defaultAgent.*scalar|Cannot set property/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects nested path on scalar key (defaultModel)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "defaultModel.bar", "value")).rejects.toThrow(
+          /defaultModel.*scalar|Cannot set property/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects incomplete nested path (providers without field)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "providers.myProvider", "value")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects incomplete nested path (models without field)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "models.myModel", "value")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects incomplete nested path (agents without field)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "agents.myAgent", "value")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("allows valid nested keys in providers", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "providers.newprovider.baseUrl", "https://example.com");
+        await cmdConfigSet(tempDir, "providers.newprovider.apiKey", "sk-test");
+        const baseUrl = await cmdConfigGet(tempDir, "providers.newprovider.baseUrl");
+        const apiKey = await cmdConfigGet(tempDir, "providers.newprovider.apiKey");
+        expect(baseUrl).toBe("https://example.com");
+        expect(apiKey).toBe("sk-test");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("allows valid nested keys in models", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "models.gpt4.provider", "openai");
+        await cmdConfigSet(tempDir, "models.gpt4.name", "gpt-4o");
+        const provider = await cmdConfigGet(tempDir, "models.gpt4.provider");
+        const name = await cmdConfigGet(tempDir, "models.gpt4.name");
+        expect(provider).toBe("openai");
+        expect(name).toBe("gpt-4o");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("allows valid nested keys in agents", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "agents.hermes.command", "uwf-hermes");
+        await cmdConfigSet(tempDir, "agents.hermes.args", '["--flag"]');
+        const command = await cmdConfigGet(tempDir, "agents.hermes.command");
+        const args = await cmdConfigGet(tempDir, "agents.hermes.args");
+        expect(command).toBe("uwf-hermes");
+        expect(args).toEqual(["--flag"]);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+});

packages/cli-workflow/src/__tests__/moderator-evaluate.test.ts

@@ -0,0 +1,132 @@
+import type { Target, WorkflowPayload } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+
+import { evaluate } from "../moderator/evaluate.js";
+
+const solveIssueGraph: WorkflowPayload["graph"] = {
+  $START: {
+    _: { role: "planner", prompt: "Start planning from the issue in the task." },
+  },
+  planner: {
+    _: { role: "developer", prompt: "Implement the plan: {{plan}}" },
+  },
+  developer: {
+    _: { role: "reviewer", prompt: "Review the changes: {{summary}}" },
+  },
+  reviewer: {
+    approved: { role: "$END", prompt: "Done." },
+    rejected: { role: "developer", prompt: "Fix: {{comments}}" },
+  },
+};
+
+describe("evaluate", () => {
+  test("$START → first role (unit status _)", () => {
+    const result = evaluate(solveIssueGraph, "$START", { $status: "_" });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "planner", prompt: "Start planning from the issue in the task." },
+    });
+  });
+
+  test("status-based routing (reviewer rejected → developer)", () => {
+    const result = evaluate(solveIssueGraph, "reviewer", {
+      $status: "rejected",
+      comments: "missing tests",
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "Fix: missing tests" },
+    });
+  });
+
+  test("status-based routing (reviewer approved → $END)", () => {
+    const result = evaluate(solveIssueGraph, "reviewer", { $status: "approved" });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "$END", prompt: "Done." },
+    });
+  });
+
+  test("missing role in graph → error", () => {
+    const result = evaluate(solveIssueGraph, "unknown-role", { $status: "_" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe('no transitions defined for role "unknown-role"');
+    }
+  });
+
+  test("missing status in graph → error", () => {
+    const result = evaluate(solveIssueGraph, "reviewer", { $status: "pending" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toBe('no transition for role "reviewer" with status "pending"');
+    }
+  });
+
+  test("mustache template rendering with simple fields", () => {
+    const result = evaluate(solveIssueGraph, "planner", {
+      $status: "_",
+      plan: "Add auth middleware",
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "Implement the plan: Add auth middleware" },
+    });
+  });
+
+  test("mustache does not HTML-escape prompt content", () => {
+    const result = evaluate(solveIssueGraph, "reviewer", {
+      $status: "rejected",
+      comments: 'use <T> & "Result<T, E>" types',
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: 'Fix: use <T> & "Result<T, E>" types' },
+    });
+  });
+
+  test("triple mustache also works for unescaped output", () => {
+    const graph: Record<string, Record<string, Target>> = {
+      reviewer: {
+        _: { role: "developer", prompt: "Fix: {{{comments}}}" },
+      },
+    };
+    const result = evaluate(graph, "reviewer", {
+      $status: "_",
+      comments: "<script>alert(1)</script>",
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "Fix: <script>alert(1)</script>" },
+    });
+  });
+
+  test("missing $status defaults to _ (unit routing)", () => {
+    const result = evaluate(solveIssueGraph, "planner", {
+      plan: "Add auth middleware",
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "Implement the plan: Add auth middleware" },
+    });
+  });
+
+  test("mustache template with nested object paths", () => {
+    const graph: Record<string, Record<string, Target>> = {
+      reviewer: {
+        _: {
+          role: "developer",
+          prompt: "Address: {{review.comments}}",
+        },
+      },
+    };
+    const result = evaluate(graph, "reviewer", {
+      $status: "_",
+      review: { comments: "refactor the handler" },
+    });
+    expect(result).toEqual({
+      ok: true,
+      value: { role: "developer", prompt: "Address: refactor the handler" },
+    });
+  });
+});

packages/cli-workflow/src/__tests__/resolve-head-hash.test.ts

@@ -40,6 +40,7 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: headHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId);
@@ -64,6 +65,7 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: historicalHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId);
@@ -87,18 +89,21 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: hash1,
       completedAt: Date.now() - 2000,
+      reason: null,
     });
     await appendThreadHistory(tmpDir, {
       thread: threadId2,
       workflow: workflowHash,
       head: hash2,
       completedAt: Date.now() - 1000,
+      reason: null,
     });
     await appendThreadHistory(tmpDir, {
       thread: threadId3,
       workflow: workflowHash,
       head: hash3,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId2);

packages/cli-workflow/src/__tests__/setup-agent-discovery.test.ts

@@ -0,0 +1,167 @@
+import { readFileSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { parse } from "yaml";
+import { _agentNameFromBinary, _printAgentMenu, cmdSetup } from "../commands/setup.js";
+
+// ─── _agentNameFromBinary ────────────────────────────────────────────────────
+
+describe("_agentNameFromBinary", () => {
+  test("strips uwf- prefix", () => {
+    expect(_agentNameFromBinary("uwf-hermes")).toBe("hermes");
+  });
+
+  test("strips uwf- prefix for compound names", () => {
+    expect(_agentNameFromBinary("uwf-claude-code")).toBe("claude-code");
+  });
+
+  test("returns as-is when no uwf- prefix", () => {
+    expect(_agentNameFromBinary("hermes")).toBe("hermes");
+  });
+
+  test("handles uwf-builtin", () => {
+    expect(_agentNameFromBinary("uwf-builtin")).toBe("builtin");
+  });
+});
+
+// ─── _printAgentMenu ─────────────────────────────────────────────────────────
+
+describe("_printAgentMenu", () => {
+  test("prints known agents with labels", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.join(" "));
+    });
+
+    _printAgentMenu(["uwf-hermes", "uwf-claude-code"]);
+
+    expect(logs.some((l) => l.includes("Hermes"))).toBe(true);
+    expect(logs.some((l) => l.includes("Claude Code"))).toBe(true);
+
+    vi.restoreAllMocks();
+  });
+
+  test("prints unknown agents with binary name as label", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.join(" "));
+    });
+
+    _printAgentMenu(["uwf-custom-agent"]);
+
+    expect(logs.some((l) => l.includes("uwf-custom-agent"))).toBe(true);
+
+    vi.restoreAllMocks();
+  });
+});
+
+// ─── cmdSetup agent config ───────────────────────────────────────────────────
+
+describe("cmdSetup agent configuration", () => {
+  let storageRoot: string;
+
+  beforeEach(async () => {
+    storageRoot = await mkdtemp(join(tmpdir(), "uwf-setup-agent-"));
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  const baseArgs = () => ({
+    provider: "testprovider",
+    baseUrl: "https://api.test.com/v1",
+    apiKey: "sk-test",
+    model: "test-model",
+    storageRoot,
+  });
+
+  test("defaults to hermes agent when no agent specified", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const result = await cmdSetup(baseArgs());
+
+    expect(result.defaultAgent).toBe("hermes");
+    const config = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config.agents.hermes).toEqual({ command: "uwf-hermes", args: [] });
+    expect(config.defaultAgent).toBe("hermes");
+  });
+
+  test("writes specified agent as default", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const result = await cmdSetup({ ...baseArgs(), agent: "claude-code" });
+
+    expect(result.defaultAgent).toBe("claude-code");
+    const config = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config.agents["claude-code"]).toEqual({ command: "uwf-claude-code", args: [] });
+    expect(config.defaultAgent).toBe("claude-code");
+  });
+
+  test("preserves existing agents when adding new one", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    // First setup with hermes
+    await cmdSetup(baseArgs());
+    // Second setup with claude-code
+    await cmdSetup({ ...baseArgs(), agent: "claude-code" });
+
+    const config = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config.agents.hermes).toBeDefined();
+    expect(config.agents["claude-code"]).toBeDefined();
+    expect(config.defaultAgent).toBe("claude-code");
+  });
+
+  test("updates defaultAgent on re-run with different agent", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    await cmdSetup(baseArgs());
+    const config1 = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config1.defaultAgent).toBe("hermes");
+
+    await cmdSetup({ ...baseArgs(), agent: "builtin" });
+    const config2 = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config2.defaultAgent).toBe("builtin");
+  });
+
+  test("normalizes agent name with uwf- prefix to bare name", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const result = await cmdSetup({ ...baseArgs(), agent: "uwf-hermes" });
+
+    expect(result.defaultAgent).toBe("hermes");
+    const config = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config.agents.hermes).toEqual({ command: "uwf-hermes", args: [] });
+    expect(config.defaultAgent).toBe("hermes");
+    // Verify no duplicate uwf- prefix
+    expect(config.agents["uwf-hermes"]).toBeUndefined();
+  });
+
+  test("normalizes uwf-claude-code to claude-code", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({}), { status: 200 }),
+    );
+
+    const result = await cmdSetup({ ...baseArgs(), agent: "uwf-claude-code" });
+
+    expect(result.defaultAgent).toBe("claude-code");
+    const config = parse(readFileSync(join(storageRoot, "config.yaml"), "utf8"));
+    expect(config.agents["claude-code"]).toEqual({ command: "uwf-claude-code", args: [] });
+    expect(config.defaultAgent).toBe("claude-code");
+    // Verify no duplicate uwf- prefix
+    expect(config.agents["uwf-claude-code"]).toBeUndefined();
+  });
+});

packages/cli-workflow/src/__tests__/setup-validate.test.ts

@@ -129,9 +129,8 @@ describe("cmdSetup with validation", () => {
     const result = await cmdSetup(setupArgs());
 
     expect(result.validation).toEqual({ ok: true, value: undefined });
-    // Config files should still be written
+    // Config file should still be written
     expect(result.configPath).toBeTruthy();
-    expect(result.envPath).toBeTruthy();
   });
 
   test("includes validation failure — config still saved", async () => {
@@ -143,8 +142,7 @@ describe("cmdSetup with validation", () => {
 
     expect(result.validation).toBeDefined();
     expect((result.validation as { ok: boolean }).ok).toBe(false);
-    // Config files should still be written despite validation failure
+    // Config file should still be written despite validation failure
     expect(result.configPath).toBeTruthy();
-    expect(result.envPath).toBeTruthy();
   });
 });

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

@@ -0,0 +1,140 @@
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+import {
+  cmdSkillActor,
+  cmdSkillAdapter,
+  cmdSkillArchitecture,
+  cmdSkillAuthor,
+  cmdSkillCli,
+  cmdSkillDeveloper,
+  cmdSkillList,
+  cmdSkillModerator,
+  cmdSkillUser,
+  cmdSkillYaml,
+} from "../commands/skill.js";
+
+describe("skill commands", () => {
+  test("skill list returns all skill names", () => {
+    const result = cmdSkillList();
+    expect(result).toBeInstanceOf(Array);
+    expect(result).toContain("cli");
+    expect(result).toContain("architecture");
+    expect(result).toContain("yaml");
+    expect(result).toContain("moderator");
+    expect(result).toContain("actor");
+    expect(result).toContain("user");
+    expect(result).toContain("author");
+    expect(result).toContain("developer");
+    expect(result).toContain("adapter");
+    for (const name of result) {
+      expect(name).toMatch(/^\S+$/);
+    }
+  });
+
+  test("skill architecture returns non-empty markdown string", () => {
+    const result = cmdSkillArchitecture();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("CAS");
+    expect(result).toContain("Thread");
+    expect(result).toContain("Workflow");
+    expect(result).toContain("Step");
+    expect(result.length).toBeGreaterThan(200);
+  });
+
+  test("skill yaml returns non-empty markdown string", () => {
+    const result = cmdSkillYaml();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("roles");
+    expect(result).toContain("graph");
+    expect(result).toContain("frontmatter");
+    expect(result.length).toBeGreaterThan(200);
+  });
+
+  test("skill moderator returns non-empty markdown string", () => {
+    const result = cmdSkillModerator();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("routing");
+    expect(result).toContain("status");
+    expect(result.length).toBeGreaterThan(200);
+    // Check for edge or graph
+    expect(result).toMatch(/edge|graph/i);
+  });
+
+  test("skill cli returns CLI reference markdown", () => {
+    const result = cmdSkillCli();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("uwf");
+  });
+
+  test("skill actor returns non-empty markdown string", () => {
+    const result = cmdSkillActor();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("frontmatter");
+    expect(result).toContain("CAS");
+    expect(result).toContain("status");
+    expect(result.length).toBeGreaterThan(200);
+  });
+
+  test("skill user returns non-empty markdown string", () => {
+    const result = cmdSkillUser();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("uwf");
+    expect(result).toContain("thread");
+    expect(result).toContain("workflow");
+    expect(result).toContain("Quick Start");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill author returns non-empty markdown string", () => {
+    const result = cmdSkillAuthor();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("frontmatter");
+    expect(result).toContain("graph");
+    expect(result).toContain("$START");
+    expect(result).toContain("$END");
+    expect(result).toContain("$status");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill developer returns non-empty markdown string", () => {
+    const result = cmdSkillDeveloper();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("Monorepo");
+    expect(result).toContain("CAS");
+    expect(result).toContain("Biome");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill adapter returns non-empty markdown string", () => {
+    const result = cmdSkillAdapter();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("createAgent");
+    expect(result).toContain("AgentContext");
+    expect(result).toContain("frontmatter");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill help subcommand is suppressed", () => {
+    const output = execFileSync("bun", ["src/cli.ts", "skill", "--help"], {
+      cwd: join(__dirname, "..", ".."),
+      encoding: "utf-8",
+      env: { ...process.env, PATH: `/opt/homebrew/bin:${process.env.PATH}` },
+    });
+    expect(output).not.toMatch(/help\s+\[command\]/i);
+    expect(output).toContain("cli");
+    expect(output).toContain("architecture");
+    expect(output).toContain("yaml");
+    expect(output).toContain("moderator");
+    expect(output).toContain("actor");
+    expect(output).toContain("user");
+    expect(output).toContain("author");
+    expect(output).toContain("developer");
+    expect(output).toContain("adapter");
+    expect(output).toContain("list");
+  });
+});

packages/cli-workflow/src/__tests__/step-read.test.ts

@@ -453,7 +453,78 @@ describe("step read", () => {
     expect(markdown).not.toContain("## Turn");
   });
 
-  test("test 6: turn content with special characters", async () => {
+  test("test 6: displays role and tool calls in turn body", async () => {
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = createFsStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+    const detailSchemas = await registerDetailSchemas(store);
+
+    const workflowHash = await store.put(schemas.workflow, {
+      name: "test-wf",
+      description: "desc",
+      roles: {
+        worker: {
+          description: "Worker",
+          goal: "You are a worker agent.",
+          capabilities: [],
+          procedure: "Do the work.",
+          output: "Summarize the work.",
+          meta: "placeholder00" as CasRef,
+        },
+      },
+      conditions: {},
+      graph: {},
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Test task",
+    });
+
+    const outputHash = await store.put(schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const turnHash = await store.put(detailSchemas.turn, {
+      index: 0,
+      role: "assistant",
+      content: "",
+      toolCalls: [{ name: "terminal", args: '{"command":"echo hi"}' }],
+      reasoning: null,
+    });
+
+    const detailHash = await store.put(detailSchemas.detail, {
+      sessionId: "session-1",
+      model: "test-model",
+      duration: 1000,
+      turnCount: 1,
+      turns: [turnHash],
+    });
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-hermes",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
+    });
+
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+
+    expect(markdown).toContain("**Turn role:** assistant");
+    expect(markdown).toContain("**terminal**");
+    expect(markdown).toContain('{"command":"echo hi"}');
+  });
+
+  test("test 7: turn content with special characters", async () => {
     const casDir = join(tmpDir, "cas");
     await mkdir(casDir, { recursive: true });
     const store = createFsStore(casDir);

packages/cli-workflow/src/__tests__/thread-cancel-status.test.ts

@@ -0,0 +1,85 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { appendThreadHistory, loadThreadHistory } from "../store.js";
+
+describe("thread cancel status", () => {
+  test("cancelled history entry has reason 'cancelled'", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL1" as ThreadId;
+
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBe("cancelled");
+  });
+
+  test("completed history entry has reason 'completed'", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL2" as ThreadId;
+
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBe("completed");
+  });
+
+  test("legacy history entry without reason parses as null", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL3" as ThreadId;
+
+    // Simulate legacy entry without reason field
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: null,
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBeNull();
+  });
+
+  test("mixed completed and cancelled entries preserve distinct reasons", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+
+    await appendThreadHistory(tmpDir, {
+      thread: "01JTEST000000000000CANCEL4" as ThreadId,
+      workflow: "test-workflow",
+      head: "head1" as CasRef,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    await appendThreadHistory(tmpDir, {
+      thread: "01JTEST000000000000CANCEL5" as ThreadId,
+      workflow: "test-workflow",
+      head: "head2" as CasRef,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(2);
+    expect(history[0]?.reason).toBe("completed");
+    expect(history[1]?.reason).toBe("cancelled");
+  });
+});

packages/cli-workflow/src/__tests__/thread-list-filters.test.ts

@@ -74,6 +74,7 @@ async function completeThread(
     workflow: workflowHash,
     head: headHash,
     completedAt: Date.now(),
+    reason: null,
   });
 }
 

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

@@ -758,6 +758,7 @@ describe("cmdStepList with completed threads", () => {
       workflow: workflowHash,
       head: step2Hash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await cmdStepList(tmpDir, threadId);
@@ -886,6 +887,7 @@ describe("cmdStepShow with completed threads", () => {
       workflow: workflowHash,
       head: stepHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await cmdStepShow(tmpDir, stepHash);
@@ -949,6 +951,7 @@ describe("cmdThreadRead with completed threads", () => {
       workflow: workflowHash,
       head: stepHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
@@ -1011,6 +1014,7 @@ describe("cmdThreadRead with completed threads", () => {
       workflow: workflowHash,
       head: step3Hash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const markdown = await cmdThreadRead(

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

@@ -250,6 +250,110 @@ describe("Suite 3: Status-Edge Consistency", () => {
   });
 });
 
+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,
+      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" },
+      rejected: { role: "writer", prompt: "Fix: {{{comments}}}" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+
+  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" },
+      rejected: { role: "writer", prompt: "Fix" },
+      timeout: { role: "$END", prompt: "Timed out" },
+    };
+    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" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("missing status keys: rejected"))).toBe(true);
+  });
+
+  test("3b.4 enum with single value (not multi-exit) treated as single-exit", () => {
+    const wf = makeWorkflow();
+    wf.roles.writer = {
+      ...wf.roles.writer,
+      frontmatter: {
+        type: "object",
+        properties: {
+          $status: { enum: ["_"] },
+          plan: { type: "string" },
+        },
+        required: ["$status", "plan"],
+      } as unknown as string,
+    };
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{plan}}}" } };
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+
+  test("3b.5 enum multi-exit mustache var not in frontmatter", () => {
+    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: {{{nonexistent}}}" },
+      rejected: { role: "writer", prompt: "Fix: {{{comments}}}" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("nonexistent") && e.includes("not found"))).toBe(true);
+  });
+});
+
 describe("Suite 4: Mustache Template Variable Existence", () => {
   test("4.1 prompt references nonexistent variable (single-exit)", () => {
     const wf = makeWorkflow();

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

@@ -31,7 +31,13 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
         capabilities: [],
         procedure: "",
         output: "",
-        frontmatter: { type: "0000000000000" } as unknown as CasRef,
+        frontmatter: {
+          type: "object",
+          properties: {
+            $status: { type: "string" },
+          },
+          required: ["$status"],
+        } as unknown as CasRef,
       },
     },
     graph: {

packages/cli-workflow/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
 import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
 import { Command } from "commander";
@@ -13,9 +13,21 @@ import {
   cmdCasSchemaList,
   cmdCasWalk,
 } from "./commands/cas.js";
+import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
-import { cmdSkillCli } from "./commands/skill.js";
+import {
+  cmdSkillActor,
+  cmdSkillAdapter,
+  cmdSkillArchitecture,
+  cmdSkillAuthor,
+  cmdSkillCli,
+  cmdSkillDeveloper,
+  cmdSkillList,
+  cmdSkillModerator,
+  cmdSkillUser,
+  cmdSkillYaml,
+} from "./commands/skill.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
@@ -55,8 +67,7 @@ program
   .description(
     "Stateless workflow CLI\n\n" +
       "Four-layer architecture:\n" +
-      "  workflow → thread → step → turn\n" +
-      "  模板定义   执行实例   单步结果   agent内部交互",
+      "  workflow → thread → step → turn",
   )
   .version(pkg.default.version, "-V, --version");
 program.option("--format <fmt>", "Output format: json or yaml", "json");
@@ -176,11 +187,11 @@ function parseStatusFilter(status: string | undefined): ThreadStatus[] | null {
   if (raw === "active") return ["idle", "running"];
 
   const parts = raw.split(",").map((s) => s.trim());
-  const validStatuses: ThreadStatus[] = ["idle", "running", "completed"];
+  const validStatuses: ThreadStatus[] = ["idle", "running", "completed", "cancelled"];
   for (const part of parts) {
     if (!validStatuses.includes(part as ThreadStatus)) {
       process.stderr.write(
-        `Invalid status: ${part}. Must be one of: idle, running, completed, active\n`,
+        `Invalid status: ${part}. Must be one of: idle, running, completed, cancelled, active\n`,
       );
       process.exit(1);
     }
@@ -233,7 +244,7 @@ thread
   .description("List threads")
   .option(
     "--status <status>",
-    "Filter by status: idle, running, completed, active (idle+running), or comma-separated values",
+    "Filter by status: idle, running, completed, cancelled, active (idle+running), or comma-separated values",
   )
   .option("--after <date>", "Filter threads created after this date (ISO or relative like '7d')")
   .option("--before <date>", "Filter threads created before this date (ISO or relative like '7d')")
@@ -474,6 +485,7 @@ For more information, see: uwf help thread list
   });
 
 const skill = program.command("skill").description("Built-in skill references for agents");
+skill.addHelpCommand(false);
 
 skill
   .command("cli")
@@ -482,6 +494,69 @@ skill
     console.log(cmdSkillCli());
   });
 
+skill
+  .command("architecture")
+  .description("Print the architecture reference")
+  .action(() => {
+    console.log(cmdSkillArchitecture());
+  });
+
+skill
+  .command("yaml")
+  .description("Print the workflow YAML schema reference")
+  .action(() => {
+    console.log(cmdSkillYaml());
+  });
+
+skill
+  .command("actor")
+  .description("Print the actor reference (frontmatter protocol + CAS)")
+  .action(() => {
+    console.log(cmdSkillActor());
+  });
+
+skill
+  .command("adapter")
+  .description("Print the adapter reference (building agent adapters)")
+  .action(() => {
+    console.log(cmdSkillAdapter());
+  });
+
+skill
+  .command("author")
+  .description("Print the author reference (workflow YAML design guide)")
+  .action(() => {
+    console.log(cmdSkillAuthor());
+  });
+
+skill
+  .command("developer")
+  .description("Print the developer reference (coding conventions + architecture)")
+  .action(() => {
+    console.log(cmdSkillDeveloper());
+  });
+
+skill
+  .command("moderator")
+  .description("Print the moderator reference")
+  .action(() => {
+    console.log(cmdSkillModerator());
+  });
+
+skill
+  .command("user")
+  .description("Print the user reference (CLI guide + typical workflows)")
+  .action(() => {
+    console.log(cmdSkillUser());
+  });
+
+skill
+  .command("list")
+  .description("List all available skill names")
+  .action(() => {
+    console.log(cmdSkillList().join("\n"));
+  });
+
 program
   .command("setup")
   .description("Configure provider, model, and agent")
@@ -677,6 +752,47 @@ log
     });
   });
 
+const config = program.command("config").description("Configuration management");
+
+config
+  .command("list")
+  .description("Display all configuration values (masks API keys)")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdConfigList(storageRoot);
+      writeOutput(result);
+    });
+  });
+
+config
+  .command("get")
+  .description("Get a specific configuration value")
+  .argument(
+    "<key>",
+    "Dot-notation path to config value (e.g., defaultAgent, providers.dashscope.baseUrl)",
+  )
+  .action((key: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdConfigGet(storageRoot, key);
+      writeOutput({ value: result });
+    });
+  });
+
+config
+  .command("set")
+  .description("Set a specific configuration value")
+  .argument("<key>", "Dot-notation path to config value")
+  .argument("<value>", "New value (use JSON array for 'args' key, e.g., '[\"--flag\"]')")
+  .action((key: string, value: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdConfigSet(storageRoot, key, value);
+      writeOutput(result);
+    });
+  });
+
 program.parseAsync(process.argv).catch((e: unknown) => {
   const message = e instanceof Error ? e.message : String(e);
   process.stderr.write(`${message}\n`);

packages/cli-workflow/src/commands/config.ts

@@ -0,0 +1,289 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+
+/**
+ * Valid configuration key schema
+ */
+const VALID_CONFIG_KEYS: Record<string, { nested: boolean; knownFields?: string[] }> = {
+  providers: {
+    nested: true,
+    knownFields: ["baseUrl", "apiKey"],
+  },
+  models: {
+    nested: true,
+    knownFields: ["provider", "name"],
+  },
+  agents: {
+    nested: true,
+    knownFields: ["command", "args"],
+  },
+  defaultAgent: { nested: false },
+  defaultModel: { nested: false },
+};
+
+/**
+ * Validate a config key path against the known schema
+ */
+function validateConfigKey(path: string[]): void {
+  if (path.length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+
+  const topLevel = path[0];
+  const schema = VALID_CONFIG_KEYS[topLevel];
+
+  if (!schema) {
+    const validKeys = Object.keys(VALID_CONFIG_KEYS).join(", ");
+    throw new Error(`Unknown config key: ${topLevel}. Valid top-level keys are: ${validKeys}`);
+  }
+
+  // Scalar keys cannot have nested paths
+  if (!schema.nested && path.length > 1) {
+    throw new Error(`${topLevel} is a scalar key and cannot have nested properties`);
+  }
+
+  // Nested keys must have at least 3 segments (e.g., providers.myProvider.baseUrl)
+  if (schema.nested && path.length < 3) {
+    const fields = schema.knownFields?.join(", ") ?? "";
+    throw new Error(
+      `Incomplete path for ${topLevel}. Must specify a field (e.g., ${topLevel}.<name>.<field>). Valid fields: ${fields}`,
+    );
+  }
+
+  // Validate the field name for nested keys
+  if (schema.nested && path.length >= 3 && schema.knownFields) {
+    const field = path[path.length - 1];
+    if (!schema.knownFields.includes(field)) {
+      throw new Error(
+        `Unknown field '${field}' in ${topLevel}. Valid fields are: ${schema.knownFields.join(", ")}`,
+      );
+    }
+  }
+}
+
+/**
+ * Returns the path to the config.yaml file
+ */
+export function getConfigPath(storageRoot: string): string {
+  return join(storageRoot, "config.yaml");
+}
+
+/**
+ * Load and parse YAML config file
+ */
+export function loadConfig(configPath: string): Record<string, unknown> {
+  if (!existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+  const content = readFileSync(configPath, "utf8");
+  if (!content.trim()) {
+    return {};
+  }
+  try {
+    const parsed = parse(content);
+    return (parsed ?? {}) as Record<string, unknown>;
+  } catch (error) {
+    throw new Error(
+      `Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * Save config as YAML
+ */
+export function saveConfig(configPath: string, config: Record<string, unknown>): void {
+  const dir = join(configPath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const yaml = stringify(config);
+  writeFileSync(configPath, yaml, "utf8");
+}
+
+/**
+ * Parse dot-notation key into path segments
+ */
+export function parseDotPath(key: string): string[] {
+  return key.split(".");
+}
+
+/**
+ * Get nested value from object using path array
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string[]): unknown {
+  let current: unknown = obj;
+  for (const segment of path) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/**
+ * Set nested value in object using path array (mutates obj)
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  if (path.length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+
+  let current: Record<string, unknown> = obj;
+
+  // Navigate/create to the parent of the target
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    const next = current[segment];
+
+    if (next === null || next === undefined) {
+      // Create intermediate object
+      const newObj: Record<string, unknown> = {};
+      current[segment] = newObj;
+      current = newObj;
+    } else if (typeof next === "object" && !Array.isArray(next)) {
+      // Navigate into existing object
+      current = next as Record<string, unknown>;
+    } else {
+      // Cannot navigate into non-object
+      throw new Error(
+        `Cannot set property '${path[i + 1]}' on non-object at path '${path.slice(0, i + 1).join(".")}'`,
+      );
+    }
+  }
+
+  // Set the final value
+  const lastSegment = path[path.length - 1];
+  current[lastSegment] = value;
+}
+
+/**
+ * Deep clone and mask all apiKey values in providers section
+ */
+export function maskApiKeys(config: Record<string, unknown>): Record<string, unknown> {
+  // Deep clone
+  const cloned = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
+
+  // Mask apiKey values in providers
+  if (cloned.providers && typeof cloned.providers === "object") {
+    const providers = cloned.providers as Record<string, unknown>;
+    for (const providerName of Object.keys(providers)) {
+      const provider = providers[providerName];
+      if (provider && typeof provider === "object") {
+        const providerObj = provider as Record<string, unknown>;
+        if ("apiKey" in providerObj) {
+          providerObj.apiKey = "***MASKED***";
+        }
+      }
+    }
+  }
+
+  return cloned;
+}
+
+/**
+ * List all configuration values (masks API keys)
+ */
+export async function cmdConfigList(storageRoot: string): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+  const config = loadConfig(configPath);
+  const masked = maskApiKeys(config);
+  return masked;
+}
+
+/**
+ * Get a specific configuration value
+ */
+export async function cmdConfigGet(storageRoot: string, key: string): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+  const config = loadConfig(configPath);
+  const path = parseDotPath(key);
+  const value = getNestedValue(config, path);
+
+  if (value === undefined) {
+    throw new Error(`Key not found: ${key}`);
+  }
+
+  return value;
+}
+
+/**
+ * Parse value for args key (must be JSON array)
+ */
+function parseArgsValue(value: string): unknown {
+  if (value.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) {
+        throw new Error("Value must be an array");
+      }
+      return parsed;
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON array for args key: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  throw new Error("Value for 'args' key must be a JSON array starting with '['");
+}
+
+/**
+ * Validate that we're not setting a property on a non-object
+ */
+function validateParentPath(
+  config: Record<string, unknown>,
+  path: string[],
+  lastSegment: string,
+): void {
+  if (path.length > 1) {
+    const parentPath = path.slice(0, -1);
+    const parent = getNestedValue(config, parentPath);
+    if (parent !== null && parent !== undefined && typeof parent !== "object") {
+      throw new Error(
+        `Cannot set property '${lastSegment}' on non-object at path '${parentPath.join(".")}'`,
+      );
+    }
+  }
+}
+
+/**
+ * Set a specific configuration value
+ */
+export async function cmdConfigSet(
+  storageRoot: string,
+  key: string,
+  value: string,
+): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+
+  // Load existing config or create empty one
+  let config: Record<string, unknown>;
+  if (existsSync(configPath)) {
+    config = loadConfig(configPath);
+  } else {
+    config = {};
+  }
+
+  const path = parseDotPath(key);
+
+  // Validate the key path
+  validateConfigKey(path);
+
+  const lastSegment = path[path.length - 1];
+
+  // Parse value if it's for an array key (args)
+  let parsedValue: unknown = value;
+  if (lastSegment === "args") {
+    parsedValue = parseArgsValue(value);
+  }
+
+  // Validate we're not setting a property on a non-object
+  validateParentPath(config, path, lastSegment);
+
+  setNestedValue(config, path, parsedValue);
+  saveConfig(configPath, config);
+
+  return { key, value: parsedValue };
+}

packages/cli-workflow/src/commands/setup.ts

@@ -85,10 +85,6 @@ function getConfigPath(root: string): string {
   return join(root, "config.yaml");
 }
 
-function getEnvPath(root: string): string {
-  return join(root, ".env");
-}
-
 /**
  * Load existing config.yaml or return empty structure.
  */
@@ -106,37 +102,6 @@ function loadExistingConfig(configPath: string): Record<string, unknown> {
   return {};
 }
 
-/**
- * Load existing .env as key=value map.
- */
-function loadEnvFile(envPath: string): Record<string, string> {
-  const env: Record<string, string> = {};
-  try {
-    if (existsSync(envPath)) {
-      for (const line of readFileSync(envPath, "utf8").split("\n")) {
-        const trimmed = line.trim();
-        if (trimmed === "" || trimmed.startsWith("#")) continue;
-        const eq = trimmed.indexOf("=");
-        if (eq > 0) {
-          env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-        }
-      }
-    }
-  } catch {
-    // ignore
-  }
-  return env;
-}
-
-function saveEnvFile(envPath: string, env: Record<string, string>): void {
-  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
-  writeFileSync(envPath, `${lines.join("\n")}\n`, "utf8");
-}
-
-function apiKeyEnvName(providerName: string): string {
-  return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
-}
-
 // ──────────────────────────────────────────────────────────────────────────────
 // Extracted helpers — _discoverAgents
 // ──────────────────────────────────────────────────────────────────────────────
@@ -297,6 +262,80 @@ export function _printModelMenu(models: string[], termCols: number): void {
   }
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Agent selection prompt
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Known agent binary → display label mapping. */
+const KNOWN_AGENTS: Record<string, string> = {
+  "uwf-hermes": "Hermes (hermes-agent)",
+  "uwf-claude-code": "Claude Code",
+  "uwf-cursor": "Cursor",
+  "uwf-builtin": "Built-in (lightweight, no external agent)",
+};
+
+/** Extract short agent name from binary name: uwf-claude-code → claude-code */
+export function _agentNameFromBinary(binary: string): string {
+  return binary.replace(/^uwf-/, "");
+}
+
+/** Prints numbered agent list to stdout. */
+export function _printAgentMenu(agents: string[]): void {
+  const numWidth = String(agents.length).length;
+  for (let i = 0; i < agents.length; i++) {
+    const bin = agents[i] ?? "";
+    const label = KNOWN_AGENTS[bin] ?? bin;
+    const num = String(i + 1).padStart(numWidth);
+    console.log(`  ${num}) ${label}  (${bin})`);
+  }
+  console.log("");
+}
+
+/**
+ * Interactive agent selection. Discovers uwf-* binaries, lets user pick default.
+ * Returns short agent name (e.g. "hermes", "claude-code").
+ */
+export async function _promptAgentSelection(
+  rl: ReturnType<typeof createInterface>,
+): Promise<string> {
+  console.log("Discovering installed agents...\n");
+  const agents = await _discoverAgents();
+
+  if (agents.length === 0) {
+    console.log("  No uwf-* agent binaries found in PATH.\n");
+    console.log("  Install one first, for example:");
+    console.log("    npm i -g @uncaged/workflow-agent-hermes");
+    console.log("    npm i -g @uncaged/workflow-agent-claude-code\n");
+    const manual = (
+      await rl.question("Agent binary name (e.g. uwf-hermes), or press Enter to skip: ")
+    ).trim();
+    if (!manual) return "hermes";
+    return _agentNameFromBinary(manual.startsWith("uwf-") ? manual : `uwf-${manual}`);
+  }
+
+  if (agents.length === 1) {
+    const name = _agentNameFromBinary(agents[0] ?? "uwf-hermes");
+    const label = KNOWN_AGENTS[agents[0] ?? ""] ?? agents[0];
+    console.log(`  Found 1 agent: ${label} — auto-selected.\n`);
+    return name;
+  }
+
+  console.log(`  Found ${agents.length} agents:\n`);
+  _printAgentMenu(agents);
+  const choice = (await rl.question(`Choose default agent [1-${agents.length}]: `)).trim();
+  const n = Number.parseInt(choice, 10);
+  if (!Number.isNaN(n) && n >= 1 && n <= agents.length) {
+    const selected = agents[n - 1] ?? "uwf-hermes";
+    const name = _agentNameFromBinary(selected);
+    console.log(`  → ${name}\n`);
+    return name;
+  }
+  // Treat as literal name
+  const name = _agentNameFromBinary(choice.startsWith("uwf-") ? choice : `uwf-${choice}`);
+  console.log(`  → ${name}\n`);
+  return name;
+}
+
 type ValidationResult = { ok: boolean; error: string | null };
 
 /** Prints the model validation result to stdout. */
@@ -323,8 +362,7 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
       : {}
   ) as Record<string, unknown>;
 
-  const envName = apiKeyEnvName(args.provider);
-  providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
+  providers[args.provider] = { baseUrl: args.baseUrl, apiKey: args.apiKey };
 
   const models = (
     typeof existing.models === "object" && existing.models !== null
@@ -339,9 +377,10 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
       : {}
   ) as Record<string, unknown>;
 
-  const agentName = args.agent ?? "hermes";
-  if (Object.keys(agents).length === 0) {
-    agents.hermes = { command: "uwf-hermes", args: [] };
+  const agentName = _agentNameFromBinary(args.agent ?? "hermes");
+  // Ensure the selected agent has an entry
+  if (!agents[agentName]) {
+    agents[agentName] = { command: `uwf-${agentName}`, args: [] };
   }
 
   return {
@@ -349,7 +388,7 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
     providers,
     models,
     agents,
-    defaultAgent: existing.defaultAgent ?? agentName,
+    defaultAgent: agentName,
     defaultModel: existing.defaultModel ?? "default",
   };
 }
@@ -362,25 +401,17 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
   mkdirSync(storageRoot, { recursive: true });
 
   const configPath = getConfigPath(storageRoot);
-  const envPath = getEnvPath(storageRoot);
 
   const existing = loadExistingConfig(configPath);
   const merged = mergeConfig(existing, args);
 
   writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");
 
-  // Write API key to .env
-  const envName = apiKeyEnvName(args.provider);
-  const envData = loadEnvFile(envPath);
-  envData[envName] = args.apiKey;
-  saveEnvFile(envPath, envData);
-
   // Validate model connectivity
   const validation = await validateModel(args.baseUrl, args.apiKey, args.model);
 
   return {
     configPath,
-    envPath,
     provider: args.provider,
     model: args.model,
     defaultAgent: merged.defaultAgent,
@@ -543,11 +574,17 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
     rl2.close();
     console.log(`  → ${providerName}/${model}\n`);
 
+    // 4. Agent discovery & selection
+    const rl3 = createInterface({ input, output });
+    const agentName = await _promptAgentSelection(rl3);
+    rl3.close();
+
     const setupResult = await cmdSetup({
       provider: providerName,
       baseUrl,
       apiKey,
       model,
+      agent: agentName,
       storageRoot,
     });
 

packages/cli-workflow/src/commands/skill.ts

@@ -1 +1,27 @@
-export { generateCliReference as cmdSkillCli } from "@uncaged/workflow-util";
+export {
+  generateActorReference as cmdSkillActor,
+  generateAdapterReference as cmdSkillAdapter,
+  generateArchitectureReference as cmdSkillArchitecture,
+  generateAuthorReference as cmdSkillAuthor,
+  generateCliReference as cmdSkillCli,
+  generateDeveloperReference as cmdSkillDeveloper,
+  generateModeratorReference as cmdSkillModerator,
+  generateUserReference as cmdSkillUser,
+  generateYamlReference as cmdSkillYaml,
+} from "@uncaged/workflow-util";
+
+const SKILL_NAMES = [
+  "cli",
+  "architecture",
+  "yaml",
+  "moderator",
+  "actor",
+  "user",
+  "author",
+  "developer",
+  "adapter",
+] as const;
+
+export function cmdSkillList(): ReadonlyArray<string> {
+  return [...SKILL_NAMES];
+}

packages/cli-workflow/src/commands/step.ts

@@ -19,9 +19,16 @@ import {
   walkChain,
 } from "./shared.js";
 
+type TurnToolCall = {
+  name: string;
+  args: string;
+};
+
 type TurnData = {
   index: number;
+  role: string;
   content: string;
+  toolCalls: TurnToolCall[] | null;
 };
 
 /**
@@ -128,8 +135,74 @@ function loadStepDetail(store: BootstrapCapableStore, detailRef: CasRef): Record
   return detailNode.payload as Record<string, unknown>;
 }
 
+function parseTurnToolCalls(raw: unknown): TurnToolCall[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const calls: TurnToolCall[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
+    }
+    const record = entry as Record<string, unknown>;
+    const name = record.name;
+    const args = record.args;
+    if (typeof name === "string") {
+      calls.push({ name, args: typeof args === "string" ? args : "" });
+    }
+  }
+  return calls.length > 0 ? calls : null;
+}
+
+function formatTurnBody(turn: TurnData): string {
+  const parts: string[] = [];
+  parts.push(`**Turn role:** ${turn.role}`);
+
+  if (turn.toolCalls !== null) {
+    for (const call of turn.toolCalls) {
+      const argsSuffix = call.args !== "" ? ` — \`${call.args}\`` : "";
+      parts.push(`- **${call.name}**${argsSuffix}`);
+    }
+  }
+
+  if (turn.content !== "") {
+    if (parts.length > 0) {
+      parts.push("");
+    }
+    parts.push(turn.content);
+  }
+
+  return parts.join("\n");
+}
+
+function parseSingleTurn(
+  store: BootstrapCapableStore,
+  turnRef: unknown,
+  fallbackIndex: number,
+): TurnData | null {
+  if (typeof turnRef !== "string") {
+    return null;
+  }
+  const turnNode = store.get(turnRef as CasRef);
+  if (turnNode === null) {
+    return null;
+  }
+  const turn = turnNode.payload as Record<string, unknown>;
+  const content = typeof turn.content === "string" ? turn.content : "";
+  const toolCalls = parseTurnToolCalls(turn.toolCalls);
+  if (content === "" && toolCalls === null) {
+    return null;
+  }
+  return {
+    index: typeof turn.index === "number" ? turn.index : fallbackIndex,
+    role: typeof turn.role === "string" ? turn.role : "assistant",
+    content,
+    toolCalls,
+  };
+}
+
 /**
- * Load all turn nodes from CAS store and extract content
+ * Load all turn nodes from CAS store and extract display fields
  */
 function loadTurnData(store: BootstrapCapableStore, turns: unknown): TurnData[] {
   if (!Array.isArray(turns) || turns.length === 0) {
@@ -138,19 +211,9 @@ function loadTurnData(store: BootstrapCapableStore, turns: unknown): TurnData[]
 
   const turnData: TurnData[] = [];
   for (const turnRef of turns) {
-    if (typeof turnRef !== "string") {
-      continue;
-    }
-    const turnNode = store.get(turnRef as CasRef);
-    if (turnNode === null) {
-      continue;
-    }
-    const turn = turnNode.payload as Record<string, unknown>;
-    if (typeof turn.content === "string") {
-      turnData.push({
-        index: typeof turn.index === "number" ? turn.index : turnData.length,
-        content: turn.content,
-      });
+    const parsed = parseSingleTurn(store, turnRef, turnData.length);
+    if (parsed !== null) {
+      turnData.push(parsed);
     }
   }
   return turnData;
@@ -168,7 +231,7 @@ function selectTurnsForQuota(turnData: TurnData[], availableQuota: number): Turn
     if (turn === undefined) continue;
 
     const turnHeader = `## Turn ${turn.index + 1}\n\n`;
-    const turnBlock = turnHeader + turn.content;
+    const turnBlock = turnHeader + formatTurnBody(turn);
     const separatorCost = selectedTurns.length > 0 ? 2 : 0;
     const addCost = turnBlock.length + separatorCost;
 
@@ -213,7 +276,7 @@ function formatStepMarkdown(
     parts.push("");
     parts.push(`## Turn ${turn.index + 1}`);
     parts.push("");
-    parts.push(turn.content);
+    parts.push(formatTurnBody(turn));
   }
 
   return parts.join("\n");

packages/cli-workflow/src/commands/thread.ts

@@ -2,8 +2,6 @@ import { execFileSync, spawn } from "node:child_process";
 import { access, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
 import { validate } from "@uncaged/json-cas";
-import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
-import { evaluate } from "@uncaged/workflow-moderator";
 import type {
   AgentAlias,
   AgentConfig,
@@ -24,9 +22,11 @@ import {
   generateUlid,
   type ProcessLogger,
 } from "@uncaged/workflow-util";
+import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-util-agent";
 import { config as loadDotenv } from "dotenv";
 import { parse } from "yaml";
 import { createMarker, deleteMarker, isThreadRunning } from "../background/index.js";
+import { evaluate } from "../moderator/index.js";
 import {
   appendThreadHistory,
   createUwfStore,
@@ -331,7 +331,7 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
   fail(`thread not found: ${threadId}`);
 }
 
-export type ThreadStatus = "idle" | "running" | "completed";
+export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
 
 export type ThreadListItemWithStatus = ThreadListItem & {
   status: ThreadStatus;
@@ -389,7 +389,7 @@ async function collectCompletedThreads(
         thread: entry.thread,
         workflow: entry.workflow,
         head: entry.head,
-        status: "completed",
+        status: entry.reason === "cancelled" ? "cancelled" : "completed",
       });
     }
   }
@@ -444,7 +444,10 @@ export async function cmdThreadList(
   let items = await collectActiveThreads(storageRoot, uwf, index);
 
   // Collect completed threads (if relevant for status filter)
-  const includeCompleted = statusFilter === null || statusFilter.includes("completed");
+  const includeCompleted =
+    statusFilter === null ||
+    statusFilter.includes("completed") ||
+    statusFilter.includes("cancelled");
   if (includeCompleted) {
     const activeIds = new Set(items.map((i) => i.thread));
     const completedItems = await collectCompletedThreads(storageRoot, activeIds);
@@ -811,6 +814,7 @@ async function archiveThread(
     workflow,
     head,
     completedAt: Date.now(),
+    reason: "completed",
   });
 }
 
@@ -1147,6 +1151,7 @@ export async function cmdThreadCancel(
     workflow,
     head,
     completedAt: Date.now(),
+    reason: "cancelled",
   };
   await appendThreadHistory(storageRoot, historyEntry);
 

packages/cli-workflow/src/moderator/evaluate.ts

@@ -0,0 +1,53 @@
+import type { Target } from "@uncaged/workflow-protocol";
+import mustache from "mustache";
+
+import type { EvaluateResult, Result } from "./types.js";
+
+// Disable HTML escaping — prompts are plain text, not HTML.
+mustache.escape = (text: string) => text;
+
+const START_ROLE = "$START";
+const UNIT_STATUS = "_";
+
+type LastOutput = Record<string, unknown>;
+
+const STATUS_KEY = "$status";
+
+export function evaluate(
+  graph: Record<string, Record<string, Target>>,
+  lastRole: string,
+  lastOutput: LastOutput,
+): Result<EvaluateResult, Error> {
+  const status =
+    lastRole === START_ROLE
+      ? UNIT_STATUS
+      : typeof lastOutput[STATUS_KEY] === "string"
+        ? (lastOutput[STATUS_KEY] as string)
+        : UNIT_STATUS;
+
+  const roleTargets = graph[lastRole];
+  if (roleTargets === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transitions defined for role "${lastRole}"`),
+    };
+  }
+
+  const target = roleTargets[status];
+  if (target === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transition for role "${lastRole}" with status "${status}"`),
+    };
+  }
+
+  try {
+    const prompt = mustache.render(target.prompt, lastOutput);
+    return { ok: true, value: { role: target.role, prompt } };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}

packages/cli-workflow/src/moderator/index.ts

@@ -0,0 +1,2 @@
+export { evaluate } from "./evaluate.js";
+export type { EvaluateResult } from "./types.js";

packages/cli-workflow/src/moderator/types.ts

@@ -0,0 +1,7 @@
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+/** The result of moderator evaluation — which role to go to, and the edge prompt. */
+export type EvaluateResult = {
+  role: string;
+  prompt: string;
+};

packages/cli-workflow/src/store.ts

@@ -88,6 +88,7 @@ export function getHistoryPath(storageRoot: string): string {
 
 export type ThreadHistoryLine = ThreadListItem & {
   completedAt: number;
+  reason: "completed" | "cancelled" | null;
 };
 
 export type UwfStore = {
@@ -228,7 +229,15 @@ export async function loadThreadHistory(storageRoot: string): Promise<ThreadHist
         typeof head === "string" &&
         typeof completedAt === "number"
       ) {
-        lines.push({ thread: thread as ThreadId, workflow, head, completedAt });
+        const reason = rec.reason;
+        const parsedReason = reason === "completed" || reason === "cancelled" ? reason : null;
+        lines.push({
+          thread: thread as ThreadId,
+          workflow,
+          head,
+          completedAt,
+          reason: parsedReason,
+        });
       }
     }
     return lines;

packages/cli-workflow/src/validate-semantic.ts

@@ -23,6 +23,28 @@ function isOneOfSchema(fm: unknown): fm is SchemaObj & { oneOf: SchemaObj[] } {
   return Array.isArray(obj.oneOf);
 }
 
+/** Check if a frontmatter schema uses enum-based multi-exit ($status with multiple enum values). */
+function isEnumMultiExit(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;
+  const statusDef = props.$status;
+  if (!Array.isArray(statusDef.enum)) return false;
+  // Filter out "_" (wildcard) — if remaining values > 1, it's multi-exit
+  const statuses = (statusDef.enum as string[]).filter((s) => s !== "_");
+  return statuses.length > 1;
+}
+
+/** 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 (!Array.isArray(statusDef.enum)) return [];
+  return (statusDef.enum as string[]).filter((s) => s !== "_");
+}
+
 /** Get property names from a schema object. */
 function getPropertyNames(schema: SchemaObj): Set<string> {
   const props = schema.properties;
@@ -230,6 +252,11 @@ function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void
       checkOneOfDiscriminant(roleName, variants, statuses, errors);
       checkMultiExitEdges(roleName, graphKeys, new Set(statuses), errors);
       checkMultiExitMustache(roleName, graphEntry, variants, errors);
+    } else if (isEnumMultiExit(fm)) {
+      const statuses = getEnumStatuses(fm as SchemaObj);
+      checkMultiExitEdges(roleName, graphKeys, new Set(statuses), errors);
+      // For enum-based schemas, mustache vars come from the flat properties
+      checkSingleExitMustache(roleName, graphEntry, fm as SchemaObj, errors);
     } else {
       checkSingleExitRole(roleName, graphKeys, graphEntry, fm as SchemaObj | null, errors);
     }
@@ -265,6 +292,27 @@ function checkSingleExitRole(
   }
 }
 
+/** Check mustache vars in all edge prompts against flat schema properties. */
+function checkSingleExitMustache(
+  roleName: string,
+  graphEntry: Record<string, { role: string; prompt: string }>,
+  fm: SchemaObj,
+  errors: string[],
+): void {
+  const propNames = getPropertyNames(fm);
+  for (const [status, target] of Object.entries(graphEntry)) {
+    const vars = extractMustacheVars(target.prompt);
+    for (const v of vars) {
+      if (v === "$status") continue;
+      if (!propNames.has(v)) {
+        errors.push(
+          `prompt variable "${v}" in graph[${roleName}][${status}] not found in role "${roleName}" frontmatter`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Validate a parsed WorkflowPayload for semantic correctness.
  * Returns an array of error messages. Empty array = valid.

packages/cli-workflow/tsconfig.json

@@ -5,9 +5,5 @@
     "outDir": "dist"
   },
   "include": ["src"],
-  "references": [
-    { "path": "../workflow-protocol" },
-    { "path": "../workflow-moderator" },
-    { "path": "../workflow-agent-kit" }
-  ]
+  "references": [{ "path": "../workflow-protocol" }, { "path": "../workflow-util-agent" }]
 }

packages/workflow-agent-builtin/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @uncaged/workflow-agent-builtin
+
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util@0.5.1
+  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-builtin/README.md

@@ -8,7 +8,7 @@ Layer 3 agent implementation. Runs an OpenAI-compatible chat completion loop wit
 
 Useful when you want a self-contained agent without an external CLI like Hermes or Claude Code.
 
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-util`
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-util`
 
 ## Installation
 

packages/workflow-agent-builtin/__tests__/prompt.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import type { AgentContext } from "@uncaged/workflow-agent-kit";
+import type { AgentContext } from "@uncaged/workflow-util-agent";
 
 import { buildBuiltinMessages } from "../src/prompt.js";
 

packages/workflow-agent-builtin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-builtin",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -22,8 +22,8 @@
     "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {

packages/workflow-agent-builtin/src/agent.ts

@@ -1,4 +1,5 @@
 import type { Store } from "@uncaged/json-cas";
+import { createLogger, generateUlid } from "@uncaged/workflow-util";
 import {
   type AgentContext,
   type AgentRunResult,
@@ -6,8 +7,7 @@ import {
   loadWorkflowConfig,
   resolveModel,
   resolveStorageRoot,
-} from "@uncaged/workflow-agent-kit";
-import { createLogger, generateUlid } from "@uncaged/workflow-util";
+} from "@uncaged/workflow-util-agent";
 
 import { storeBuiltinDetail } from "./detail.js";
 import type { ChatMessage } from "./llm/index.js";

packages/workflow-agent-builtin/src/llm/llm.ts

@@ -1,4 +1,4 @@
-import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
+import type { ResolvedLlmProvider } from "@uncaged/workflow-util-agent";
 
 import type {
   ChatMessage,

packages/workflow-agent-builtin/src/loop.ts

@@ -1,5 +1,5 @@
-import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
 import { createLogger } from "@uncaged/workflow-util";
+import type { ResolvedLlmProvider } from "@uncaged/workflow-util-agent";
 
 import {
   type ChatMessage,

packages/workflow-agent-builtin/src/prompt.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, buildRolePrompt } from "@uncaged/workflow-agent-kit";
+import { type AgentContext, buildRolePrompt } from "@uncaged/workflow-util-agent";
 
 import type { ChatMessage } from "./llm/index.js";
 

packages/workflow-agent-builtin/tsconfig.json

@@ -5,5 +5,5 @@
     "outDir": "dist"
   },
   "include": ["src"],
-  "references": [{ "path": "../workflow-agent-kit" }, { "path": "../workflow-util" }]
+  "references": [{ "path": "../workflow-util-agent" }, { "path": "../workflow-util" }]
 }

packages/workflow-agent-claude-code/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @uncaged/workflow-agent-claude-code
+
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util@0.5.1
+  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-claude-code/README.md

@@ -6,7 +6,7 @@
 
 Layer 3 agent implementation. Spawns the `claude` CLI with a composed system prompt (role definition, task, prior steps, edge prompt). Parses stream or JSON stdout, caches session IDs for multi-turn continuation, and stores raw output plus structured detail in CAS.
 
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`
 
 ## Installation
 
@@ -86,6 +86,6 @@ src/
 
 ## Configuration
 
-Uses session caching from `@uncaged/workflow-agent-kit` (`getCachedSessionId` / `setCachedSessionId`). No separate config file — relies on the Claude Code CLI's own authentication.
+Uses session caching from `@uncaged/workflow-util-agent` (`getCachedSessionId` / `setCachedSessionId`). No separate config file — relies on the Claude Code CLI's own authentication.
 
 Maximum turns per invocation: 90 (constant in `claude-code.ts`).

packages/workflow-agent-claude-code/__tests__/claude-code.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import type { AgentContext } from "@uncaged/workflow-agent-kit";
 import type { ThreadId } from "@uncaged/workflow-protocol";
+import type { AgentContext } from "@uncaged/workflow-util-agent";
 import { buildClaudeCodePrompt } from "../src/claude-code.js";
 
 function makeCtx(overrides: Partial<AgentContext> = {}): AgentContext {

packages/workflow-agent-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-claude-code",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -22,8 +22,8 @@
     "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {

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

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import type { Store } from "@uncaged/json-cas";
+import { createLogger } from "@uncaged/workflow-util";
 import {
   type AgentContext,
   type AgentRunResult,
@@ -8,8 +9,7 @@ import {
   createAgent,
   getCachedSessionId,
   setCachedSessionId,
-} from "@uncaged/workflow-agent-kit";
-import { createLogger } from "@uncaged/workflow-util";
+} from "@uncaged/workflow-util-agent";
 
 import { parseClaudeCodeStreamOutput, storeClaudeCodeDetail } from "./session-detail.js";
 

packages/workflow-agent-claude-code/tsconfig.json

@@ -2,5 +2,5 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": { "rootDir": "src", "outDir": "dist" },
   "include": ["src"],
-  "references": [{ "path": "../workflow-agent-kit" }]
+  "references": [{ "path": "../workflow-util-agent" }]
 }

packages/workflow-agent-hermes/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @uncaged/workflow-agent-hermes
+
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util@0.5.1
+  - @uncaged/workflow-protocol@0.5.1
+  - @uncaged/workflow-util-agent@0.5.1

packages/workflow-agent-hermes/README.md

@@ -6,7 +6,7 @@
 
 Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
 
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
 
 ## Installation
 
@@ -18,6 +18,15 @@ bun add -g @uncaged/workflow-agent-hermes
 
 Requires the `hermes` CLI on `PATH`.
 
+Hermes must write session JSON snapshots so `uwf-hermes` can load structured tool calls from disk. Add this to `~/.hermes/config.yaml`:
+
+```yaml
+sessions:
+  write_json_snapshots: true
+```
+
+Session files are stored at `~/.hermes/sessions/session_{sessionId}.json`.
+
 ## CLI Usage
 
 Invoked by `uwf thread step` (not typically run directly):

packages/workflow-agent-hermes/__tests__/acp-client.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 
 import { HermesAcpClient } from "../src/acp-client.js";
 
-describe("handleSessionUpdate — helper extraction", () => {
+describe("handleSessionUpdate — text extraction", () => {
   let client: HermesAcpClient;
 
   beforeEach(() => {
@@ -14,82 +14,41 @@ describe("handleSessionUpdate — helper extraction", () => {
   });
 
   it("agent_message_chunk accumulates text in messageChunks", () => {
-    (client as any).handleSessionUpdate({
+    (
+      client as unknown as { handleSessionUpdate: (u: Record<string, unknown>) => void }
+    ).handleSessionUpdate({
       sessionUpdate: "agent_message_chunk",
       content: { type: "text", text: "hello" },
     });
-    (client as any).handleSessionUpdate({
+    (
+      client as unknown as { handleSessionUpdate: (u: Record<string, unknown>) => void }
+    ).handleSessionUpdate({
       sessionUpdate: "agent_message_chunk",
       content: { type: "text", text: " world" },
     });
-    expect((client as any).messageChunks).toEqual(["hello", " world"]);
+    expect((client as unknown as { messageChunks: string[] }).messageChunks).toEqual([
+      "hello",
+      " world",
+    ]);
   });
 
-  it("agent_thought_chunk accumulates reasoning in reasoningChunks", () => {
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "agent_thought_chunk",
-      content: { type: "text", text: "thinking" },
+  it("non-text chunks and other update types are ignored", () => {
+    (
+      client as unknown as { handleSessionUpdate: (u: Record<string, unknown>) => void }
+    ).handleSessionUpdate({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "image", text: "ignored" },
     });
-    expect((client as any).reasoningChunks).toEqual(["thinking"]);
-  });
-
-  it("tool_call registers a pending tool and flushes message chunks", () => {
-    (client as any).messageChunks = ["pre-tool text"];
-    (client as any).handleSessionUpdate({
+    (
+      client as unknown as { handleSessionUpdate: (u: Record<string, unknown>) => void }
+    ).handleSessionUpdate({
       sessionUpdate: "tool_call",
       title: "Bash",
-      rawInput: { command: "ls" },
       toolCallId: "tc-1",
     });
-    expect((client as any).pendingTools.get("tc-1")).toEqual({
-      name: "Bash",
-      args: JSON.stringify({ command: "ls" }),
-    });
-    expect((client as any).messageChunks).toEqual([]);
-    expect((client as any).messages).toHaveLength(1);
-    expect((client as any).messages[0].role).toBe("assistant");
-  });
-
-  it("tool_call_update completed pushes tool_call and tool messages", () => {
-    (client as any).pendingTools.set("tc-2", { name: "Read", args: '{"path":"/foo"}' });
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "tool_call_update",
-      status: "completed",
-      toolCallId: "tc-2",
-      rawOutput: "file contents",
-    });
-    const msgs = (client as any).messages as Array<{
-      role: string;
-      tool_calls: unknown;
-      content: string | null;
-    }>;
-    expect(msgs).toHaveLength(2);
-    expect(msgs[0].role).toBe("assistant");
-    expect(msgs[0].tool_calls).toEqual([
-      { function: { name: "Read", arguments: '{"path":"/foo"}' } },
-    ]);
-    expect(msgs[1].role).toBe("tool");
-    expect(msgs[1].content).toBe("file contents");
-    expect((client as any).pendingTools.has("tc-2")).toBe(false);
-  });
-
-  it("tool_call_update with non-string rawOutput JSON-stringifies it", () => {
-    (client as any).pendingTools.set("tc-3", { name: "Fetch", args: "" });
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "tool_call_update",
-      status: "completed",
-      toolCallId: "tc-3",
-      rawOutput: { html: "<p>page</p>" },
-    });
-    const msgs = (client as any).messages as Array<{ role: string; content: string | null }>;
-    expect(msgs[1].content).toBe(JSON.stringify({ html: "<p>page</p>" }));
-  });
-
-  it("unknown updateType is a no-op", () => {
-    (client as any).handleSessionUpdate({ sessionUpdate: "unknown_type", data: {} });
-    expect((client as any).messages).toHaveLength(0);
-    expect((client as any).messageChunks).toHaveLength(0);
+    (
+      client as unknown as { handleSessionUpdate: (u: Record<string, unknown>) => void }
+    ).handleSessionUpdate({ sessionUpdate: "unknown_type", data: {} });
+    expect((client as unknown as { messageChunks: string[] }).messageChunks).toHaveLength(0);
   });
 });
-
-

packages/workflow-agent-hermes/__tests__/hermes-prompt.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import type { AgentContext } from "@uncaged/workflow-agent-kit";
 import type { ThreadId } from "@uncaged/workflow-protocol";
+import type { AgentContext } from "@uncaged/workflow-util-agent";
 import { buildHermesPrompt } from "../src/hermes.js";
 
 function makeCtx(overrides: Partial<AgentContext> = {}): AgentContext {

packages/workflow-agent-hermes/__tests__/integration/acp-client.integration.test.ts

@@ -53,23 +53,4 @@ describe("HermesAcpClient", () => {
     },
     { timeout: 2 * 60 * 1000 },
   );
-
-  // TODO(#435): flaky — depends on live LLM; mock or move to integration suite
-  it.skip(
-    "prompt() collects structured messages including tool calls",
-    async () => {
-      await client.connect(process.cwd());
-      const result = await client.prompt("Run this command: echo TOOL_DETAIL_TEST");
-      expect(result.messages.length).toBeGreaterThan(0);
-      const toolMessages = result.messages.filter((m) => m.role === "tool");
-      expect(toolMessages.length).toBeGreaterThan(0);
-      const toolContent = toolMessages[0]?.content ?? "";
-      expect(toolContent).toContain("TOOL_DETAIL_TEST");
-      const assistantWithTools = result.messages.filter(
-        (m) => m.role === "assistant" && m.tool_calls !== null,
-      );
-      expect(assistantWithTools.length).toBeGreaterThan(0);
-    },
-    { timeout: 2 * 60 * 1000 },
-  );
 });

packages/workflow-agent-hermes/__tests__/integration/resume-e2e.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
 
-import { HermesAcpClient } from "../src/acp-client.js";
+import { HermesAcpClient } from "../../src/acp-client.js";
 
 /**
  * E2E test for cross-process session resume.

packages/workflow-agent-hermes/__tests__/session-detail.test.ts

@@ -1,9 +1,15 @@
+import { Database } from "bun:sqlite";
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createMemoryStore, refs, validate, walk } from "@uncaged/json-cas";
 
 import {
   computeDurationMs,
   extractLastAssistantContent,
+  getHermesDbPath,
+  loadHermesSessionFromDb,
   messageToTurnPayload,
   parseSessionIdFromStdout,
   storeHermesSessionDetail,
@@ -124,3 +130,236 @@ describe("storeHermesSessionDetail", () => {
     }
   });
 });
+
+// ── SQLite fallback tests ──────────────────────────────────────────
+
+function createTestDb(dbPath: string): Database {
+  const db = new Database(dbPath);
+  db.run(`CREATE TABLE sessions (
+    id TEXT PRIMARY KEY,
+    model TEXT NOT NULL,
+    started_at INTEGER NOT NULL
+  )`);
+  db.run(`CREATE TABLE messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    content TEXT,
+    reasoning TEXT,
+    tool_calls TEXT,
+    FOREIGN KEY (session_id) REFERENCES sessions(id)
+  )`);
+  return db;
+}
+
+describe("getHermesDbPath", () => {
+  test("returns correct path", () => {
+    const { homedir } = require("node:os");
+    const { join } = require("node:path");
+    expect(getHermesDbPath()).toBe(join(homedir(), ".hermes", "state.db"));
+  });
+});
+
+describe("loadHermesSessionFromDb", () => {
+  test("returns session data from SQLite", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-session-001";
+    const startedAt = 1748099519;
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "claude-opus-4.6",
+      startedAt,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "hello", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "hi there", "thinking...", null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.session_id).toBe(sessionId);
+    expect(result!.model).toBe("claude-opus-4.6");
+    expect(result!.messages).toHaveLength(2);
+    expect(result!.messages[0]!.role).toBe("user");
+    expect(result!.messages[0]!.content).toBe("hello");
+    expect(result!.messages[1]!.role).toBe("assistant");
+    expect(result!.messages[1]!.content).toBe("hi there");
+    expect(result!.messages[1]!.reasoning).toBe("thinking...");
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("returns null when no session exists in DB", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+    db.close();
+
+    const result = await loadHermesSessionFromDb("nonexistent", dbPath);
+    expect(result).toBeNull();
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("returns null when DB file does not exist", async () => {
+    const result = await loadHermesSessionFromDb("any-id", "/tmp/nonexistent-hermes-db.db");
+    expect(result).toBeNull();
+  });
+
+  test("correctly parses tool_calls from DB JSON string", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-tool-calls";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "gpt-4",
+      1748099519,
+    ]);
+    const toolCallsJson = JSON.stringify([
+      { function: { name: "read_file", arguments: '{"path":"x"}' } },
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "", null, toolCallsJson],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.messages[0]!.tool_calls).toEqual([
+      { function: { name: "read_file", arguments: '{"path":"x"}' } },
+    ]);
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("handles null fields in DB messages gracefully", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-nulls";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", null, null, null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    const msg = result!.messages[0]!;
+    expect(msg.content).toBeNull();
+    expect(msg.reasoning).toBeNull();
+    expect(msg.tool_calls).toBeNull();
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("messages ordered by insertion order", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-order";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "first", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "second", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "third", null, null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.messages.map((m) => m.content)).toEqual(["first", "second", "third"]);
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("converts unix timestamp to ISO string for session_start", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-timestamp";
+    const startedAt = 1748099519;
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      startedAt,
+    ]);
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.session_start).toBe(new Date(startedAt * 1000).toISOString());
+
+    await rm(tmpDir, { recursive: true });
+  });
+});
+
+describe("loadHermesSession with SQLite fallback", () => {
+  test("JSON file takes priority over DB", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const jsonPath = join(tmpDir, "session.json");
+
+    // Create DB with one model value
+    const db = createTestDb(dbPath);
+    const sessionId = "test-priority";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "db-model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "from db", null, null],
+    );
+    db.close();
+
+    // Create JSON file with a different model value
+    const jsonData: HermesSessionJson = {
+      session_id: sessionId,
+      model: "json-model",
+      session_start: "2026-05-24T12:00:00.000Z",
+      messages: [{ role: "user", content: "from json", reasoning: null, tool_calls: null }],
+    };
+    await writeFile(jsonPath, JSON.stringify(jsonData));
+
+    // loadHermesSession reads from JSON path, so we test the existing function directly
+    // The JSON-first priority is inherent in the implementation
+    const { readFile } = await import("node:fs/promises");
+    const text = await readFile(jsonPath, "utf8");
+    const parsed = JSON.parse(text);
+    expect(parsed.model).toBe("json-model");
+
+    await rm(tmpDir, { recursive: true });
+  });
+});

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -19,11 +19,11 @@
   },
   "scripts": {
     "test": "bun test",
-"test:ci": "bun test __tests__/*.test.ts"
+    "test:ci": "bun test __tests__/*.test.ts"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-protocol": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },

packages/workflow-agent-hermes/src/acp-client.ts

@@ -2,8 +2,6 @@ import type { ChildProcess } from "node:child_process";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 
-import type { HermesSessionMessage } from "./types.js";
-
 const HERMES_COMMAND = "hermes";
 const PROTOCOL_VERSION = 1;
 
@@ -19,16 +17,9 @@ type PendingRequest = {
   reject: (reason: Error) => void;
 };
 
-/** Tracks in-flight tool calls so we can build complete messages when they finish. */
-type PendingToolCall = {
-  name: string;
-  args: string;
-};
-
 export type AcpPromptResult = {
   text: string;
   sessionId: string;
-  messages: HermesSessionMessage[];
 };
 
 export class HermesAcpClient {
@@ -38,11 +29,8 @@ export class HermesAcpClient {
   private stderrBuffer = "";
   private pending = new Map<number, PendingRequest>();
 
-  // Message collection state
+  /** Accumulated assistant text chunks from agent_message_chunk updates. */
   private messageChunks: string[] = [];
-  private reasoningChunks: string[] = [];
-  private pendingTools = new Map<string, PendingToolCall>();
-  messages: HermesSessionMessage[] = [];
 
   /** Spawn hermes acp, initialize, create session */
   async connect(cwd: string): Promise<string> {
@@ -84,14 +72,13 @@ export class HermesAcpClient {
     return sessionId;
   }
 
-  /** Send prompt and collect full response text + structured messages. */
+  /** Send prompt and collect final assistant text from ACP stream chunks. */
   async prompt(text: string): Promise<AcpPromptResult> {
     if (this.sessionId === null) {
       throw new Error("Not connected — call connect() first");
     }
 
     this.messageChunks = [];
-    this.reasoningChunks = [];
 
     const response = await this.sendRequest("session/prompt", {
       sessionId: this.sessionId,
@@ -104,28 +91,9 @@ export class HermesAcpClient {
       );
     }
 
-    // Flush any trailing assistant text that wasn't followed by a tool call.
-    this.flushAssistantMessage();
-
-    // Extract the final assistant text from collected messages.
-    let finalText = "";
-    for (let i = this.messages.length - 1; i >= 0; i--) {
-      const msg = this.messages[i];
-      if (
-        msg !== undefined &&
-        msg.role === "assistant" &&
-        msg.content !== null &&
-        msg.content.trim() !== ""
-      ) {
-        finalText = msg.content;
-        break;
-      }
-    }
-
     return {
-      text: finalText,
+      text: this.messageChunks.join(""),
       sessionId: this.sessionId,
-      messages: this.messages,
     };
   }
 
@@ -242,94 +210,16 @@ export class HermesAcpClient {
     }
   }
 
-  // ---- Session update → structured messages ----
-
   private handleSessionUpdate(update: Record<string, unknown>): void {
-    switch (update.sessionUpdate as string) {
-      case "agent_message_chunk":
-        this.handleAgentMessageChunk(update);
-        break;
-      case "agent_thought_chunk":
-        this.handleAgentThoughtChunk(update);
-        break;
-      case "tool_call":
-        this.handleToolCall(update);
-        break;
-      case "tool_call_update":
-        this.handleToolCallUpdate(update);
-        break;
-      default:
-        break;
+    if (update.sessionUpdate !== "agent_message_chunk") {
+      return;
     }
-  }
-
-  private handleAgentMessageChunk(update: Record<string, unknown>): void {
     const content = update.content as { type?: string; text?: string } | undefined;
     if (content?.type === "text" && typeof content.text === "string") {
       this.messageChunks.push(content.text);
     }
   }
 
-  private handleAgentThoughtChunk(update: Record<string, unknown>): void {
-    const content = update.content as { type?: string; text?: string } | undefined;
-    if (content?.type === "text" && typeof content.text === "string") {
-      this.reasoningChunks.push(content.text);
-    }
-  }
-
-  private handleToolCall(update: Record<string, unknown>): void {
-    const title = (update.title as string) ?? "";
-    const rawInput = update.rawInput;
-    const args = rawInput !== undefined && rawInput !== null ? JSON.stringify(rawInput) : "";
-    const toolCallId = update.toolCallId as string;
-    this.pendingTools.set(toolCallId, { name: title, args });
-    this.flushAssistantMessage();
-  }
-
-  private handleToolCallUpdate(update: Record<string, unknown>): void {
-    const status = update.status as string | undefined;
-    if (status !== "completed" && status !== "failed") return;
-    const toolCallId = update.toolCallId as string;
-    const pending = this.pendingTools.get(toolCallId);
-    const toolName = pending?.name ?? toolCallId;
-    const rawOutput = update.rawOutput;
-    const outputStr =
-      rawOutput !== undefined && rawOutput !== null
-        ? typeof rawOutput === "string"
-          ? rawOutput
-          : JSON.stringify(rawOutput)
-        : "";
-    this.messages.push({
-      role: "assistant",
-      content: null,
-      reasoning: null,
-      tool_calls: [{ function: { name: toolName, arguments: pending?.args ?? "" } }],
-    });
-    this.messages.push({
-      role: "tool",
-      content: outputStr,
-      reasoning: null,
-      tool_calls: null,
-    });
-    this.pendingTools.delete(toolCallId);
-  }
-
-  /** Flush any accumulated text/reasoning into an assistant message. */
-  private flushAssistantMessage(): void {
-    const text = this.messageChunks.join("");
-    const reasoning = this.reasoningChunks.join("");
-    if (text !== "" || reasoning !== "") {
-      this.messages.push({
-        role: "assistant",
-        content: text || null,
-        reasoning: reasoning || null,
-        tool_calls: null,
-      });
-    }
-    this.messageChunks = [];
-    this.reasoningChunks = [];
-  }
-
   private rejectAll(err: Error): void {
     for (const handler of this.pending.values()) {
       handler.reject(err);

packages/workflow-agent-hermes/src/hermes.ts

@@ -1,16 +1,16 @@
 import type { Store } from "@uncaged/json-cas";
+import { createLogger } from "@uncaged/workflow-util";
 import {
   type AgentContext,
   type AgentRunResult,
   buildContinuationPrompt,
   buildRolePrompt,
   createAgent,
-} from "@uncaged/workflow-agent-kit";
-import { createLogger } from "@uncaged/workflow-util";
+} from "@uncaged/workflow-util-agent";
 
 import { HermesAcpClient } from "./acp-client.js";
 import { getCachedSessionId, isResumeDisabled, setCachedSessionId } from "./session-cache.js";
-import { storeHermesSessionDetail } from "./session-detail.js";
+import { loadHermesSession, storeHermesSessionDetail } from "./session-detail.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
 
@@ -49,17 +49,11 @@ export function buildHermesPrompt(ctx: AgentContext): string {
   return parts.join("\n");
 }
 
-async function storePromptResult(
-  store: Store,
-  sessionId: string,
-  messages: Awaited<ReturnType<HermesAcpClient["prompt"]>>["messages"],
-): Promise<{ detailHash: string }> {
-  const session = {
-    session_id: sessionId,
-    model: "",
-    session_start: new Date().toISOString(),
-    messages,
-  };
+async function storePromptResult(store: Store, sessionId: string): Promise<{ detailHash: string }> {
+  const session = await loadHermesSession(sessionId);
+  if (session === null) {
+    throw new Error(`Hermes session file not found: ${sessionId}`);
+  }
   return storeHermesSessionDetail(store, session);
 }
 
@@ -116,8 +110,8 @@ export function createHermesAgent(): () => Promise<void> {
   async function runPrompt(ctx: AgentContext, useContinuation: boolean): Promise<AgentRunResult> {
     const effectiveCtx = useContinuation ? ctx : { ...ctx, isFirstVisit: true };
     const fullPrompt = buildHermesPrompt(effectiveCtx);
-    const { text, sessionId, messages } = await client.prompt(fullPrompt);
-    const { detailHash } = await storePromptResult(ctx.store, sessionId, messages);
+    const { text, sessionId } = await client.prompt(fullPrompt);
+    const { detailHash } = await storePromptResult(ctx.store, sessionId);
 
     if (!isResumeDisabled()) {
       await setCachedSessionId(ctx.threadId, ctx.role, sessionId);
@@ -152,8 +146,8 @@ export function createHermesAgent(): () => Promise<void> {
   ): Promise<AgentRunResult> {
     // Client is already connected from runHermes — same ACP session,
     // so the agent sees the full conversation history (crucial for retries).
-    const { text, sessionId, messages } = await client.prompt(message);
-    const { detailHash } = await storePromptResult(store, sessionId, messages);
+    const { text, sessionId } = await client.prompt(message);
+    const { detailHash } = await storePromptResult(store, sessionId);
     return { output: text, detailHash, sessionId };
   }
 

packages/workflow-agent-hermes/src/session-cache.ts

@@ -1,10 +1,10 @@
 // Re-export session cache from the shared agent-kit package with agent name injected.
 
+import type { ThreadId } from "@uncaged/workflow-protocol";
 import {
   getCachedSessionId as getCachedSessionIdBase,
   setCachedSessionId as setCachedSessionIdBase,
-} from "@uncaged/workflow-agent-kit";
-import type { ThreadId } from "@uncaged/workflow-protocol";
+} from "@uncaged/workflow-util-agent";
 
 export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
   return getCachedSessionIdBase("hermes", threadId, role);

packages/workflow-agent-hermes/src/session-detail.ts

@@ -1,3 +1,4 @@
+import { Database } from "bun:sqlite";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -108,15 +109,99 @@ function parseSessionJson(raw: unknown): HermesSessionJson | null {
   return { session_id, model, session_start, messages };
 }
 
+export function getHermesDbPath(): string {
+  return join(homedir(), ".hermes", "state.db");
+}
+
+type DbSessionRow = {
+  id: string;
+  model: string;
+  started_at: number;
+};
+
+type DbMessageRow = {
+  role: string;
+  content: string | null;
+  reasoning: string | null;
+  tool_calls: string | null;
+};
+
+function parseDbToolCalls(raw: string | null): HermesSessionMessage["tool_calls"] {
+  if (raw === null) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parseToolCalls(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function dbMessageToSessionMessage(row: DbMessageRow): HermesSessionMessage {
+  return {
+    role: row.role,
+    content: row.content ?? null,
+    reasoning: row.reasoning ?? null,
+    tool_calls: parseDbToolCalls(row.tool_calls),
+  };
+}
+
+export function loadHermesSessionFromDb(
+  sessionId: string,
+  dbPath: string | null = null,
+): HermesSessionJson | null {
+  const resolvedPath = dbPath ?? getHermesDbPath();
+  let db: InstanceType<typeof Database> | null = null;
+  try {
+    db = new Database(resolvedPath, { readonly: true });
+    const session = db
+      .query("SELECT id, model, started_at FROM sessions WHERE id = ?")
+      .get(sessionId) as DbSessionRow | null;
+    if (session === null) {
+      return null;
+    }
+    const rows = db
+      .query(
+        "SELECT role, content, reasoning, tool_calls FROM messages WHERE session_id = ? ORDER BY id",
+      )
+      .all(sessionId) as DbMessageRow[];
+
+    const messages: HermesSessionMessage[] = [];
+    for (const row of rows) {
+      const role = row.role;
+      if (role !== "user" && role !== "assistant" && role !== "tool") {
+        continue;
+      }
+      messages.push(dbMessageToSessionMessage(row));
+    }
+
+    return {
+      session_id: session.id,
+      model: session.model,
+      session_start: new Date(session.started_at * 1000).toISOString(),
+      messages,
+    };
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
 export async function loadHermesSession(sessionId: string): Promise<HermesSessionJson | null> {
   const path = getHermesSessionPath(sessionId);
   try {
     const text = await readFile(path, "utf8");
     const raw = JSON.parse(text) as unknown;
-    return parseSessionJson(raw);
+    const result = parseSessionJson(raw);
+    if (result !== null) {
+      return result;
+    }
   } catch {
-    return null;
+    // JSON file not available, fall through to DB
   }
+  return loadHermesSessionFromDb(sessionId);
 }
 
 export function computeDurationMs(sessionStart: string, nowMs: number = Date.now()): number {

packages/workflow-agent-hermes/tsconfig.json

@@ -5,5 +5,5 @@
     "outDir": "dist"
   },
   "include": ["src"],
-  "references": [{ "path": "../workflow-agent-kit" }]
+  "references": [{ "path": "../workflow-util-agent" }]
 }

packages/workflow-protocol/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @uncaged/workflow-protocol
+
+## 0.5.1

packages/workflow-protocol/README.md

@@ -100,7 +100,7 @@ type ProviderAlias = string;
 type ModelAlias = string;
 type AgentAlias = string;
 
-type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
+type ProviderConfig = { baseUrl: string; apiKey: string };
 type ModelConfig = {
   provider: ProviderAlias;
   name: string;
@@ -183,4 +183,4 @@ src/
 
 ## Configuration
 
-This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-agent-kit` (`loadWorkflowConfig`).
+This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-util-agent` (`loadWorkflowConfig`).

packages/workflow-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/json-cas-fs": "^0.5.2"
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/json-cas-fs": "^0.5.3"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

packages/workflow-protocol/src/types.ts

@@ -151,7 +151,7 @@ export type Scenario = string;
 
 export type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
 };
 
 export type ModelConfig = {

packages/workflow-util-agent/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @uncaged/workflow-util-agent
+
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-util@0.5.1
+  - @uncaged/workflow-protocol@0.5.1

packages/workflow-util-agent/README.md

@@ -1,4 +1,4 @@
-# @uncaged/workflow-agent-kit
+# @uncaged/workflow-util-agent
 
 Agent framework — `createAgent` factory, context builder, frontmatter fast-path, and LLM extract pipeline.
 
@@ -13,7 +13,7 @@ Also exports prompt builders, config/storage helpers, and session ID caching for
 ## Installation
 
 ```bash
-bun add @uncaged/workflow-agent-kit
+bun add @uncaged/workflow-util-agent
 ```
 
 ## API
@@ -140,8 +140,8 @@ function loadWorkflowConfig(storageRoot: string): Promise<WorkflowConfig>
 ## Usage
 
 ```typescript
-import { createAgent, buildRolePrompt } from "@uncaged/workflow-agent-kit";
-import type { AgentContext, AgentRunResult } from "@uncaged/workflow-agent-kit";
+import { createAgent, buildRolePrompt } from "@uncaged/workflow-util-agent";
+import type { AgentContext, AgentRunResult } from "@uncaged/workflow-util-agent";
 
 async function run(ctx: AgentContext): Promise<AgentRunResult> {
   const prompt = buildRolePrompt(ctx.workflow.roles[ctx.role]!);

packages/workflow-util-agent/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@uncaged/workflow-agent-kit",
-  "version": "0.5.0",
+  "name": "@uncaged/workflow-util-agent",
+  "version": "0.5.1",
   "files": [
     "src",
     "dist",
@@ -19,8 +19,8 @@
     "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.5.2",
-    "@uncaged/json-cas-fs": "^0.5.2",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/json-cas-fs": "^0.5.3",
     "@uncaged/workflow-protocol": "workspace:^",
     "@uncaged/workflow-util": "workspace:^",
     "dotenv": "^16.6.1",
@@ -35,7 +35,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
-    "directory": "packages/workflow-agent-kit"
+    "directory": "packages/workflow-util-agent"
   },
   "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
   "bugs": {

packages/workflow-util-agent/src/build-agent-prompt.ts

@@ -1,64 +0,0 @@
-import type { AgentContext } from "@uncaged/workflow-runtime";
-
-/** Max characters of step content to include in the prompt. */
-const CONTENT_QUOTA = 16_000;
-
-/** Builds the full agent prompt: system instructions plus summarized thread history. */
-export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
-  const lines: string[] = [];
-  lines.push(ctx.currentRole.systemPrompt);
-  lines.push("");
-  lines.push("## Task");
-  lines.push(ctx.start.content);
-
-  const { steps } = ctx;
-  if (steps.length === 0) {
-    return lines.join("\n");
-  }
-
-  if (steps.length === 1) {
-    const s = steps[0];
-    lines.push("");
-    lines.push(`## Step: ${s.role}`);
-    lines.push("");
-    lines.push(`Meta: ${JSON.stringify(s.meta)}`);
-    appendContent(lines, s.content);
-  } else {
-    lines.push("");
-    lines.push("## Previous Steps");
-    for (let i = 0; i < steps.length - 1; i++) {
-      const s = steps[i];
-      lines.push("");
-      lines.push(`### Step ${i + 1}: ${s.role}`);
-      lines.push(`Summary: ${JSON.stringify(s.meta)}`);
-    }
-    const last = steps[steps.length - 1];
-    lines.push("");
-    lines.push(`## Latest Step: ${last.role}`);
-    lines.push("");
-    lines.push(`Meta: ${JSON.stringify(last.meta)}`);
-    appendContent(lines, last.content);
-  }
-
-  lines.push("");
-  lines.push("## Tools");
-  lines.push(
-    `Use \`uncaged-workflow thread ${ctx.threadId}\` to read full details of any previous step.`,
-  );
-
-  return lines.join("\n");
-}
-
-function appendContent(lines: string[], content: string | null | undefined): void {
-  if (content === null || content === undefined || content.trim() === "") {
-    return;
-  }
-  const truncated =
-    content.length > CONTENT_QUOTA
-      ? `${content.slice(0, CONTENT_QUOTA)}\n... (truncated)`
-      : content;
-  lines.push("");
-  lines.push("<output>");
-  lines.push(truncated);
-  lines.push("</output>");
-}