fix: output instructions now specify required frontmatter meta fields

fix: remove redundant condition null from $START
refactor: graph fallback pattern + positive condition names
2026-05-22 05:42:17 +00:00 · 2026-05-22 05:33:39 +00:00 · 2026-05-22 05:31:43 +00:00 · 2026-05-22 05:27:21 +00:00 · 2026-05-22 05:21:19 +00:00 · 2026-05-22 04:50:12 +00:00
458 changed files with 5479 additions and 3098 deletions
@@ -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
@@ -10,3 +10,4 @@ xiaoju/
 solve-issue-entry.ts
 packages/workflow-template-develop/develop.esm.js
 .DS_Store
+*.py
@@ -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 "<markdown content>"` and capture the returned hash
+      2. Put the hash in meta.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)."
+    meta:
+      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)."
+    meta:
+      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)."
+    meta:
+      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)."
+    meta:
+      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)."
+    meta:
+      type: object
+      properties:
+        success:
+          type: boolean
+      required: [success]
+conditions:
+  insufficientInfo:
+    description: "Planner determined there's not enough info to proceed"
+    expression: "steps[-1].output.status = 'insufficient_info'"
+  devFailed:
+    description: "Developer failed to implement"
+    expression: "steps[-1].output.status = 'failed'"
+  rejected:
+    description: "Reviewer rejected the implementation"
+    expression: "steps[-1].output.approved = false"
+  fixCode:
+    description: "Tester found code issues"
+    expression: "steps[-1].output.status = 'fix_code'"
+  fixSpec:
+    description: "Tester found spec issues"
+    expression: "steps[-1].output.status = 'fix_spec'"
+  hookFailed:
+    description: "Push hook failed"
+    expression: "steps[-1].output.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"
@@ -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 | ...
 ```
@@ -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.
@@ -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": {
@@ -1,271 +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 **21** 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-office` → `workflow-agent-office` | `AdapterFn` via `office-agent` CLI; generates or edits Word documents, stores outputs per threadId. |
-| | `@uncaged/workflow-agent-docx-diff` → `workflow-agent-docx-diff` | `AdapterFn` via `docx-diff` CLI; produces Word-format diff reports for document edit workflows. |
-| | `@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. |
-| | `@uncaged/workflow-template-document` → `workflow-template-document` | Document generation/editing workflow definition (writer + differ roles, moderator table, descriptor). |
-| 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 |
-| **21-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. |
@@ -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 = {
@@ -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.
+    meta:
+      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
@@ -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."
+    meta:
      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."
+    meta:
      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."
+    meta:
      type: object
      properties:
        approved:
@@ -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"
+  }
+}
@@ -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);
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
xiaoju	8a425521da	fix: output instructions now specify required frontmatter meta fields	2026-05-22 05:42:17 +00:00
xiaoju	f174f2fd0a	fix: remove redundant condition null from $START	2026-05-22 05:33:39 +00:00
xiaoju	355594d074	refactor: graph fallback pattern + positive condition names - Last transition in each graph node is now the fallback (no condition) - Remove redundant positive conditions (ready, devDone, approved, passed, pushSuccess) - notApproved → rejected (positive naming)	2026-05-22 05:31:43 +00:00
xiaoju	fd7609fe90	fix: address review feedback from xingyue 1. npm/npx → bun/bunx (project standard) 2. Fix tea CLI usage (tea comment + -r flag) 3. cursor-agent → coding (abstract capability) 4. Clarify committer inherits developer's worktree 5. Mark meta.plan required when status=ready 6. PR description must follow What/Why/Changes/Ref template 7. Note maxRounds loop protection in description	2026-05-22 05:27:21 +00:00
xiaoju	dacecfbbb7	feat: create .workflows/solve-issue.yaml TDD-driven issue resolution workflow with 5 roles: - planner: analyzes issue, outputs TDD test spec (stored in CAS) - developer: implements code following TDD - reviewer: code standards compliance check (not functionality) - tester: functional correctness verification - committer: commits and creates PR Graph handles bounce-backs: reviewer→developer, tester→developer, tester→planner (fix_spec), committer→developer (hook_failed). Refs #370	2026-05-22 05:21:19 +00:00
xiaomo	3238eaeddf	Merge pull request 'feat: add uwf skill cli command and Prepare section' (#371 ) from feat/369-uwf-skill-cli into main	2026-05-22 04:50:12 +00:00
xiaoju	995f273fa5	address review: move CLI reference to workflow-util, inline in prompt - Move generateCliReference() to @uncaged/workflow-util - buildRolePrompt inlines CLI reference directly (no agent tool call) - Fix Role terminology to use new field names - Add maintenance comment in cli-reference.ts - Fix test assertions	2026-05-22 03:29:01 +00:00
xiaoju	866154ad73	feat: add uwf skill cli command and Prepare section in role prompt - Add 'uwf skill cli' command that prints markdown CLI reference - buildRolePrompt now generates ## Prepare section: - Always prompts agent to run 'uwf skill cli' (explicit skill) - Renders capabilities as keyword hints for implicit skill loading Fixes #369	2026-05-22 03:20:04 +00:00
xiaomo	8efc5050cb	Merge pull request 'chore: exclude legacy code from biome check' (#368 ) from chore/ignore-legacy-biome into main	2026-05-22 02:10:20 +00:00
xiaoju	3fb60ee649	chore: exclude legacy-packages and scripts from biome check - Add legacy-packages/ and scripts/ to biome ignore - Allow noDefaultExport in vitest.config.* and .d.ts - Allow console in cli.ts and setup.ts (CLI user output) - Fix unused imports in cas.ts and setup.ts	2026-05-22 02:09:18 +00:00
xiaomo	e181f67a2d	Merge pull request 'feat: support project-local workflow discovery' (#367 ) from feat/365-project-local-workflows into main	2026-05-22 02:07:33 +00:00
xiaoju	a3114bf840	chore: apply biome formatting across codebase	2026-05-22 02:06:05 +00:00
xiaoju	e59ae9aca1	feat: support project-local workflow discovery - Add .workflows/*.yaml scanning from project root (cwd) - Resolution: project-local first, then global registry - On-the-fly CAS materialization for local workflows - Filename/name consistency check - uwf workflow list shows origin (local/global) Fixes #365	2026-05-22 01:01:45 +00:00
xiaomo	c050a38f38	Merge pull request 'refactor: rename RoleDefinition fields for clarity' (#366 ) from refactor/364-rename-role-fields into main	2026-05-22 00:48:23 +00:00
xiaoju	c60c310074	refactor: rename RoleDefinition fields for clarity - identity → goal - prepare → capabilities (string[]) - execute → procedure - report → output - outputSchema → meta Fixes #364	2026-05-22 00:46:06 +00:00
xiaomo	fe035c065d	Merge pull request 'feat: Role 四段式描述 (identity/prepare/execute/report)' (#361 ) from feat/359-role-four-phase into main	2026-05-21 03:11:00 +00:00
xiaoju	192ad656a4	refactor: remove systemPrompt, make four-phase fields required Breaking change per review: - Remove systemPrompt from RoleDefinition entirely - identity/prepare/execute/report are now required (string, not nullable) - Remove all legacy fallback logic in buildRolePrompt - Simplify validate.ts, workflow.ts materialize - Migrate all test fixtures and example workflows Refs #359	2026-05-21 03:07:56 +00:00
xiaoju	c0c8d6499e	feat: add four-phase example workflow (analyze-topic) Refs #359, #363	2026-05-21 02:56:11 +00:00
xiaoju	505f85e3c4	feat: add buildRolePrompt in agent-kit, integrate with uwf-hermes - New buildRolePrompt() in workflow-agent-kit: four-phase prompt assembly with fallback to systemPrompt - Export from agent-kit index - Update uwf-hermes to use buildRolePrompt instead of raw systemPrompt - Add tests for all modes: four-phase, legacy, mixed Refs #359, #362	2026-05-21 02:31:56 +00:00
xiaoju	fc7d482b4f	feat: add four-phase role description (identity/prepare/execute/report) - Extend RoleDefinition with identity, prepare, execute, report fields - Make systemPrompt optional (nullable) for four-phase workflows - Update ROLE_DEFINITION JSON Schema (all new fields optional) - Update validate.ts to accept new fields - Update workflow.ts to strip null fields before CAS storage - Update thread read to prefer identity over systemPrompt - Add --version flag to uwf CLI - Bump all packages to 0.5.0 Refs #359	2026-05-21 01:41:20 +00:00
xiaoju	f9979c3c89	chore: upgrade json-cas to 0.4.x, fix Store → BootstrapCapableStore - @uncaged/json-cas ^0.3.0 → ^0.4.0 - @uncaged/json-cas-fs ^0.3.0 → ^0.4.0 (now publishes .d.ts + .js) - UwfStore.store typed as BootstrapCapableStore - tsc --build now clean (no more node_modules type errors) 小橘 🍊（NEKO Team）	2026-05-19 10:29:57 +00:00
xiaoju	46def2945a	chore: update dev workflow — fix publish script, remove deploy.sh, update CLAUDE.md - scripts/publish-all.mjs: update to 6 active packages only - scripts/deploy.sh: removed (dashboard/gateway in legacy) - package.json: release script uses publish-all.mjs directly - CLAUDE.md: add complete dev workflow section (setup, build, check, test, publish) 小橘 🍊（NEKO Team）	2026-05-19 08:07:45 +00:00
xiaoju	4e89508246	docs: rewrite README.md and CLAUDE.md for current architecture Remove all references to ESM bundles, old packages, old CLI name. Update to reflect YAML workflow definitions, uwf CLI, 6 active packages, frontmatter markdown output format, and stateless single-step execution. 小橘 🍊（NEKO Team）	2026-05-19 08:03:13 +00:00
xiaoju	77d799d458	chore: remove obsolete .env.example, config via uwf setup 小橘 🍊（NEKO Team）	2026-05-19 07:58:50 +00:00
xiaoju	6c14259184	chore: remove pnpm-lock.yaml files, bun only 小橘 🍊（NEKO Team）	2026-05-19 07:58:24 +00:00
xiaoju	7b9cb6a9c8	chore: rename uwf-* → workflow-, cli-uwf → cli-workflow Reclaim the workflow- package names now that legacy packages are archived. Package renames: - @uncaged/uwf-protocol → @uncaged/workflow-protocol - @uncaged/uwf-moderator → @uncaged/workflow-moderator - @uncaged/uwf-agent-kit → @uncaged/workflow-agent-kit - @uncaged/uwf-agent-hermes → @uncaged/workflow-agent-hermes - @uncaged/cli-uwf → @uncaged/cli-workflow All internal imports, tsconfig references, and docs updated. CLI binary name 'uwf' unchanged. 小橘 🍊（NEKO Team）	2026-05-19 07:52:16 +00:00
xiaoju	68246e20b1	fix: remove workflow-util dependency on workflow-protocol Inline Result type and ok/err helpers into workflow-util to break dependency on the now-archived workflow-protocol package. Also add explicit @uncaged/json-cas dep to uwf-protocol (was only available as transitive dep via json-cas-fs). 小橘 🍊（NEKO Team）	2026-05-19 07:22:15 +00:00
xiaoju	d63d58ccb5	chore: reorganize repo — legacy packages to legacy-packages/, templates to examples/ - Move 15 old workflow-* packages to legacy-packages/ (inactive, preserved for reference) - Rename templates/ → examples/ for clarity - Rewrite docs/architecture.md to reflect current uwf architecture - Active packages remain in packages/: cli-uwf, uwf-agent-hermes, uwf-agent-kit, uwf-moderator, uwf-protocol, workflow-util 小橘 🍊（NEKO Team）	2026-05-19 07:19:40 +00:00
xiaomo	2a3a40b9d9	Merge pull request 'feat(cli-uwf): thread read Content + step-details — #357 ' (#358 ) from feat/357-thread-read-content into main	2026-05-19 06:58:24 +00:00
xiaoju	762ecec872	feat(cli-uwf): thread read shows Content + new step-details command - thread read: add ### Content section (last assistant message) before ### Output - Remove --detail flag (replaced by step-details command) - New: uwf thread step-details <step-hash> — full detail dump as yaml Closes #357	2026-05-19 06:44:18 +00:00
xiaoju	c0ac4ade09	fix(uwf-agent-hermes): consume outputFormatInstruction in prompt buildHermesPrompt was ignoring ctx.outputFormatInstruction — the deliverable format and scope constraint were injected into context but never passed to the agent. Now prepends it before systemPrompt (deliverable-first principle). Refs #355	2026-05-19 06:23:13 +00:00
xiaomo	a991393053	Merge pull request 'feat(uwf-agent-kit): frontmatter fast path + prompt injection — #355 ' (#356 ) from feat/355-uwf-frontmatter into main	2026-05-19 06:21:35 +00:00
xiaoju	892ccab8d5	feat(uwf-agent-kit): frontmatter fast path + prompt injection Port RFC #351 frontmatter markdown to uwf-* path: - tryFrontmatterFastPath(): parse → validate → JSON Schema check via json-cas - Happy path skips LLM extract, fallback to existing extract() - buildOutputFormatInstruction(): generates deliverable format from JSON Schema - Injected into agent context before execution - Scope reminder: 'Focus exclusively on YOUR role's deliverable' - 14 new tests (vitest) Closes #355	2026-05-19 06:20:15 +00:00
xiaomo	70c83c65b0	Merge pull request 'feat(workflow-util-agent): prompt restructure + scope focus — RFC #351 Phase 3' (#354 ) from feat/351-phase3-prompt-focus into main	2026-05-19 05:57:37 +00:00
xiaoju	8a7e756fe3	feat(workflow-util-agent): prompt restructure + scope focus — Phase 3 - buildOutputFormatInstruction(schema): auto-generates frontmatter format guide from Zod schema, injected at top of system prompt - Adapter prepends deliverable format before role's systemPrompt - buildThreadInput reordered: Task → Steps → Parent → Tools - Scope reminder: 'Focus exclusively on YOUR role's deliverable' - 8 tests for buildOutputFormatInstruction Refs #351	2026-05-19 05:56:27 +00:00
xiaomo	4a4ddba9f6	Merge pull request 'feat(workflow-util-agent): two-layer frontmatter safeguard — RFC #351 Phase 2' (#353 ) from feat/351-phase2-adapter-frontmatter into main	2026-05-19 05:47:46 +00:00
xiaoju	d5f47d1a18	feat(workflow-util-agent): two-layer frontmatter safeguard in adapter Phase 2 of RFC #351 — adapter tries frontmatter first (zero LLM cost), falls back to runtime.extract() when frontmatter is missing/invalid. - tryFrontmatterMeta(): parse → validate → schema.safeParse - Happy path stores body (no frontmatter) in CAS - Fallback stores full raw in CAS + LLM extract - 5 tests covering both paths Refs #351	2026-05-19 05:46:36 +00:00
xiaoju	37c35560e9	docs: fix parseMinimalYaml JSDoc (nit from #352 review) Refs #351	2026-05-19 05:41:18 +00:00
xiaomo	f174b96028	Merge pull request 'feat(workflow-util): frontmatter markdown parser — RFC #351 Phase 1' (#352 ) from feat/351-frontmatter-markdown-phase1 into main	2026-05-19 04:56:58 +00:00
xiaoju	43978360ff	feat(workflow-util): add frontmatter markdown parser and validator Phase 1 of RFC #351 — define AgentFrontmatter type, parseFrontmatterMarkdown() and validateFrontmatter() with 45 tests. - Built-in minimal YAML parser (no new deps) - Never throws on malformed input — degrades gracefully - All fields use T \| null (no optional properties) Refs #351	2026-05-19 04:41:56 +00:00
xiaomo	432400ee20	Merge pull request 'feat: uwf thread read — human-readable markdown with pagination' (#350 ) from feat/349-thread-read into main	2026-05-19 03:45:02 +00:00
xiaoju	dacebe1841	feat(thread-read): show role system prompt in each step Each step block now includes a '### Prompt' section showing the role's systemPrompt from the workflow definition. Refs #349	2026-05-19 03:23:50 +00:00
xiaoju	c42125946d	feat(thread-read): expand detail recursively via cas_ref --detail now uses expandDeep to recursively resolve all cas_ref fields in the detail merkle tree, showing full turn content instead of raw hashes. Refs #349	2026-05-19 03:19:40 +00:00
xiaoju	4c9ce72395	feat: uwf thread read — human-readable markdown with pagination - Outputs markdown directly (not JSON/YAML) - --quota <chars>: character budget, loads steps backward until exceeded (default 4000) - --before <step-hash>: load steps before this hash (exclusive), omits start - --start: force include start section even with --before - --detail: expand detail CAS node content for each step - Skip hint with uwf thread read command for pagination - Reuses walkChain/collectOrderedSteps/expandOutput Closes #349	2026-05-19 03:15:38 +00:00
xiaomo	8b43f7993b	Merge pull request 'fix: parse session_id from stderr — hermes --quiet writes it there' (#348 ) from fix/348-session-id-stderr into main	2026-05-18 17:10:29 +00:00
xiaoju	cf9e2cd3d6	fix: parse session_id from stderr (hermes --quiet writes it there) hermes --quiet outputs session_id to stderr and AI response to stdout. The agent was only parsing stdout, so session_id was never found and detail always fell back to raw output. Now checks stderr first, then stdout as fallback.	2026-05-18 17:05:54 +00:00
xiaomo	7a99c1a9d6	Merge pull request 'fix: hermes agent empty detail — parse session_id from any line' (#347 ) from fix/342-parse-session-id into main	2026-05-18 16:58:24 +00:00
xiaoju	546237db85	fix: parseSessionIdFromStdout scans all lines, not just last --quiet mode outputs session_id on the first line, not the last. The old code only checked the last non-empty line and broke immediately if it didn't match, causing session detail to always be empty. Fixes the empty detail bug when hermes agent runs in quiet mode.	2026-05-18 16:57:24 +00:00
xiaomo	1ed7e32067	Merge pull request 'simplify: thread fork only takes step-hash' (#346 ) from fix/342-fork-simplify into main	2026-05-18 16:43:33 +00:00
xiaoju	bd5e5a435b	simplify: thread fork only takes step-hash Remove thread-id argument — CAS node is self-contained, no need to specify which thread it belongs to. Just verify the hash is a valid StartNode or StepNode. Refs #342	2026-05-18 16:38:55 +00:00
xiaomo	67e689ff1a	Merge pull request 'feat: thread steps + thread fork' (#345 ) from feat/342-thread-steps-fork into main	2026-05-18 16:34:55 +00:00
xiaoju	06eb2dff3b	feat: add thread steps and thread fork commands - uwf thread steps <thread-id>: walk CAS chain, list all steps chronologically - uwf thread fork <thread-id> <step-hash>: create new thread from history point - New types: StartEntry, StepEntry, ThreadStepsOutput, ThreadForkOutput - Supports both active and archived threads Refs #342	2026-05-18 16:30:12 +00:00
xiaomo	a2bd3126c8	Merge pull request 'refactor: AgentContext extends ModeratorContext, remove redundant fields' (#341 ) from refactor/simplify-agent-context into main	2026-05-18 16:17:16 +00:00
xiaoju	710d42d6b9	refactor(agent-kit): base AgentContext on ModeratorContext AgentContext now extends ModeratorContext (start + steps) with threadId, role, store, and expanded workflow. Hermes and mock-agent read prompt/steps/systemPrompt from the new shape. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-18 16:14:13 +00:00
xiaomo	072d900fcb	Merge pull request 'refactor: pass store via AgentContext, eliminate duplicate store instances' (#340 ) from refactor/pass-store-via-context into main	2026-05-18 16:05:38 +00:00