fix: StepOutput.sessionId → string | null, legacy fallback → null

Breaking changes:
- AgentRunResult now requires sessionId field
- AgentOptions now requires continue function
- Agent CLI outputs JSON {stepHash, sessionId} instead of plain CAS hash
- Engine parses JSON output (with legacy CAS hash fallback)

New features:
- Frontmatter validation retry: if agent output lacks valid frontmatter,
  engine calls agent.continue() up to 2 times with correction message
- Session tracking: sessionId flows from agent → engine → StepOutput
- Hermes agent: session parse failure is now a hard error (no raw text fallback)
- Hermes agent: supports --resume for continue sessions

Closes #384

.env.example

@@ -1,40 +0,0 @@
-# ──────────────────────────────────────────────
-# Workflow Engine — Environment Variables
-# ──────────────────────────────────────────────
-# Copy this file to .env and fill in the values.
-
-# ── Cursor Agent ──
-
-# CLI command to invoke the Cursor agent (required for develop workflow)
-WORKFLOW_CURSOR_COMMAND=
-
-# Model override for Cursor agent
-WORKFLOW_CURSOR_MODEL=
-
-# Timeout in milliseconds for Cursor agent operations
-WORKFLOW_CURSOR_TIMEOUT=
-
-# ── Hermes Agent (used by develop tester/committer + solve-issue) ──
-
-# CLI command to invoke the Hermes agent (absolute path required)
-WORKFLOW_HERMES_COMMAND=
-
-# Model override for Hermes agent
-WORKFLOW_HERMES_MODEL=
-
-# Timeout in milliseconds for Hermes agent operations
-WORKFLOW_HERMES_TIMEOUT=
-
-# ── Storage ──
-
-# Override the workflow storage root directory
-# Default: ~/.uncaged/workflow
-WORKFLOW_STORAGE_ROOT=
-
-# Gateway secret for the serve command
-WORKFLOW_DASHBOARD_SECRET=
-
-# ── Display ──
-
-# Set to any value to disable colored output
-# NO_COLOR=1

.gitignore

@@ -9,3 +9,5 @@ bunfig.toml
 xiaoju/
 solve-issue-entry.ts
 packages/workflow-template-develop/develop.esm.js
+.DS_Store
+*.py

.workflows/solve-issue.yaml

@@ -0,0 +1,167 @@
+name: "solve-issue"
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
+roles:
+  planner:
+    description: "Analyzes issue and outputs a TDD test spec"
+    goal: "You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: |
+      On first run (no previous steps):
+      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
+      2. Read CLAUDE.md (or equivalent project conventions file) to understand coding standards
+      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
+      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)
+    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)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [ready, insufficient_info]
+        plan:
+          type: string
+      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."
+    capabilities:
+      - coding
+    procedure: |
+      1. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's meta.plan)
+      2. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
+      3. Write tests first based on the spec
+      4. Implement the code to make tests pass
+      5. Ensure `bun run build` passes with no errors
+      6. Run `bun test` to verify all tests pass
+    output: "List all files changed and provide a summary. Frontmatter must include: status (done or failed)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [done, failed]
+      required: [status]
+  reviewer:
+    description: "Code standards compliance check"
+    goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: |
+      Hard checks (must all pass):
+      1. `bun run build` — no build errors
+      2. `bunx biome check` — no lint violations
+      3. 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)
+      - 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: approved (true or false)."
+    frontmatter:
+      type: object
+      properties:
+        approved:
+          type: boolean
+      required: [approved]
+  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: |
+      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 meta.plan)
+      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)."
+    frontmatter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [passed, fix_code, fix_spec]
+      required: [status]
+  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: |
+      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 --title "..." --description "..."`
+         - PR description must follow the project template: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+    output: "Include PR URL on success or error log on failure. Frontmatter must include: success (true or false)."
+    frontmatter:
+      type: object
+      properties:
+        success:
+          type: boolean
+      required: [success]
+conditions:
+  insufficientInfo:
+    description: "Planner determined there's not enough info to proceed"
+    expression: "$last('planner').status = 'insufficient_info'"
+  devFailed:
+    description: "Developer failed to implement"
+    expression: "$last('developer').status = 'failed'"
+  rejected:
+    description: "Reviewer rejected the implementation"
+    expression: "$last('reviewer').approved = false"
+  fixCode:
+    description: "Tester found code issues"
+    expression: "$last('tester').status = 'fix_code'"
+  fixSpec:
+    description: "Tester found spec issues"
+    expression: "$last('tester').status = 'fix_spec'"
+  hookFailed:
+    description: "Push hook failed"
+    expression: "$last('committer').success = false"
+graph:
+  $START:
+    - role: "planner"
+  planner:
+    - role: "$END"
+      condition: "insufficientInfo"
+    - role: "developer"
+  developer:
+    - role: "$END"
+      condition: "devFailed"
+    - role: "reviewer"
+  reviewer:
+    - role: "developer"
+      condition: "rejected"
+    - role: "tester"
+  tester:
+    - role: "developer"
+      condition: "fixCode"
+    - role: "planner"
+      condition: "fixSpec"
+    - role: "committer"
+  committer:
+    - role: "developer"
+      condition: "hookFailed"
+    - role: "$END"

CLAUDE.md

@@ -2,46 +2,41 @@
 
 ## Project Overview
 
-This monorepo implements a workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file with an XXH64 hash as its version identifier. Shared types live in `@uncaged/workflow-protocol`; bundle authors typically depend on `@uncaged/workflow-runtime`.
+This monorepo implements a stateless workflow engine driven by a single-step CLI (`uwf`). 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.
 
 ### Key Terms
 
 | Concept | What it is |
 |---------|-----------|
-| **Workflow** | A single-file ESM module that exports `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash (Crockford Base32). |
-| **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
-| **Thread** | A single execution of a workflow, identified by a ULID. State lives in CAS (linked nodes); active threads indexed in `threads.json`; completed rows in `history/*.jsonl`. Debug logs use `.info.jsonl`. |
-| **Role** | A named actor within a workflow. Each role produces output with typed `meta`. |
-| **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
+| **Workflow** | A YAML definition (`WorkflowPayload`) with roles, conditions, and a routing graph. Stored as a CAS node, identified by its XXH64 hash. |
+| **Thread** | A single execution of a workflow, identified by a ULID. State is an immutable CAS chain; active threads indexed in `threads.yaml`; completed threads in `history.jsonl`. |
+| **Role** | A named actor within a workflow. Each role has a system prompt and a JSON Schema `outputSchema`. |
+| **Moderator** | JSONata-based graph evaluator — determines the next role (or `$END`) with zero LLM cost. |
+| **Agent** | An external CLI command (`uwf-hermes`, etc.) spawned by `uwf thread step`. Produces frontmatter markdown output. |
+| **CAS** | Content-Addressed Storage via `@uncaged/json-cas` — all workflow definitions, thread nodes, and outputs are immutable CAS nodes. |
+| **Registry** | `~/.uncaged/workflow/registry.yaml` — maps workflow names to current CAS hashes. |
 
 ### Monorepo Structure
 
 ```
 workflow/
   packages/
-    workflow-protocol/              # @uncaged/workflow-protocol — shared types + Result
-    workflow-runtime/               # @uncaged/workflow-runtime — createWorkflow, type re-exports
-    workflow-util/                  # @uncaged/workflow-util — Base32, ULID, logger, storage paths, refs helpers
-    workflow-reactor/               # @uncaged/workflow-reactor — LLM fn + thread reactor (tool calls)
-    workflow-cas/                   # @uncaged/workflow-cas — CAS store, hash, Merkle
-    workflow-register/              # @uncaged/workflow-register — bundle validation, registry YAML, model resolution
-    workflow-execute/               # @uncaged/workflow-execute — engine, extract, fork, GC, workflowAsAgent
-    cli-workflow/                   # @uncaged/cli-workflow — uncaged-workflow CLI
-    workflow-agent-cursor/          # @uncaged/workflow-agent-cursor
-    workflow-agent-hermes/          # @uncaged/workflow-agent-hermes
-    workflow-agent-llm/             # @uncaged/workflow-agent-llm
-    workflow-agent-react/             # @uncaged/workflow-agent-react
-    workflow-util-agent/            # @uncaged/workflow-util-agent — buildAgentPrompt, spawnCli
-    workflow-template-develop/      # @uncaged/workflow-template-develop
-    workflow-template-solve-issue/  # @uncaged/workflow-template-solve-issue
-    workflow-dashboard/             # @uncaged/workflow-dashboard — React dashboard (private app)
-  docs/             # RFCs, conventions
-  biome.json        # root Biome config
-  tsconfig.json     # root TypeScript config
+    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 — JSONata graph evaluator
+    workflow-agent-kit/   # @uncaged/workflow-agent-kit — 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
+  legacy-packages/       # Archived packages (preserved for reference, not active)
+  examples/              # Workflow YAML examples (solve-issue.yaml)
+  docs/                  # Architecture docs
+  biome.json             # root Biome config
+  tsconfig.json          # root TypeScript config
 ```
 
-- Execution stack layers: `workflow-protocol` → (`workflow-runtime`, `workflow-util`, `workflow-reactor`) → (`workflow-cas`, `workflow-register`) → `workflow-execute` → `cli-workflow`
+- Dependency layers: `workflow-protocol` → (`workflow-util`, `workflow-moderator`) → `workflow-agent-kit` → `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)
 
 ## Language & Paradigm
 
@@ -109,8 +104,6 @@ type WorkflowEntry = {
 - Always named exports, never default exports
 - One module = one responsibility, filename = purpose
 
-Workflow bundles (`.esm.js`) follow the same rule: export `const run` and `const descriptor`, not `export default`.
-
 ### Folder Module Discipline
 
 Every folder under `src/` is a **module boundary**. Four rules:
@@ -136,10 +129,10 @@ export { createCasStore } from "../cas/cas.js";
 
 // ❌ Bad — types defined in index.ts
 // in cas/index.ts:
-export type CasStore = { ... };  // should be in cas/types.ts
+export type CasStore = { ... }; // should be in cas/types.ts
 ```
 
-**Exception**: The package-level `src/index.ts` is the public API surface and re-exports from folder `index.ts` files. Files that remain at `src/` root (e.g. `types.ts`, `workflow-as-agent.ts`) are not inside a folder module and follow normal rules.
+**Exception**: The package-level `src/index.ts` is the public API surface and re-exports from folder `index.ts` files. Files that remain at `src/` root (e.g. `types.ts`) are not inside a folder module and follow normal rules.
 
 ## Naming
 
@@ -160,7 +153,7 @@ Workflow names use **verb-first** kebab-case:
 ### ID Encoding
 
 All IDs use **Crockford Base32**:
-- Bundle hash: XXH64 → 13-char Crockford Base32
+- CAS hash: XXH64 → 13-char Crockford Base32
 - Thread ID: ULID → 26-char Crockford Base32 (10 timestamp + 16 random)
 
 ## Error Handling
@@ -189,7 +182,7 @@ import { createLogger } from "@uncaged/workflow-util";
 const log = createLogger();
 
 // Each call site has a fixed 8-char Crockford Base32 tag
-log("4KNMR2PX", "Loading workflow bundle...");
+log("4KNMR2PX", "Loading workflow...");
 log("7BQST3VW", `Role ${role} started`);
 ```
 
@@ -204,7 +197,7 @@ log("7BQST3VW", `Role ${role} started`);
 
 ### Why fixed tags?
 
-- `grep "4KNMR2PX"` in `.info.jsonl` → instant code location
+- `grep "4KNMR2PX"` in logs → instant code location
 - No need for file/line info in the log — tag is the locator
 - Survives refactoring (tag stays the same when code moves)
 
@@ -221,74 +214,76 @@ console.log(result);
 
 Do NOT use `await import()` in production code. Always use static top-level `import`.
 
-**Exception**: The bundle loader and `extractBundleExports` dynamically import user workflow files at runtime.
-
-```ts
-// Dynamic import required: user bundle path resolved at runtime
-const mod = await import(bundlePath);
-```
-
 Test files (`__tests__/**`) are exempt.
 
 ## Toolchain
 
 | Tool | Purpose |
 |------|---------|
-| **bun** | Package manager + runtime + test runner |
+| **bun** | Package manager + runtime |
 | **TypeScript** | Type checking (strict mode) |
 | **Biome** | Lint + format (replaces ESLint + Prettier) |
+| **vitest** | Test runner (`cli-workflow` uses vitest; other packages use `bun test`) |
 
-### Commands
+### Development Workflow
 
 ```bash
-bun run check       # tsc --build + biome check
-bun run format      # biome format --write
-bun test            # run tests
+# ── Setup ──
+bun install                 # install all workspace dependencies
+
+# ── Daily development ──
+bun run build               # tsc --build (all packages, dependency order)
+bun run check               # tsc --build + biome check + lint-log-tags
+bun run format              # biome format --write
+bun test                    # run tests across all packages
+
+# ── Before committing ──
+bun run check               # must pass — typecheck + lint + log tag validation
+bun test                    # must pass — all package tests
 ```
 
-### Version Management & Publishing
+### Publishing
 
-All public `@uncaged/*` packages are published to **npmjs.org** via `@changesets/cli` with **fixed mode** (all packages share the same version number). `workflow-dashboard` is private and excluded.
+All public `@uncaged/*` packages are published to **npmjs.org** with **fixed mode** (all packages share the same version number).
 
 ```bash
-# 1. After making changes, add a changeset describing the change
+# 1. Add a changeset describing the change
 bun changeset
 
-# 2. Before release, bump all package versions + generate CHANGELOGs
+# 2. Bump all package versions + generate CHANGELOGs
 bun version
 
-# 3. Build, test, and publish to npmjs
+# 3. Build, test, and publish (runs scripts/publish-all.mjs)
 bun release
+
+# Or publish manually with a tag:
+node scripts/publish-all.mjs --tag alpha
+node scripts/publish-all.mjs --dry-run    # preview without publishing
 ```
 
 - `workspace:^` dependencies resolve to `^x.y.z` on publish
+- Publish order defined in `scripts/publish-all.mjs` (dependency order)
 - Changesets config: `.changeset/config.json` (fixed mode, public access)
-- Each package has auto-generated `CHANGELOG.md`
 
-### Consuming @uncaged/* Packages
-
-External workflow repos just `bun install` — packages come from npmjs like any other dependency. No special registry config needed.
-
-### End-to-end: Monorepo → Registry → Workspace → Bundle
+### End-to-end: Author → Register → Run
 
 ```
-workflow/ (monorepo)           — engine, runtime, templates, agents
-  │  bun release               — build + test + changeset publish
+examples/solve-issue.yaml       — write a workflow YAML definition
+  │  uwf workflow put
   ▼
-npmjs.org                      — @uncaged/* scoped packages (public)
-  │  bun install
+~/.uncaged/workflow/cas/        — Workflow stored as CAS node
+~/.uncaged/workflow/registry.yaml — name → hash mapping updated
+  │  uwf thread start <name> -p "..."
   ▼
-my-workflows/ (workspace)     — normal package.json
-  │  bun run build:develop     — bun build → single .esm.js
+~/.uncaged/workflow/threads.yaml — new thread head pointer
+  │  uwf thread step <thread-id>
   ▼
-uncaged-workflow workflow add  — register bundle locally
-uncaged-workflow run           — execute workflow
+moderator → agent → extract      — one step per invocation, repeat until $END
 ```
 
-1. **Monorepo changes** → `bun changeset` (describe change) → `bun version` (bump) → `bun release` (publish)
-2. **Workspace** → `bun install` fetches latest from npmjs
-3. **Build** → produces single-file ESM bundle with `@uncaged/*` as externals
-4. **Register & Run** → `uncaged-workflow workflow add <name> <bundle>` then `uncaged-workflow run <name>`
+1. **Author** — write a workflow YAML file with roles, conditions, and graph
+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
 
 ## Commit Convention
 
@@ -296,5 +291,5 @@ uncaged-workflow run           — execute workflow
 <type>(<scope>): <description>
 
 type: feat | fix | refactor | docs | chore | test
-scope: workflow | cli | rfc-001 | ...
+scope: workflow | cli | moderator | agent-kit | hermes | util | protocol | ...
 ```

README.md

@@ -1,71 +1,93 @@
 # @uncaged/workflow
 
-A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32).
+A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, JSONata routing conditions, and a directed graph. Threads are immutable CAS-linked chains — each `uwf thread step` runs one moderator→agent→extract cycle and exits.
 
-## Core Concepts
+## Package Map
 
-| Concept | Description |
-|---------|-------------|
-| **Workflow** | A single-file ESM module exporting `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash. |
-| **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
-| **Thread** | A single execution of a workflow, identified by a ULID. CAS-backed chain plus `threads.json` / `history/*.jsonl`; `.info.jsonl` for debug logs. |
-| **Role** | A named actor within a workflow. Each role produces output with typed `meta`. Roles live inside template packages (`src/roles/`). |
-| **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
-| **CAS** | Content-Addressed Storage — bundles are immutable and addressed by hash. |
+| Package | npm | Role |
+|---------|-----|------|
+| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI binary — thread lifecycle, workflow registry, CAS inspection, setup |
+| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `WorkflowConfig`, etc.) |
+| `workflow-moderator` | `@uncaged/workflow-moderator` | JSONata graph evaluator — determines next role or `$END` |
+| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, two-layer extract pipeline |
+| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` agent — spawns Hermes chat, captures session |
+| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing |
 
-## Monorepo Packages
-
-```
-packages/
-  workflow/                      # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
-  cli-workflow/                  # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
-  workflow-template-develop/     # @uncaged/workflow-template-develop — develop workflow template (includes roles)
-  workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
-  workflow-agent-hermes/         # @uncaged/workflow-agent-hermes — Hermes agent adapter
-  workflow-agent-cursor/         # @uncaged/workflow-agent-cursor — Cursor agent adapter
-  workflow-agent-llm/            # @uncaged/workflow-agent-llm — LLM agent adapter
-  workflow-util-agent/           # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
-```
-
-Managed with **bun workspace** using the `workspace:*` protocol.
+External: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (CAS store + JSON Schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
 
 ## Quick Start
 
 ```bash
-# Install dependencies
-bun install
+# 1. Configure provider and model
+uwf setup
 
-# Build all packages
-bun run build
+# 2. Register a workflow from YAML
+uwf workflow put examples/solve-issue.yaml
 
-# Register a workflow bundle
-uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
+# 3. Start a thread
+uwf thread start solve-issue -p "Fix the login redirect bug"
 
-# Run a workflow
-uncaged-workflow run solve-issue --prompt "Fix bug #42"
+# 4. Execute steps (one at a time, until done)
+uwf thread step <thread-id>
 ```
 
-## CLI Usage
+## CLI Commands
 
-```bash
-uncaged-workflow                   # Print full command usage (exits with status 1)
-uncaged-workflow workflow list     # List registered workflows
-uncaged-workflow run <name>        # Start a workflow thread
-uncaged-workflow thread list       # List all threads
-uncaged-workflow thread show <id>  # Inspect a thread
-uncaged-workflow skill             # Agent-consumable reference docs
-```
+### Thread
 
-Run `uncaged-workflow` with no arguments to print usage, or `uncaged-workflow skill cli` for the full CLI skill reference.
+| Command | Description |
+|---------|-------------|
+| `uwf thread start <workflow> -p <prompt>` | Create a thread (no execution) |
+| `uwf thread step <thread-id> [--agent <cmd>]` | Execute one moderator→agent→extract cycle |
+| `uwf thread show <thread-id>` | Show head pointer and done status |
+| `uwf thread list [--all]` | List threads (`--all` includes archived) |
+| `uwf thread steps <thread-id>` | List all steps chronologically |
+| `uwf thread read <thread-id> [--quota N]` | Render thread as readable markdown |
+| `uwf thread fork <step-hash>` | Fork from a specific step |
+| `uwf thread step-details <step-hash>` | Dump full detail node |
+| `uwf thread kill <thread-id>` | Terminate and archive |
+
+### Workflow
+
+| Command | Description |
+|---------|-------------|
+| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
+| `uwf workflow show <name-or-hash>` | Show workflow definition |
+| `uwf workflow list` | List registered workflows |
+
+### CAS
+
+| Command | Description |
+|---------|-------------|
+| `uwf cas get <hash>` | Read a CAS node |
+| `uwf cas put <type-hash> <data>` | Store a node |
+| `uwf cas has <hash>` | Check existence |
+| `uwf cas refs <hash>` | List direct references |
+| `uwf cas walk <hash>` | Recursive traversal |
+| `uwf cas reindex` | Rebuild type index |
+| `uwf cas schema list` | List schemas |
+| `uwf cas schema get <hash>` | Show a schema |
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `uwf setup` | Interactive provider/model/agent configuration |
+| `uwf setup --provider ... --base-url ... --api-key ... --model ...` | Non-interactive setup |
+
+Config stored in `~/.uncaged/workflow/config.yaml`. API keys in `~/.uncaged/workflow/.env`.
 
 ## Development
 
 ```bash
-bun run check    # Biome lint + format check
-bun run format   # Auto-format with Biome
-bun test         # Run tests
+bun install --no-cache     # Install dependencies
+bun run check              # tsc + biome + lint-log-tags
+bun run format             # Auto-format with Biome
+bun test                   # Run all tests
 ```
 
+Managed with **bun workspace**. See [CLAUDE.md](CLAUDE.md) for coding conventions.
+
 ## Architecture
 
-See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.
+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.

biome.json

@@ -5,6 +5,8 @@
       "**",
       "!**/dist",
       "!**/node_modules",
+      "!**/legacy-packages",
+      "!scripts",
       "!packages/workflow/workflow",
       "!xiaoju/scripts/bundle.ts"
     ]
@@ -36,7 +38,7 @@
       }
     },
     {
-      "includes": ["**/*.d.ts"],
+      "includes": ["**/*.d.ts", "**/vitest.config.*"],
       "linter": {
         "rules": {
           "style": {
@@ -44,6 +46,16 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/cli.ts", "**/setup.ts"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
     }
   ],
   "linter": {

docs/architecture.md

@@ -1,268 +1,495 @@
-# Uncaged workflow — Architecture
+# Workflow Engine — Architecture
 
-**Last updated:** 2026-05-09
+**Last updated:** 2026-05-19
 
 ---
 
 ## Overview
 
-A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32). No daemon — processes start on demand and exit when done.
+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 **15** Bun workspace packages under `packages/`, using the `workspace:*` protocol.
+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.
 
 ## Package map
 
-Grouped by responsibility (npm name → folder).
-
 | Layer | Package | One-line role |
-|-------|---------|----------------|
-| Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types and `Result` helpers; peer `zod` only — no other workspace deps. |
-| Author API | `@uncaged/workflow-runtime` → `workflow-runtime` | `createWorkflow` and re-exports of protocol workflow types for bundle authors. |
-| Shared infra | `@uncaged/workflow-util` → `workflow-util` | Base32/ULID, logger, storage root paths, global CAS dir, ref-field helpers. |
-| LLM plumbing | `@uncaged/workflow-reactor` → `workflow-reactor` | `createLlmFn`, `createThreadReactor`, and related tool-call types for threaded LLM invocation. |
-| CAS | `@uncaged/workflow-cas` → `workflow-cas` | `CasStore` implementation, XXH64 hashing, Merkle helpers over CAS payloads. |
-| Registry / bundles | `@uncaged/workflow-register` → `workflow-register` | Bundle validation & dynamic export extraction, `workflow.yaml` registry I/O, provider/model resolution. |
-| Engine | `@uncaged/workflow-execute` → `workflow-execute` | Thread execution, worker entry path, fork/GC, extract pipeline, `workflowAsAgent`. |
-| CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uncaged-workflow` binary (depends on engine, registry, CAS, protocol, util, runtime). |
-| Agent adapters | `@uncaged/workflow-agent-cursor` → `workflow-agent-cursor` | `AgentFn` via `cursor-agent` CLI + workspace extraction. |
-| | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `AgentFn` via `hermes chat` CLI. |
-| | `@uncaged/workflow-agent-llm` → `workflow-agent-llm` | `AgentFn` via OpenAI-compatible HTTP (`LlmProvider` from runtime). |
-| Agent shared | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `buildAgentPrompt`, `spawnCli` for CLI-backed agents. |
-| Templates | `@uncaged/workflow-template-develop` → `workflow-template-develop` | Develop workflow definition, roles, descriptor builder. |
-| | `@uncaged/workflow-template-solve-issue` → `workflow-template-solve-issue` | Solve-issue workflow definition, roles, descriptor builder. |
-| Dashboard | `@uncaged/workflow-dashboard` → `workflow-dashboard` | Private Vite + React app (`src/main.tsx`); only `react` / `react-dom` dependencies — no workspace packages. |
+|-------|---------|---------------|
+| 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` | JSONata-based graph evaluator: given a `WorkflowPayload` and `ModeratorContext`, 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: 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. |
 
-## Dependency graph (workspace packages)
+### External dependencies
 
-Bottom-up layering for the execution stack:
+| Package | Role |
+|---------|------|
+| `@uncaged/json-cas` | Content-addressed store API, XXH64 hashing, JSON Schema registration and validation. |
+| `@uncaged/json-cas-fs` | Filesystem backend for `json-cas`. |
+| `jsonata` | JSONata expression evaluator (used by `workflow-moderator`). |
+| `commander` | CLI argument parsing (used by `cli-workflow`). |
+| `dotenv` | Loads `.env` files for API keys. |
+| `yaml` | YAML parse/stringify. |
+
+## Dependency graph
 
 ```mermaid
 flowchart BT
+  subgraph External
+    jcas["@uncaged/json-cas"]
+    jcasfs["@uncaged/json-cas-fs"]
+  end
   subgraph L0["Layer 0 — contract"]
     protocol["@uncaged/workflow-protocol"]
   end
-  subgraph L1["Layer 1 — on protocol"]
-    runtime["@uncaged/workflow-runtime"]
+  subgraph L1["Layer 1 — shared"]
     util["@uncaged/workflow-util"]
-    reactor["@uncaged/workflow-reactor"]
+    moderator["@uncaged/workflow-moderator"]
   end
-  subgraph L2["Layer 2 — protocol + util"]
-    cas["@uncaged/workflow-cas"]
-    register["@uncaged/workflow-register"]
+  subgraph L2["Layer 2 — agent framework"]
+    kit["@uncaged/workflow-agent-kit"]
   end
-  subgraph L3["Layer 3 — engine"]
-    execute["@uncaged/workflow-execute"]
+  subgraph L3["Layer 3 — agent implementations"]
+    hermes["@uncaged/workflow-agent-hermes"]
   end
   subgraph L4["Layer 4 — CLI"]
     cli["@uncaged/cli-workflow"]
   end
-  runtime --> protocol
+  protocol --> jcasfs
   util --> protocol
-  reactor --> protocol
-  cas --> protocol
-  cas --> util
-  register --> protocol
-  register --> util
-  execute --> protocol
-  execute --> runtime
-  execute --> util
-  execute --> cas
-  execute --> reactor
-  execute --> register
+  moderator --> protocol
+  kit --> protocol
+  kit --> util
+  kit --> jcas
+  kit --> jcasfs
+  hermes --> kit
+  hermes --> jcas
   cli --> protocol
   cli --> util
-  cli --> cas
-  cli --> execute
-  cli --> register
-  cli --> runtime
+  cli --> kit
+  cli --> moderator
+  cli --> jcas
+  cli --> jcasfs
 ```
 
-**Adjacent consumers** (not in the main CLI stack):
+## Workflow definition
 
-- `@uncaged/workflow-util-agent` → `@uncaged/workflow-runtime`
-- `@uncaged/workflow-agent-llm` → `@uncaged/workflow-runtime`
-- `@uncaged/workflow-agent-cursor` → `@uncaged/workflow-runtime`, `@uncaged/workflow-util-agent`, `zod`
-- `@uncaged/workflow-agent-hermes` → `@uncaged/workflow-runtime`, `@uncaged/workflow-util-agent`
-- `@uncaged/workflow-template-develop` → `@uncaged/workflow-register`, `@uncaged/workflow-runtime`, `zod`
-- `@uncaged/workflow-template-solve-issue` → `@uncaged/workflow-register`, `@uncaged/workflow-runtime`, `zod` (dev-only workspace deps: `@uncaged/workflow-cas`, `@uncaged/workflow-execute` for tests/tooling per `package.json`)
+Workflows are **YAML files** (not ESM bundles). `uwf workflow put <file.yaml>` parses the YAML, registers output schemas as JSON Schema CAS nodes, and stores the `WorkflowPayload` as a CAS node.
 
-## Package roles (detail)
+Example (`examples/solve-issue.yaml`):
 
-- **`workflow-protocol`** — Pure types (`WorkflowFn`, contexts, `CasStore` interface, descriptor shapes), `START` / `END`, `ok` / `err`. Depends only on peer `zod` for schema-related types in signatures.
-- **`workflow-runtime`** — Workflow author surface: `createWorkflow` from `src/create-workflow.js`, re-exports protocol types/constants used when authoring bundles.
-- **`workflow-util`** — Cross-cutting utilities: Crockford Base32, ULID, `createLogger`, `getDefaultWorkflowStorageRoot`, `getGlobalCasDir`, ref normalization; re-exports `ok`/`err` from protocol.
-- **`workflow-cas`** — Filesystem CAS (`createCasStore`), `hashString` / `hashWorkflowBundleBytes`, Merkle node serialization and helpers (`merkle.js`).
-- **`workflow-register`** — Bundle pipeline (`validateWorkflowBundle`, `extractBundleExports`, descriptor builders), registry YAML read/write, `resolveModel` / `splitProviderModelRef`.
-- **`workflow-execute`** — `executeThread`, supervisor/worker wiring (`engine/`), fork/GC/pause gate, `createExtract` + LLM extract helpers (`extract/`), `workflowAsAgent`. Imports `@uncaged/workflow-reactor` for LLM-backed extract/supervisor paths (`extract-fn.ts`, `supervisor.ts`).
-- **`workflow-reactor`** — `createLlmFn`, `createThreadReactor`, and thread tool-invocation types — consumed by `workflow-execute`.
-- **`cli-workflow`** — CLI commands and HTTP/dashboard-related wiring (`hono`, `yaml`); composes register + execute + CAS + util.
-- **`workflow-agent-*`** — Replaceable `AgentFn` implementations (Cursor / Hermes CLIs, or HTTP LLM).
-- **`workflow-util-agent`** — Shared prompt assembly and subprocess spawning for CLI agents.
-- **`workflow-template-*`** — Concrete `WorkflowDefinition` graphs + Zod role schemas + descriptor builders for publishing bundles.
-- **`workflow-dashboard`** — Standalone React UI; no published library entry matching `src/index.ts`.
+```yaml
+name: "solve-issue"
+description: "End-to-end issue resolution"
+roles:
+  planner:
+    description: "Creates implementation plan"
+    goal: "You are a planning agent. Analyze the issue and create a step-by-step plan."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: "Analyze the issue and create a detailed, actionable implementation plan."
+    output: "Output the plan summary and list of concrete steps."
+    meta:
+      type: object
+      properties:
+        plan: { type: string }
+        steps: { type: array, items: { type: string } }
+      required: [plan, steps]
+  developer:
+    description: "Implements code changes"
+    goal: "You are a developer agent. Implement the plan."
+    capabilities:
+      - file-edit
+      - shell
+    procedure: "Implement the plan. Write code, tests, and ensure existing tests pass."
+    output: "List all files changed and provide a summary of the implementation."
+    meta:
+      type: object
+      properties:
+        filesChanged: { type: array, items: { type: string } }
+        summary: { type: string }
+      required: [filesChanged, summary]
+  reviewer:
+    description: "Reviews code changes"
+    goal: "You are a code reviewer. Review the implementation."
+    capabilities:
+      - code-review
+    procedure: "Review the implementation against the plan."
+    output: "Approve or reject with detailed comments."
+    meta:
+      type: object
+      properties:
+        approved: { type: boolean }
+        comments: { type: string }
+      required: [approved, comments]
+conditions:
+  notApproved:
+    description: "Reviewer rejected the implementation"
+    expression: "steps[-1].output.approved = false"
+graph:
+  $START:
+    - role: "planner"
+      condition: null
+  planner:
+    - role: "developer"
+      condition: null
+  developer:
+    - role: "reviewer"
+      condition: null
+  reviewer:
+    - role: "developer"
+      condition: "notApproved"
+    - role: "$END"
+      condition: null
+```
+
+Key properties:
+
+- **`roles`** — inline role definitions; each `meta` is a JSON Schema (stored as its own CAS node on registration)
+- **`conditions`** — named JSONata expressions evaluated against the `ModeratorContext`
+- **`graph`** — `Record<Role | "$START", Transition[]>` — first matching transition wins; `condition: null` = fallback
+- **No agent binding** — agent selection is a deployment concern, configured in `config.yaml`
+- **No Zod** — all schemas are JSON Schema, validated through `@uncaged/json-cas`
 
 ## Three-phase engine loop
 
-Each role round is implemented in `packages/workflow-runtime/src/create-workflow.ts` (`advanceOneRound`): moderator → agent → extractor, with progressive context types from `@uncaged/workflow-protocol`.
+Each `uwf thread step` runs exactly one cycle: moderator → agent → extract. The CLI orchestrates this in `packages/cli-workflow/src/commands/thread.ts` (`cmdThreadStep`).
 
 ```
 ┌─→ Phase 1: MODERATOR
-│   Context: ModeratorContext { threadId, depth, start, steps }
-│   Action:  moderator(ctx) → role name | END
+│   Input:  WorkflowPayload + ModeratorContext { start, steps[] }
+│   Engine: JSONata conditions evaluated against the graph
+│   Output: next role name | $END
 │
 │   Phase 2: AGENT
-│   Context: AgentContext = ModeratorCtx + { currentRole: { name, systemPrompt } }
-│   Action:  agent(ctx) → raw string
+│   Input:  thread-id + role (via argv)
+│   Engine: agent-kit builds context from CAS chain, prepends
+│           output format instruction to system prompt, spawns agent
+│   Output: raw string (frontmatter markdown)
 │
-│   Phase 3: EXTRACTOR
-│   Context: ExtractContext = AgentCtx + { agentContent }
-│   Action:  runtime.extract(schema, extractPrompt, ctx) → typed meta
+│   Phase 3: EXTRACT
+│   Input:  raw agent output + role's meta schema
+│   Engine: two-layer extract (frontmatter fast path → LLM fallback)
+│   Output: CasRef to structured output node
 │
-│   Merge: RoleStep { role, contentHash, meta, refs, timestamp }
-│   Append to steps
-└─────────────────────────────────────────────────────┘
+│   Persist: StepNode { start, prev, role, output, detail, agent }
+│   Update:  threads.yaml head pointer
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-### Context types (progressive)
+### Context types
 
 Defined in `packages/workflow-protocol/src/types.ts`:
 
 ```typescript
-type ModeratorContext<M> = ThreadContext<M>;
-type AgentContext<M> = ModeratorContext<M> & {
-  currentRole: { name: string; systemPrompt: string };
+type StepContext = {
+  role: string;
+  output: unknown;    // CAS node payload, expanded (not hash)
+  detail: CasRef;
+  agent: string;
+};
+
+type ModeratorContext = {
+  start: StartNodePayload;  // { workflow: CasRef, prompt: string }
+  steps: StepContext[];     // chronological, oldest first
+};
+
+type AgentContext = ModeratorContext & {
+  threadId: ThreadId;
+  role: string;
+  store: Store;
+  workflow: WorkflowPayload;
+  outputFormatInstruction: string;
 };
-type ExtractContext<M> = AgentContext<M> & { agentContent: string };
 ```
 
 ### Key properties
 
-- **Moderator is synchronous and pure** — no I/O, no state mutation inside `createWorkflow`’s moderator call path.
-- **Agent receives `AgentContext`** — reads `ctx.currentRole.systemPrompt`; raw output becomes `agentContent` for extract.
-- **Extractor is `WorkflowRuntime.extract`** — supplied by the engine from registry-resolved LLM config (`workflow-execute`); stores agent body in CAS and yields `contentHash` + `refs` on each step (`create-workflow.ts`).
-- **`extractPrompt` is a call parameter** on `RoleDefinition`, not implicit context state.
+- **Moderator** — pure JSONata evaluation; no LLM call, no I/O beyond CAS reads. Evaluates `workflow.graph[currentRole]` transitions in order, returns first match.
+- **Agent** — receives `AgentContext` with thread history + role system prompt + output format instruction. Raw output is frontmatter markdown.
+- **Extractor** — two-layer: tries frontmatter fast-path first (zero LLM cost), falls back to LLM extract if frontmatter is absent or invalid.
+- **Stateless** — each `uwf thread step` is an atomic, self-contained operation. No in-memory state between steps.
 
-## Agent information sources
+## Agent CLI protocol
 
-An agent has exactly three information sources:
+Each agent is an external command invoked by `uwf thread step`:
 
-1. **Prior knowledge** — LLM training, agent memory, agent skills
-2. **Thread context** — `AgentContext` (`start`, `steps`, `currentRole`)
-3. **Derived information** — from 1 & 2 (e.g. tool calls, shell commands)
-
-No hidden environment parameters. If an agent needs something (like a workspace path), it obtains it via `ExtractFn` (e.g. Cursor agent).
-
-## Bundle contract
-
-A workflow bundle is a single `.esm.js` file with two named exports (see `WorkflowFn` / `WorkflowDescriptor` in `packages/workflow-protocol/src/types.ts`):
-
-```typescript
-export const descriptor: WorkflowDescriptor;
-export const run: WorkflowFn;
-
-type WorkflowFn = (
-  thread: ThreadContext,
-  runtime: WorkflowRuntime,
-) => AsyncGenerator<RoleOutput, WorkflowCompletion>;
+```bash
+<agent-cmd> <thread-id> <role>
 ```
 
-`RoleOutput` carries `contentHash`, `meta`, and `refs` (agent text lives in CAS, addressed by hash).
+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:
+   - Parses argv
+   - Loads `.env` from storage root
+   - Builds `AgentContext` by walking the CAS chain from `threads.yaml` head
+   - Resolves the role's `meta` schema and builds `outputFormatInstruction`
+   - Calls the agent's `run` function
+   - Runs two-layer extract on the raw output
+   - Writes `StepNode` to CAS (output + detail + prev link)
+   - Prints the new `StepNode` CAS hash to stdout
+4. `uwf thread step` reads stdout, updates `threads.yaml` head pointer, re-evaluates moderator for `done`
+5. Exit 0 = success, non-zero = failure
 
-### Constraints
+Agent resolution priority: `--agent` CLI override → `config.yaml` per-workflow/role override → `config.yaml` `defaultAgent`.
 
-- Single `.esm.js` file
-- No dynamic `import()` in bundles (loader exempt in engine)
-- Portable bundle static imports are constrained by validation in `@uncaged/workflow-register` (`validateWorkflowBundle`)
-- XXH64 hash (Crockford Base32) = version ID
+## Agent output format: frontmatter markdown (RFC #351)
 
-### Why AsyncGenerator?
+Agents produce **frontmatter markdown** — YAML frontmatter for structured meta, followed by a markdown body for content:
 
-- Each `yield` lets `workflow-execute` persist state, CAS rows, and enforce pause/abort
-- `return` supplies `WorkflowCompletion`
-- Fork replays historical steps into a new thread context
-- Bundle does not import the engine — only protocol/runtime types at build time
+```markdown
+---
+status: done
+next: reviewer
+confidence: 0.9
+artifacts:
+  - src/auth.ts
+scope: role
+---
+
+## Implementation
+
+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.
+
+## Two-layer extract
+
+Structured output extraction uses a two-layer strategy (`workflow-agent-kit`):
+
+### Layer 1: frontmatter fast path (`frontmatter.ts`)
+
+1. Parse YAML frontmatter from raw agent output (`parseFrontmatterMarkdown`)
+2. Validate required fields (`validateFrontmatter`)
+3. Build a candidate object from frontmatter fields (`status`, `next`, `confidence`, `artifacts`, `scope`)
+4. `store.put()` the candidate against the role's `meta` schema
+5. Validate with `json-cas` schema validation
+6. If valid → return `outputHash` (zero LLM cost)
+
+### Layer 2: LLM extract fallback (`extract.ts`)
+
+If the fast path returns `null` (no frontmatter, invalid, or doesn't satisfy schema):
+
+1. Resolve extract model alias from config (`modelOverrides.extract` → `models.extract` → `defaultModel`)
+2. Call OpenAI-compatible chat completion with JSON mode
+3. System prompt: "Extract structured data matching this JSON Schema: ..."
+4. User message: the raw agent output
+5. Parse response, `store.put()`, validate
+6. Return `outputHash`
+
+## Prompt injection
+
+`workflow-agent-kit` 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."
+
+This ensures agents produce parseable frontmatter output without requiring per-agent format knowledge.
+
+## CAS node types
+
+### Workflow
+
+```yaml
+type: <workflow-schema-hash>
+payload:
+  name: "solve-issue"
+  description: "End-to-end issue resolution"
+  roles:
+    planner:
+      description: "Creates implementation plan"
+      goal: "You are a planning agent..."
+      capabilities: [planning, issue-analysis]
+      procedure: "Analyze the issue and create a plan."
+      output: "Output the plan summary."
+      meta: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema node
+  conditions:
+    notApproved:
+      description: "Reviewer rejected"
+      expression: "steps[-1].output.approved = false"
+  graph:
+    $START:
+      - role: "planner"
+        condition: null
+```
+
+### StartNode
+
+```yaml
+type: <start-node-schema-hash>
+payload:
+  workflow: "4KNM2PXR3B1QW"    # cas_ref → Workflow
+  prompt: "Fix the login bug..."
+```
+
+### StepNode
+
+```yaml
+type: <step-node-schema-hash>
+payload:
+  start: "4TNVW8KR2B3MA"      # cas_ref → StartNode
+  prev: "2MXBG6PN4A8JR"       # cas_ref → previous StepNode (null for first step)
+  role: "developer"
+  output: "9KRVW3TN5F1QA"     # cas_ref → structured output (validated against meta schema)
+  detail: "7BQST3VW9F2MA"     # cas_ref → execution detail (raw turns, session data)
+  agent: "uwf-hermes"         # agent command used (plain string)
+```
+
+### Chain structure
+
+```
+threads.yaml: { "01J7K9...4T": "8FWKR3TN5V1QA" }
+                                    │
+                                    ▼
+                            StepNode (step 3)
+                            ├── start ──→ StartNode
+                            │              ├── workflow → Workflow (CAS)
+                            │              └── prompt: "Fix..."
+                            ├── prev ──→ StepNode (step 2)
+                            │             ├── prev ──→ StepNode (step 1)
+                            │             │             └── prev: null
+                            │             └── ...
+                            ├── role: "reviewer"
+                            ├── output → CAS({ approved: true })
+                            ├── detail → CAS(session turns)
+                            └── agent: "uwf-hermes"
+```
 
 ## Storage layout
 
 ```
 ~/.uncaged/workflow/
-├── cas/                           # Global content-addressed blobs (see getGlobalCasDir)
-├── bundles/
-│   ├── C9NMV6V2TQT81.esm.js       # Crockford Base32 of XXH64
-│   ├── C9NMV6V2TQT81.yaml         # Role descriptor sidecar (when present)
-│   └── C9NMV6V2TQT81/             # Per-hash bundle dir (alongside or instead of loose files)
-│       ├── threads.json           # Active threads: threadId → { head, start, updatedAt }
-│       └── history/
-│           └── 2026-05-09.jsonl   # Completed threads (one JSON object per line)
-├── logs/                          # One folder per bundle hash
-│   └── C9NMV6V2TQT81/
-│       ├── 01KQXKW…YG.running     # Present while worker executes this thread (optional)
-│       └── 01KQXKW…YG.info.jsonl   # Debug log
-└── workflow.yaml                  # Registry
+├── cas/                          # json-cas filesystem store (all CAS nodes)
+├── config.yaml                   # Provider, model, agent configuration
+├── threads.yaml                  # Active thread head pointers: threadId → CasRef
+├── history.jsonl                 # Archived thread records
+├── registry.yaml                 # Workflow name → CAS hash mapping
+└── .env                          # API keys (loaded by dotenv)
 ```
 
+### Mutable state
+
+Only three files carry mutable state:
+
+| File | Contents |
+|------|----------|
+| `threads.yaml` | `Record<ThreadId, CasRef>` — maps active thread IDs to head node hash |
+| `history.jsonl` | Append-only log of completed threads (`thread`, `workflow`, `head`, `completedAt`) |
+| `registry.yaml` | Workflow name → current CAS hash |
+
+Everything else is immutable CAS content.
+
 ### ID encoding: Crockford Base32
 
 - Case-insensitive, filesystem-safe, no ambiguous chars (0/O, 1/I/L)
-- Bundle hash: XXH64 → 13-char
-- Thread ID: ULID → 26-char (10 timestamp + 16 random)
+- CAS hash: XXH64 → 13-char Crockford Base32
+- Thread ID: ULID → 26-char Crockford Base32 (10 timestamp + 16 random)
 
-### Registry (`workflow.yaml`)
+### Config (`config.yaml`)
 
-Managed by `@uncaged/workflow-register` (`readWorkflowRegistry`, `writeWorkflowRegistry`, …). Shape includes workflow entries and a top-level `config` section used for extract/supervisor model resolution.
+```yaml
+providers:
+  openrouter:
+    baseUrl: "https://openrouter.ai/api/v1"
+    apiKeyEnv: "OPENROUTER_API_KEY"
 
-### Thread storage (CAS + index)
+models:
+  sonnet:
+    provider: "openrouter"
+    name: "anthropic/claude-sonnet-4"
+  gpt4o-mini:
+    provider: "openai"
+    name: "gpt-4o-mini"
 
-Thread execution state is a chain of immutable CAS nodes (`StartNode`, `StateNode`, content Merkle blobs). Per bundle:
+agents:
+  hermes:
+    command: "uwf-hermes"
+    args: []
+  cursor:
+    command: "uwf-cursor"
+    args: []
 
-- **`threads.json`** — only in-flight threads (`head`, `start`, `updatedAt`).
-- **`history/{YYYY-MM-DD}.jsonl`** — completed threads (`threadId`, `head`, `start`, `completedAt`).
-- **CAS (`cas/`)** — payloads and refs for replay, GC, and fork sharing.
+defaultAgent: "hermes"
+agentOverrides:
+  solve-issue:
+    developer: "cursor"
 
-**`.info.jsonl`** — Structured debug log via `@uncaged/workflow-util` `createLogger`:
-
-```jsonc
-{ "tag": "4KNMR2PX", "content": "Loading bundle...", "timestamp": ... }
+defaultModel: "sonnet"
+modelOverrides:
+  extract: "gpt4o-mini"
 ```
 
-Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNMR2PX"` → code location.
-
-## Execution model
-
-- **No daemon.** `uncaged-workflow run <name>` starts a worker process (`workflow-execute` worker entry via `getWorkerHostScriptPath`)
-- Threads share bundle-scoped workers as implemented in CLI/engine
-- Pause/resume/abort via engine IPC and pause gate (`createThreadPauseGate`)
-
 ## CLI commands
 
-| Priority | Command | Description |
-|----------|---------|-------------|
-| P1 | `add <name> <file.esm.js>` | Register a bundle |
-| P1 | `list` | List registered workflows |
-| P1 | `show <name>` | Show workflow details |
-| P1 | `remove <name>` | Remove a workflow |
-| P1 | `run <name> [--prompt] [--max-rounds]` | Start a thread |
-| P1 | `threads [name]` | List threads |
-| P1 | `thread <id>` | Show thread state |
-| P1 | `thread rm <id>` | Delete a thread |
-| P1 | `ps` | List running threads |
-| P1 | `kill <thread-id>` | Terminate a running thread |
-| P2 | `history <name>` | Show version history |
-| P2 | `rollback <name> [hash]` | Switch to a previous version |
-| P2 | `pause <thread-id>` | Pause a running thread |
-| P2 | `resume <thread-id>` | Resume a paused thread |
-| P3 | `fork <thread-id> [--from-role <role>]` | Fork from historical state |
+Binary: `uwf`
+
+### Thread commands
+
+| Command | Description |
+|---------|-------------|
+| `uwf thread start <workflow> -p <prompt>` | Create a thread (StartNode → CAS, head → threads.yaml). No execution. |
+| `uwf thread step <thread-id> [--agent <cmd>]` | Execute one moderator→agent→extract cycle. |
+| `uwf thread show <thread-id>` | Show thread head pointer and done status. |
+| `uwf thread list [--all]` | List active threads (`--all` includes archived). |
+| `uwf thread steps <thread-id>` | List all steps in chronological order. |
+| `uwf thread read <thread-id> [--quota <chars>] [--before <hash>]` | Render thread as human-readable markdown. |
+| `uwf thread fork <step-hash>` | Fork a thread from a specific CAS node. |
+| `uwf thread step-details <step-hash>` | Dump full detail node as YAML. |
+| `uwf thread kill <thread-id>` | Terminate and archive a thread. |
+
+### Workflow commands
+
+| Command | Description |
+|---------|-------------|
+| `uwf workflow put <file.yaml>` | Register a workflow from YAML definition. |
+| `uwf workflow show <id>` | Show workflow by name or CAS hash. |
+| `uwf workflow list` | List registered workflows. |
+
+### CAS commands
+
+| Command | Description |
+|---------|-------------|
+| `uwf cas get <hash>` | Read a CAS node. |
+| `uwf cas put <type-hash> <data>` | Store a node, print its hash. |
+| `uwf cas has <hash>` | Check if a hash exists. |
+| `uwf cas refs <hash>` | List direct CAS references. |
+| `uwf cas walk <hash>` | Recursive traversal from a node. |
+| `uwf cas reindex` | Rebuild type index from all nodes. |
+| `uwf cas schema list` | List registered schemas. |
+| `uwf cas schema get <hash>` | Show a schema by type hash. |
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `uwf setup [--provider --base-url --api-key --model --agent]` | Configure provider/model/agent (interactive if no flags). |
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **bun** | Package manager + runtime |
+| **TypeScript** | Type checking (strict mode) |
+| **Biome** | Lint + format |
+| **vitest** | Test runner |
 
 ## Design decisions
 
 | Decision | Rationale |
 |----------|-----------|
-| **Role = pure data** | Decouples definition from execution; same role with different agents |
-| **Agent bound at runtime** | `WorkflowDefinition` is reusable; agent choice is deployment concern |
-| **Three-phase context** | Each phase sees only what it needs; types live in `workflow-protocol` |
-| **`WorkflowRuntime.extract` + CAS `contentHash`** | Large agent bodies deduplicated globally; Merkle roots summarize threads |
-| **`workflow-reactor` split** | LLM tool-calling loop isolated from filesystem/registry concerns |
-| **Single-file ESM** | Hash = version, self-contained bundle |
-| **No daemon** | OS handles process lifecycle |
-| **Crockford Base32** | Filesystem-safe, readable, compact |
-| **15-package split** | Clear boundaries: protocol ↔ runtime author API ↔ util/CAS/register ↔ execute ↔ CLI ↔ agents/templates/UI |
+| **YAML workflow definitions** | Human-readable, versionable, no build step required. JSON Schema inline in YAML, registered as CAS nodes on `workflow put`. |
+| **Stateless single-step CLI** | Each `uwf thread step` is atomic — no in-memory state, no daemon, no long-running process. OS handles lifecycle. |
+| **CAS-backed thread state** | Immutable linked nodes enable fork, replay, and GC without copying data. Content-addressed deduplication across threads. |
+| **JSONata moderator** | Declarative condition expressions evaluated against thread history. No LLM cost for routing decisions. |
+| **Frontmatter markdown output** | Agents produce structured meta (YAML frontmatter) alongside free-form content (markdown body). Enables zero-cost extraction when frontmatter is well-formed. |
+| **Two-layer extract** | Fast path avoids LLM calls when agents follow the format; LLM fallback handles messy output gracefully. |
+| **Prompt injection for format** | Output format instruction prepended to system prompt ensures agents produce parseable output without per-agent configuration. |
+| **JSON Schema (not Zod)** | Schemas are CAS-native data — storable, hashable, validatable through `json-cas`. No code generation, no runtime library dependency. |
+| **Agent as external command** | Agents are independent CLI binaries (`uwf-hermes`, `uwf-cursor`). Swappable per workflow/role via config. No tight coupling to the engine. |
+| **No daemon** | Process starts, does one step, exits. Simpler failure model, no connection management. |
+| **Crockford Base32** | Filesystem-safe, case-insensitive, readable, compact. |

docs/superpowers/specs/2026-05-18-office-agent-document-template.md

@@ -0,0 +1,387 @@
+# 设计文档：office-agent 文档生成/编辑 Workflow 体系
+
+**日期：** 2026-05-18
+
+---
+
+## 概述
+
+在 monorepo 中新增三个包，实现通过 `office-agent` CLI 生成或编辑 Word 文档的完整 workflow 体系。
+
+| 包 | npm name | 职责 |
+|---|---|---|
+| `workflow-template-document` | `@uncaged/workflow-template-document` | 纯结构：角色定义、meta schema、调度表、descriptor |
+| `workflow-agent-office` | `@uncaged/workflow-agent-office` | writer 角色执行器：调用 `office-agent` CLI |
+| `workflow-agent-docx-diff` | `@uncaged/workflow-agent-docx-diff` | differ 角色执行器：调用 `docx-diff` CLI |
+
+Template 只定义结构，不含执行逻辑。执行器与 template 解耦。
+
+---
+
+## 一、`workflow-template-document`
+
+### Thread 启动输入
+
+```typescript
+// src/types.ts
+type DocumentStartInput = {
+  prompt: string;           // 用户指令
+  inputDocx: string | null; // null = 生成模式；本机绝对路径 = 编辑模式
+};
+```
+
+start.content 为 JSON `{ prompt, inputDocx }` 或纯文本（fallback：generate 模式，整段作为 prompt）。
+
+### 角色与 Meta
+
+`WriterMeta` 使用 discriminated union，在 schema 层区分两种模式：
+
+```typescript
+const writerMetaSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("generate"),
+    outputDocx: z.string(),   // 生成产物绝对路径
+    sourceDocx: z.null(),
+  }),
+  z.object({
+    mode: z.literal("edit"),
+    outputDocx: z.string(),   // 修改后产物：<outputDir>/modified.docx
+    sourceDocx: z.string(),   // 原始副本：<outputDir>/original.docx
+  }),
+]);
+type WriterMeta = z.infer<typeof writerMetaSchema>;
+
+// differ：仅编辑模式执行
+const differMetaSchema = z.object({
+  sourceDocx: z.string(),
+  modifiedDocx: z.string(),
+  diffDocx: z.string(),
+});
+type DifferMeta = z.infer<typeof differMetaSchema>;
+```
+
+两个角色的 `systemPrompt` 均为 `""`。
+
+### 调度表
+
+```
+START → writer ──(mode = "edit")──→ differ → END
+               ↘(mode = "generate")→ END
+```
+
+### 公开导出
+
+template 导出两个对象供消费方使用：
+
+- `documentWorkflowDefinition: WorkflowDefinition<DocumentMeta>` — 传入 `createWorkflow` 的 `def` 参数
+- `buildDocumentDescriptor(): WorkflowDescriptor` — bundle 导出用
+
+```typescript
+// bundle 侧用法
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, { adapter, overrides });
+```
+
+### 包文件结构
+
+```
+packages/workflow-template-document/
+  src/
+    types.ts           # DocumentStartInput
+    roles/
+      writer.ts        # writerMetaSchema, WriterMeta, writerRole
+      differ.ts        # differMetaSchema, DifferMeta, differRole
+      index.ts
+    roles.ts           # DocumentMeta, documentRoles
+    moderator.ts       # writerIsEditMode condition + documentTable
+    definition.ts      # documentWorkflowDefinition
+    descriptor.ts      # buildDocumentDescriptor()
+    index.ts
+  __tests__/
+    moderator.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-runtime": "workspace:^",
+  "@uncaged/workflow-register": "workspace:^",
+  "zod": "^4.0.0"
+}
+```
+
+---
+
+## 二、`workflow-agent-office`
+
+### office-agent CLI 接口
+
+```bash
+# 生成模式：在 CWD 生成 output.docx
+office-agent create "<prompt>" -o output.docx
+
+# 编辑模式：在 CWD 对 modified.docx 进行修改（覆写）
+office-agent edit modified.docx "<instruction>"
+```
+
+- 两个命令均为阻塞调用（CLI 内部消费 SSE，退出即完成）
+- 输出文件落到调用方设定的 CWD
+- 退出码 0 = 成功，非零 = 失败
+
+### 文件命名约定
+
+| 模式 | 文件 | 路径 |
+|---|---|---|
+| generate | 输出 | `<outputDir>/output.docx` |
+| edit | 原始副本（workflow-owned 快照） | `<outputDir>/original.docx` |
+| edit | 修改后产物 | `<outputDir>/modified.docx` |
+
+edit 模式先将 `inputDocx` 复制为 `original.docx`（不可变快照），再复制为 `modified.docx`，对 `modified.docx` 调用 CLI。agent 覆写 `modified.docx`，`original.docx` 保持不变。differ 对比这两个 workflow-owned 文件，不依赖用户原始路径。
+
+### 执行流程
+
+**生成模式（`inputDocx = null`）：**
+1. `mkdir -p <outputDir>`（`<config.outputDir>/<ctx.threadId>`）
+2. `const command = config.command ?? "office-agent"`
+3. `spawnCli(command, ["create", prompt, "-o", "output.docx"], { cwd: outputDir, timeoutMs })`
+4. 验证 `outputDir/output.docx` 存在
+5. 返回 `JSON.stringify({ mode: "generate", outputDocx, sourceDocx: null })`
+
+**编辑模式（`inputDocx ≠ null`）：**
+1. `mkdir -p <outputDir>`
+2. `copyFile(inputDocx, <outputDir>/original.docx)`
+3. `copyFile(inputDocx, <outputDir>/modified.docx)`
+4. `const command = config.command ?? "office-agent"`
+5. `spawnCli(command, ["edit", "modified.docx", prompt], { cwd: outputDir, timeoutMs })`
+6. 验证 `outputDir/modified.docx` 存在
+7. 返回 `JSON.stringify({ mode: "edit", outputDocx: modifiedPath, sourceDocx: originalPath })`
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+CLI 产出确定性 JSON，直接 `schema.parse(JSON.parse(raw))` 跳过 LLM extraction：
+
+```typescript
+export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
+  return <T>(_systemPrompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const { prompt, inputDocx } = parseStartInput(ctx.start.content);
+      const raw = await runOfficeAgent(config, ctx.threadId, prompt, inputDocx);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+`_systemPrompt` 为 writer 角色的 systemPrompt（空字符串），实际指令从 `ctx.start.content` 解析。
+
+### 配置
+
+```typescript
+type OfficeAgentConfig = {
+  outputDir: string;        // 输出根目录，runner 在此下按 threadId 建子目录
+  command: string | null;   // null → runner 内 resolve 为 "office-agent"
+  timeout: number | null;   // null → 不设超时；单位 ms
+};
+```
+
+### 错误处理
+
+```typescript
+if (!result.ok) {
+  const e = result.error;
+  if (e.kind === "non_zero_exit")
+    throw new Error(`office-agent failed (exit ${e.exitCode}): ${e.stderr}`);
+  if (e.kind === "timeout")
+    throw new Error("office-agent: timed out");
+  // "spawn_failed"
+  throw new Error(`office-agent: spawn failed: ${e.message}`);
+}
+if (!existsSync(expectedPath))
+  throw new Error(`office-agent: output file not found: ${expectedPath}`);
+```
+
+### packageDescriptor
+
+```typescript
+// src/package-descriptor.ts
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-office",
+  version: "0.1.0",
+  capabilities: ["office-agent-cli", "docx-generate", "docx-edit"],
+  configSchema: {
+    type: "object",
+    required: ["outputDir"],
+    properties: {
+      outputDir: { type: "string", description: "Root directory for workflow outputs." },
+      command:   { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to office-agent CLI; null uses PATH." },
+      timeout:   { anyOf: [{ type: "number" }, { type: "null" }], description: "Timeout in ms; null means no limit." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-office/
+  src/
+    types.ts                # OfficeAgentConfig, OfficeAgentOpt
+    runner.ts               # runOfficeAgent()（spawnCli 封装 + 文件验证）
+    agent.ts                # createOfficeAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^"
+}
+```
+
+---
+
+## 三、`workflow-agent-docx-diff`
+
+`differ` 角色专用执行器。从 `ctx.steps` 读取 `WriterMeta`，调用本地 `docx-diff` CLI。
+
+### docx-diff 退出码约定
+
+| 退出码 | 含义 | runner 处理 |
+|---|---|---|
+| 0 | 无差异 | 正常，验证 diffDocx 存在 |
+| 1 | 有差异 | 正常（显式处理为成功），验证 diffDocx 存在 |
+| 2+ | 错误 | throw |
+
+runner 收到 `SpawnCliError { kind: "non_zero_exit", exitCode: 1 }` 时视为成功，验证文件后继续；`exitCode >= 2` 才 throw。
+
+### 执行流程
+
+```
+1. 从 ctx.steps 找到 writer 步骤，读取 WriterMeta
+2. 验证 mode === "edit"（否则 throw）
+3. diffDocx = join(dirname(writer.outputDocx), "diff.docx")
+4. const command = config.command ?? "docx-diff"
+5. spawnCli(command,
+     [writer.sourceDocx, writer.outputDocx, "--output", "docx", "--out-file", diffDocx],
+     { cwd: null, timeoutMs: null })
+   exit 0 或 1 → 验证 diffDocx 存在
+   exit 2+ → throw
+6. 返回 JSON.stringify({ sourceDocx, modifiedDocx: writer.outputDocx, diffDocx })
+```
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+```typescript
+export function createDocxDiffAgent(config: DocxDiffAgentConfig = { command: null }): AdapterFn {
+  return <T>(_prompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const writerStep = ctx.steps.find(s => s.role === "writer");
+      if (!writerStep) throw new Error("differ: no writer step found");
+      const writerMeta = writerStep.meta as WriterMeta;
+      if (writerMeta.mode !== "edit")
+        throw new Error("differ: writer did not run in edit mode");
+      const raw = await runDocxDiff(config, writerMeta);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+### 配置
+
+```typescript
+type DocxDiffAgentConfig = {
+  command: string | null;   // null → runner 内 resolve 为 "docx-diff"
+};
+```
+
+### packageDescriptor
+
+```typescript
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-docx-diff",
+  version: "0.1.0",
+  capabilities: ["docx-diff-cli", "docx-diff-report"],
+  configSchema: {
+    type: "object",
+    properties: {
+      command: { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to docx-diff CLI; null uses PATH." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-docx-diff/
+  src/
+    types.ts                # DocxDiffAgentConfig
+    runner.ts               # runDocxDiff()（exit 1 处理 + 文件验证）
+    agent.ts                # createDocxDiffAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^",
+  "@uncaged/workflow-template-document": "workspace:^"
+}
+```
+
+---
+
+## 四、外部 bundle（外部 workspace 消费）
+
+```typescript
+import { createOfficeAgent } from "@uncaged/workflow-agent-office";
+import { createDocxDiffAgent } from "@uncaged/workflow-agent-docx-diff";
+import {
+  buildDocumentDescriptor,
+  documentWorkflowDefinition,
+} from "@uncaged/workflow-template-document";
+import { createWorkflow } from "@uncaged/workflow-runtime";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow-util";
+import { join } from "node:path";
+
+const outputDir = join(getDefaultWorkflowStorageRoot(), "outputs");
+
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, {
+  adapter: createOfficeAgent({ outputDir, command: null, timeout: null }),
+  overrides: { differ: createDocxDiffAgent() },
+});
+```
+
+---
+
+## 不在范围内
+
+- 重试逻辑（失败直接 throw）
+- office-agent server 的启停管理（假设 server 已在运行）
+- docx-diff HTML/terminal 格式输出（仅 docx）
+- 跨机器执行（`inputDocx` 须为本机有效绝对路径）

docs/wf-stateless-design.md

@@ -112,8 +112,8 @@ uwf-hermes <thread-id> <role>
 
 **约定：**
 - `uwf step` 负责 moderator 决策，将 role 传给 agent CLI
-- agent-kit 根据 thread + role 从 CAS 读 systemPrompt / outputSchema
-- agent-kit 组装完整 prompt（role systemPrompt + thread context + user prompt from StartNode）
+- agent-kit 根据 thread + role 从 CAS 读 goal / capabilities / procedure / output / meta
+- agent-kit 组装完整 prompt（role goal/capabilities/procedure/output + thread context + user prompt from StartNode）
 - agent 执行实际逻辑，agent-kit 负责 extract
 - agent 将 StepNode 写入 CAS（含 output、detail、agent、prev），但**不挪链头指针**
 - stdout 输出新 StepNode 的 CAS hash（纯文本，一行）
@@ -143,7 +143,7 @@ uwf-hermes <thread-id> <role>
 
 #### `Workflow`
 
-Roles 和 moderator 内联在 Workflow 中，只有 outputSchema 独立为 CAS 节点（方便 json-cas 校验）。
+Roles 和 moderator 内联在 Workflow 中，只有 meta 独立为 CAS 节点（方便 json-cas 校验）。
 
 ```yaml
 type: <workflow-schema-hash>
@@ -153,16 +153,25 @@ payload:
   roles:
     planner:
       description: "Creates implementation plan"
-      systemPrompt: "You are a planning agent..."
-      outputSchema: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
+      goal: "You are a planning agent..."
+      capabilities: [planning, issue-analysis]
+      procedure: "Analyze the issue and create a plan."
+      output: "Output the plan summary."
+      meta: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
     developer:
       description: "Implements code changes"
-      systemPrompt: "You are a developer agent..."
-      outputSchema: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
+      goal: "You are a developer agent..."
+      capabilities: [file-edit, shell]
+      procedure: "Implement the plan."
+      output: "List all files changed."
+      meta: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
     reviewer:
       description: "Reviews code changes"
-      systemPrompt: "You are a code reviewer..."
-      outputSchema: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
+      goal: "You are a code reviewer..."
+      capabilities: [code-review]
+      procedure: "Review the implementation."
+      output: "Approve or reject with comments."
+      meta: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
   conditions:
     needsClarification:
       description: "Planner requests clarification from user"
@@ -189,7 +198,7 @@ payload:
         condition: null
 ```
 
-- `roles` — 内联定义，每个 role 的 `outputSchema` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
+- `roles` — 内联定义，每个 role 的 `meta` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
 - `conditions` — `Record<Name, JSONata>`，命名条件，方便画图描述
 - `graph` — `Record<Role | "$START", Transition[]>`，每个 Transition = `{ role, condition }`
 - `condition` 引用 conditions 中的 key，`null` = fallback
@@ -234,14 +243,14 @@ payload:
   start: "4TNVW8KR2B3MA"          # cas_ref → StartNode（每个 step 都引用）
   prev: "2MXBG6PN4A8JR"           # cas_ref → 前一个 StepNode，第一步为 null
   role: "developer"
-  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 outputSchema）
+  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 meta schema）
   detail: "7BQST3VW9F2MA"         # cas_ref → 执行详情（content node / 子 workflow terminal StepNode / ...）
   agent: "uwf-cursor"              # 实际使用的 agent 命令（纯字符串）
 ```
 
 - `start` — 每个 StepNode 都直接引用 StartNode，方便随机访问
 - `prev` — 前一个 StepNode 的 cas_ref，第一步为 `null`（不指向 StartNode）
-- `output` — cas_ref，指向符合 role outputSchema 的 CAS 节点，可用 json-cas 校验
+- `output` — cas_ref，指向符合 role meta schema 的 CAS 节点，可用 json-cas 校验
 - `detail` — cas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景）
 - `agent` — 纯字符串，不是 CAS 节点
 
@@ -340,12 +349,12 @@ OPENROUTER_API_KEY=sk-or-...
 
 ```
 packages/
-├── cli-uwf/              # @uncaged/cli-uwf — uwf CLI（thread/workflow 命令）
-├── uwf-moderator/        # @uncaged/uwf-moderator — JSONata moderator 引擎
-├── uwf-agent-kit/        # @uncaged/uwf-agent-kit — Agent CLI 框架（含 extractor）
-├── uwf-agent-hermes/     # @uncaged/uwf-agent-hermes — uwf-hermes CLI
-├── uwf-agent-cursor/     # @uncaged/uwf-agent-cursor — uwf-cursor CLI
-└── uwf-protocol/         # @uncaged/uwf-protocol — 共享类型定义
+├── cli-workflow/              # @uncaged/cli-workflow — uwf CLI（thread/workflow 命令）
+├── workflow-moderator/        # @uncaged/workflow-moderator — JSONata moderator 引擎
+├── workflow-agent-kit/        # @uncaged/workflow-agent-kit — 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 — 共享类型定义
 ```
 
 **外部依赖：**
@@ -372,7 +381,7 @@ type ThreadId = string;
 /** 一个 step 的核心数据，被 StepNode payload 和 JSONata 上下文共享 */
 type StepRecord = {
   role: string;
-  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role outputSchema）
+  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role meta schema）
   detail: CasRef;                    // cas_ref → 执行详情（content node / 子 workflow terminal StepNode）
   agent: string;                     // 实际使用的 agent 命令（纯字符串）
 };
@@ -383,8 +392,11 @@ type StepRecord = {
 ```typescript
 type RoleDefinition = {
   description: string;
-  systemPrompt: string;
-  outputSchema: CasRef;              // cas_ref → json-cas 内置 JSON Schema 节点
+  goal: string;
+  capabilities: string[];
+  procedure: string;
+  output: string;
+  meta: CasRef;                      // cas_ref → json-cas 内置 JSON Schema 节点
 };
 
 type Transition = {

examples/analyze-topic.yaml

@@ -0,0 +1,41 @@
+name: "analyze-topic"
+description: "Single-role topic analysis using four-phase role description"
+roles:
+  analyst:
+    description: "Analyzes a given topic and produces a structured summary"
+    goal: |
+      You are a research analyst with expertise in breaking down complex topics
+      into clear, structured summaries. You think critically and cite key points.
+    capabilities:
+      - research
+      - critical-thinking
+      - structured-writing
+    procedure: |
+      Analyze the topic by:
+      1. Identifying the main thesis or question
+      2. Listing 3-5 key points with brief explanations
+      3. Noting any counterarguments or caveats
+      Keep your analysis concise (under 500 words).
+    output: |
+      Provide your analysis as markdown under the frontmatter.
+      The frontmatter must include your structured findings.
+    frontmatter:
+      type: object
+      properties:
+        thesis:
+          type: string
+        keyPoints:
+          type: array
+          items:
+            type: string
+        caveats:
+          type: string
+      required: [thesis, keyPoints]
+conditions: {}
+graph:
+  $START:
+    - role: "analyst"
+      condition: null
+  analyst:
+    - role: "$END"
+      condition: null

examples/solve-issue.yaml

@@ -3,8 +3,13 @@ description: "End-to-end issue resolution"
 roles:
   planner:
     description: "Creates implementation plan"
-    systemPrompt: "You are a planning agent. Analyze the issue and create a step-by-step plan."
-    outputSchema:
+    goal: "You are a planning agent. You analyze issues and create step-by-step plans."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: "Analyze the issue and create a detailed, actionable implementation plan."
+    output: "Output the plan summary and list of concrete steps."
+    frontmatter:
       type: object
       properties:
         plan:
@@ -16,8 +21,14 @@ roles:
       required: [plan, steps]
   developer:
     description: "Implements code changes"
-    systemPrompt: "You are a developer agent. Implement the plan."
-    outputSchema:
+    goal: "You are a developer agent. You implement code changes according to plans."
+    capabilities:
+      - file-edit
+      - shell
+      - testing
+    procedure: "Implement the plan. Write code, tests, and ensure existing tests pass."
+    output: "List all files changed and provide a summary of the implementation."
+    frontmatter:
       type: object
       properties:
         filesChanged:
@@ -29,8 +40,13 @@ roles:
       required: [filesChanged, summary]
   reviewer:
     description: "Reviews code changes"
-    systemPrompt: "You are a code reviewer. Review the implementation."
-    outputSchema:
+    goal: "You are a code reviewer. You review implementations for correctness and quality."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: "Review the implementation against the plan. Check for bugs, edge cases, and style."
+    output: "Approve or reject with detailed comments explaining your decision."
+    frontmatter:
       type: object
       properties:
         approved:
@@ -41,7 +57,7 @@ roles:
 conditions:
   notApproved:
     description: "Reviewer rejected the implementation"
-    expression: "steps[-1].output.approved = false"
+    expression: "$last('reviewer').approved = false"
 graph:
   $START:
     - role: "planner"

legacy-packages/cli-workflow/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@uncaged/cli-workflow",
+  "version": "0.5.0-alpha.4",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uncaged-workflow": "src/cli.ts"
+  },
+  "dependencies": {
+    "@uncaged/workflow-gateway": "workspace:^",
+    "@uncaged/workflow-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "@uncaged/workflow-cas": "workspace:^",
+    "@uncaged/workflow-execute": "workspace:^",
+    "@uncaged/workflow-register": "workspace:^",
+    "@uncaged/workflow-runtime": "workspace:^",
+    "hono": "^4.12.18",
+    "yaml": "^2.8.4"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+import { runCli } from "./cli-dispatch.js";
+import { resolveWorkflowStorageRoot } from "./storage-env.js";
+
+const argv = process.argv.slice(2);
+const storageRoot = resolveWorkflowStorageRoot();
+const code = await runCli(storageRoot, argv);
+process.exit(code);