feat: remove LLM extract fallback, require YAML frontmatter

Agent output must contain valid YAML frontmatter matching the role schema.
If frontmatter parsing fails, the step fails immediately with a clear error
instead of falling back to an LLM extraction that can fabricate values.

The extract module remains as a public API export but is no longer used
in the agent run loop.

Breaking change: agents that relied on LLM extraction to produce valid
output will now fail. They must output proper frontmatter.

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

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": {

examples/analyze-topic.yaml

@@ -19,7 +19,7 @@ roles:
     output: |
       Provide your analysis as markdown under the frontmatter.
       The frontmatter must include your structured findings.
-    meta:
+    frontmatter:
       type: object
       properties:
         thesis:

examples/solve-issue.yaml

@@ -9,7 +9,7 @@ roles:
       - planning
     procedure: "Analyze the issue and create a detailed, actionable implementation plan."
     output: "Output the plan summary and list of concrete steps."
-    meta:
+    frontmatter:
       type: object
       properties:
         plan:
@@ -28,7 +28,7 @@ roles:
       - 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:
+    frontmatter:
       type: object
       properties:
         filesChanged:
@@ -46,7 +46,7 @@ roles:
       - 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:
+    frontmatter:
       type: object
       properties:
         approved:
@@ -57,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/workflow-agent-docx-diff/__tests__/agent.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { packageDescriptor } from "../src/package-descriptor.js";
 import { createDocxDiffAgent } from "../src/agent.js";
+import { packageDescriptor } from "../src/package-descriptor.js";
 
 describe("createDocxDiffAgent", () => {
   test("returns an AdapterFn (function)", () => {

legacy-packages/workflow-agent-docx-diff/__tests__/runner.test.ts

@@ -1,8 +1,8 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
 import { describe, expect, mock, test } from "bun:test";
-import { ok, err } from "@uncaged/workflow-util";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { err, ok } from "@uncaged/workflow-util";
 import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
 import { runDocxDiff } from "../src/runner.js";
 
@@ -74,7 +74,12 @@ describe("runDocxDiff", () => {
   test("exit 2: throws error", async () => {
     const dir = tempDir();
     const spawnFn = makeSpawn(
-      err({ kind: "non_zero_exit", exitCode: 2, stdout: "", stderr: "fatal error" }) as MockSpawnResult,
+      err({
+        kind: "non_zero_exit",
+        exitCode: 2,
+        stdout: "",
+        stderr: "fatal error",
+      }) as MockSpawnResult,
     );
 
     await expect(

legacy-packages/workflow-agent-docx-diff/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-agent-docx-diff",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

legacy-packages/workflow-agent-docx-diff/src/agent.ts

@@ -1,7 +1,12 @@
-import * as z from "zod/v4";
 import { dirname, join } from "node:path";
-import type { AdapterFn, RoleResult, ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import type {
+  AdapterFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
 import type { WriterMeta } from "@uncaged/workflow-template-document";
+import type * as z from "zod/v4";
 import { runDocxDiff } from "./runner.js";
 import type { DocxDiffAgentConfig } from "./types.js";
 
@@ -12,16 +17,10 @@ export function createDocxDiffAgent(config: DocxDiffAgentConfig): AdapterFn {
       if (writerStep === undefined) 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");
+      if (writerMeta.mode !== "edit") throw new Error("differ: writer did not run in edit mode");
 
       const diffDocx = join(dirname(writerMeta.outputDocx), "diff.docx");
-      const raw = await runDocxDiff(
-        config,
-        writerMeta.sourceDocx,
-        writerMeta.outputDocx,
-        diffDocx,
-      );
+      const raw = await runDocxDiff(config, writerMeta.sourceDocx, writerMeta.outputDocx, diffDocx);
 
       const meta = schema.parse(JSON.parse(raw)) as T;
       return { meta, childThread: null };

legacy-packages/workflow-agent-docx-diff/src/runner.ts

@@ -1,6 +1,6 @@
 import { stat } from "node:fs/promises";
-import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { SpawnCliError } from "@uncaged/workflow-util-agent";
+import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { DocxDiffAgentConfig } from "./types.js";
 
 type SpawnCliFn = typeof spawnCli;
@@ -8,8 +8,7 @@ type SpawnCliFn = typeof spawnCli;
 function throwSpawnError(e: SpawnCliError): never {
   if (e.kind === "non_zero_exit")
     throw new Error(`docx-diff failed (exit ${e.exitCode}): ${e.stderr}`);
-  if (e.kind === "timeout")
-    throw new Error("docx-diff: timed out");
+  if (e.kind === "timeout") throw new Error("docx-diff: timed out");
   throw new Error(`docx-diff: spawn failed: ${e.message}`);
 }
 

legacy-packages/workflow-agent-office/__tests__/agent.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { packageDescriptor } from "../src/package-descriptor.js";
 import { createOfficeAgent } from "../src/agent.js";
+import { packageDescriptor } from "../src/package-descriptor.js";
 
 describe("createOfficeAgent", () => {
   test("returns an AdapterFn (function)", () => {

legacy-packages/workflow-agent-office/__tests__/runner.test.ts

@@ -1,8 +1,8 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
 import { describe, expect, mock, test } from "bun:test";
-import { ok, err } from "@uncaged/workflow-util";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { err, ok } from "@uncaged/workflow-util";
 import type { SpawnCliConfig } from "@uncaged/workflow-util-agent";
 import { editDocument, generateDocument } from "../src/runner.js";
 
@@ -123,7 +123,13 @@ describe("editDocument", () => {
     );
 
     await expect(
-      editDocument({ outputDir: base, command: null, timeout: null }, "te2", "edit", inputFile, spawnFn),
+      editDocument(
+        { outputDir: base, command: null, timeout: null },
+        "te2",
+        "edit",
+        inputFile,
+        spawnFn,
+      ),
     ).rejects.toThrow("spawn failed");
   });
 });

legacy-packages/workflow-agent-office/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-agent-office",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

legacy-packages/workflow-agent-office/src/agent.ts

@@ -1,6 +1,11 @@
-import * as z from "zod/v4";
-import type { AdapterFn, RoleResult, ThreadContext, WorkflowRuntime } from "@uncaged/workflow-runtime";
+import type {
+  AdapterFn,
+  RoleResult,
+  ThreadContext,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
 import { createLogger } from "@uncaged/workflow-util";
+import type * as z from "zod/v4";
 import { editDocument, generateDocument } from "./runner.js";
 import type { OfficeAgentConfig } from "./types.js";
 
@@ -27,7 +32,10 @@ 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);
-      log("8FQKP3NV", `office-agent: mode=${inputDocx === null ? "generate" : "edit"} thread=${ctx.threadId}`);
+      log(
+        "8FQKP3NV",
+        `office-agent: mode=${inputDocx === null ? "generate" : "edit"} thread=${ctx.threadId}`,
+      );
 
       let raw: string;
       if (inputDocx === null) {
@@ -35,7 +43,11 @@ export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
         raw = JSON.stringify({ mode: "generate", outputDocx: result.outputDocx, sourceDocx: null });
       } else {
         const result = await editDocument(config, ctx.threadId, prompt, inputDocx);
-        raw = JSON.stringify({ mode: "edit", outputDocx: result.outputDocx, sourceDocx: result.sourceDocx });
+        raw = JSON.stringify({
+          mode: "edit",
+          outputDocx: result.outputDocx,
+          sourceDocx: result.sourceDocx,
+        });
       }
 
       const meta = schema.parse(JSON.parse(raw)) as T;

legacy-packages/workflow-agent-office/src/runner.ts

@@ -1,7 +1,7 @@
 import { copyFile, mkdir, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { SpawnCliError } from "@uncaged/workflow-util-agent";
+import { spawnCli } from "@uncaged/workflow-util-agent";
 import type { OfficeAgentConfig } from "./types.js";
 
 type SpawnCliFn = typeof spawnCli;
@@ -9,8 +9,7 @@ type SpawnCliFn = typeof spawnCli;
 function throwSpawnError(e: SpawnCliError): never {
   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");
+  if (e.kind === "timeout") throw new Error("office-agent: timed out");
   throw new Error(`office-agent: spawn failed: ${e.message}`);
 }
 

legacy-packages/workflow-dashboard/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Workflow Dashboard</title>
     <script>
-      (function () {
+      (() => {
         var t = localStorage.getItem("theme");
         if (t === "dark" || (!t && matchMedia("(prefers-color-scheme: dark)").matches)) {
           document.documentElement.classList.add("dark");

legacy-packages/workflow-dashboard/plugins/vite-limit-line-plugin.ts

@@ -54,10 +54,14 @@ type CallExpression = {
   arguments: Array<AstExpression>;
 };
 
-type AstExpression = Identifier | MemberExpression | CallExpression | {
-  type: string;
-  [key: string]: unknown;
-};
+type AstExpression =
+  | Identifier
+  | MemberExpression
+  | CallExpression
+  | {
+      type: string;
+      [key: string]: unknown;
+    };
 
 type VariableDeclarator = {
   id: Identifier | null;
@@ -258,15 +262,21 @@ function createLimitResolver(options: LimitLineOptions): (id: string) => Resolve
 }
 
 function shouldProcess(id: string, options: LimitLineOptions): boolean {
-  return options.include.test(id) && !id.includes("node_modules") && (options.exclude === null || !options.exclude.test(id));
+  return (
+    options.include.test(id) &&
+    !id.includes("node_modules") &&
+    (options.exclude === null || !options.exclude.test(id))
+  );
 }
 
 // --- Plugin ---
 
-function viteLimitLinePlugin(
-  userOptions: Partial<LimitLineOptions> = {},
-): Array<Plugin> {
-  const options: LimitLineOptions = { ...DEFAULT_OPTIONS, ...userOptions, overrides: userOptions.overrides ?? [] };
+function viteLimitLinePlugin(userOptions: Partial<LimitLineOptions> = {}): Array<Plugin> {
+  const options: LimitLineOptions = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    overrides: userOptions.overrides ?? [],
+  };
   const resolve = createLimitResolver(options);
 
   const rawCodeCache = new Map<string, string>();
@@ -358,5 +368,5 @@ function viteLimitLinePlugin(
   ];
 }
 
-export { viteLimitLinePlugin };
 export type { LimitLineOptions, LimitLineOverride };
+export { viteLimitLinePlugin };

legacy-packages/workflow-dashboard/src/components/ui/resizable-panel.tsx

@@ -55,10 +55,7 @@ export function ResizablePanel({
   }, []);
 
   return (
-    <div
-      className={cn("relative shrink-0", className)}
-      style={{ ...style, width }}
-    >
+    <div className={cn("relative shrink-0", className)} style={{ ...style, width }}>
       {children}
       <div
         className="absolute top-0 -right-1 w-2 h-full cursor-col-resize z-10 group"

legacy-packages/workflow-template-document/__tests__/document-template.test.ts

@@ -9,9 +9,7 @@ import type { DocumentMeta } from "../src/roles.js";
 
 const documentModerator = tableToModerator(documentTable);
 
-function makeCtx(
-  steps: ModeratorContext<DocumentMeta>["steps"],
-): ModeratorContext<DocumentMeta> {
+function makeCtx(steps: ModeratorContext<DocumentMeta>["steps"]): ModeratorContext<DocumentMeta> {
   return {
     threadId: "01TEST000000000000000000TR",
     depth: 0,
@@ -25,7 +23,11 @@ function writerGenerateStep(): RoleStep<DocumentMeta> {
   return {
     role: "writer",
     contentHash: "STUBHASHWRITER001",
-    meta: { mode: "generate", outputDocx: "/out/output.docx", sourceDocx: null } satisfies WriterMeta,
+    meta: {
+      mode: "generate",
+      outputDocx: "/out/output.docx",
+      sourceDocx: null,
+    } satisfies WriterMeta,
     refs: [],
     timestamp: 1,
   };
@@ -35,7 +37,11 @@ function writerEditStep(): RoleStep<DocumentMeta> {
   return {
     role: "writer",
     contentHash: "STUBHASHWRITER002",
-    meta: { mode: "edit", outputDocx: "/out/modified.docx", sourceDocx: "/out/original.docx" } satisfies WriterMeta,
+    meta: {
+      mode: "edit",
+      outputDocx: "/out/modified.docx",
+      sourceDocx: "/out/original.docx",
+    } satisfies WriterMeta,
     refs: [],
     timestamp: 1,
   };

legacy-packages/workflow-template-document/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@uncaged/workflow-template-document",
   "version": "0.1.0",
-  "files": ["src", "dist", "package.json"],
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "types": "src/index.ts",
   "exports": {

packages/cli-workflow/src/cli.ts

@@ -14,6 +14,7 @@ import {
   cmdCasWalk,
 } from "./commands/cas.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdSkillCli } from "./commands/skill.js";
 import {
   cmdThreadFork,
   cmdThreadKill,
@@ -47,7 +48,10 @@ const program = new Command();
 
 // eslint-disable-next-line -- dynamic import for version
 const pkg = await import("../package.json", { with: { type: "json" } });
-program.name("uwf").description("Stateless workflow CLI").version(pkg.default.version, "-V, --version");
+program
+  .name("uwf")
+  .description("Stateless workflow CLI")
+  .version(pkg.default.version, "-V, --version");
 program.option("--format <fmt>", "Output format: json or yaml", "json");
 
 const workflow = program.command("workflow").description("Workflow registry and CAS");
@@ -82,7 +86,7 @@ workflow
   .action(() => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdWorkflowList(storageRoot);
+      const result = await cmdWorkflowList(storageRoot, process.cwd());
       writeOutput(result);
     });
   });
@@ -97,7 +101,7 @@ thread
   .action((workflow: string, opts: { prompt: string }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt);
+      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt, process.cwd());
       writeOutput(result);
     });
   });
@@ -217,6 +221,15 @@ thread
     });
   });
 
+const skill = program.command("skill").description("Built-in skill references for agents");
+
+skill
+  .command("cli")
+  .description("Print a markdown reference of all uwf commands")
+  .action(() => {
+    console.log(cmdSkillCli());
+  });
+
 program
   .command("setup")
   .description("Configure provider, model, and agent")

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

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { Hash, JSONSchema, Store } from "@uncaged/json-cas";
+import type { JSONSchema, Store } from "@uncaged/json-cas";
 import { bootstrap, getSchema, refs, walk } from "@uncaged/json-cas";
 import { createFsStore } from "@uncaged/json-cas-fs";
 
@@ -53,18 +53,12 @@ export async function cmdCasPut(
   return { hash };
 }
 
-export async function cmdCasHas(
-  storageRoot: string,
-  hash: string,
-): Promise<{ exists: boolean }> {
+export async function cmdCasHas(storageRoot: string, hash: string): Promise<{ exists: boolean }> {
   const store = openStore(storageRoot);
   return { exists: store.has(hash) };
 }
 
-export async function cmdCasRefs(
-  storageRoot: string,
-  hash: string,
-): Promise<{ refs: string[] }> {
+export async function cmdCasRefs(storageRoot: string, hash: string): Promise<{ refs: string[] }> {
   const store = openStore(storageRoot);
   const node = store.get(hash);
   if (node === null) {
@@ -73,10 +67,7 @@ export async function cmdCasRefs(
   return { refs: refs(store, node) };
 }
 
-export async function cmdCasWalk(
-  storageRoot: string,
-  hash: string,
-): Promise<{ hashes: string[] }> {
+export async function cmdCasWalk(storageRoot: string, hash: string): Promise<{ hashes: string[] }> {
   const store = openStore(storageRoot);
   const result: string[] = [];
   walk(store, hash, (h) => {
@@ -90,9 +81,7 @@ export type SchemaListEntry = {
   title: string;
 };
 
-export async function cmdCasSchemaList(
-  storageRoot: string,
-): Promise<SchemaListEntry[]> {
+export async function cmdCasSchemaList(storageRoot: string): Promise<SchemaListEntry[]> {
   const store = openStore(storageRoot);
   const metaHash = await bootstrap(store);
   const entries: SchemaListEntry[] = [];
@@ -115,9 +104,7 @@ export async function cmdCasSchemaList(
   return entries;
 }
 
-export async function cmdCasReindex(
-  storageRoot: string,
-): Promise<{ status: string }> {
+export async function cmdCasReindex(storageRoot: string): Promise<{ status: string }> {
   const indexDir = join(storageRoot, "cas", "_index");
   const { rmSync } = await import("node:fs");
   rmSync(indexDir, { recursive: true, force: true });
@@ -126,10 +113,7 @@ export async function cmdCasReindex(
   return { status: "reindexed" };
 }
 
-export async function cmdCasSchemaGet(
-  storageRoot: string,
-  hash: string,
-): Promise<unknown> {
+export async function cmdCasSchemaGet(storageRoot: string, hash: string): Promise<unknown> {
   const store = openStore(storageRoot);
   const schema = getSchema(store, hash);
   if (schema === null) {

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

@@ -1,10 +1,9 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
 
-import { stringify, parse } from "yaml";
+import { parse, stringify } from "yaml";
 
 /**
  * Preset provider list — embedded to avoid runtime YAML loading dependency.
@@ -17,10 +16,18 @@ const PRESET_PROVIDERS = [
   { name: "openrouter", label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1" },
   { name: "venice", label: "Venice", baseUrl: "https://api.venice.ai/api/v1" },
   // China
-  { name: "dashscope", label: "DashScope (Alibaba)", baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1" },
+  {
+    name: "dashscope",
+    label: "DashScope (Alibaba)",
+    baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  },
   { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1" },
   { name: "siliconflow", label: "SiliconFlow", baseUrl: "https://api.siliconflow.cn/v1" },
-  { name: "volcengine", label: "Volcengine (ByteDance)", baseUrl: "https://ark.cn-beijing.volces.com/api/v3" },
+  {
+    name: "volcengine",
+    label: "Volcengine (ByteDance)",
+    baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+  },
   { name: "kimi", label: "Kimi (Moonshot)", baseUrl: "https://api.moonshot.cn/v1" },
   { name: "glm", label: "GLM (Zhipu AI)", baseUrl: "https://open.bigmodel.cn/api/paas/v4" },
   { name: "stepfun", label: "StepFun", baseUrl: "https://api.stepfun.com/v1" },
@@ -98,21 +105,27 @@ function apiKeyEnvName(providerName: string): string {
  * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
  */
 function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record<string, unknown> {
-  const providers = (typeof existing.providers === "object" && existing.providers !== null
-    ? { ...(existing.providers as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const providers = (
+    typeof existing.providers === "object" && existing.providers !== null
+      ? { ...(existing.providers as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
 
   const envName = apiKeyEnvName(args.provider);
   providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
 
-  const models = (typeof existing.models === "object" && existing.models !== null
-    ? { ...(existing.models as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const models = (
+    typeof existing.models === "object" && existing.models !== null
+      ? { ...(existing.models as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
   models.default = { provider: args.provider, name: args.model };
 
-  const agents = (typeof existing.agents === "object" && existing.agents !== null
-    ? { ...(existing.agents as Record<string, unknown>) }
-    : {}) as Record<string, unknown>;
+  const agents = (
+    typeof existing.agents === "object" && existing.agents !== null
+      ? { ...(existing.agents as Record<string, unknown>) }
+      : {}
+  ) as Record<string, unknown>;
 
   const agentName = args.agent ?? "hermes";
   if (Object.keys(agents).length === 0) {
@@ -211,8 +224,12 @@ async function fetchModels(baseUrl: string, apiKey: string): Promise<string[]> {
     if (!res.ok) return [];
     const body = (await res.json()) as { data?: { id: string }[] };
     if (!Array.isArray(body.data)) return [];
-    const NON_CHAT = /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
-    return body.data.map((m) => m.id).filter((id) => !NON_CHAT.test(id)).sort();
+    const NON_CHAT =
+      /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
+    return body.data
+      .map((m) => m.id)
+      .filter((id) => !NON_CHAT.test(id))
+      .sort();
   } catch {
     return [];
   }

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

@@ -0,0 +1 @@
+export { generateCliReference as cmdSkillCli } from "@uncaged/workflow-util";

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

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
 import { getSchema, validate } from "@uncaged/json-cas";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
@@ -24,21 +25,24 @@ import type {
 } from "@uncaged/workflow-protocol";
 import { generateUlid } from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
-import { stringify } from "yaml";
+import { parse, stringify } from "yaml";
 
 import {
   appendThreadHistory,
   createUwfStore,
+  discoverProjectWorkflows,
   findThreadInHistory,
   loadThreadHistory,
   loadThreadsIndex,
   loadWorkflowRegistry,
+  resolveProjectWorkflowFile,
   resolveWorkflowHash,
   saveThreadsIndex,
   type ThreadHistoryLine,
   type UwfStore,
 } from "../store.js";
-import { isCasRef } from "../validate.js";
+import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
+import { materializeWorkflowPayload } from "./workflow.js";
 
 const END_ROLE = "$END";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
@@ -66,11 +70,55 @@ function fail(message: string): never {
   process.exit(1);
 }
 
+async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`project workflow file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text) as unknown;
+  } catch (e) {
+    fail(`invalid YAML in ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail(`invalid workflow YAML in ${filePath}: expected WorkflowPayload shape`);
+  }
+
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    fail(filenameError);
+  }
+
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+  const hash = await uwf.store.put(uwf.schemas.workflow, materialized);
+  const stored = uwf.store.get(hash);
+  if (stored === null || !validate(uwf.store, stored)) {
+    fail("stored local workflow failed schema validation");
+  }
+
+  return hash;
+}
+
 async function resolveWorkflowCasRef(
   uwf: UwfStore,
   storageRoot: string,
   workflowId: string,
+  projectRoot: string,
 ): Promise<CasRef> {
+  // Project-local resolution: check .workflows/<workflowId>.yaml first
+  const localEntries = await discoverProjectWorkflows(projectRoot);
+  const localFile = resolveProjectWorkflowFile(localEntries, workflowId);
+  if (localFile !== null) {
+    return materializeLocalWorkflow(uwf, localFile);
+  }
+
+  // Global registry fallback
   const registry = await loadWorkflowRegistry(storageRoot);
   const hash = resolveWorkflowHash(registry, workflowId);
   if (!isCasRef(hash)) {
@@ -114,9 +162,10 @@ export async function cmdThreadStart(
   storageRoot: string,
   workflowId: string,
   prompt: string,
+  projectRoot: string,
 ): Promise<StartOutput> {
   const uwf = await createUwfStore(storageRoot);
-  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId);
+  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId, projectRoot);
 
   const threadId = generateUlid(Date.now()) as ThreadId;
   const startPayload: StartNodePayload = {

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

@@ -2,22 +2,31 @@ import { readFile } from "node:fs/promises";
 
 import type { JSONSchema } from "@uncaged/json-cas";
 import { putSchema, validate } from "@uncaged/json-cas";
-import type { CasRef, RoleDefinition, WorkflowPayload } from "@uncaged/workflow-protocol";
+import type {
+  CasRef,
+  RoleDefinition,
+  Transition,
+  WorkflowPayload,
+} from "@uncaged/workflow-protocol";
 import { parse } from "yaml";
 
 import {
   createUwfStore,
+  discoverProjectWorkflows,
   findRegistryName,
   loadWorkflowRegistry,
   resolveWorkflowHash,
   saveWorkflowRegistry,
   type UwfStore,
 } from "../store.js";
-import { parseWorkflowPayload } from "../validate.js";
+import { checkWorkflowFilenameConsistency, parseWorkflowPayload } from "../validate.js";
+
+export type WorkflowOrigin = "local" | "global";
 
 export type WorkflowListEntry = {
   name: string;
   hash: CasRef;
+  origin: WorkflowOrigin;
 };
 
 export type WorkflowPutOutput = {
@@ -42,30 +51,41 @@ function isJsonSchema(value: unknown): value is JSONSchema {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function resolveMetaRef(
+/** Normalize graph transitions: ensure condition is null (not undefined) for fallback entries. */
+function normalizeGraph(graph: Record<string, Transition[]>): Record<string, Transition[]> {
+  const result: Record<string, Transition[]> = {};
+  for (const [node, transitions] of Object.entries(graph)) {
+    result[node] = transitions.map((t) => ({
+      role: t.role,
+      condition: t.condition ?? null,
+    }));
+  }
+  return result;
+}
+
+async function resolveFrontmatterRef(
   uwf: UwfStore,
   roleName: string,
-  meta: unknown,
+  frontmatter: unknown,
 ): Promise<CasRef> {
-  if (!isJsonSchema(meta)) {
-    fail(`role "${roleName}": meta must be a JSON Schema object`);
+  if (!isJsonSchema(frontmatter)) {
+    fail(`role "${roleName}": frontmatter must be a JSON Schema object`);
   }
-  const schema: JSONSchema = meta.title === undefined
-    ? { ...meta, title: roleName }
-    : meta;
+  const schema: JSONSchema =
+    frontmatter.title === undefined ? { ...frontmatter, title: roleName } : frontmatter;
   return putSchema(uwf.store, schema);
 }
 
-async function materializeWorkflowPayload(
+export async function materializeWorkflowPayload(
   uwf: UwfStore,
   raw: WorkflowPayload,
 ): Promise<WorkflowPayload> {
   const roles: Record<string, RoleDefinition> = {};
   for (const [roleName, role] of Object.entries(raw.roles)) {
-    const meta = await resolveMetaRef(
+    const frontmatter = await resolveFrontmatterRef(
       uwf,
       `${raw.name}.${roleName}`,
-      role.meta,
+      role.frontmatter,
     );
     roles[roleName] = {
       description: role.description,
@@ -73,7 +93,7 @@ async function materializeWorkflowPayload(
       capabilities: role.capabilities,
       procedure: role.procedure,
       output: role.output,
-      meta,
+      frontmatter,
     };
   }
   return {
@@ -81,7 +101,7 @@ async function materializeWorkflowPayload(
     description: raw.description,
     roles,
     conditions: raw.conditions,
-    graph: raw.graph,
+    graph: normalizeGraph(raw.graph),
   };
 }
 
@@ -108,6 +128,11 @@ export async function cmdWorkflowPut(
     fail("invalid workflow YAML: expected WorkflowPayload shape");
   }
 
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    fail(filenameError);
+  }
+
   const uwf = await createUwfStore(storageRoot);
   const materialized = await materializeWorkflowPayload(uwf, payload);
 
@@ -150,7 +175,26 @@ export async function cmdWorkflowShow(
   };
 }
 
-export async function cmdWorkflowList(storageRoot: string): Promise<WorkflowListEntry[]> {
+export async function cmdWorkflowList(
+  storageRoot: string,
+  projectRoot: string,
+): Promise<WorkflowListEntry[]> {
+  const localEntries = await discoverProjectWorkflows(projectRoot);
   const registry = await loadWorkflowRegistry(storageRoot);
-  return Object.entries(registry).map(([name, hash]) => ({ name, hash }));
+
+  const result: WorkflowListEntry[] = [];
+  const localNames = new Set<string>();
+
+  for (const entry of localEntries) {
+    localNames.add(entry.name);
+    result.push({ name: entry.name, hash: "(local)", origin: "local" });
+  }
+
+  for (const [name, hash] of Object.entries(registry)) {
+    if (!localNames.has(name)) {
+      result.push({ name, hash, origin: "global" });
+    }
+  }
+
+  return result;
 }

packages/cli-workflow/src/schemas.ts

@@ -1,10 +1,6 @@
 import type { Hash, Store } from "@uncaged/json-cas";
 import { putSchema } from "@uncaged/json-cas";
-import {
-  START_NODE_SCHEMA,
-  STEP_NODE_SCHEMA,
-  WORKFLOW_SCHEMA,
-} from "@uncaged/workflow-protocol";
+import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@uncaged/workflow-protocol";
 
 export type UwfSchemaHashes = {
   workflow: Hash;

packages/cli-workflow/src/store.ts

@@ -1,4 +1,4 @@
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -11,6 +11,44 @@ import { registerUwfSchemas, type UwfSchemaHashes } from "./schemas.js";
 
 export type WorkflowRegistry = Record<string, CasRef>;
 
+/** A workflow entry discovered from the project-local .workflows/ directory. */
+export type ProjectWorkflowEntry = {
+  /** Workflow name (from YAML `name` field, equals filename stem). */
+  name: string;
+  /** Absolute path to the YAML file. */
+  filePath: string;
+};
+
+/**
+ * Scan `<projectRoot>/.workflows/*.yaml` (non-recursive) and return discovered entries.
+ * Returns an empty array if the directory does not exist.
+ */
+export async function discoverProjectWorkflows(
+  projectRoot: string,
+): Promise<ProjectWorkflowEntry[]> {
+  const dir = join(projectRoot, ".workflows");
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") {
+      return [];
+    }
+    throw e;
+  }
+
+  const result: ProjectWorkflowEntry[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) {
+      continue;
+    }
+    const stem = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.slice(0, -4);
+    result.push({ name: stem, filePath: join(dir, entry) });
+  }
+  return result;
+}
+
 /** Default filesystem root for uwf data (`~/.uncaged/workflow`). */
 export function getDefaultStorageRoot(): string {
   return join(homedir(), ".uncaged", "workflow");
@@ -104,6 +142,22 @@ export function resolveWorkflowHash(registry: WorkflowRegistry, id: string): Cas
   return registry[id] !== undefined ? registry[id] : id;
 }
 
+/**
+ * Resolve a workflow name to a project-local YAML file path.
+ * Returns null if the name is not found in the local entries.
+ */
+export function resolveProjectWorkflowFile(
+  localEntries: ProjectWorkflowEntry[],
+  name: string,
+): string | null {
+  for (const entry of localEntries) {
+    if (entry.name === name) {
+      return entry.filePath;
+    }
+  }
+  return null;
+}
+
 export function findRegistryName(registry: WorkflowRegistry, hash: Hash): string | null {
   for (const [name, h] of Object.entries(registry)) {
     if (h === hash) {

packages/cli-workflow/src/validate.ts

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import type { CasRef, WorkflowPayload } from "@uncaged/workflow-protocol";
 
 const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
@@ -14,8 +15,8 @@ function isRoleDefinition(value: unknown): boolean {
   if (!isRecord(value)) {
     return false;
   }
-  const meta = value.meta;
-  const metaOk = isRecord(meta) && typeof meta.type === "string";
+  const frontmatter = value.frontmatter;
+  const frontmatterOk = isRecord(frontmatter) && typeof frontmatter.type === "string";
   const capabilities = value.capabilities;
   const capabilitiesOk =
     Array.isArray(capabilities) && capabilities.every((c) => typeof c === "string");
@@ -25,7 +26,7 @@ function isRoleDefinition(value: unknown): boolean {
     capabilitiesOk &&
     typeof value.procedure === "string" &&
     typeof value.output === "string" &&
-    metaOk
+    frontmatterOk
   );
 }
 
@@ -41,7 +42,10 @@ function isTransition(value: unknown): boolean {
     return false;
   }
   const condition = value.condition;
-  return typeof value.role === "string" && (condition === null || typeof condition === "string");
+  return (
+    typeof value.role === "string" &&
+    (condition === null || condition === undefined || typeof condition === "string")
+  );
 }
 
 function isStringRecord(value: unknown, itemCheck: (item: unknown) => boolean): boolean {
@@ -60,6 +64,33 @@ function isGraph(value: unknown): boolean {
   );
 }
 
+/**
+ * Derive the expected workflow name from a file path (stem without extension).
+ * Returns the stem for `.yaml` / `.yml` files.
+ */
+export function workflowNameFromPath(filePath: string): string {
+  const base = basename(filePath);
+  if (base.endsWith(".yaml")) return base.slice(0, -5);
+  if (base.endsWith(".yml")) return base.slice(0, -4);
+  return base;
+}
+
+/**
+ * Check that the `name` field in a parsed payload matches the expected name
+ * derived from the file path.  Returns an error message string on mismatch,
+ * or null when the names are consistent.
+ */
+export function checkWorkflowFilenameConsistency(
+  filePath: string,
+  payload: WorkflowPayload,
+): string | null {
+  const expected = workflowNameFromPath(filePath);
+  if (payload.name !== expected) {
+    return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
+  }
+  return null;
+}
+
 /** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
 export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
   if (!isRecord(raw)) {

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

@@ -1,6 +1,11 @@
 import { spawn } from "node:child_process";
 
-import { type AgentContext, type AgentRunResult, buildRolePrompt, createAgent } from "@uncaged/workflow-agent-kit";
+import {
+  type AgentContext,
+  type AgentRunResult,
+  buildRolePrompt,
+  createAgent,
+} from "@uncaged/workflow-agent-kit";
 
 import {
   loadHermesSession,

packages/workflow-agent-kit/__tests__/build-role-prompt.test.ts

@@ -18,13 +18,16 @@ describe("buildRolePrompt", () => {
     expect(result).toContain("## Capabilities");
     expect(result).toContain("- cursor-agent");
     expect(result).toContain("- file-edit");
+    expect(result).toContain("## Prepare");
+    expect(result).toContain("uwf CLI Reference");
+    expect(result).toContain("cursor-agent, file-edit");
     expect(result).toContain("## Procedure");
     expect(result).toContain("Implement the feature.");
     expect(result).toContain("## Output");
     expect(result).toContain("Summarize changes.");
   });
 
-  test("empty fields are omitted", () => {
+  test("empty fields are omitted but Prepare is always present", () => {
     const role: RoleDefinition = {
       description: "A reviewer",
       goal: "You are a code reviewer.",
@@ -35,12 +38,14 @@ describe("buildRolePrompt", () => {
     };
     const result = buildRolePrompt(role);
     expect(result).toContain("## Goal");
+    expect(result).toContain("## Prepare");
+    expect(result).toContain("uwf CLI Reference");
     expect(result).toContain("## Procedure");
     expect(result).not.toContain("## Capabilities");
     expect(result).not.toContain("## Output");
   });
 
-  test("all empty returns empty string", () => {
+  test("all empty still includes Prepare section", () => {
     const role: RoleDefinition = {
       description: "Minimal",
       goal: "",
@@ -50,7 +55,12 @@ describe("buildRolePrompt", () => {
       meta: "placeholder00000" as string,
     };
     const result = buildRolePrompt(role);
-    expect(result).toBe("");
+    expect(result).toContain("## Prepare");
+    expect(result).toContain("uwf CLI Reference");
+    expect(result).not.toContain("## Goal");
+    expect(result).not.toContain("## Capabilities");
+    expect(result).not.toContain("## Procedure");
+    expect(result).not.toContain("## Output");
   });
 
   test("capabilities rendered as bullet list", () => {

packages/workflow-agent-kit/__tests__/frontmatter-fast-path.test.ts

@@ -1,6 +1,5 @@
-import { describe, expect, test } from "vitest";
-
 import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
 
 import { tryFrontmatterFastPath } from "../src/frontmatter.js";
 
@@ -68,7 +67,8 @@ describe("tryFrontmatterFastPath — happy path", () => {
   test("stored CAS node payload matches frontmatter fields", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
 
-    const raw = "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
+    const raw =
+      "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).not.toBeNull();

packages/workflow-agent-kit/src/build-role-prompt.ts

@@ -1,10 +1,15 @@
 import type { RoleDefinition } from "@uncaged/workflow-protocol";
+import { generateCliReference } from "@uncaged/workflow-util";
 
 /**
  * Build the role prompt from a RoleDefinition.
  *
- * Assembles structured sections: Goal, Capabilities, Procedure, Output.
+ * Assembles structured sections: Goal, Capabilities, Prepare, Procedure, Output.
  * Empty strings and empty arrays are omitted from the output.
+ *
+ * The Prepare section always inlines the uwf CLI reference so the agent has
+ * workflow knowledge without needing to run an external command. The capabilities
+ * array is rendered as keyword hints for implicit skill loading.
  */
 export function buildRolePrompt(role: RoleDefinition): string {
   const sections: string[] = [];
@@ -18,6 +23,15 @@ export function buildRolePrompt(role: RoleDefinition): string {
     sections.push(`## Capabilities\n\n${list}`);
   }
 
+  const prepareLines: string[] = [generateCliReference()];
+  if (role.capabilities.length > 0) {
+    const keywords = role.capabilities.join(", ");
+    prepareLines.push(
+      `You have the following capabilities: ${keywords}. Load relevant skills matching these keywords before starting work.`,
+    );
+  }
+  sections.push(`## Prepare\n\n${prepareLines.join("\n\n")}`);
+
   if (role.procedure !== "") {
     sections.push(`## Procedure\n\n${role.procedure}`);
   }

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

@@ -6,8 +6,8 @@ import type {
   StepNodePayload,
   ThreadId,
 } from "@uncaged/workflow-protocol";
-import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
 import type { AgentStore } from "./storage.js";
+import { createAgentStore, loadThreadsIndex, resolveStorageRoot } from "./storage.js";
 import type { AgentContext } from "./types.js";
 
 type ChainState = {
@@ -21,11 +21,7 @@ function fail(message: string): never {
   throw new Error(message);
 }
 
-function walkChain(
-  store: Store,
-  schemas: AgentStore["schemas"],
-  headHash: CasRef,
-): ChainState {
+function walkChain(store: Store, schemas: AgentStore["schemas"], headHash: CasRef): ChainState {
   const headNode = store.get(headHash);
   if (headNode === null) {
     fail(`CAS node not found: ${headHash}`);
@@ -78,10 +74,7 @@ function walkChain(
   };
 }
 
-function expandOutput(
-  store: Store,
-  outputRef: CasRef,
-): unknown {
+function expandOutput(store: Store, outputRef: CasRef): unknown {
   const node = store.get(outputRef);
   if (node === null) {
     return {};
@@ -106,11 +99,7 @@ async function buildHistory(
   return history;
 }
 
-async function loadWorkflow(
-  store: Store,
-  schemas: AgentStore["schemas"],
-  workflowRef: CasRef,
-) {
+async function loadWorkflow(store: Store, schemas: AgentStore["schemas"], workflowRef: CasRef) {
   const node = store.get(workflowRef);
   if (node === null) {
     fail(`workflow CAS node not found: ${workflowRef}`);

packages/workflow-agent-kit/src/frontmatter.ts

@@ -1,5 +1,5 @@
-import { validate } from "@uncaged/json-cas";
 import type { Store } from "@uncaged/json-cas";
+import { validate } from "@uncaged/json-cas";
 import type { CasRef } from "@uncaged/workflow-protocol";
 import { parseFrontmatterMarkdown, validateFrontmatter } from "@uncaged/workflow-util";
 

packages/workflow-agent-kit/src/index.ts

@@ -1,3 +1,5 @@
+export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
+export { buildRolePrompt } from "./build-role-prompt.js";
 export type { BuildContextMeta } from "./context.js";
 export { buildContext, buildContextWithMeta } from "./context.js";
 export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
@@ -6,8 +8,6 @@ export {
   resolveExtractModelAlias,
   resolveModel,
 } from "./extract.js";
-export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
-export { buildRolePrompt } from "./build-role-prompt.js";
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
 export { createAgent } from "./run.js";

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

@@ -1,13 +1,11 @@
 import { getSchema, validate } from "@uncaged/json-cas";
 import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/workflow-protocol";
 import { config as loadDotenv } from "dotenv";
-
-import { buildContextWithMeta } from "./context.js";
 import { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
-import { extract } from "./extract.js";
+import { buildContextWithMeta } from "./context.js";
 import { tryFrontmatterFastPath } from "./frontmatter.js";
 import type { AgentStore } from "./storage.js";
-import { getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
+import { getEnvPath, resolveStorageRoot } from "./storage.js";
 import type { AgentContext, AgentOptions, AgentRunResult } from "./types.js";
 
 function fail(message: string): never {
@@ -74,24 +72,19 @@ async function runAgent(options: AgentOptions, ctx: AgentContext): Promise<Agent
 async function extractOutput(
   rawOutput: string,
   outputSchema: CasRef,
-  storageRoot: string,
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
 ): Promise<CasRef> {
-  const fastPath = await runWithMessage("frontmatter fast path", () =>
-    tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store),
-  ).catch(() => null);
+  const fastPath = await tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store);
 
   if (fastPath !== null) {
     return fastPath.outputHash;
   }
 
-  const config = await runWithMessage("failed to load config", () =>
-    loadWorkflowConfig(storageRoot),
+  fail(
+    "Agent output does not contain valid YAML frontmatter matching the role schema.\n" +
+      "The agent must output a YAML frontmatter block (--- delimited) as the first thing in its response.\n" +
+      `Raw output (first 500 chars): ${rawOutput.slice(0, 500)}`,
   );
-  const extracted = await runWithMessage("extract failed", () =>
-    extract(rawOutput, outputSchema, config),
-  );
-  return extracted.hash;
 }
 
 async function persistStep(options: {
@@ -131,13 +124,13 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       fail(`unknown role: ${role}`);
     }
 
-    const metaSchema = getSchema(ctx.meta.store, roleDef.meta);
-    if (metaSchema !== null) {
-      ctx.outputFormatInstruction = buildOutputFormatInstruction(metaSchema);
+    const frontmatterSchema = getSchema(ctx.meta.store, roleDef.frontmatter);
+    if (frontmatterSchema !== null) {
+      ctx.outputFormatInstruction = buildOutputFormatInstruction(frontmatterSchema);
     }
 
     const agentResult = await runAgent(options, ctx);
-    const outputHash = await extractOutput(agentResult.output, roleDef.meta, storageRoot, ctx);
+    const outputHash = await extractOutput(agentResult.output, roleDef.frontmatter, ctx);
     const stepHash = await persistStep({
       ctx,
       outputHash,

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

@@ -35,11 +35,11 @@ const solveIssueWorkflow: WorkflowPayload = {
   conditions: {
     needsClarification: {
       description: "Planner requests clarification from user",
-      expression: "$exists(steps[-1].output.needsClarification)",
+      expression: "$exists($last('planner').needsClarification)",
     },
-    notApproved: {
+    rejected: {
       description: "Reviewer rejected the implementation",
-      expression: "steps[-1].output.approved = false",
+      expression: "$last('reviewer').approved = false",
     },
   },
   graph: {
@@ -50,7 +50,7 @@ const solveIssueWorkflow: WorkflowPayload = {
     ],
     developer: [{ role: "reviewer", condition: null }],
     reviewer: [
-      { role: "developer", condition: "notApproved" },
+      { role: "developer", condition: "rejected" },
       { role: "$END", condition: null },
     ],
   },
@@ -72,7 +72,7 @@ describe("evaluate", () => {
     expect(result).toEqual({ ok: true, value: "planner" });
   });
 
-  test("condition match (notApproved → developer)", async () => {
+  test("condition match (rejected → developer)", async () => {
     const context = makeContext([
       {
         role: "reviewer",
@@ -126,4 +126,116 @@ describe("evaluate", () => {
     const result = await evaluate(solveIssueWorkflow, context);
     expect(result).toEqual({ ok: true, value: "developer" });
   });
+
+  test("$last returns most recent matching role's frontmatter", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        devFailed: {
+          description: "Developer failed",
+          expression: "$last('developer').status = 'failed'",
+        },
+      },
+      graph: {
+        $START: [{ role: "developer", condition: null }],
+        developer: [
+          { role: "$END", condition: "devFailed" },
+          { role: "reviewer", condition: null },
+        ],
+      },
+    };
+    const context = makeContext([
+      {
+        role: "developer",
+        output: { status: "done" },
+        detail: "1VPBG9SM5E7WK",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "2MXBG6PN4A8JR",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "developer",
+        output: { status: "failed" },
+        detail: "3QNTH7WK8D2PA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
+    expect(result).toEqual({ ok: true, value: "$END" });
+  });
+
+  test("$first returns earliest matching role's frontmatter", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        firstPlanReady: {
+          description: "First planner run was ready",
+          expression: "$first('planner').status = 'ready'",
+        },
+      },
+      graph: {
+        $START: [{ role: "planner", condition: null }],
+        planner: [
+          { role: "$END", condition: "firstPlanReady" },
+          { role: "developer", condition: null },
+        ],
+      },
+    };
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { status: "ready", plan: "ABC123" },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "developer",
+        output: { status: "done" },
+        detail: "1VPBG9SM5E7WK",
+        agent: "uwf-hermes",
+      },
+      {
+        role: "planner",
+        output: { status: "revised", plan: "DEF456" },
+        detail: "4RNMK6PX8B3WQ",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
+    expect(result).toEqual({ ok: true, value: "$END" });
+  });
+
+  test("$last returns undefined for unmatched role", async () => {
+    const workflow: WorkflowPayload = {
+      ...solveIssueWorkflow,
+      conditions: {
+        hasReviewer: {
+          description: "Reviewer has run",
+          expression: "$exists($last('reviewer'))",
+        },
+      },
+      graph: {
+        $START: [{ role: "planner", condition: null }],
+        planner: [
+          { role: "$END", condition: "hasReviewer" },
+          { role: "developer", condition: null },
+        ],
+      },
+    };
+    const context = makeContext([
+      {
+        role: "planner",
+        output: { status: "ready" },
+        detail: "7BQST3VW9F2MA",
+        agent: "uwf-hermes",
+      },
+    ]);
+    const result = await evaluate(workflow, context);
+    // no reviewer step → $exists returns false → fallback to developer
+    expect(result).toEqual({ ok: true, value: "developer" });
+  });
 });

packages/workflow-moderator/src/evaluate.ts

@@ -21,9 +21,44 @@ function isTruthy(value: unknown): boolean {
   return true;
 }
 
-async function evaluateJsonata(expression: string, context: ModeratorContext): Promise<Result<unknown, Error>> {
+function findByRole(
+  steps: ModeratorContext["steps"],
+  role: string,
+  direction: "first" | "last",
+): unknown {
+  if (direction === "last") {
+    for (let i = steps.length - 1; i >= 0; i--) {
+      if (steps[i].role === role) {
+        return steps[i].output;
+      }
+    }
+  } else {
+    for (const step of steps) {
+      if (step.role === role) {
+        return step.output;
+      }
+    }
+  }
+  return undefined;
+}
+
+async function evaluateJsonata(
+  expression: string,
+  context: ModeratorContext,
+): Promise<Result<unknown, Error>> {
   try {
-    const result = await jsonata(expression).evaluate(context);
+    const expr = jsonata(expression);
+    expr.registerFunction(
+      "first",
+      (role: string) => findByRole(context.steps, role, "first"),
+      "<s:x>",
+    );
+    expr.registerFunction(
+      "last",
+      (role: string) => findByRole(context.steps, role, "last"),
+      "<s:x>",
+    );
+    const result = await expr.evaluate(context);
     return { ok: true, value: result };
   } catch (error) {
     return {

packages/workflow-protocol/src/schemas.ts

@@ -2,14 +2,14 @@ import type { JSONSchema } from "@uncaged/json-cas";
 
 const ROLE_DEFINITION: JSONSchema = {
   type: "object",
-  required: ["description", "goal", "capabilities", "procedure", "output", "meta"],
+  required: ["description", "goal", "capabilities", "procedure", "output", "frontmatter"],
   properties: {
     description: { type: "string" },
     goal: { type: "string" },
     capabilities: { type: "array", items: { type: "string" } },
     procedure: { type: "string" },
     output: { type: "string" },
-    meta: { type: "string", format: "cas_ref" },
+    frontmatter: { type: "string", format: "cas_ref" },
   },
   additionalProperties: false,
 };

packages/workflow-protocol/src/types.ts

@@ -22,7 +22,7 @@ export type RoleDefinition = {
   capabilities: string[];
   procedure: string;
   output: string;
-  meta: CasRef;
+  frontmatter: CasRef;
 };
 
 export type Transition = {

packages/workflow-util/src/cli-reference.ts

@@ -0,0 +1,72 @@
+// MAINTENANCE: This string must be kept in sync with the actual uwf CLI commands.
+// Update whenever commands are added, removed, or their signatures change.
+export function generateCliReference(): string {
+  return `# uwf CLI Reference
+
+## Setup
+
+\`\`\`
+uwf setup                                         # interactive setup wizard
+uwf setup --provider <name> --base-url <url> \\
+           --api-key <key> --model <name>          # non-interactive setup
+           [--agent <name>]                        # optional: default agent alias
+\`\`\`
+
+## Workflow Commands
+
+\`\`\`
+uwf workflow put <file>           # register a workflow from YAML file
+uwf workflow show <id>            # show workflow by name or CAS hash
+uwf workflow list                 # list all registered workflows
+\`\`\`
+
+## Thread Commands
+
+\`\`\`
+uwf thread start <workflow> -p <prompt>           # create a thread (no execution)
+uwf thread step <thread-id>                       # execute one moderator→agent→extract cycle
+               [--agent <cmd>]                    # override agent command
+uwf thread show <thread-id>                       # show thread head pointer
+uwf thread list                                   # list active threads
+               [--all]                            # include archived threads
+uwf thread kill <thread-id>                       # terminate and archive a thread
+uwf thread steps <thread-id>                      # list all steps in a thread
+uwf thread read <thread-id>                       # render thread context as markdown
+               [--quota <chars>]                  # max output characters (default 32000)
+               [--before <step-hash>]             # load steps before this hash (exclusive)
+               [--start]                          # include start step in output
+uwf thread fork <step-hash>                       # fork a thread from a specific step
+uwf thread step-details <step-hash>               # dump full detail node of a step as YAML
+\`\`\`
+
+## CAS Commands
+
+\`\`\`
+uwf cas get <hash>                # read a CAS node (type + payload)
+            [--timestamp]         # include timestamp in output
+uwf cas put <type-hash> <data>    # store a node, print its hash
+                                  # <data>: JSON file path or inline JSON string
+uwf cas has <hash>                # check if a hash exists
+uwf cas refs <hash>               # list direct CAS references from a node
+uwf cas walk <hash>               # recursive traversal from a node
+uwf cas reindex                   # rebuild type index from all CAS nodes
+uwf cas schema list               # list all registered schemas
+uwf cas schema get <hash>         # show a schema by its type hash
+\`\`\`
+
+## Global Options
+
+\`\`\`
+uwf --format <fmt>                # output format: json (default) or yaml
+uwf -V, --version                 # print version
+\`\`\`
+
+## Key Concepts
+
+- **Workflow**: YAML definition with roles, conditions, and a routing graph; stored as a CAS node identified by its XXH64 hash.
+- **Thread**: A single workflow execution (ULID). State is an immutable CAS chain; active threads are indexed in \`threads.yaml\`.
+- **Step**: One moderator→agent→extract cycle. Run \`uwf thread step\` repeatedly until \`$END\`.
+- **CAS**: Content-Addressed Storage — all nodes are immutable and identified by hash.
+- **Role**: Named actor with goal, capabilities, procedure, output, and meta; the moderator routes between roles.
+`;
+}

packages/workflow-util/src/index.ts

@@ -1,10 +1,6 @@
-export { err, ok } from "./result.js";
 export { encodeUint64AsCrockford } from "./base32.js";
+export { generateCliReference } from "./cli-reference.js";
 export { env } from "./env.js";
-export {
-  parseFrontmatterMarkdown,
-  validateFrontmatter,
-} from "./frontmatter-markdown/index.js";
 export type {
   AgentFrontmatter,
   FrontmatterScope,
@@ -12,8 +8,13 @@ export type {
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,
 } from "./frontmatter-markdown/index.js";
+export {
+  parseFrontmatterMarkdown,
+  validateFrontmatter,
+} from "./frontmatter-markdown/index.js";
 export { createLogger } from "./logger.js";
 export { normalizeRefsField } from "./refs-field.js";
+export { err, ok } from "./result.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
 export type { LogFn, Result } from "./types.js";
 export { generateUlid } from "./ulid.js";