improve: committer — check git status before staging (from retrospect PR #578)

Developer already commits changes, so committer's git add -A is redundant.
Now checks git status first and skips to push if tree is clean.

.cursor/rules/no-dynamic-import.mdc

@@ -1,27 +1,3 @@
----
-description: Ban dynamic import() in production code — use static imports instead
-globs: packages/*/src/**/*.ts
-alwaysApply: true
----
+# No Dynamic Import
 
-# No Dynamic Import in Production Code
-
-## Rule
-
-Do NOT use `await import()` or dynamic `import()` expressions in production source code.
-Always use static top-level `import` statements.
-
-## Exception (must include a comment explaining why)
-
-1. **Bundle loader** — loads user-authored workflow bundles whose paths are only known at runtime
-
-When suppressing, add a comment directly above:
-
-```ts
-// Dynamic import required: user bundle path resolved at runtime
-const mod = await import(bundlePath);
-```
-
-## Test Files
-
-Test files (`__tests__/**`) are exempt.
+See [docs/no-dynamic-import.md](../../docs/no-dynamic-import.md) for full rules.

.cursor/rules/sync-readme.mdc

@@ -1,67 +1,3 @@
-# Sync README
+# Sync Readme
 
-When updating README.md files in this monorepo, follow these conventions.
-
-## Scope
-
-- Root `README.md` — project overview and navigation hub
-- Per-package `packages/*/README.md` — each package self-contained
-
-## Root README Structure
-
-The root README should have these sections in order:
-
-1. **Title and one-liner** — stateless workflow engine driven by single-step CLI
-2. **Overview** — 2-3 paragraphs explaining what it does and key concepts
-3. **Architecture** — dependency layer diagram (text-based)
-4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app)
-5. **Quick Start** — install, build, register workflow, start thread, run step
-6. **CLI Reference** — brief command list, detailed usage in cli-workflow README
-7. **Development** — bun install / build / check / test
-
-## Per-Package README Structure
-
-Each package README should have:
-
-1. **Title** — package name
-2. **One-line description** — matching package.json
-3. **Overview** — what it does, where it sits in the architecture, dependencies
-4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents)
-5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
-6. **CLI Usage** (cli/agent packages) — command reference with examples
-7. **Internal Structure** — brief src/ file organization
-8. **Configuration** (if applicable)
-
-## Execution Steps
-
-### Step 1: Gather current state
-For each package read:
-- package.json (name, version, description, dependencies, bin)
-- src/index.ts (public API exports)
-- Existing README.md (preserve hand-written content worth keeping)
-
-### Step 2: Update root README
-- Ensure ALL packages in packages/ directory are listed in the table
-- Update CLI command reference from uwf --help output
-- Keep Quick Start examples valid
-
-### Step 3: Write/update each package README
-- Follow the per-package structure
-- API section MUST match actual src/index.ts exports — never invent
-- For agent packages: document CLI binary name, how it is invoked
-- For lib packages: document exported types and functions
-- Internal structure: list actual files in src/
-
-### Step 4: Verify
-- All relative links work
-- Package names match package.json
-- No references to removed/renamed packages
-- bun run build still passes
-
-## Guidelines
-
-- Only document what src/index.ts actually exports
-- Root README summarizes, package READMEs go into detail
-- Verify CLI examples against actual commands
-- Preserve existing good prose when updating
-- English for all README content
+See [docs/sync-readme.md](../../docs/sync-readme.md) for full rules.

.gitea/workflows/ci.yml

@@ -0,0 +1,28 @@
+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: Lint
+        run: bun run lint
+
+      - name: Type check
+        run: bun run typecheck
+
+      - name: Test
+        run: bun test

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+labels: bug
+---
+
+## Describe the bug
+
+A clear description of what the bug is.
+
+## To reproduce
+
+Steps or commands to reproduce:
+
+```bash
+uwf ...
+```
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened. Include error messages or logs.
+
+## Environment
+
+- OS: 
+- Bun version: 
+- uwf version (`uwf --version`): 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+## What
+
+Describe the feature or improvement.
+
+## Why
+
+Why is this needed? What problem does it solve?
+
+## Proposed solution
+
+How should it work? Include API sketches, CLI examples, or workflow YAML snippets if applicable.

.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What
+
+What this PR does.
+
+## Why
+
+Why the change is needed.
+
+## Changes
+
+- `path/to/file` — what changed and why
+
+## Ref
+
+Fixes #

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Lint
+        run: bunx biome check .
+
+      - name: Test
+        run: bun run test:ci

.workflows/retrospect-workflow.yaml

@@ -0,0 +1,220 @@
+name: "retrospect-workflow"
+description: "Post-execution retrospective: analyze a completed thread, find inefficiencies, and improve the workflow definition."
+roles:
+  analyst:
+    description: "Scans thread execution for anomalies and produces a findings report"
+    goal: "You are a workflow execution analyst. You review completed thread data to find inefficiencies, wasted effort, and procedure gaps."
+    capabilities:
+      - data-analysis
+    procedure: |
+      You receive a completed thread ID in your task prompt.
+
+      Phase 0 — Validation (must pass before any analysis):
+      1. Run `uwf step list <thread-id>` to get thread metadata including the workflow hash
+      2. Run `uwf workflow show <workflow-hash>` to get the workflow name
+      3. Verify the workflow exists locally: check `.workflows/<name>.yaml` in the current repo
+         - If NOT found: output $status=wrong_project with the workflow name. Do NOT proceed.
+      4. Compare the thread's workflow hash against the current registered version:
+         - Run `uwf workflow show <name>` to get the current hash
+         - If hashes differ: the thread ran on an older version. Note this — you will need to diff versions after analysis.
+
+      Phase 1 — Overview scan:
+      5. From the step list, compute a health signal for each step:
+         - Duration: flag if >2x the median of other steps
+         - Output tokens: flag if >2x the median
+         - Status flow: flag non-happy-path transitions (rejected, fix_code, fix_spec, hook_failed)
+         - Step count: flag if the same role appears more than expected (indicates loops)
+      6. If no anomalies found AND versions match: output $status=clean
+      7. If no anomalies found BUT versions differ:
+         - Diff the two workflow versions to check if any procedure changes are relevant
+         - If the current version already addresses potential concerns: output $status=clean with a note
+         - Otherwise: proceed to Phase 2
+
+      Phase 2 — Targeted deep-dive (only for flagged steps):
+      8. For each flagged step, run `uwf step show <hash>` to get the detail with turns
+      9. Analyze the turn sequence for:
+         - Repeated tool calls with the same or similar input (blind retries)
+         - Tool errors followed by no strategy change (same approach retried)
+         - Unnecessary exploration (reading files or running commands unrelated to the task)
+         - Hallucinated commands or flags (commands that don't exist or wrong syntax)
+         - Excessive turns before reaching the goal
+      10. For each finding, record:
+          - Which role and step hash
+          - What happened (specific turn indices and commands)
+          - Root cause hypothesis (procedure gap, missing pitfall, unclear instruction)
+          - Suggested fix (what to add/change in the procedure)
+      11. If versions differ: compare findings against the version diff.
+          Mark any finding that is already fixed in the current version as "resolved_in_current".
+          Only report findings that are NOT yet addressed.
+
+      Output a structured findings report. Set $status=clean if nothing actionable, $status=findings if unresolved issues exist, or $status=wrong_project if the workflow doesn't belong here.
+    output: "A findings report with per-issue root cause and suggested procedure fixes. Set $status to clean or findings (with report hash)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "clean" }
+            summary: { type: string }
+          required: [$status, summary]
+        - properties:
+            $status: { const: "findings" }
+            report: { type: string }
+            targetWorkflow: { type: string }
+          required: [$status, report, targetWorkflow]
+        - properties:
+            $status: { const: "wrong_project" }
+            workflowName: { type: string }
+          required: [$status, workflowName]
+  proposer:
+    description: "Translates findings into concrete workflow edits"
+    goal: "You are a workflow improvement proposer. You read the analyst's findings and produce specific, minimal edits to the workflow YAML."
+    capabilities:
+      - planning
+    procedure: |
+      1. Read the analyst's findings report from your task prompt
+      2. Locate the target workflow YAML:
+         - Workflow definitions live in the WORKFLOW ENGINE repo (where `uwf` is developed), NOT in the repo that was analyzed.
+         - Find it via: `uwf workflow show <targetWorkflow> --format yaml` to read the current definition
+         - The physical file is `.workflows/<targetWorkflow>.yaml` in the workflow engine repo
+         - Use `git rev-parse --show-toplevel` in the current directory to find the workflow engine repo root
+      3. Read the current workflow YAML to understand existing procedures
+      4. For each finding, draft a minimal edit:
+         - Prefer adding a pitfall note or clarifying instruction over restructuring
+         - If a procedure step is ambiguous, make it explicit
+         - If a tool usage pattern is wrong, add a "Do NOT" or "IMPORTANT" note
+         - Keep edits surgical — don't rewrite procedures that work fine
+      5. Check if existing tests need updating (search for test files referencing the workflow)
+      6. Produce a change plan as CAS text node via `uwf cas put-text "<plan>"`
+
+      The plan should list each edit with:
+      - File path
+      - What to change (old text → new text, or addition)
+      - Why (linked to which finding)
+      - Any test updates needed
+    output: "A change plan stored in CAS. Set $status to ready (with plan hash and repoPath) or no_action (if findings don't warrant changes)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+          required: [$status, plan, repoPath]
+        - properties:
+            $status: { const: "no_action" }
+            reason: { type: string }
+          required: [$status, reason]
+  developer:
+    description: "Applies the proposed workflow edits"
+    goal: "You are a developer agent. You apply workflow YAML edits and update related tests."
+    capabilities:
+      - coding
+    procedure: |
+      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+      The workflow definitions live in THIS repo (the workflow engine), not the repo that was analyzed.
+
+      Before starting any work, set up an isolated worktree:
+      1. Use `git rev-parse --show-toplevel` to find the repo root (do NOT use repoPath from proposer — that's the analyzed repo)
+      2. `git fetch origin` to get latest refs
+      3. `git worktree add .worktrees/retrospect/<short-slug> -b retrospect/<short-slug> origin/main`
+      4. `cd .worktrees/retrospect/<short-slug> && bun install`
+      5. ALL subsequent work must happen inside the worktree directory.
+
+      Then apply changes:
+      6. Read the change plan from CAS: `uwf cas get <plan hash>`
+      7. Apply each edit from the plan to the workflow YAML
+      8. Update or add tests as specified in the plan
+      9. Run `bun run build` and `bun test` to verify
+      10. Run `bun run check` for lint
+      11. Commit with message: `improve: <workflow-name> — <brief summary>`
+    output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "done" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - properties:
+            $status: { const: "failed" }
+            reason: { type: string }
+          required: [$status, reason]
+  reviewer:
+    description: "Reviews the workflow edits for correctness"
+    goal: "You are a reviewer. You verify that workflow edits are minimal, correct, and actually address the findings."
+    capabilities:
+      - code-review
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      Review criteria:
+      1. Each edit must trace back to a specific finding — no drive-by changes
+      2. Edits should be minimal — don't rewrite working procedures
+      3. New pitfall notes or instructions must be clear and actionable
+      4. Tests must be updated if assertions changed
+      5. `bun run build` and `bun test` must pass
+      6. `bunx biome check` must pass
+
+      IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files.
+    output: "Explain your decision. Set $status to approved (with branch/worktree) or rejected (with comments)."
+    frontmatter:
+      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]
+  committer:
+    description: "Commits and creates PR"
+    goal: "You are a committer agent. You create a clean commit and push a PR."
+    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: `git commit -m "improve: <workflow> — <summary>"`
+      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 --title "..." --description "..."`
+         - IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. cd to the repo root first.
+         - Do NOT pass `--repo` — let tea auto-detect from the main repo's git remote.
+         - PR description must include: What / Why / Findings / Changes sections
+         - 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: "analyst", prompt: "Analyze completed thread {{{threadId}}} for execution anomalies." }
+  analyst:
+    clean: { role: "$END", prompt: "No issues found. Thread executed cleanly." }
+    findings: { role: "proposer", prompt: "Findings report: {{{report}}}. Target workflow: {{{targetWorkflow}}}. Propose minimal edits." }
+    wrong_project: { role: "$END", prompt: "Thread uses workflow '{{{workflowName}}}' which does not exist in this project. Run retrospect from the correct repo." }
+  proposer:
+    no_action: { role: "$END", prompt: "No actionable changes needed: {{{reason}}}." }
+    ready: { role: "developer", prompt: "Apply the change plan (CAS hash: {{{plan}}}) to the workflow definitions in this repo." }
+  developer:
+    done: { role: "reviewer", prompt: "Review workflow edits on branch {{{branch}}} at {{{worktree}}}." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
+  reviewer:
+    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in {{{worktree}}}." }
+    approved: { role: "committer", prompt: "Approved. 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 improved." }

.workflows/solve-issue.yaml

@@ -10,9 +10,9 @@ roles:
     procedure: |
       On first run (no previous steps):
       1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
-      2. Read CLAUDE.md (or equivalent project conventions file) to understand coding standards
+      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 and terminate
+      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):
@@ -21,17 +21,19 @@ roles:
 
       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)
-    output: "Output a brief summary of the test spec. Frontmatter must include: $status (ready or insufficient_info) and plan (CAS hash of the test spec, required when status=ready)."
+      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:
-          type: string
-          enum: [ready, insufficient_info]
-        plan:
-          type: string
-      required: [$status]
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+          required: [$status, plan, repoPath]
+        - properties:
+            $status: { const: "insufficient_info" }
+          required: [$status]
   developer:
     description: "TDD implementation per test spec"
     goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
@@ -39,33 +41,41 @@ roles:
       - coding
     procedure: |
       IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+      The repo path and other details are provided in your task prompt.
 
       Before starting any work, set up an isolated worktree:
-      1. `cd ~/repos/workflow && git fetch origin` to get latest refs
-      2. First time (no existing branch):
-         - `git worktree add ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
-         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> && bun install`
-      3. If bounced back from reviewer or tester (branch already exists):
-         - The worktree should already exist at `~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
-         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
+      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`
-      4. ALL subsequent work must happen inside the worktree directory.
+      5. ALL subsequent work must happen inside the worktree directory.
 
       Then implement TDD:
-      5. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
-      6. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
-      7. Write tests first based on the spec
-      8. Implement the code to make tests pass
-      9. Ensure `bun run build` passes with no errors
-      10. Run `bun test` to verify all tests pass
-    output: "List all files changed and provide a summary. Frontmatter must include: $status (done or failed)."
+      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:
-          type: string
-          enum: [done, failed]
-      required: [$status]
+      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: "Code standards compliance check"
     goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
@@ -73,7 +83,7 @@ roles:
       - code-review
       - static-analysis
     procedure: |
-      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+      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
@@ -85,91 +95,105 @@ roles:
       4. `bunx biome check` — no lint violations
       5. TypeScript strict mode — no type errors
 
-      Soft checks (review against CLAUDE.md conventions):
-      - Functional-first: `function` + `type`, not `class` + `interface`
-      - No optional properties (`?:`) — use `T | null`
-      - Naming conventions (kebab-case files, PascalCase types, camelCase functions)
-      - Module boundary discipline (folder exports via index.ts)
-      - No `console.log` (use structured logger)
+      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. Frontmatter must include: $status (approved or rejected)."
+    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:
-          type: string
-          enum: [approved, rejected]
-      required: [$status]
+      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: |
-      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+      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 latest planner step's frontmatter.plan)
+      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. Frontmatter must include: $status (passed, fix_code, or fix_spec)."
+    output: "Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report)."
     frontmatter:
-      type: object
-      properties:
-        $status:
-          type: string
-          enum: [passed, fix_code, fix_spec]
-      required: [$status]
+      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: |
-      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+      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"`
+      1. Check `git status` — if working tree is clean and branch is ahead of origin, skip to step 3 (push).
+      2. If there are unstaged/uncommitted changes: `git add -A` then `git commit -m "type: description\n\nFixes #N"`
       3. Push the branch: `git push -u origin <branch-name>`
          - 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 uncaged/workflow --title "..." --description "..."`
-         - The `--repo` flag is required to work in worktree directories (fixes #474 "path segment [0] is empty" error)
-         - If working on a different repo, extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
-         - PR description must follow the project template: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
-         - On tea failure: capture stderr/stdout, log the error clearly, include PR details (title, description, branch) for manual creation, and mark success=false
+      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
+         - IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. cd to the repo root first.
+         - Do NOT pass `--repo` — let tea auto-detect from the main repo's git remote.
+         - 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 ~/repos/workflow`
-         - `git worktree remove ~/repos/workflow-worktrees/fix/<issue-number>-<slug>`
-    output: "Include PR URL on success or error log on failure. Frontmatter must include: $status (committed or hook_failed)."
+         - 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:
-      type: object
-      properties:
-        $status:
-          type: string
-          enum: [committed, hook_failed]
-      required: [$status]
+      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 and produce an implementation plan." }
   planner:
     insufficient_info: { role: "$END", prompt: "Insufficient information to proceed; end the workflow." }
-    ready: { role: "developer", prompt: "Implement the plan from the planner." }
+    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}." }
   developer:
-    failed: { role: "$END", prompt: "Development failed; end the workflow." }
-    done: { role: "reviewer", prompt: "Send the implementation to the reviewer." }
+    done: { role: "reviewer", prompt: "Review branch {{{branch}}} at {{{worktree}}} for code standards compliance." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
   reviewer:
-    rejected: { role: "developer", prompt: "Reviewer rejected the implementation; fix the issues." }
-    approved: { role: "tester", prompt: "Review passed; run tests on the implementation." }
+    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; return to developer." }
-    fix_spec: { role: "planner", prompt: "Tests found spec issues; return to planner." }
-    passed: { role: "committer", prompt: "Tests passed; commit and push the changes." }
+    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; return to developer to fix." }
-    committed: { role: "$END", prompt: "Commit succeeded; complete the workflow." }
+    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit." }
+    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow complete." }

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)
 
@@ -285,6 +284,11 @@ moderator → agent → extract      — one step per invocation, repeat until $
 2. **Register** — `uwf workflow put <file.yaml>` parses YAML, registers output schemas, stores `WorkflowPayload` in CAS
 3. **Run** — `uwf thread start` creates a thread, `uwf thread step` executes one cycle per invocation
 
+## Project Rules
+
+- [docs/sync-readme.md](docs/sync-readme.md) — README sync conventions
+- [docs/no-dynamic-import.md](docs/no-dynamic-import.md) — no dynamic import in production code
+
 ## Commit Convention
 
 ```

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to @uncaged/workflow
+
+Thank you for your interest in contributing! This guide covers setup, conventions, and the PR workflow.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (latest)
+- [Node.js](https://nodejs.org/) 20+
+- Git
+
+## Setup
+
+```bash
+git clone https://github.com/shazhou-ww/uncaged-workflow.git
+cd uncaged-workflow
+bun install
+bun run build
+bun test
+```
+
+## Development Workflow
+
+```bash
+bun run build     # TypeScript compilation (all packages)
+bun run check     # tsc + biome lint + log tag validation
+bun run format    # Auto-format with Biome
+bun test          # Run all tests
+```
+
+All three (`build`, `check`, `test`) must pass before submitting a PR. A pre-push hook runs `check` + `test` automatically.
+
+## Coding Conventions
+
+See [CLAUDE.md](CLAUDE.md) for the full coding standard. Key points:
+
+- **Functional-first** — `function` + `type`, not `class` + `interface`
+- **No optional properties** — use `T | null` instead of `?:`
+- **Named exports only** — no default exports
+- **No `console.log`** — use the structured logger from `@uncaged/workflow-util`
+- **Static imports only** — no `await import()` in production code
+- **Biome** for lint + format — run `bun run check` before committing
+
+## Commit Messages
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: cli | moderator | agent-kit | hermes | builtin | claude-code | util | protocol | dashboard
+```
+
+Examples:
+- `feat(moderator): add cycle detection to graph evaluator`
+- `fix(cli): handle missing config file gracefully`
+- `docs(protocol): update StepNode field descriptions`
+
+## Pull Request Process
+
+1. **Branch** from `main`: `git checkout -b feat/123-short-description`
+2. **Implement** your change with tests
+3. **Run checks**: `bun run check && bun test`
+4. **Commit** with a descriptive message referencing the issue: `Fixes #123`
+5. **Push** and open a PR
+
+### PR Description Template
+
+```
+## What
+What this PR does.
+
+## Why
+Why the change is needed.
+
+## Changes
+- `path/to/file.ts` — what changed and why
+
+## Ref
+Fixes #N
+```
+
+## Adding a Changeset
+
+For any user-facing change (feat, fix, breaking change), add a changeset:
+
+```bash
+bun changeset
+```
+
+This creates a markdown file in `.changeset/` describing the change. It will be consumed on the next release to bump versions and generate CHANGELOG entries.
+
+## Project Structure
+
+```
+packages/
+  workflow-protocol/      # Shared types and JSON Schema
+  workflow-util/          # Encoding, IDs, logging, frontmatter
+  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
+  cli-workflow/           # uwf CLI binary
+  workflow-dashboard/     # Web UI (private, alpha)
+```
+
+Dependency flows downward — lower layers have no dependency on higher layers. See [CLAUDE.md](CLAUDE.md) for the full architecture.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uncaged
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,5 +1,10 @@
 # @uncaged/workflow
 
+[![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-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.
 
 ## Overview
@@ -10,50 +15,13 @@ Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes fo
 
 Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `<thread-id>` and `<role>`, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay.
 
-## Architecture
+## Install
 
-Dependency layers (lower layers have no dependency on higher layers):
-
-```
-Layer 0 — Contract
-  workflow-protocol          Shared types and JSON Schema definitions
-
-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
-
-Layer 3 — Agent implementations
-  workflow-agent-hermes      Hermes ACP agent (uwf-hermes)
-  workflow-agent-builtin     Built-in LLM + tools agent (uwf-builtin)
-  workflow-agent-claude-code Claude Code agent (uwf-claude-code)
-
-Layer 4 — CLI
-  cli-workflow               uwf binary — thread lifecycle, registry, CAS, setup
-
-App (uses protocol; not in the runtime engine stack)
-  workflow-dashboard         Web UI for visual workflow editing
+```bash
+npm install -g @uncaged/cli-workflow
 ```
 
-External CAS: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
-
-See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
-
-## Packages
-
-| Package | npm | Description | Type | README |
-|---------|-----|-------------|------|--------|
-| `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` | `@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) |
-| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) |
-| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) |
+Requires [Bun](https://bun.sh/) runtime (used internally for TypeScript execution).
 
 ## Quick Start
 
@@ -73,6 +41,49 @@ uwf thread exec <thread-id>
 
 Use `-c, --count <number>` on `thread exec` to run multiple steps in one invocation. Override the agent with `--agent <cmd>`.
 
+## Architecture
+
+Dependency layers (lower layers have no dependency on higher layers):
+
+```
+Layer 0 — Contract
+  workflow-protocol          Shared types and JSON Schema definitions
+
+Layer 1 — Shared infra
+  workflow-util              Encoding, IDs, logging, frontmatter, paths
+
+Layer 2 — Agent framework
+  workflow-util-agent         createAgent factory, context builder, extract pipeline
+
+Layer 3 — Agent implementations
+  workflow-agent-hermes      Hermes ACP agent (uwf-hermes)
+  workflow-agent-builtin     Built-in LLM + tools agent (uwf-builtin)
+  workflow-agent-claude-code Claude Code agent (uwf-claude-code)
+
+Layer 4 — CLI
+  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
+```
+
+External CAS: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
+
+See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
+
+## Packages
+
+| Package | npm | Description | Type | README |
+|---------|-----|-------------|------|--------|
+| `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-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) |
+| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) |
+| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) |
+
 ## CLI Reference
 
 Global options: `-V, --version`, `--format <json|yaml>`, `-h, --help`.

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."

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" +
@@ -425,7 +425,7 @@ 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];
@@ -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/no-dynamic-import.md

@@ -0,0 +1,27 @@
+---
+description: Ban dynamic import() in production code — use static imports instead
+globs: packages/*/src/**/*.ts
+alwaysApply: true
+---
+
+# No Dynamic Import in Production Code
+
+## Rule
+
+Do NOT use `await import()` or dynamic `import()` expressions in production source code.
+Always use static top-level `import` statements.
+
+## Exception (must include a comment explaining why)
+
+1. **Bundle loader** — loads user-authored workflow bundles whose paths are only known at runtime
+
+When suppressing, add a comment directly above:
+
+```ts
+// Dynamic import required: user bundle path resolved at runtime
+const mod = await import(bundlePath);
+```
+
+## Test Files
+
+Test files (`__tests__/**`) are exempt.

docs/sync-readme.md

@@ -0,0 +1,67 @@
+# Sync README
+
+When updating README.md files in this monorepo, follow these conventions.
+
+## Scope
+
+- Root `README.md` — project overview and navigation hub
+- Per-package `packages/*/README.md` — each package self-contained
+
+## Root README Structure
+
+The root README should have these sections in order:
+
+1. **Title and one-liner** — stateless workflow engine driven by single-step CLI
+2. **Overview** — 2-3 paragraphs explaining what it does and key concepts
+3. **Architecture** — dependency layer diagram (text-based)
+4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app)
+5. **Quick Start** — install, build, register workflow, start thread, run step
+6. **CLI Reference** — brief command list, detailed usage in cli-workflow README
+7. **Development** — bun install / build / check / test
+
+## Per-Package README Structure
+
+Each package README should have:
+
+1. **Title** — package name
+2. **One-line description** — matching package.json
+3. **Overview** — what it does, where it sits in the architecture, dependencies
+4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents)
+5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
+6. **CLI Usage** (cli/agent packages) — command reference with examples
+7. **Internal Structure** — brief src/ file organization
+8. **Configuration** (if applicable)
+
+## Execution Steps
+
+### Step 1: Gather current state
+For each package read:
+- package.json (name, version, description, dependencies, bin)
+- src/index.ts (public API exports)
+- Existing README.md (preserve hand-written content worth keeping)
+
+### Step 2: Update root README
+- Ensure ALL packages in packages/ directory are listed in the table
+- Update CLI command reference from uwf --help output
+- Keep Quick Start examples valid
+
+### Step 3: Write/update each package README
+- Follow the per-package structure
+- API section MUST match actual src/index.ts exports — never invent
+- For agent packages: document CLI binary name, how it is invoked
+- For lib packages: document exported types and functions
+- Internal structure: list actual files in src/
+
+### Step 4: Verify
+- All relative links work
+- Package names match package.json
+- No references to removed/renamed packages
+- bun run build still passes
+
+## Guidelines
+
+- Only document what src/index.ts actually exports
+- Root README summarizes, package READMEs go into detail
+- Verify CLI examples against actual commands
+- Preserve existing good prose when updating
+- English for all README content

docs/wf-stateless-design.md

@@ -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 — 共享类型定义

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

@@ -15,7 +15,8 @@
     }
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "test:ci": "bun test"
   },
   "dependencies": {
     "@uncaged/workflow-protocol": "workspace:^",
@@ -27,5 +28,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "legacy-packages/workflow-moderator"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

package.json

@@ -11,6 +11,7 @@
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",
     "test": "bun run --filter './packages/*' test",
+    "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"
@@ -23,5 +24,14 @@
     "@types/xxhashjs": "^0.2.4",
     "@uncaged/workflow-agent-hermes": "workspace:*",
     "bun-types": "^1.3.13"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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
 
@@ -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

@@ -11,23 +11,35 @@
     "uwf": "./src/cli.ts"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/json-cas-fs": "^0.4.0",
-    "@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": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@types/mustache": "^4.2.6",
     "vitest": "^4.1.6"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/cli-workflow"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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__/setup-agent-discovery.test.ts

@@ -0,0 +1,137 @@
+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");
+  });
+});

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

@@ -0,0 +1,78 @@
+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 {
+  cmdSkillArchitecture,
+  cmdSkillCli,
+  cmdSkillList,
+  cmdSkillModerator,
+  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");
+    for (const name of result) {
+      expect(typeof name).toBe("string");
+      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 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("list");
+  });
+});

packages/cli-workflow/src/__tests__/solve-issue-tea-worktree.test.ts

@@ -13,10 +13,18 @@ import { parse } from "yaml";
  */
 
 describe("solve-issue workflow: tea pr create worktree fix", () => {
-  // Navigate up from packages/cli-workflow to repo root
-  const workflowPath = join(process.cwd(), "..", "..", ".workflows", "solve-issue.yaml");
+  // Navigate up from packages/cli-workflow/src/__tests__ to repo root
+  const workflowPath = join(
+    import.meta.dirname,
+    "..",
+    "..",
+    "..",
+    "..",
+    ".workflows",
+    "solve-issue.yaml",
+  );
 
-  test("committer procedure should include --repo flag in tea pr create command", async () => {
+  test("committer procedure should require running tea pr create from main repo directory", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
@@ -24,19 +32,12 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     const committerProcedure = workflow.roles.committer?.procedure;
     expect(committerProcedure).toBeDefined();
 
-    // Verify the procedure includes tea pr create with --repo flag
+    // Verify the procedure includes tea pr create
     expect(committerProcedure).toContain("tea pr create");
-    expect(committerProcedure).toContain("--repo");
 
-    // Verify the --repo flag appears before or together with tea pr create
-    // This ensures the command is: tea pr create --repo <owner/repo> ...
-    const teaPrCreateMatch = committerProcedure?.match(/tea pr create[^\n]*/);
-    expect(teaPrCreateMatch).not.toBeNull();
-
-    if (teaPrCreateMatch) {
-      const teaCommandLine = teaPrCreateMatch[0];
-      expect(teaCommandLine).toContain("--repo");
-    }
+    // Verify the procedure warns about running from main repo dir (not worktree)
+    expect(committerProcedure).toMatch(/main repo directory/i);
+    expect(committerProcedure).toMatch(/not a worktree/i);
   });
 
   test("committer procedure should mention repo extraction from git remote", async () => {
@@ -81,17 +82,18 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     expect(workflow.roles.committer?.frontmatter).toBeDefined();
   });
 
-  test("committer frontmatter schema should require $status field", async () => {
+  test("committer frontmatter schema should be oneOf with $status discriminant", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     // Parse as any to access the raw YAML structure (frontmatter is inline JSON Schema in YAML)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const workflow = parse(yamlContent) as any;
-
     const frontmatter = workflow.roles.committer?.frontmatter;
     expect(frontmatter).toBeDefined();
-    expect(frontmatter?.type).toBe("object");
-    expect(frontmatter?.properties?.["$status"]).toBeDefined();
-    expect(frontmatter?.properties?.["$status"]?.enum).toContain("committed");
-    expect(frontmatter?.required).toContain("$status");
+    expect(frontmatter?.oneOf).toBeDefined();
+    const committedVariant = frontmatter.oneOf.find(
+      (v: any) => v.properties?.["$status"]?.const === "committed",
+    );
+    expect(committedVariant).toBeDefined();
+    expect(committedVariant.required).toContain("$status");
   });
 });

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

@@ -144,6 +144,8 @@ describe("step read", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step with large quota
@@ -227,6 +229,8 @@ describe("step read", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step with limited quota (700 chars)
@@ -304,6 +308,8 @@ describe("step read", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step with minimal quota (1 char)
@@ -357,6 +363,8 @@ describe("step read", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step - should return metadata only (no error)
@@ -431,6 +439,8 @@ describe("step read", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step - should return metadata only (no error)
@@ -443,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);
@@ -505,6 +586,8 @@ describe("step read", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     // Read step

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

@@ -0,0 +1,378 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap, putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { STEP_NODE_SCHEMA } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdStepList } from "../commands/step.js";
+import { cmdThreadRead } from "../commands/thread.js";
+import { registerUwfSchemas } from "../schemas.js";
+import { saveThreadsIndex } from "../store.js";
+
+// ── schemas ──────────────────────────────────────────────────────────────────
+
+const TURN_SCHEMA = {
+  title: "hermes-turn",
+  type: "object" as const,
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" as const },
+    role: { type: "string" as const },
+    content: { type: "string" as const },
+    toolCalls: {
+      anyOf: [
+        { type: "array" as const, items: { type: "object" as const } },
+        { type: "null" as const },
+      ],
+    },
+    reasoning: { anyOf: [{ type: "string" as const }, { type: "null" as const }] },
+  },
+  additionalProperties: false,
+};
+
+const DETAIL_SCHEMA = {
+  title: "hermes-detail",
+  type: "object" as const,
+  required: ["sessionId", "model", "duration", "turnCount", "turns"],
+  properties: {
+    sessionId: { type: "string" as const },
+    model: { type: "string" as const },
+    duration: { type: "integer" as const },
+    turnCount: { type: "integer" as const },
+    turns: {
+      type: "array" as const,
+      items: { type: "string" as const, format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+async function registerDetailSchemas(store: ReturnType<typeof createFsStore>) {
+  await bootstrap(store);
+  const [turn, detail] = await Promise.all([
+    putSchema(store, TURN_SCHEMA),
+    putSchema(store, DETAIL_SCHEMA),
+  ]);
+  return { turn, detail };
+}
+
+// ── fixture ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-step-timing-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── 1. Protocol types (compile-time) ─────────────────────────────────────────
+
+describe("protocol types", () => {
+  test("StepRecord has startedAtMs and completedAtMs as required fields", () => {
+    // Type-level test: this block compiles only if fields exist and are number
+    const record: import("@uncaged/workflow-protocol").StepRecord = {
+      role: "test",
+      output: "hash1" as CasRef,
+      detail: "hash2" as CasRef,
+      agent: "uwf-test",
+      edgePrompt: "",
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+    expect(record.startedAtMs).toBe(1000);
+    expect(record.completedAtMs).toBe(2000);
+  });
+
+  test("StepEntry has durationMs as required field", () => {
+    const entry: import("@uncaged/workflow-protocol").StepEntry = {
+      hash: "hash" as CasRef,
+      role: "test",
+      output: {},
+      detail: "hash2" as CasRef,
+      agent: "uwf-test",
+      timestamp: 123,
+      durationMs: 5000,
+    };
+    expect(entry.durationMs).toBe(5000);
+  });
+});
+
+// ── 2. JSON Schema ───────────────────────────────────────────────────────────
+
+describe("StepNode JSON schema", () => {
+  test("schema requires startedAtMs and completedAtMs", () => {
+    const required = STEP_NODE_SCHEMA.required as string[];
+    expect(required).toContain("startedAtMs");
+    expect(required).toContain("completedAtMs");
+  });
+
+  test("schema defines timing fields as integer", () => {
+    const props = STEP_NODE_SCHEMA.properties as Record<string, { type: string }>;
+    expect(props.startedAtMs.type).toBe("integer");
+    expect(props.completedAtMs.type).toBe("integer");
+  });
+
+  test("StepNode with timing fields passes CAS validation", async () => {
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = createFsStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: "placeholder0000" as CasRef,
+      prompt: "test",
+    });
+
+    const outputHash = await store.put(schemas.text, "output text");
+
+    const detailSchemas = await registerDetailSchemas(store);
+    const detailHash = await store.put(detailSchemas.detail, {
+      sessionId: "s1",
+      model: "m1",
+      duration: 100,
+      turnCount: 0,
+      turns: [],
+    });
+
+    // Should succeed — valid timing fields
+    const hash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-test",
+      edgePrompt: "",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
+    });
+    expect(hash).toBeTruthy();
+  });
+});
+
+// ── 3. step list — durationMs computed ───────────────────────────────────────
+
+describe("step list timing", () => {
+  test("step list includes durationMs = completedAtMs - startedAtMs", 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: {},
+      graph: {},
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "test",
+    });
+
+    const outputHash = await store.put(schemas.text, "output");
+    const detailHash = await store.put(detailSchemas.detail, {
+      sessionId: "s1",
+      model: "m1",
+      duration: 100,
+      turnCount: 0,
+      turns: [],
+    });
+
+    const startedAt = 1716600000000;
+    const completedAt = 1716600003500;
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-test",
+      edgePrompt: "",
+      startedAtMs: startedAt,
+      completedAtMs: completedAt,
+    });
+
+    const threadId = "01HX2Q3R4S5T6V7W8X9YZ1" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
+
+    const result = await cmdStepList(tmpDir, threadId);
+    const stepEntries = result.steps.slice(1); // skip start entry
+    expect(stepEntries).toHaveLength(1);
+
+    const step = stepEntries[0] as import("@uncaged/workflow-protocol").StepEntry;
+    expect(step.durationMs).toBe(3500);
+  });
+});
+
+// ── 4. thread read — duration in header ──────────────────────────────────────
+
+describe("thread read timing", () => {
+  test("thread read header includes Duration", 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: "Do work",
+          capabilities: [],
+          procedure: "work",
+          output: "result",
+          frontmatter: "placeholder0000" as CasRef,
+        },
+      },
+      graph: {
+        $START: { _: { role: "worker", prompt: "go" } },
+        worker: { _: { role: "$END", prompt: "" } },
+      },
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "test task",
+    });
+
+    const turnHash = await store.put(detailSchemas.turn, {
+      index: 0,
+      role: "assistant",
+      content: "Done.",
+      toolCalls: null,
+      reasoning: null,
+    });
+    const detailHash = await store.put(detailSchemas.detail, {
+      sessionId: "s1",
+      model: "m1",
+      duration: 100,
+      turnCount: 1,
+      turns: [turnHash],
+    });
+    const outputHash = await store.put(schemas.text, "output");
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-test",
+      edgePrompt: "",
+      startedAtMs: 1716600000000,
+      completedAtMs: 1716600042000,
+    });
+
+    const threadId = "01HX2Q3R4S5T6V7W8X9YZ3" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, 10000, null, false);
+    expect(markdown).toContain("**Duration:** 42.0s");
+  });
+
+  test("thread read shows sub-second duration as ms", 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: "Do work",
+          capabilities: [],
+          procedure: "work",
+          output: "result",
+          frontmatter: "placeholder0000" as CasRef,
+        },
+      },
+      graph: {
+        $START: { _: { role: "worker", prompt: "go" } },
+        worker: { _: { role: "$END", prompt: "" } },
+      },
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "test",
+    });
+
+    const turnHash = await store.put(detailSchemas.turn, {
+      index: 0,
+      role: "assistant",
+      content: "Done.",
+      toolCalls: null,
+      reasoning: null,
+    });
+    const detailHash = await store.put(detailSchemas.detail, {
+      sessionId: "s1",
+      model: "m1",
+      duration: 100,
+      turnCount: 1,
+      turns: [turnHash],
+    });
+    const outputHash = await store.put(schemas.text, "output");
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-test",
+      edgePrompt: "",
+      startedAtMs: 1716600000000,
+      completedAtMs: 1716600000350,
+    });
+
+    const threadId = "01HX2Q3R4S5T6V7W8X9YZ4" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, 10000, null, false);
+    expect(markdown).toContain("**Duration:** 350ms");
+  });
+});
+
+// ── 6. Breaking change — old data without timing fails ───────────────────────
+
+describe("breaking change", () => {
+  test("StepNode schema rejects payload without timing fields", () => {
+    const required = STEP_NODE_SCHEMA.required as string[];
+    // Both fields must be in the required array
+    expect(required).toContain("startedAtMs");
+    expect(required).toContain("completedAtMs");
+
+    // Payload without timing fields would fail schema validation
+    // because the schema marks them as required
+    const payloadWithoutTiming = {
+      start: "hash1",
+      prev: null,
+      role: "worker",
+      output: "hash2",
+      detail: "hash3",
+      agent: "uwf-test",
+      edgePrompt: "",
+    };
+    // Verify the payload is missing required fields
+    expect(payloadWithoutTiming).not.toHaveProperty("startedAtMs");
+    expect(payloadWithoutTiming).not.toHaveProperty("completedAtMs");
+  });
+});

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

@@ -141,6 +141,8 @@ describe("thread read --quota flag", () => {
         output: outputHash,
         detail: detailHash,
         agent: "uwf-test",
+        startedAtMs: 1000000000000,
+        completedAtMs: 1000000005000,
       });
       steps.push(stepHash);
     }
@@ -221,6 +223,8 @@ describe("thread read --quota flag", () => {
       output: outputHash,
       detail: step1DetailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const step2Content = generateContent(600, "Second");
@@ -245,6 +249,8 @@ describe("thread read --quota flag", () => {
       output: outputHash,
       detail: step2DetailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ1" as ThreadId;
@@ -328,6 +334,8 @@ describe("thread read --quota flag", () => {
         output: outputHash,
         detail: detailHash,
         agent: "uwf-test",
+        startedAtMs: 1000000000000,
+        completedAtMs: 1000000005000,
       });
       steps.push(stepHash);
     }
@@ -338,8 +346,8 @@ describe("thread read --quota flag", () => {
     // Set tight quota with --start flag
     const markdown = await cmdThreadRead(tmpDir, threadId, 600, null, true);
 
-    // Quota must be reasonably enforced (allow ~210 char tolerance for structure)
-    expect(markdown.length).toBeLessThanOrEqual(810);
+    // Quota must be reasonably enforced (allow ~260 char tolerance for structure)
+    expect(markdown.length).toBeLessThanOrEqual(860);
 
     // Should contain thread header
     expect(markdown).toMatch(/# Thread/);
@@ -405,6 +413,8 @@ describe("thread read --quota flag", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ4" as ThreadId;
@@ -480,6 +490,8 @@ describe("thread read --quota flag", () => {
         output: outputHash,
         detail: detailHash,
         agent: "uwf-test",
+        startedAtMs: 1000000000000,
+        completedAtMs: 1000000005000,
       });
       steps.push(stepHash);
     }
@@ -559,6 +571,8 @@ describe("thread read --quota flag", () => {
         output: outputHash,
         detail: detailHash,
         agent: "uwf-test",
+        startedAtMs: 1000000000000,
+        completedAtMs: 1000000005000,
       });
       steps.push(stepHash);
     }

packages/cli-workflow/src/__tests__/thread-read-xml-tags.test.ts

@@ -139,6 +139,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-claude-code",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000001" as ThreadId;
@@ -214,6 +216,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-claude-code",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000002" as ThreadId;
@@ -274,6 +278,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -283,6 +289,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000003" as ThreadId;
@@ -335,6 +343,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000004" as ThreadId;
@@ -387,6 +397,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: missingDetailRef,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000005" as ThreadId;
@@ -439,6 +451,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000006" as ThreadId;
@@ -511,6 +525,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -520,6 +536,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const step3 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -529,6 +547,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: null,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000007" as ThreadId;
@@ -607,6 +627,8 @@ describe("thread read XML tag isolation", () => {
       output: outputHash,
       detail: detailHash,
       agent: "uwf-test",
+      startedAtMs: 1000000000000,
+      completedAtMs: 1000000005000,
     });
 
     const threadId = "01JTEST0000000000000008" as ThreadId;
@@ -661,6 +683,8 @@ describe("thread read XML tag isolation", () => {
         output: outputHash,
         detail: null,
         agent: "uwf-test",
+        startedAtMs: 1000000000000,
+        completedAtMs: 1000000005000,
       })) as CasRef;
       steps.push(step);
       prev = step;

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

@@ -0,0 +1,470 @@
+import type { WorkflowPayload } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { validateWorkflow } from "../validate-semantic.js";
+
+/** Build a valid two-role workflow that passes all checks. */
+function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
+  const base: WorkflowPayload = {
+    name: "test-workflow",
+    description: "A test workflow",
+    roles: {
+      writer: {
+        description: "Writes content",
+        goal: "Write content",
+        capabilities: ["writing"],
+        procedure: "Write it",
+        output: "The content",
+        frontmatter: {
+          type: "object",
+          properties: {
+            $status: { enum: ["_"] },
+            plan: { type: "string" },
+          },
+          required: ["$status", "plan"],
+        } as unknown as string,
+      },
+      reviewer: {
+        description: "Reviews content",
+        goal: "Review content",
+        capabilities: ["reviewing"],
+        procedure: "Review it",
+        output: "The review",
+        frontmatter: {
+          type: "object",
+          oneOf: [
+            {
+              properties: {
+                $status: { const: "approved" },
+                summary: { type: "string" },
+              },
+              required: ["$status", "summary"],
+            },
+            {
+              properties: {
+                $status: { const: "rejected" },
+                reason: { type: "string" },
+              },
+              required: ["$status", "reason"],
+            },
+          ],
+        } as unknown as string,
+      },
+    },
+    graph: {
+      $START: { _: { role: "writer", prompt: "Begin writing" } },
+      writer: { _: { role: "reviewer", prompt: "Review this: {{{plan}}}" } },
+      reviewer: {
+        approved: { role: "$END", prompt: "Done: {{{summary}}}" },
+        rejected: { role: "writer", prompt: "Fix: {{{reason}}}" },
+      },
+    },
+  };
+
+  if (!overrides) return base;
+  return { ...base, ...overrides };
+}
+
+describe("Suite 1: Role Reference Integrity", () => {
+  test("1.1 graph references unknown role", () => {
+    const wf = makeWorkflow();
+    wf.graph.nonexistent = { _: { role: "$END", prompt: "done" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('unknown role "nonexistent"'))).toBe(true);
+  });
+
+  test("1.2 orphan role not in graph", () => {
+    const wf = makeWorkflow();
+    wf.roles.orphan = {
+      description: "Orphan",
+      goal: "Nothing",
+      capabilities: [],
+      procedure: "None",
+      output: "None",
+      frontmatter: {
+        type: "object",
+        properties: { $status: { enum: ["_"] } },
+        required: ["$status"],
+      } as unknown as string,
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('role "orphan" is defined but not referenced in graph')),
+    ).toBe(true);
+  });
+
+  test("1.3 $START in roles", () => {
+    const wf = makeWorkflow();
+    (wf.roles as Record<string, unknown>).$START = {
+      description: "Bad",
+      goal: "Bad",
+      capabilities: [],
+      procedure: "Bad",
+      output: "Bad",
+      frontmatter: { type: "object", properties: {}, required: [] },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('reserved name "$START"'))).toBe(true);
+  });
+
+  test("1.4 $END in roles", () => {
+    const wf = makeWorkflow();
+    (wf.roles as Record<string, unknown>).$END = {
+      description: "Bad",
+      goal: "Bad",
+      capabilities: [],
+      procedure: "Bad",
+      output: "Bad",
+      frontmatter: { type: "object", properties: {}, required: [] },
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('reserved name "$END"'))).toBe(true);
+  });
+
+  test("1.5 valid workflow returns no errors", () => {
+    const wf = makeWorkflow();
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+});
+
+describe("Suite 2: Graph Structure", () => {
+  test("2.1 $START missing from graph", () => {
+    const wf = makeWorkflow();
+    delete wf.graph.$START;
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("$START must be defined in graph"))).toBe(true);
+  });
+
+  test("2.2 $START has multiple status keys", () => {
+    const wf = makeWorkflow();
+    wf.graph.$START = {
+      _: { role: "writer", prompt: "Begin" },
+      other: { role: "reviewer", prompt: "Also" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+    ).toBe(true);
+  });
+
+  test("2.3 $START edge uses non-_ status", () => {
+    const wf = makeWorkflow();
+    wf.graph.$START = { ready: { role: "writer", prompt: "Begin" } };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
+    ).toBe(true);
+  });
+
+  test("2.4 $END has outgoing edges", () => {
+    const wf = makeWorkflow();
+    wf.graph.$END = { _: { role: "writer", prompt: "Loop" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("$END must not have outgoing edges"))).toBe(true);
+  });
+
+  test("2.5 unreachable role", () => {
+    const wf = makeWorkflow();
+    wf.roles.isolated = {
+      description: "Isolated",
+      goal: "Isolated",
+      capabilities: [],
+      procedure: "Isolated",
+      output: "Isolated",
+      frontmatter: {
+        type: "object",
+        properties: { $status: { enum: ["_"] } },
+        required: ["$status"],
+      } as unknown as string,
+    };
+    wf.graph.isolated = { _: { role: "$END", prompt: "done" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('role "isolated" is not reachable from $START'))).toBe(
+      true,
+    );
+  });
+
+  test("2.6 edge target references invalid role", () => {
+    const wf = makeWorkflow();
+    wf.graph.writer = { _: { role: "ghost", prompt: "Go to ghost" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('unknown target role "ghost"'))).toBe(true);
+  });
+});
+
+describe("Suite 3: Status-Edge Consistency", () => {
+  test("3.1 single-exit role with multiple graph keys", () => {
+    const wf = makeWorkflow();
+    wf.graph.writer = {
+      _: { role: "reviewer", prompt: "Review" },
+      extra: { role: "$END", prompt: "Done" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) =>
+        e.includes('role "writer" is single-exit but has status keys other than "_"'),
+      ),
+    ).toBe(true);
+  });
+
+  test("3.2 single-exit role missing _ key", () => {
+    const wf = makeWorkflow();
+    wf.graph.writer = { done: { role: "reviewer", prompt: "Review" } };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('role "writer" is single-exit but graph has no "_" key')),
+    ).toBe(true);
+  });
+
+  test("3.3 multi-exit role with extra statuses", () => {
+    const wf = makeWorkflow();
+    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('role "reviewer" graph has extra status keys: timeout')),
+    ).toBe(true);
+  });
+
+  test("3.4 multi-exit role missing a status", () => {
+    const wf = makeWorkflow();
+    wf.graph.reviewer = {
+      approved: { role: "$END", prompt: "Done" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('role "reviewer" graph is missing status keys: rejected')),
+    ).toBe(true);
+  });
+
+  test("3.5 multi-exit role with _ key", () => {
+    const wf = makeWorkflow();
+    wf.graph.reviewer = { _: { role: "$END", prompt: "Done" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes('role "reviewer" is multi-exit but graph uses "_"'))).toBe(
+      true,
+    );
+  });
+});
+
+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();
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{branch}}}" } };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) =>
+        e.includes('prompt variable "branch" not found in role "writer" frontmatter'),
+      ),
+    ).toBe(true);
+  });
+
+  test("4.2 prompt references nonexistent variable (multi-exit)", () => {
+    const wf = makeWorkflow();
+    wf.graph.reviewer = {
+      approved: { role: "$END", prompt: "Done: {{{branch}}}" },
+      rejected: { role: "writer", prompt: "Fix: {{{reason}}}" },
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) =>
+        e.includes('prompt variable "branch" not found in role "reviewer" variant "approved"'),
+      ),
+    ).toBe(true);
+  });
+
+  test("4.3 valid mustache variables pass", () => {
+    const wf = makeWorkflow();
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+
+  test("4.4 $status variable is always valid", () => {
+    const wf = makeWorkflow();
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Status: {{$status}}" } };
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+});
+
+describe("Suite 5: oneOf Discriminant Validity", () => {
+  test("5.1 oneOf without $status const", () => {
+    const wf = makeWorkflow();
+    wf.roles.reviewer = {
+      ...wf.roles.reviewer,
+      frontmatter: {
+        type: "object",
+        oneOf: [
+          { properties: { summary: { type: "string" } }, required: ["summary"] },
+          { properties: { reason: { type: "string" } }, required: ["reason"] },
+        ],
+      } as unknown as string,
+    };
+    const errors = validateWorkflow(wf);
+    expect(
+      errors.some((e) => e.includes('oneOf variants must have "$status" as const discriminant')),
+    ).toBe(true);
+  });
+
+  test("5.2 oneOf with non-const $status", () => {
+    const wf = makeWorkflow();
+    wf.roles.reviewer = {
+      ...wf.roles.reviewer,
+      frontmatter: {
+        type: "object",
+        oneOf: [
+          {
+            properties: { $status: { type: "string" }, summary: { type: "string" } },
+            required: ["$status", "summary"],
+          },
+          {
+            properties: { $status: { type: "string" }, reason: { type: "string" } },
+            required: ["$status", "reason"],
+          },
+        ],
+      } as unknown as string,
+    };
+    const errors = validateWorkflow(wf);
+    expect(errors.some((e) => e.includes("oneOf variant $status must be a const value"))).toBe(
+      true,
+    );
+  });
+
+  test("5.3 valid oneOf passes", () => {
+    const wf = makeWorkflow();
+    const errors = validateWorkflow(wf);
+    expect(errors).toEqual([]);
+  });
+});
+
+describe("Suite 6: Multiple Errors Collection", () => {
+  test("6.1 multiple errors collected", () => {
+    const wf = makeWorkflow();
+    // orphan role
+    wf.roles.orphan = {
+      description: "Orphan",
+      goal: "Nothing",
+      capabilities: [],
+      procedure: "None",
+      output: "None",
+      frontmatter: {
+        type: "object",
+        properties: { $status: { enum: ["_"] } },
+        required: ["$status"],
+      } as unknown as string,
+    };
+    // unknown graph reference
+    wf.graph.nonexistent = { _: { role: "$END", prompt: "done" } };
+    // bad mustache var
+    wf.graph.writer = { _: { role: "reviewer", prompt: "{{{badvar}}}" } };
+    const errors = validateWorkflow(wf);
+    expect(errors.length).toBeGreaterThanOrEqual(3);
+  });
+});

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

@@ -20,23 +20,43 @@ async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
   return { storageRoot, store, schemas };
 }
 
-async function storeWorkflow(uwf: UwfStore, name: string): Promise<CasRef> {
-  const payload: WorkflowPayload = {
+function makeMinimalPayload(name: string, description: string): WorkflowPayload {
+  return {
     name,
-    description: "Test workflow",
-    roles: {},
-    graph: {},
+    description,
+    roles: {
+      worker: {
+        description: "worker role",
+        goal: "do work",
+        capabilities: [],
+        procedure: "",
+        output: "",
+        frontmatter: {
+          type: "object",
+          properties: {
+            $status: { type: "string" },
+          },
+          required: ["$status"],
+        } as unknown as CasRef,
+      },
+    },
+    graph: {
+      $START: { _: { role: "worker", prompt: "start working" } },
+      worker: { _: { role: "$END", prompt: "done" } },
+    },
   };
+}
+
+async function storeWorkflow(uwf: UwfStore, name: string): Promise<CasRef> {
+  const payload = makeMinimalPayload(name, "Test workflow");
   return await uwf.store.put(uwf.schemas.workflow, payload);
 }
 
 async function createWorkflowYaml(name: string, version: string | null = null): Promise<string> {
-  const payload: WorkflowPayload = {
+  const payload = makeMinimalPayload(
     name,
-    description: version !== null ? `Test workflow (${version})` : "Test workflow",
-    roles: {},
-    graph: {},
-  };
+    version !== null ? `Test workflow (${version})` : "Test workflow",
+  );
   const yaml = stringify(payload);
   return yaml;
 }

packages/cli-workflow/src/cli.ts

@@ -15,7 +15,13 @@ import {
 } from "./commands/cas.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
-import { cmdSkillCli } from "./commands/skill.js";
+import {
+  cmdSkillArchitecture,
+  cmdSkillCli,
+  cmdSkillList,
+  cmdSkillModerator,
+  cmdSkillYaml,
+} from "./commands/skill.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
@@ -55,8 +61,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");
@@ -474,6 +479,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 +488,34 @@ 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("moderator")
+  .description("Print the moderator reference")
+  .action(() => {
+    console.log(cmdSkillModerator());
+  });
+
+skill
+  .command("list")
+  .description("List all available skill names")
+  .action(() => {
+    console.log(cmdSkillList().join("\n"));
+  });
+
 program
   .command("setup")
   .description("Configure provider, model, and agent")

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

@@ -297,6 +297,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. */
@@ -340,8 +414,9 @@ 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: [] };
+  // Ensure the selected agent has an entry
+  if (!agents[agentName]) {
+    agents[agentName] = { command: `uwf-${agentName}`, args: [] };
   }
 
   return {
@@ -349,7 +424,7 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
     providers,
     models,
     agents,
-    defaultAgent: existing.defaultAgent ?? agentName,
+    defaultAgent: agentName,
     defaultModel: existing.defaultModel ?? "default",
   };
 }
@@ -543,11 +618,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,12 @@
-export { generateCliReference as cmdSkillCli } from "@uncaged/workflow-util";
+export {
+  generateArchitectureReference as cmdSkillArchitecture,
+  generateCliReference as cmdSkillCli,
+  generateModeratorReference as cmdSkillModerator,
+  generateYamlReference as cmdSkillYaml,
+} from "@uncaged/workflow-util";
+
+const SKILL_NAMES = ["cli", "architecture", "yaml", "moderator"] 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;
 };
 
 /**
@@ -58,6 +65,7 @@ export async function cmdStepList(
       detail: item.payload.detail ?? null,
       agent: item.payload.agent,
       timestamp: item.timestamp,
+      durationMs: item.payload.completedAtMs - item.payload.startedAtMs,
     });
   }
 
@@ -127,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) {
@@ -137,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;
@@ -167,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;
 
@@ -212,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,
@@ -40,6 +40,7 @@ import {
   type UwfStore,
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
+import { validateWorkflow } from "../validate-semantic.js";
 import {
   type ChainState,
   collectOrderedSteps,
@@ -169,6 +170,11 @@ async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promis
     fail(filenameError);
   }
 
+  const semanticErrors = validateWorkflow(payload);
+  if (semanticErrors.length > 0) {
+    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
+  }
+
   const materialized = await materializeWorkflowPayload(uwf, payload);
   const hash = await uwf.store.put(uwf.schemas.workflow, materialized);
   const stored = uwf.store.get(hash);
@@ -560,14 +566,25 @@ function selectByQuota(
   return { selected, skippedCount: candidates.length - selected.length };
 }
 
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSec = Math.round(seconds % 60);
+  return `${minutes}m${remainingSec}s`;
+}
+
 function formatStepHeader(stepNum: number, item: OrderedStepItem): string {
   const ts = new Date(item.timestamp)
     .toISOString()
     .replace("T", " ")
     .replace(/\.\d+Z$/, "");
+  const durationMs = item.payload.completedAtMs - item.payload.startedAtMs;
+  const duration = formatDuration(durationMs);
   return [
     `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
-    `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
+    `**Agent:** ${item.payload.agent} | **Time:** ${ts} | **Duration:** ${duration}`,
   ].join("\n");
 }
 

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

@@ -15,6 +15,7 @@ import {
   type UwfStore,
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, parseWorkflowPayload } from "../validate.js";
+import { validateWorkflow } from "../validate-semantic.js";
 
 export type WorkflowOrigin = "local" | "global";
 
@@ -136,6 +137,11 @@ export async function cmdWorkflowAdd(
     fail(filenameError);
   }
 
+  const semanticErrors = validateWorkflow(payload);
+  if (semanticErrors.length > 0) {
+    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
+  }
+
   const uwf = await createUwfStore(storageRoot);
   const materialized = await materializeWorkflowPayload(uwf, payload);
 

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

@@ -0,0 +1,326 @@
+import type { WorkflowPayload } from "@uncaged/workflow-protocol";
+
+type SchemaObj = Record<string, unknown>;
+
+const RESERVED_NAMES = new Set(["$START", "$END"]);
+
+/** Extract mustache variable names from a prompt string. */
+function extractMustacheVars(prompt: string): string[] {
+  const vars: string[] = [];
+  const re = /\{\{\{?([^}]+)\}\}\}?/g;
+  let m: RegExpExecArray | null = re.exec(prompt);
+  while (m !== null) {
+    vars.push(m[1]);
+    m = re.exec(prompt);
+  }
+  return vars;
+}
+
+/** Check if a frontmatter schema is a oneOf (multi-exit) type. */
+function isOneOfSchema(fm: unknown): fm is SchemaObj & { oneOf: SchemaObj[] } {
+  if (typeof fm !== "object" || fm === null) return false;
+  const obj = fm as 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;
+  if (typeof props !== "object" || props === null) return new Set();
+  return new Set(Object.keys(props as Record<string, unknown>));
+}
+
+/** Extract $status const values from oneOf variants. */
+function getOneOfStatuses(variants: SchemaObj[]): string[] {
+  const statuses: string[] = [];
+  for (const variant of variants) {
+    const props = variant.properties as Record<string, SchemaObj> | undefined;
+    if (props?.$status) {
+      const statusDef = props.$status;
+      if (typeof statusDef.const === "string") {
+        statuses.push(statusDef.const);
+      }
+    }
+  }
+  return statuses;
+}
+
+/** Check reserved names and role/graph reference integrity. */
+function checkRoleReferences(payload: WorkflowPayload, errors: string[]): void {
+  const roleNames = new Set(Object.keys(payload.roles));
+  const graphNodes = new Set(Object.keys(payload.graph));
+
+  for (const name of roleNames) {
+    if (RESERVED_NAMES.has(name)) {
+      errors.push(`reserved name "${name}" must not appear in roles`);
+    }
+  }
+
+  for (const node of graphNodes) {
+    if (!RESERVED_NAMES.has(node) && !roleNames.has(node)) {
+      errors.push(`graph references unknown role "${node}"`);
+    }
+  }
+
+  for (const name of roleNames) {
+    if (RESERVED_NAMES.has(name)) continue;
+    if (!graphNodes.has(name)) {
+      errors.push(`role "${name}" is defined but not referenced in graph`);
+    }
+  }
+}
+
+/** Check $START/$END constraints, edge targets, and reachability. */
+function checkGraphStructure(payload: WorkflowPayload, errors: string[]): void {
+  const roleNames = new Set(Object.keys(payload.roles));
+  const graphNodes = new Set(Object.keys(payload.graph));
+
+  if (!graphNodes.has("$START")) {
+    errors.push("$START must be defined in graph");
+  } else {
+    const startKeys = Object.keys(payload.graph.$START);
+    if (startKeys.length !== 1 || startKeys[0] !== "_") {
+      errors.push('$START must have exactly one edge with status "_"');
+    }
+  }
+
+  if (graphNodes.has("$END")) {
+    errors.push("$END must not have outgoing edges");
+  }
+
+  for (const [node, statusMap] of Object.entries(payload.graph)) {
+    for (const [status, target] of Object.entries(statusMap)) {
+      if (target.role !== "$END" && !roleNames.has(target.role)) {
+        errors.push(`edge ${node}→${status}: unknown target role "${target.role}"`);
+      }
+    }
+  }
+
+  checkReachability(roleNames, collectReachableRoles(payload.graph), errors);
+}
+
+/** BFS to collect all roles reachable from $START. */
+function collectReachableRoles(graph: WorkflowPayload["graph"]): Set<string> {
+  const reachable = new Set<string>();
+  const startEdges = graph.$START;
+  if (!startEdges) return reachable;
+
+  const queue: string[] = [];
+  for (const target of Object.values(startEdges)) {
+    if (target.role !== "$END" && !reachable.has(target.role)) {
+      reachable.add(target.role);
+      queue.push(target.role);
+    }
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift() as string;
+    const edges = graph[current];
+    if (!edges) continue;
+    for (const target of Object.values(edges)) {
+      if (target.role !== "$END" && !reachable.has(target.role)) {
+        reachable.add(target.role);
+        queue.push(target.role);
+      }
+    }
+  }
+
+  return reachable;
+}
+
+/** Check that all defined roles are reachable from $START. */
+function checkReachability(roleNames: Set<string>, reachable: Set<string>, errors: string[]): void {
+  for (const name of roleNames) {
+    if (RESERVED_NAMES.has(name)) continue;
+    if (!reachable.has(name)) {
+      errors.push(`role "${name}" is not reachable from $START`);
+    }
+  }
+}
+
+/** Check oneOf discriminant validity for a role. */
+function checkOneOfDiscriminant(
+  roleName: string,
+  variants: SchemaObj[],
+  statuses: string[],
+  errors: string[],
+): void {
+  if (statuses.length === variants.length) return;
+
+  let foundMissing = false;
+  for (const variant of variants) {
+    const props = variant.properties as Record<string, SchemaObj> | undefined;
+    if (!props?.$status) {
+      errors.push(`role "${roleName}": oneOf variants must have "$status" as const discriminant`);
+      foundMissing = true;
+      break;
+    }
+    if (typeof props.$status.const !== "string") {
+      errors.push(`role "${roleName}": oneOf variant $status must be a const value`);
+      foundMissing = true;
+      break;
+    }
+  }
+
+  if (!foundMissing) {
+    errors.push(`role "${roleName}": oneOf variant $status must be a const value`);
+  }
+}
+
+/** Check status-edge consistency for a multi-exit role. */
+function checkMultiExitEdges(
+  roleName: string,
+  graphKeys: Set<string>,
+  statusSet: Set<string>,
+  errors: string[],
+): void {
+  if (graphKeys.has("_")) {
+    errors.push(`role "${roleName}" is multi-exit but graph uses "_"`);
+    return;
+  }
+
+  const extraKeys = [...graphKeys].filter((k) => !statusSet.has(k));
+  const missingKeys = [...statusSet].filter((k) => !graphKeys.has(k));
+  if (extraKeys.length > 0) {
+    errors.push(`role "${roleName}" graph has extra status keys: ${extraKeys.join(", ")}`);
+  }
+  if (missingKeys.length > 0) {
+    errors.push(`role "${roleName}" graph is missing status keys: ${missingKeys.join(", ")}`);
+  }
+}
+
+/** Check mustache variables for multi-exit role. */
+function checkMultiExitMustache(
+  roleName: string,
+  graphEntry: Record<string, { role: string; prompt: string }>,
+  variants: SchemaObj[],
+  errors: string[],
+): void {
+  for (const [status, target] of Object.entries(graphEntry)) {
+    const vars = extractMustacheVars(target.prompt);
+    const variant = variants.find((v) => {
+      const props = v.properties as Record<string, SchemaObj> | undefined;
+      return props?.$status?.const === status;
+    });
+    if (!variant) continue;
+    const propNames = getPropertyNames(variant);
+    for (const v of vars) {
+      if (v === "$status") continue;
+      if (!propNames.has(v)) {
+        errors.push(`prompt variable "${v}" not found in role "${roleName}" variant "${status}"`);
+      }
+    }
+  }
+}
+
+/** Check status-edge consistency and mustache for each role. */
+function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void {
+  for (const [roleName, role] of Object.entries(payload.roles)) {
+    if (RESERVED_NAMES.has(roleName)) continue;
+    const graphEntry = payload.graph[roleName];
+    if (!graphEntry) continue;
+
+    const fm = role.frontmatter as unknown;
+    const graphKeys = new Set(Object.keys(graphEntry));
+
+    if (isOneOfSchema(fm)) {
+      const variants = fm.oneOf as SchemaObj[];
+      const statuses = getOneOfStatuses(variants);
+
+      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);
+    }
+  }
+}
+
+/** Check single-exit role status and mustache. */
+function checkSingleExitRole(
+  roleName: string,
+  graphKeys: Set<string>,
+  graphEntry: Record<string, { role: string; prompt: string }>,
+  fm: SchemaObj | null,
+  errors: string[],
+): void {
+  if (graphKeys.size > 1 || (graphKeys.size === 1 && !graphKeys.has("_"))) {
+    if (!graphKeys.has("_")) {
+      errors.push(`role "${roleName}" is single-exit but graph has no "_" key`);
+    } else {
+      errors.push(`role "${roleName}" is single-exit but has status keys other than "_"`);
+    }
+  }
+
+  const singleTarget = graphEntry._;
+  if (!singleTarget) return;
+
+  const vars = extractMustacheVars(singleTarget.prompt);
+  const propNames = fm ? getPropertyNames(fm) : new Set<string>();
+  for (const v of vars) {
+    if (v === "$status") continue;
+    if (!propNames.has(v)) {
+      errors.push(`prompt variable "${v}" not found in role "${roleName}" frontmatter`);
+    }
+  }
+}
+
+/** 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.
+ */
+export function validateWorkflow(payload: WorkflowPayload): string[] {
+  const errors: string[] = [];
+  checkRoleReferences(payload, errors);
+  checkGraphStructure(payload, errors);
+  checkRoleConsistency(payload, errors);
+  return errors;
+}

packages/cli-workflow/src/validate.ts

@@ -16,7 +16,9 @@ function isRoleDefinition(value: unknown): boolean {
     return false;
   }
   const frontmatter = value.frontmatter;
-  const frontmatterOk = isRecord(frontmatter) && typeof frontmatter.type === "string";
+  const frontmatterOk =
+    isRecord(frontmatter) &&
+    (typeof frontmatter.type === "string" || Array.isArray(frontmatter.oneOf));
   const capabilities = value.capabilities;
   const capabilitiesOk =
     Array.isArray(capabilities) && capabilities.every((c) => typeof c === "string");

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/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

@@ -18,11 +18,12 @@
     }
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {
@@ -30,5 +31,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-agent-builtin"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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/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

@@ -18,11 +18,12 @@
     }
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {
@@ -30,5 +31,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-agent-claude-code"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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/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,9 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 
 import { HermesAcpClient } from "../src/acp-client.js";
 
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-describe("handleSessionUpdate — helper extraction", () => {
+describe("handleSessionUpdate — text extraction", () => {
   let client: HermesAcpClient;
 
   beforeEach(() => {
@@ -16,153 +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);
   });
 });
-
-describe("HermesAcpClient", () => {
-  let client: HermesAcpClient;
-
-  beforeEach(() => {
-    client = new HermesAcpClient();
-  });
-
-  afterEach(async () => {
-    await client.close();
-  });
-
-  it(
-    "connect() returns a UUID sessionId",
-    async () => {
-      const sessionId = await client.connect(process.cwd());
-      expect(typeof sessionId).toBe("string");
-      expect(sessionId).toMatch(UUID_RE);
-    },
-    { timeout: 2 * 60 * 1000 },
-  );
-
-  it(
-    "prompt() returns a non-empty text response",
-    async () => {
-      await client.connect(process.cwd());
-      const result = await client.prompt("Reply with exactly the word: PONG");
-      expect(typeof result.text).toBe("string");
-      expect(result.text.length).toBeGreaterThan(0);
-      expect(typeof result.sessionId).toBe("string");
-      expect(result.sessionId).toMatch(UUID_RE);
-    },
-    { timeout: 2 * 60 * 1000 },
-  );
-
-  it(
-    "prompt() can be called twice on the same session (resume)",
-    async () => {
-      await client.connect(process.cwd());
-
-      const first = await client.prompt("Say the word ALPHA and nothing else.");
-      expect(first.text.length).toBeGreaterThan(0);
-
-      const second = await client.prompt("Now say the word BETA and nothing else.");
-      expect(second.text.length).toBeGreaterThan(0);
-
-      expect(first.sessionId).toBe(second.sessionId);
-    },
-    { 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);
-      // Should have at least one tool message (the echo command)
-      const toolMessages = result.messages.filter((m) => m.role === "tool");
-      expect(toolMessages.length).toBeGreaterThan(0);
-      // Tool message should contain the output
-      const toolContent = toolMessages[0]?.content ?? "";
-      expect(toolContent).toContain("TOOL_DETAIL_TEST");
-      // Should have assistant messages with tool_calls
-      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__/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

@@ -0,0 +1,56 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import { HermesAcpClient } from "../../src/acp-client.js";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+describe("HermesAcpClient", () => {
+  let client: HermesAcpClient;
+
+  beforeEach(() => {
+    client = new HermesAcpClient();
+  });
+
+  afterEach(async () => {
+    await client.close();
+  });
+
+  it(
+    "connect() returns a UUID sessionId",
+    async () => {
+      const sessionId = await client.connect(process.cwd());
+      expect(typeof sessionId).toBe("string");
+      expect(sessionId).toMatch(UUID_RE);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+
+  it(
+    "prompt() returns a non-empty text response",
+    async () => {
+      await client.connect(process.cwd());
+      const result = await client.prompt("Reply with exactly the word: PONG");
+      expect(typeof result.text).toBe("string");
+      expect(result.text.length).toBeGreaterThan(0);
+      expect(typeof result.sessionId).toBe("string");
+      expect(result.sessionId).toMatch(UUID_RE);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+
+  it(
+    "prompt() can be called twice on the same session (resume)",
+    async () => {
+      await client.connect(process.cwd());
+
+      const first = await client.prompt("Say the word ALPHA and nothing else.");
+      expect(first.text.length).toBeGreaterThan(0);
+
+      const second = await client.prompt("Now say the word BETA and nothing else.");
+      expect(second.text.length).toBeGreaterThan(0);
+
+      expect(first.sessionId).toBe(second.sessionId);
+    },
+    { 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/package.json

@@ -18,11 +18,12 @@
     }
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "test:ci": "bun test __tests__/*.test.ts"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/workflow-util-agent": "workspace:^",
     "@uncaged/workflow-protocol": "workspace:^",
     "@uncaged/workflow-util": "workspace:^"
   },
@@ -31,5 +32,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-agent-hermes"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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/tsconfig.json

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

packages/workflow-protocol/README.md

@@ -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

@@ -15,13 +15,23 @@
     }
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/json-cas-fs": "^0.4.0"
+    "@uncaged/json-cas": "^0.5.3",
+    "@uncaged/json-cas-fs": "^0.5.3"
   },
   "devDependencies": {
     "typescript": "^5.8.3"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-protocol"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

packages/workflow-protocol/src/schemas.ts

@@ -60,7 +60,7 @@ export const START_NODE_SCHEMA: JSONSchema = {
 export const STEP_NODE_SCHEMA: JSONSchema = {
   title: "StepNode",
   type: "object",
-  required: ["start", "prev", "role", "output", "detail", "agent"],
+  required: ["start", "prev", "role", "output", "detail", "agent", "startedAtMs", "completedAtMs"],
   properties: {
     start: { type: "string", format: "cas_ref" },
     prev: {
@@ -71,6 +71,8 @@ export const STEP_NODE_SCHEMA: JSONSchema = {
     detail: { type: "string", format: "cas_ref" },
     agent: { type: "string" },
     edgePrompt: { type: "string" },
+    startedAtMs: { type: "integer" },
+    completedAtMs: { type: "integer" },
   },
   additionalProperties: false,
 };

packages/workflow-protocol/src/types.ts

@@ -14,6 +14,10 @@ export type StepRecord = {
   agent: string;
   /** Moderator edge prompt that led to this step. Missing in legacy nodes → "". */
   edgePrompt: string;
+  /** Date.now() before agent spawn */
+  startedAtMs: number;
+  /** Date.now() after agent returns */
+  completedAtMs: number;
 };
 
 // ── 4.2 Workflow 定义 ───────────────────────────────────────────────
@@ -89,6 +93,7 @@ export type StepEntry = {
   detail: CasRef;
   agent: string;
   timestamp: number;
+  durationMs: number;
 };
 
 /** uwf thread steps — start entry */

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/__tests__/build-output-format-instruction.test.ts

@@ -87,7 +87,7 @@ describe("buildOutputFormatInstruction", () => {
     expect(result).toContain("beta: <number>");
   });
 
-  test("lists union of fields from a oneOf schema", () => {
+  test("lists union of fields from a oneOf schema (no discriminant — flat merge)", () => {
     const schema = {
       oneOf: [
         {
@@ -101,12 +101,71 @@ describe("buildOutputFormatInstruction", () => {
       ],
     };
     const result = buildOutputFormatInstruction(schema);
+    // No discriminant detected → falls back to flat merge
     expect(result).toContain("`foo`");
     expect(result).toContain("`bar`");
     expect(result).toContain("foo: <string>");
     expect(result).toContain("bar: true  # true | false");
   });
 
+  test("renders per-variant instructions for discriminated oneOf", () => {
+    const schema = {
+      oneOf: [
+        {
+          type: "object",
+          properties: {
+            $status: { const: "ready" },
+            plan: { type: "string" },
+          },
+          required: ["$status", "plan"],
+        },
+        {
+          type: "object",
+          properties: {
+            $status: { const: "insufficient_info" },
+          },
+          required: ["$status"],
+        },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("Choose ONE of the following variants");
+    expect(result).toContain("When `$status: ready`");
+    expect(result).toContain("When `$status: insufficient_info`");
+    expect(result).toContain("plan: <string>");
+    // The insufficient_info variant should NOT mention plan
+    const insufficientBlock = result.split("When `$status: insufficient_info`")[1];
+    expect(insufficientBlock).not.toContain("plan:");
+  });
+
+  test("renders per-variant for single-enum discriminant", () => {
+    const schema = {
+      oneOf: [
+        {
+          type: "object",
+          properties: {
+            $status: { type: "string", enum: ["approved"] },
+            branch: { type: "string" },
+          },
+          required: ["$status"],
+        },
+        {
+          type: "object",
+          properties: {
+            $status: { type: "string", enum: ["rejected"] },
+            comments: { type: "string" },
+          },
+          required: ["$status"],
+        },
+      ],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("When `$status: approved`");
+    expect(result).toContain("When `$status: rejected`");
+    expect(result).toContain("branch: <string>");
+    expect(result).toContain("comments: <string>");
+  });
+
   test("falls back gracefully for a non-object schema with no properties", () => {
     const result = buildOutputFormatInstruction({ type: "string" });
     expect(result).toContain("schema fields will be extracted automatically");

packages/workflow-util-agent/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@uncaged/workflow-agent-kit",
+  "name": "@uncaged/workflow-util-agent",
   "version": "0.5.0",
   "files": [
     "src",
@@ -15,11 +15,12 @@
     }
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "test:ci": "bun test"
   },
   "dependencies": {
-    "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/json-cas-fs": "^0.4.0",
+    "@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",
@@ -30,5 +31,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-util-agent"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

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>");
-}

packages/workflow-util-agent/src/build-output-format-instruction.ts

@@ -166,14 +166,109 @@ function buildFieldList(properties: SchemaProperty[]): string {
     .join("\n");
 }
 
+/**
+ * Detect the discriminant property name from a oneOf schema.
+ * Returns the property name if all variants share a const/single-enum string property, else null.
+ */
+function detectDiscriminant(variants: JSONSchema[]): string | null {
+  // Find property names that appear in ALL variants with const or single-enum
+  const candidateNames = new Set<string>();
+
+  for (const variant of variants) {
+    const props = variant.properties as Record<string, JSONSchema> | null | undefined;
+    if (typeof props !== "object" || props === null) return null;
+
+    for (const [name, propSchema] of Object.entries(props)) {
+      const isConst =
+        propSchema.const !== undefined ||
+        (Array.isArray(propSchema.enum) && propSchema.enum.length === 1);
+      if (isConst) candidateNames.add(name);
+    }
+  }
+
+  // Check which candidate appears in ALL variants
+  for (const name of candidateNames) {
+    const allHaveIt = variants.every((v) => {
+      const props = v.properties as Record<string, JSONSchema> | null | undefined;
+      if (typeof props !== "object" || props === null) return false;
+      const propSchema = props[name];
+      if (!propSchema) return false;
+      return (
+        propSchema.const !== undefined ||
+        (Array.isArray(propSchema.enum) && propSchema.enum.length === 1)
+      );
+    });
+    if (allHaveIt) return name;
+  }
+
+  return null;
+}
+
+function getConstValue(propSchema: JSONSchema): string {
+  if (propSchema.const !== undefined) return String(propSchema.const);
+  if (Array.isArray(propSchema.enum) && propSchema.enum.length === 1)
+    return String(propSchema.enum[0]);
+  return "<unknown>";
+}
+
+function buildVariantBlock(variant: JSONSchema, discriminant: string): string {
+  const props = extractSchemaProperties(variant);
+  const value = getConstValue(
+    ((variant.properties as Record<string, JSONSchema>) ?? {})[discriminant] ?? {},
+  );
+  const yamlExample = buildYamlExampleBlock(props);
+  const fieldList = buildFieldList(props);
+
+  return `### When \`${discriminant}: ${value}\`
+
+\`\`\`
+${yamlExample}
+\`\`\`
+
+Fields:
+${fieldList}`;
+}
+
 /**
  * Build a concise output format instruction block for an agent role.
  *
- * The instruction describes the expected frontmatter markdown format and lists
- * the meta fields derived from the JSON Schema.  It is prepended to the agent's
- * system prompt so the deliverable format is the first thing the agent sees.
+ * For discriminated union schemas (oneOf with a shared const/$status field),
+ * renders per-variant instructions so the agent knows exactly which fields
+ * belong to which outcome.
+ *
+ * For flat object schemas, renders a single YAML example block.
  */
 export function buildOutputFormatInstruction(schema: JSONSchema): string {
+  // Check for discriminated union (oneOf with shared discriminant)
+  const unionKey = Array.isArray(schema.oneOf)
+    ? "oneOf"
+    : Array.isArray(schema.anyOf)
+      ? "anyOf"
+      : null;
+
+  if (unionKey !== null) {
+    const variants = schema[unionKey] as JSONSchema[];
+    const discriminant = detectDiscriminant(variants);
+
+    if (discriminant !== null && variants.length > 1) {
+      const variantBlocks = variants.map((v) => buildVariantBlock(v, discriminant)).join("\n\n");
+
+      return `## Deliverable Format
+
+Your response MUST begin with a YAML frontmatter block followed by your markdown work.
+
+Choose ONE of the following variants based on your outcome:
+
+${variantBlocks}
+
+The frontmatter is the **primary deliverable** — the engine reads it directly.
+Output ONLY the fields listed for your chosen variant. Do not add extra fields that are not specified in the schema.
+
+Focus exclusively on YOUR role's deliverable. Do not perform actions outside your role's scope.`;
+    }
+  }
+
+  // Flat object schema fallback
   const properties = extractSchemaProperties(schema);
   const yamlExample = buildYamlExampleBlock(properties);
   const fieldList = buildFieldList(properties);

packages/workflow-util-agent/src/context.ts

@@ -128,6 +128,8 @@ async function buildHistory(
       detail: step.detail,
       agent: step.agent,
       edgePrompt: step.edgePrompt ?? "",
+      startedAtMs: step.startedAtMs,
+      completedAtMs: step.completedAtMs,
       content,
     });
   }

packages/workflow-util-agent/src/run.ts

@@ -59,6 +59,8 @@ async function writeStepNode(options: {
   detailHash: CasRef;
   agentName: string;
   edgePrompt: string;
+  startedAtMs: number;
+  completedAtMs: number;
 }): Promise<CasRef> {
   const payload: StepNodePayload = {
     start: options.startHash,
@@ -68,6 +70,8 @@ async function writeStepNode(options: {
     detail: options.detailHash,
     agent: options.agentName,
     edgePrompt: options.edgePrompt,
+    startedAtMs: options.startedAtMs,
+    completedAtMs: options.completedAtMs,
   };
   const hash = await options.store.put(options.schemas.stepNode, payload);
   const node = options.store.get(hash);
@@ -94,6 +98,8 @@ async function persistStep(options: {
   outputHash: CasRef;
   detailHash: CasRef;
   agentName: string;
+  startedAtMs: number;
+  completedAtMs: number;
 }): Promise<CasRef> {
   const { store, schemas, chain, headHash } = options.ctx.meta;
   return writeStepNode({
@@ -106,6 +112,8 @@ async function persistStep(options: {
     detailHash: options.detailHash,
     agentName: options.agentName,
     edgePrompt: options.ctx.edgePrompt,
+    startedAtMs: options.startedAtMs,
+    completedAtMs: options.completedAtMs,
   });
 }
 
@@ -127,6 +135,7 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       ctx.outputFormatInstruction = buildOutputFormatInstruction(frontmatterSchema);
     }
 
+    const startedAtMs = Date.now();
     let agentResult = await runWithMessage("agent run failed", () => options.run(ctx));
 
     // Preserve the primary detail from the first run — it contains the full
@@ -156,12 +165,14 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
           `Raw output (first 500 chars): ${agentResult.output.slice(0, 500)}`,
       );
     }
-
+    const completedAtMs = Date.now();
     const stepHash = await persistStep({
       ctx,
       outputHash,
       detailHash: primaryDetailHash,
       agentName: agentLabel(options.name),
+      startedAtMs,
+      completedAtMs,
     });
 
     process.stdout.write(`${stepHash}\n`);