fix(cli): remove Chinese text from uwf --help description

Remove the annotation line entirely — the layer names are self-explanatory.

小橘 🍊

.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/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,7 +21,8 @@ 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)
+      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:
       oneOf:
@@ -40,32 +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. Include branch name and worktree path in frontmatter."
+      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:
-        branch: { type: string }
-        worktree: { type: string }
-      required: [branch, worktree]
+      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,12 +95,9 @@ 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.
@@ -106,17 +113,18 @@ roles:
         - properties:
             $status: { const: "rejected" }
             comments: { type: string }
-          required: [$status, comments]
+            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
@@ -143,21 +151,21 @@ roles:
     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"`
       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 --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 ~/repos/workflow`
-         - `git worktree remove ~/repos/workflow-worktrees/fix/<issue-number>-<slug>`
+         - 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:
@@ -176,9 +184,10 @@ graph:
     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 branch {{{branch}}} at {{{worktree}}} for code standards compliance." }
+    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: {{{comments}}}. Fix the issues." }
+    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." }

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

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.2",
+    "@uncaged/json-cas-fs": "^0.5.2",
     "@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__/solve-issue-tea-worktree.test.ts

@@ -13,8 +13,16 @@ 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 () => {
     const yamlContent = await readFile(workflowPath, "utf-8");

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

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

packages/cli-workflow/src/cli.ts

@@ -55,8 +55,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");

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

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/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.2",
+    "@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.2",
+    "@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
 

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

@@ -2,8 +2,6 @@ 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", () => {
   let client: HermesAcpClient;
 
@@ -93,76 +91,3 @@ describe("handleSessionUpdate — helper extraction", () => {
     expect((client as any).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,75 @@
+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 },
+  );
+
+  // TODO(#435): flaky — depends on live LLM; mock or move to integration suite
+  it.skip(
+    "prompt() collects structured messages including tool calls",
+    async () => {
+      await client.connect(process.cwd());
+      const result = await client.prompt("Run this command: echo TOOL_DETAIL_TEST");
+      expect(result.messages.length).toBeGreaterThan(0);
+      const toolMessages = result.messages.filter((m) => m.role === "tool");
+      expect(toolMessages.length).toBeGreaterThan(0);
+      const toolContent = toolMessages[0]?.content ?? "";
+      expect(toolContent).toContain("TOOL_DETAIL_TEST");
+      const assistantWithTools = result.messages.filter(
+        (m) => m.role === "assistant" && m.tool_calls !== null,
+      );
+      expect(assistantWithTools.length).toBeGreaterThan(0);
+    },
+    { timeout: 2 * 60 * 1000 },
+  );
+});

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

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

packages/workflow-agent-hermes/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.2",
+    "@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/hermes.ts

@@ -1,12 +1,12 @@
 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";

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.2",
+    "@uncaged/json-cas-fs": "^0.5.2"
   },
   "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-util-agent/README.md

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

packages/workflow-util-agent/package.json

@@ -1,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.2",
+    "@uncaged/json-cas-fs": "^0.5.2",
     "@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/package.json

@@ -20,5 +20,15 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "directory": "packages/workflow-util"
+  },
+  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+  },
+  "license": "MIT"
 }

scripts/publish-all.mjs

@@ -18,8 +18,7 @@ const dryRun = args.includes("--dry-run");
 const publishOrder = [
   "workflow-protocol",
   "workflow-util",
-  "workflow-moderator",
-  "workflow-agent-kit",
+  "workflow-util-agent",
   "workflow-agent-hermes",
   "workflow-agent-builtin",
   "cli-workflow",

tsconfig.json

@@ -20,8 +20,7 @@
   "references": [
     { "path": "packages/workflow-util" },
     { "path": "packages/workflow-protocol" },
-    { "path": "packages/workflow-moderator" },
-    { "path": "packages/workflow-agent-kit" },
+    { "path": "packages/workflow-util-agent" },
     { "path": "packages/workflow-agent-hermes" },
     { "path": "packages/workflow-agent-builtin" },
     { "path": "packages/cli-workflow" }