fix(cli): usage not red + skill subcommand + --help flag on groups

1. No-args usage uses printCliLine (not printCliError), exit 1
2. 'skill [topic]' as first-class command (help --skill kept as compat)
3. 'workflow --help', 'thread --help' etc. show group subcommands
4. Role prompts updated: 'uncaged-workflow skill develop'

240 tests (6 new), build clean.

Closes #83

小橘 🍊

packages/cli-workflow/__tests__/help.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, test } from "bun:test";
+import { runCli } from "../src/cli-dispatch.js";
+import {
+  formatSkillDoc,
+  formatSkillIndex,
+  formatSkillTopic,
+  getSkillTopics,
+} from "../src/cmd-help.js";
+
+const STORAGE_ROOT = "/tmp/help-test-storage";
+
+describe("help command", () => {
+  test("help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["help"]);
+    expect(code).toBe(0);
+  });
+
+  test("no args prints usage (not red) and returns 1", async () => {
+    const code = await runCli(STORAGE_ROOT, []);
+    expect(code).toBe(1);
+  });
+});
+
+describe("skill command", () => {
+  test("skill (no topic) lists topics and returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["skill"]);
+    expect(code).toBe(0);
+  });
+
+  test("skill cli returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["skill", "cli"]);
+    expect(code).toBe(0);
+  });
+
+  test("skill develop returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["skill", "develop"]);
+    expect(code).toBe(0);
+  });
+
+  test("skill author returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["skill", "author"]);
+    expect(code).toBe(0);
+  });
+
+  test("skill unknown returns 1", async () => {
+    const code = await runCli(STORAGE_ROOT, ["skill", "unknown"]);
+    expect(code).toBe(1);
+  });
+});
+
+describe("--help flag on groups", () => {
+  test("workflow --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["workflow", "--help"]);
+    expect(code).toBe(0);
+  });
+
+  test("thread --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["thread", "--help"]);
+    expect(code).toBe(0);
+  });
+
+  test("cas --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["cas", "--help"]);
+    expect(code).toBe(0);
+  });
+
+  test("init --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["init", "--help"]);
+    expect(code).toBe(0);
+  });
+});
+
+describe("legacy help --skill compat", () => {
+  test("help --skill still works (lists topics)", async () => {
+    const code = await runCli(STORAGE_ROOT, ["help", "--skill"]);
+    expect(code).toBe(0);
+  });
+});
+
+describe("getSkillTopics", () => {
+  test("returns all topics", () => {
+    const topics = getSkillTopics();
+    const names = topics.map((t) => t.name);
+    expect(names).toContain("cli");
+    expect(names).toContain("develop");
+    expect(names).toContain("author");
+  });
+});
+
+describe("formatSkillIndex", () => {
+  test("lists all topics", () => {
+    const idx = formatSkillIndex();
+    expect(idx).toContain("cli");
+    expect(idx).toContain("develop");
+    expect(idx).toContain("author");
+    expect(idx).toContain("skill <topic>");
+  });
+});
+
+describe("formatSkillTopic('cli') — legacy formatSkillDoc", () => {
+  const doc = formatSkillDoc();
+
+  test("contains title", () => {
+    expect(doc).toContain("# uncaged-workflow CLI Reference");
+  });
+
+  test("contains all command group headers", () => {
+    expect(doc).toContain("### workflow");
+    expect(doc).toContain("### thread");
+    expect(doc).toContain("### cas");
+    expect(doc).toContain("### init");
+    expect(doc).toContain("### Top-level shortcuts");
+  });
+
+  test("contains core concepts", () => {
+    expect(doc).toContain("## Core Concepts");
+    expect(doc).toContain("Workflow");
+    expect(doc).toContain("Bundle");
+    expect(doc).toContain("Thread");
+    expect(doc).toContain("CAS");
+    expect(doc).toContain("Registry");
+  });
+
+  test("mentions all workflow subcommands", () => {
+    for (const sub of ["add", "list", "show", "rm", "history", "rollback"]) {
+      expect(doc).toContain(`workflow ${sub}`);
+    }
+  });
+
+  test("mentions all thread subcommands", () => {
+    for (const sub of [
+      "run",
+      "list",
+      "show",
+      "rm",
+      "fork",
+      "ps",
+      "kill",
+      "live",
+      "pause",
+      "resume",
+    ]) {
+      expect(doc).toContain(`thread ${sub}`);
+    }
+  });
+
+  test("mentions all cas subcommands", () => {
+    for (const sub of ["get", "put", "list", "rm", "gc"]) {
+      expect(doc).toContain(`cas ${sub}`);
+    }
+  });
+
+  test("contains exit codes section", () => {
+    expect(doc).toContain("## Exit Codes");
+  });
+
+  test("contains environment variables section", () => {
+    expect(doc).toContain("## Environment Variables");
+    expect(doc).toContain("UNCAGED_WORKFLOW_STORAGE_ROOT");
+  });
+
+  test("contains typical workflow section", () => {
+    expect(doc).toContain("## Typical Workflow");
+  });
+});
+
+describe("formatSkillTopic('develop')", () => {
+  const doc = formatSkillTopic("develop");
+
+  test("returns non-null", () => {
+    expect(doc).not.toBeNull();
+  });
+
+  test("contains thread ID info", () => {
+    expect(doc).toContain("Thread ID");
+    expect(doc).toContain("Crockford Base32");
+  });
+
+  test("contains CAS commands", () => {
+    expect(doc).toContain("cas put");
+    expect(doc).toContain("cas get");
+  });
+
+  test("contains meta output section", () => {
+    expect(doc).toContain("Meta Output");
+  });
+});
+
+describe("formatSkillTopic('author')", () => {
+  const doc = formatSkillTopic("author");
+
+  test("returns non-null", () => {
+    expect(doc).not.toBeNull();
+  });
+
+  test("contains bundle structure", () => {
+    expect(doc).toContain("Bundle Structure");
+    expect(doc).toContain(".esm.js");
+  });
+
+  test("contains descriptor info", () => {
+    expect(doc).toContain("WorkflowDescriptor");
+  });
+
+  test("contains role definition", () => {
+    expect(doc).toContain("Role Definition");
+  });
+});
+
+describe("formatSkillTopic unknown", () => {
+  test("returns null for unknown topic", () => {
+    expect(formatSkillTopic("nonexistent")).toBeNull();
+  });
+});

packages/cli-workflow/__tests__/storage-env.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
+import { resolveWorkflowStorageRoot } from "../src/storage-env.js";
+
+describe("resolveWorkflowStorageRoot", () => {
+  let savedInternal: string | undefined;
+  let savedUser: string | undefined;
+
+  beforeEach(() => {
+    savedInternal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    savedUser = process.env.WORKFLOW_STORAGE_ROOT;
+    delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    delete process.env.WORKFLOW_STORAGE_ROOT;
+  });
+
+  afterEach(() => {
+    if (savedInternal === undefined) {
+      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = savedInternal;
+    }
+    if (savedUser === undefined) {
+      delete process.env.WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.WORKFLOW_STORAGE_ROOT = savedUser;
+    }
+  });
+
+  test("returns default when no env vars are set", () => {
+    expect(resolveWorkflowStorageRoot()).toBe(getDefaultWorkflowStorageRoot());
+  });
+
+  test("WORKFLOW_STORAGE_ROOT overrides default", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/custom-storage";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/custom-storage");
+  });
+
+  test("UNCAGED_WORKFLOW_STORAGE_ROOT takes priority over WORKFLOW_STORAGE_ROOT", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/user-path";
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = "/tmp/internal-path";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/internal-path");
+  });
+
+  test("ignores empty WORKFLOW_STORAGE_ROOT", () => {
+    process.env.WORKFLOW_STORAGE_ROOT = "";
+    expect(resolveWorkflowStorageRoot()).toBe(getDefaultWorkflowStorageRoot());
+  });
+
+  test("ignores empty UNCAGED_WORKFLOW_STORAGE_ROOT and falls through to WORKFLOW_STORAGE_ROOT", () => {
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = "";
+    process.env.WORKFLOW_STORAGE_ROOT = "/tmp/user-fallback";
+    expect(resolveWorkflowStorageRoot()).toBe("/tmp/user-fallback");
+  });
+});

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

@@ -3,6 +3,7 @@ import { cmdAdd, formatAddSuccess, parseAddArgv } from "./cmd-add.js";
 import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "./cmd-cas.js";
 import { cmdFork, parseForkArgv } from "./cmd-fork.js";
 import { cmdGc } from "./cmd-gc.js";
+import { formatSkillDoc, formatSkillIndex, formatSkillTopic } from "./cmd-help.js";
 import { cmdHistory } from "./cmd-history.js";
 import { cmdInitTemplate, cmdInitWorkspace } from "./cmd-init.js";
 import { cmdKill } from "./cmd-kill.js";
@@ -20,80 +21,49 @@ import { cmdThreads } from "./cmd-threads.js";
 import { parseLiveArgv } from "./live-argv.js";
 import { parseRunArgv } from "./run-argv.js";
 
-export function formatCliUsage(): string {
-  return [
-    "Usage:",
-    "  uncaged-workflow workflow add <name> <file.esm.js> [--types <path>]",
-    "  uncaged-workflow workflow list",
-    "  uncaged-workflow workflow show <name>",
-    "  uncaged-workflow workflow rm <name>",
-    "  uncaged-workflow workflow history <name>",
-    "  uncaged-workflow workflow rollback <name> [hash]",
-    "",
-    "  uncaged-workflow thread run <name> [--prompt <text>] [--max-rounds N]",
-    "  uncaged-workflow thread list [name]",
-    "  uncaged-workflow thread show <id>",
-    "  uncaged-workflow thread rm <id>",
-    "  uncaged-workflow thread ps",
-    "  uncaged-workflow thread kill <thread-id>",
-    "  uncaged-workflow thread live <thread-id> [--debug] [--role <name>]",
-    "  uncaged-workflow thread live --latest [--debug] [--role <name>]",
-    "  uncaged-workflow thread pause <thread-id>",
-    "  uncaged-workflow thread resume <thread-id>",
-    "  uncaged-workflow thread fork <thread-id> [--from-role <role>]",
-    "",
-    "  uncaged-workflow cas get <thread-id> <hash>",
-    "  uncaged-workflow cas put <thread-id> <content>",
-    "  uncaged-workflow cas list <thread-id>",
-    "  uncaged-workflow cas rm <thread-id> <hash>",
-    "  uncaged-workflow cas gc",
-    "",
-    "  uncaged-workflow init workspace <name>",
-    "  uncaged-workflow init template <name>",
-    "",
-    "  uncaged-workflow run <name> [...]          (shortcut for thread run)",
-    "  uncaged-workflow live <thread-id> [...]    (shortcut for thread live)",
-  ].join("\n");
-}
-
-function printDeprecation(oldCmd: string, newCmd: string): void {
-  printCliWarn(`⚠ "${oldCmd}" is deprecated, use "${newCmd}" instead`);
-}
-
 type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
 
+type CommandEntry = {
+  handler: DispatchFn;
+  args: string;
+  description: string;
+};
+
+type CommandGroup = {
+  name: string;
+  commands: ReadonlyArray<{ name: string; args: string; description: string }>;
+};
+
 // ── Individual dispatch functions ──────────────────────────────────────
 
-async function dispatchInit(_storageRoot: string, argv: string[]): Promise<number> {
-  const sub = argv[0];
-  const name = argv[1];
-  if (sub === undefined || name === undefined || argv.length > 2) {
-    printCliError(`${formatCliUsage()}\n\nerror: init requires workspace|template <name>`);
+async function dispatchInitWorkspace(_storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${formatCliUsage()}\n\nerror: init workspace requires <name>`);
     return 1;
   }
-
-  if (sub === "workspace") {
-    const result = await cmdInitWorkspace(process.cwd(), name);
-    if (!result.ok) {
-      printCliError(result.error);
-      return 1;
-    }
-    printCliLine(`initialized workflow workspace at ${result.value.rootPath}`);
-    return 0;
+  const result = await cmdInitWorkspace(process.cwd(), name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
   }
+  printCliLine(`initialized workflow workspace at ${result.value.rootPath}`);
+  return 0;
+}
 
-  if (sub === "template") {
-    const result = await cmdInitTemplate(process.cwd(), name);
-    if (!result.ok) {
-      printCliError(result.error);
-      return 1;
-    }
-    printCliLine(`initialized template at ${result.value.templatePath}`);
-    return 0;
+async function dispatchInitTemplate(_storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${formatCliUsage()}\n\nerror: init template requires <name>`);
+    return 1;
   }
-
-  printCliError(`${formatCliUsage()}\n\nerror: unknown init subcommand: ${sub}`);
-  return 1;
+  const result = await cmdInitTemplate(process.cwd(), name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`initialized template at ${result.value.templatePath}`);
+  return 0;
 }
 
 async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number> {
@@ -421,49 +391,213 @@ async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<numbe
   return 0;
 }
 
-const CAS_SUBCOMMAND_TABLE: Record<string, DispatchFn> = {
-  get: dispatchCasGet,
-  put: dispatchCasPut,
-  list: dispatchCasList,
-  rm: dispatchCasRm,
-  gc: dispatchGc,
+// ── Subcommand tables with metadata ────────────────────────────────────
+
+const WORKFLOW_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  add: {
+    handler: dispatchAdd,
+    args: "<name> <file.esm.js> [--types <path>]",
+    description: "Register a workflow bundle in the registry",
+  },
+  list: { handler: dispatchList, args: "", description: "List all registered workflows" },
+  show: {
+    handler: dispatchShow,
+    args: "<name>",
+    description: "Show details of a registered workflow",
+  },
+  rm: {
+    handler: dispatchRemove,
+    args: "<name>",
+    description: "Remove a workflow from the registry",
+  },
+  history: {
+    handler: dispatchHistory,
+    args: "<name>",
+    description: "Show version history of a workflow",
+  },
+  rollback: {
+    handler: dispatchRollback,
+    args: "<name> [hash]",
+    description: "Rollback a workflow to a previous version",
+  },
 };
 
-async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
-  const sub = argv[0];
-  if (sub === undefined) {
-    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: (none)`);
-    return 1;
-  }
-  const handler = CAS_SUBCOMMAND_TABLE[sub];
-  if (handler === undefined) {
-    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
-    return 1;
-  }
-  return handler(storageRoot, argv.slice(1));
+const THREAD_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  run: {
+    handler: dispatchRun,
+    args: "<name> [--prompt <text>] [--max-rounds N]",
+    description: "Start a new thread executing a workflow",
+  },
+  list: {
+    handler: dispatchThreadList,
+    args: "[name]",
+    description: "List threads, optionally filtered by workflow name",
+  },
+  show: { handler: dispatchThreadShow, args: "<id>", description: "Show thread details and state" },
+  rm: { handler: dispatchThreadRm, args: "<id>", description: "Remove a thread" },
+  fork: {
+    handler: dispatchFork,
+    args: "<thread-id> [--from-role <role>]",
+    description: "Fork a thread, optionally from a specific role",
+  },
+  ps: { handler: dispatchPs, args: "", description: "List running threads" },
+  kill: { handler: dispatchKill, args: "<thread-id>", description: "Kill a running thread" },
+  live: {
+    handler: dispatchLive,
+    args: "<thread-id> | --latest [--debug] [--role <name>]",
+    description: "Attach to a thread and stream output live",
+  },
+  pause: { handler: dispatchPause, args: "<thread-id>", description: "Pause a running thread" },
+  resume: { handler: dispatchResume, args: "<thread-id>", description: "Resume a paused thread" },
+};
+
+const CAS_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  get: {
+    handler: dispatchCasGet,
+    args: "<thread-id> <hash>",
+    description: "Retrieve content by hash from a thread's CAS",
+  },
+  put: {
+    handler: dispatchCasPut,
+    args: "<thread-id> <content>",
+    description: "Store content in a thread's CAS, returns hash",
+  },
+  list: {
+    handler: dispatchCasList,
+    args: "<thread-id>",
+    description: "List all CAS entries for a thread",
+  },
+  rm: { handler: dispatchCasRm, args: "<thread-id> <hash>", description: "Remove a CAS entry" },
+  gc: { handler: dispatchGc, args: "", description: "Garbage-collect unreferenced CAS entries" },
+};
+
+const INIT_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  workspace: {
+    handler: dispatchInitWorkspace,
+    args: "<name>",
+    description: "Initialize a new workflow workspace",
+  },
+  template: {
+    handler: dispatchInitTemplate,
+    args: "<name>",
+    description: "Initialize a new workflow template",
+  },
+};
+
+// ── Command registry ───────────────────────────────────────────────────
+
+export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
+  return [
+    {
+      name: "workflow",
+      commands: Object.entries(WORKFLOW_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "thread",
+      commands: Object.entries(THREAD_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "cas",
+      commands: Object.entries(CAS_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "init",
+      commands: Object.entries(INIT_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+  ];
 }
 
-// ── Workflow subcommand table (Phase 1) ────────────────────────────────
+// ── Auto-generated CLI usage ───────────────────────────────────────────
 
-const WORKFLOW_SUBCOMMAND_TABLE: Record<string, DispatchFn> = {
-  add: dispatchAdd,
-  list: dispatchList,
-  show: dispatchShow,
-  rm: dispatchRemove,
-  history: dispatchHistory,
-  rollback: dispatchRollback,
-};
+export function formatCliUsage(): string {
+  const groups = getCommandRegistry();
+  const lines: string[] = ["Usage:"];
+  for (const group of groups) {
+    for (const cmd of group.commands) {
+      const args = cmd.args ? ` ${cmd.args}` : "";
+      lines.push(`  uncaged-workflow ${group.name} ${cmd.name}${args}`);
+    }
+    lines.push("");
+  }
+  lines.push("  uncaged-workflow run <name> [...]          (shortcut for thread run)");
+  lines.push("  uncaged-workflow live <thread-id> [...]    (shortcut for thread live)");
+  lines.push("");
+  lines.push("  uncaged-workflow skill [topic]             agent-consumable reference docs");
+  lines.push("  uncaged-workflow help                      show this usage");
+  lines.push("");
+  lines.push("Environment variables:");
+  lines.push(
+    "  WORKFLOW_STORAGE_ROOT              Override storage directory (default: ~/.uncaged/workflow)",
+  );
+  lines.push(
+    "  UNCAGED_WORKFLOW_STORAGE_ROOT      Internal override (takes priority over WORKFLOW_STORAGE_ROOT)",
+  );
+  return lines.join("\n");
+}
+
+function printDeprecation(oldCmd: string, newCmd: string): void {
+  printCliWarn(`⚠ "${oldCmd}" is deprecated, use "${newCmd}" instead`);
+}
+
+// ── Group dispatchers ──────────────────────────────────────────────────
+
+function dispatchGroup(
+  tableName: string,
+  table: Record<string, CommandEntry>,
+  storageRoot: string,
+  argv: string[],
+): Promise<number> | null {
+  const sub = argv[0];
+  if (sub === undefined || sub === "--help" || sub === "-h") {
+    const entries = Object.entries(table);
+    const lines = [`${tableName} subcommands:\n`];
+    for (const [name, e] of entries) {
+      const args = e.args ? ` ${e.args}` : "";
+      lines.push(`  uncaged-workflow ${tableName} ${name}${args}`);
+      lines.push(`      ${e.description}\n`);
+    }
+    printCliLine(lines.join("\n"));
+    return Promise.resolve(sub === undefined ? 1 : 0);
+  }
+  const entry = table[sub];
+  if (entry === undefined) {
+    return null;
+  }
+  return entry.handler(storageRoot, argv.slice(1));
+}
+
+async function dispatchInit(storageRoot: string, argv: string[]): Promise<number> {
+  const result = dispatchGroup("init", INIT_SUBCOMMAND_TABLE, storageRoot, argv);
+  if (result !== null) {
+    return result;
+  }
+  const sub = argv[0];
+  printCliError(`${formatCliUsage()}\n\nerror: unknown init subcommand: ${sub}`);
+  return 1;
+}
 
 async function dispatchWorkflow(storageRoot: string, argv: string[]): Promise<number> {
+  const result = dispatchGroup("workflow", WORKFLOW_SUBCOMMAND_TABLE, storageRoot, argv);
+  if (result !== null) {
+    return result;
+  }
   const sub = argv[0];
-  if (sub === undefined) {
-    printCliError(`${formatCliUsage()}\n\nerror: unknown workflow subcommand: (none)`);
-    return 1;
-  }
-  const handler = WORKFLOW_SUBCOMMAND_TABLE[sub];
-  if (handler !== undefined) {
-    return handler(storageRoot, argv.slice(1));
-  }
   if (sub === "remove") {
     printDeprecation("workflow remove", "workflow rm");
     return dispatchRemove(storageRoot, argv.slice(1));
@@ -472,33 +606,62 @@ async function dispatchWorkflow(storageRoot: string, argv: string[]): Promise<nu
   return 1;
 }
 
-// ── Thread subcommand table (Phase 2) ──────────────────────────────────
-
-const THREAD_SUBCOMMAND_TABLE: Record<string, DispatchFn> = {
-  run: dispatchRun,
-  list: dispatchThreadList,
-  show: dispatchThreadShow,
-  rm: dispatchThreadRm,
-  fork: dispatchFork,
-  ps: dispatchPs,
-  kill: dispatchKill,
-  live: dispatchLive,
-  pause: dispatchPause,
-  resume: dispatchResume,
-};
-
 async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
+  const result = dispatchGroup("thread", THREAD_SUBCOMMAND_TABLE, storageRoot, argv);
+  if (result !== null) {
+    return result;
+  }
   const sub = argv[0];
-  if (sub === undefined) {
-    printCliError(`${formatCliUsage()}\n\nerror: unknown thread subcommand: (none)`);
+  printCliError(`${formatCliUsage()}\n\nerror: unknown thread subcommand: ${sub}`);
+  return 1;
+}
+
+async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
+  const result = dispatchGroup("cas", CAS_SUBCOMMAND_TABLE, storageRoot, argv);
+  if (result !== null) {
+    return result;
+  }
+  const sub = argv[0];
+  printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
+  return 1;
+}
+
+// ── Help ────────────────────────────────────────────────────────────────
+
+async function dispatchSkill(_storageRoot: string, argv: string[]): Promise<number> {
+  const topic = argv[0];
+  if (topic === undefined) {
+    printCliLine(formatSkillIndex());
+    return 0;
+  }
+  const doc = formatSkillTopic(topic);
+  if (doc === null) {
+    printCliError(`unknown skill topic: ${topic}\n\n${formatSkillIndex()}`);
     return 1;
   }
-  const handler = THREAD_SUBCOMMAND_TABLE[sub];
-  if (handler === undefined) {
-    printCliError(`${formatCliUsage()}\n\nerror: unknown thread subcommand: ${sub}`);
-    return 1;
+  printCliLine(doc);
+  return 0;
+}
+
+async function dispatchHelp(_storageRoot: string, argv: string[]): Promise<number> {
+  // Legacy compat: help --skill [topic] → skill [topic]
+  const skillIdx = argv.indexOf("--skill");
+  if (skillIdx !== -1) {
+    const topic = argv[skillIdx + 1];
+    if (topic === undefined) {
+      printCliLine(formatSkillIndex());
+      return 0;
+    }
+    const doc = formatSkillTopic(topic);
+    if (doc === null) {
+      printCliError(`unknown skill topic: ${topic}\n\n${formatSkillIndex()}`);
+      return 1;
+    }
+    printCliLine(doc);
+    return 0;
   }
-  return handler(storageRoot, argv.slice(1));
+  printCliLine(formatCliUsage());
+  return 0;
 }
 
 // ── Top-level command table (Phase 3) ──────────────────────────────────
@@ -509,6 +672,8 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
+  help: dispatchHelp,
+  skill: dispatchSkill,
 
   // Top-level shortcuts (no deprecation)
   run: dispatchRun,
@@ -534,12 +699,12 @@ const DEPRECATED_ALIASES: Record<string, { newCmd: string; handler: DispatchFn }
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length === 0) {
-    printCliError(formatCliUsage());
+    printCliLine(formatCliUsage());
     return 1;
   }
   const command = argv[0];
   if (command === undefined) {
-    printCliError(formatCliUsage());
+    printCliLine(formatCliUsage());
     return 1;
   }
   const rest = argv.slice(1);

packages/cli-workflow/src/cmd-help.ts

@@ -0,0 +1,238 @@
+import { getCommandRegistry } from "./cli-dispatch.js";
+
+type SkillTopic = {
+  name: string;
+  description: string;
+  format: () => string;
+};
+
+const SKILL_TOPICS: ReadonlyArray<SkillTopic> = [
+  { name: "cli", description: "Full CLI command reference", format: formatSkillCli },
+  {
+    name: "develop",
+    description: "Guide for agents executing roles inside a workflow",
+    format: formatSkillDevelop,
+  },
+  {
+    name: "author",
+    description: "Guide for building and publishing workflow bundles",
+    format: formatSkillAuthor,
+  },
+];
+
+export function getSkillTopics(): ReadonlyArray<{ name: string; description: string }> {
+  return SKILL_TOPICS.map((t) => ({ name: t.name, description: t.description }));
+}
+
+export function formatSkillTopic(topic: string): string | null {
+  const entry = SKILL_TOPICS.find((t) => t.name === topic);
+  if (entry === undefined) {
+    return null;
+  }
+  return entry.format();
+}
+
+export function formatSkillIndex(): string {
+  const rows = SKILL_TOPICS.map((t) => `| \`${t.name}\` | ${t.description} |`);
+  return `# uncaged-workflow help --skill
+
+Available topics:
+
+| Topic | Description |
+|-------|-------------|
+${rows.join("\n")}
+
+Usage: \`uncaged-workflow skill <topic>\`
+`;
+}
+
+// ── cli topic (existing full reference) ────────────────────────────────
+
+function formatSkillCli(): string {
+  const groups = getCommandRegistry();
+
+  const commandSections: string[] = [];
+  for (const group of groups) {
+    const rows = group.commands.map((cmd) => {
+      const args = cmd.args ? `\`${cmd.args}\`` : "(none)";
+      return `| \`${group.name} ${cmd.name}\` | ${args} | ${cmd.description} |`;
+    });
+    commandSections.push(
+      `### ${group.name}\n\n| Command | Args | Description |\n|---------|------|-------------|\n${rows.join("\n")}`,
+    );
+  }
+
+  return `# uncaged-workflow CLI Reference
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Workflow** | A single-file ESM bundle (\`.esm.js\`) that exports \`run\` and \`descriptor\`. Identified by name and XXH64 hash. |
+| **Bundle** | The physical \`.esm.js\` file stored in the bundles directory. Immutable once written. |
+| **Thread** | A single execution of a workflow, identified by a ULID. Persists state as JSONL files. |
+| **CAS** | Content-Addressable Storage. Per-thread key-value store keyed by content hash. |
+| **Registry** | \`workflow.yaml\` — maps workflow names to their current and historical bundle hashes. |
+
+## Commands
+
+${commandSections.join("\n\n")}
+
+### Top-level shortcuts
+
+| Command | Equivalent | Description |
+|---------|------------|-------------|
+| \`run\` | \`thread run\` | Shortcut to start a thread |
+| \`live\` | \`thread live\` | Shortcut to attach to a thread |
+
+## Typical Workflow
+
+1. \`uncaged-workflow workflow add my-wf ./my-wf.esm.js\` — register a workflow
+2. \`uncaged-workflow run my-wf --prompt "do the thing"\` — start a thread
+3. \`uncaged-workflow live --latest\` — attach and watch output
+4. \`uncaged-workflow thread show <thread-id>\` — inspect completed thread
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| \`UNCAGED_WORKFLOW_STORAGE_ROOT\` | Override the default storage directory for all workflow data |
+`;
+}
+
+// ── develop topic (for agents inside a workflow) ───────────────────────
+
+function formatSkillDevelop(): string {
+  return `# Workflow Role Guide
+
+Reference for agents executing roles (planner, coder, reviewer, etc.) inside a running workflow thread.
+
+## Thread ID
+
+Every thread has a 26-character Crockford Base32 ULID (e.g. \`06F03H5V6JTMDST6P3TVH42RWM\`).
+
+It appears in the **first message** of the conversation. If unsure:
+
+\`\`\`
+uncaged-workflow thread list
+\`\`\`
+
+## CAS (Content-Addressable Storage)
+
+Store and retrieve content by hash, scoped to the current thread.
+
+| Operation | Command |
+|-----------|---------|
+| **Store** | \`uncaged-workflow cas put <THREAD_ID> '<content>'\` → prints hash |
+| **Read** | \`uncaged-workflow cas get <THREAD_ID> <HASH>\` → prints content |
+| **List** | \`uncaged-workflow cas list <THREAD_ID>\` |
+
+CAS is the **only** supported way to persist structured data (phase plans, review notes, etc.) within a thread. Do not use temp files.
+
+## Meta Output
+
+Each role must produce structured output that the moderator extracts. The exact schema depends on the role, but the pattern is:
+
+1. Do your work (write code, run tests, etc.)
+2. Output a compact JSON object matching the role's schema
+3. The moderator extracts and validates it automatically
+
+## Thread Context
+
+The conversation history contains outputs from previous roles. Read it to understand:
+- What task was requested (from the initial prompt)
+- What previous roles produced (plans, code changes, review results)
+- What the moderator decided (which phase to work on, whether to retry)
+`;
+}
+
+// ── author topic (for workflow developers) ─────────────────────────────
+
+function formatSkillAuthor(): string {
+  return `# Workflow Authoring Guide
+
+How to build, test, and publish workflow bundles for uncaged-workflow.
+
+## Bundle Structure
+
+A workflow bundle is a single ESM file (\`.esm.js\`) that exports:
+
+\`\`\`typescript
+// Required exports
+export const descriptor: WorkflowDescriptor;
+export const run: WorkflowRun;
+\`\`\`
+
+## WorkflowDescriptor
+
+Defines the workflow's metadata and role sequence:
+
+\`\`\`typescript
+type WorkflowDescriptor = {
+  name: string;           // verb-first kebab-case, e.g. "solve-issue"
+  description: string;    // one-line summary
+  roles: string[];        // ordered role names, e.g. ["planner", "coder", "reviewer"]
+};
+\`\`\`
+
+## WorkflowRun
+
+The main function that creates and returns a moderator:
+
+\`\`\`typescript
+type WorkflowRun = (ctx: WorkflowContext) => Moderator;
+\`\`\`
+
+The **Moderator** controls the flow — it decides which role runs next, handles retries, and determines when the workflow is complete.
+
+## Role Definition
+
+Each role has:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| \`description\` | string | What the role does |
+| \`systemPrompt\` | string | System prompt for the agent |
+| \`extractPrompt\` | string | Instruction for extracting structured meta |
+| \`schema\` | ZodSchema | Validates the extracted meta |
+| \`extractRefs\` | fn or null | Extracts CAS hashes from meta for DAG linking |
+| \`extractMode\` | "single" | Extraction mode |
+
+## Development Workflow
+
+\`\`\`bash
+# 1. Initialize a workspace
+uncaged-workflow init workspace my-workflow
+
+# 2. Write your template (roles + moderator + descriptor)
+
+# 3. Build the ESM bundle
+bun run build
+
+# 4. Register locally
+uncaged-workflow workflow add my-workflow ./dist/my-workflow.esm.js
+
+# 5. Test
+uncaged-workflow run my-workflow --prompt "test task"
+uncaged-workflow live --latest
+\`\`\`
+
+## Versioning
+
+Bundles are immutable and identified by XXH64 hash. Re-registering a workflow with a new bundle creates a new version. Use \`workflow history\` and \`workflow rollback\` to manage versions.
+`;
+}
+
+// ── Legacy compat ──────────────────────────────────────────────────────
+
+/** @deprecated Use formatSkillTopic("cli") instead */
+export function formatSkillDoc(): string {
+  return formatSkillCli();
+}

packages/cli-workflow/src/storage-env.ts

@@ -1,10 +1,21 @@
 import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
 
-/** Resolve storage root, honoring `UNCAGED_WORKFLOW_STORAGE_ROOT` for tests/tools. */
+/**
+ * Resolve storage root with env var override support.
+ *
+ * Priority (highest first):
+ *  1. `UNCAGED_WORKFLOW_STORAGE_ROOT` — internal/test override
+ *  2. `WORKFLOW_STORAGE_ROOT` — user-facing override
+ *  3. Default (`~/.uncaged/workflow`)
+ */
 export function resolveWorkflowStorageRoot(): string {
-  const override = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-  if (override !== undefined && override !== "") {
-    return override;
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
   }
   return getDefaultWorkflowStorageRoot();
 }

packages/workflow-role-coder/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-coder",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "echo no tests"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-coder/src/index.ts

@@ -1 +0,0 @@
-export { type CoderMeta, coderMetaSchema, coderRole } from "./coder.js";

packages/workflow-role-coder/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-role-committer/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-committer",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-committer/src/index.ts

@@ -1 +0,0 @@
-export { type CommitterMeta, committerMetaSchema, committerRole } from "./committer.js";

packages/workflow-role-committer/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-role-planner/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-planner",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "echo no tests"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-planner/src/index.ts

@@ -1,6 +0,0 @@
-export {
-  type PlannerMeta,
-  phaseSchema,
-  plannerMetaSchema,
-  plannerRole,
-} from "./planner.js";

packages/workflow-role-planner/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-role-preparer/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-preparer",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "echo no tests"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-preparer/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"]
-}

packages/workflow-role-reviewer/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-reviewer",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-reviewer/src/index.ts

@@ -1 +0,0 @@
-export { type ReviewerMeta, reviewerMetaSchema, reviewerRole } from "./reviewer.js";

packages/workflow-role-reviewer/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-role-submitter/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-submitter",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-submitter/src/index.ts

@@ -1 +0,0 @@
-export { type SubmitterMeta, submitterMetaSchema, submitterRole } from "./submitter.js";

packages/workflow-role-submitter/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-role-tester/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/workflow-role-tester",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "echo 'TODO'",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
-  }
-}

packages/workflow-role-tester/src/index.ts

@@ -1 +0,0 @@
-export { type TesterMeta, testerMetaSchema, testerRole } from "./tester.js";

packages/workflow-role-tester/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "composite": true
-  },
-  "include": ["src/**/*.ts"],
-  "references": [{ "path": "../workflow" }]
-}

packages/workflow-template-develop/__tests__/committer.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { committerMetaSchema, committerRole } from "../src/committer.js";
+import { committerMetaSchema, committerRole } from "../src/roles/committer.js";
 
 describe("committerRole", () => {
   test("committed sample validates against schema", () => {

packages/workflow-template-develop/__tests__/develop-template.test.ts

@@ -6,12 +6,9 @@ import {
   START,
   validateWorkflowDescriptor,
 } from "@uncaged/workflow";
-
-import type { CommitterMeta } from "@uncaged/workflow-role-committer";
-import type { PlannerMeta } from "@uncaged/workflow-role-planner";
-
 import { buildDevelopDescriptor } from "../src/descriptor.js";
 import { developModerator } from "../src/index.js";
+import type { CommitterMeta, PlannerMeta } from "../src/roles/index.js";
 import type { DevelopMeta } from "../src/roles.js";
 
 const DEFAULT_PHASES: PlannerMeta["phases"] = [

packages/workflow-template-develop/__tests__/reviewer.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { reviewerMetaSchema, reviewerRole } from "../src/reviewer.js";
+import { reviewerMetaSchema, reviewerRole } from "../src/roles/reviewer.js";
 
 describe("reviewerRole", () => {
   test("approved sample validates against schema", () => {

packages/workflow-template-develop/package.json

@@ -10,10 +10,6 @@
   },
   "dependencies": {
     "@uncaged/workflow": "workspace:*",
-    "@uncaged/workflow-role-coder": "workspace:*",
-    "@uncaged/workflow-role-committer": "workspace:*",
-    "@uncaged/workflow-role-planner": "workspace:*",
-    "@uncaged/workflow-role-reviewer": "workspace:*",
-    "@uncaged/workflow-role-tester": "workspace:*"
+    "zod": "^4.0.0"
   }
 }

packages/workflow-template-develop/src/index.ts

@@ -10,34 +10,26 @@ import {
 import { developModerator } from "./moderator.js";
 import { DEVELOP_WORKFLOW_DESCRIPTION, type DevelopMeta, developRoles } from "./roles.js";
 
+export { buildDevelopDescriptor } from "./descriptor.js";
+export { developModerator } from "./moderator.js";
 export {
   type CoderMeta,
+  type CommitterMeta,
   coderMetaSchema,
   coderRole,
-} from "@uncaged/workflow-role-coder";
-export {
-  type CommitterMeta,
   committerMetaSchema,
   committerRole,
-} from "@uncaged/workflow-role-committer";
-export {
   type PlannerMeta,
   phaseSchema,
   plannerMetaSchema,
   plannerRole,
-} from "@uncaged/workflow-role-planner";
-export {
   type ReviewerMeta,
   reviewerMetaSchema,
   reviewerRole,
-} from "@uncaged/workflow-role-reviewer";
-export {
   type TesterMeta,
   testerMetaSchema,
   testerRole,
-} from "@uncaged/workflow-role-tester";
-export { buildDevelopDescriptor } from "./descriptor.js";
-export { developModerator } from "./moderator.js";
+} from "./roles/index.js";
 export {
   DEVELOP_WORKFLOW_DESCRIPTION,
   type DevelopMeta,

packages/workflow-template-develop/src/roles.ts

@@ -1,9 +1,9 @@
 import type { RoleDefinition } from "@uncaged/workflow";
-import { type CoderMeta, coderRole } from "@uncaged/workflow-role-coder";
-import { type CommitterMeta, committerRole } from "@uncaged/workflow-role-committer";
-import { type PlannerMeta, plannerRole } from "@uncaged/workflow-role-planner";
-import { type ReviewerMeta, reviewerRole } from "@uncaged/workflow-role-reviewer";
-import { type TesterMeta, testerRole } from "@uncaged/workflow-role-tester";
+import { type CoderMeta, coderRole } from "./roles/coder.js";
+import { type CommitterMeta, committerRole } from "./roles/committer.js";
+import { type PlannerMeta, plannerRole } from "./roles/planner.js";
+import { type ReviewerMeta, reviewerRole } from "./roles/reviewer.js";
+import { type TesterMeta, testerRole } from "./roles/tester.js";
 
 export const DEVELOP_WORKFLOW_DESCRIPTION =
   "Plan phases, implement incrementally, review, verify with tests/build/lint, and commit (planner → coder [repeat per phase] → reviewer → tester → committer).";

packages/workflow-template-develop/src/roles/coder.ts

@@ -11,21 +11,13 @@ export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 const CODER_SYSTEM = `You are a **coder**. Read the thread for the plan and work on the NEXT incomplete phase only.
 
-## Finding the current thread ID
-
-The thread ID is a 26-character Crockford Base32 string (e.g. \`06F03H5V6JTMDST6P3TVH42RWM\`). It appears in the first message of this conversation. If you are unsure, run:
-
-  uncaged-workflow threads
-
-and use the ID of the active thread.
+Run \`uncaged-workflow skill develop\` for thread ID lookup, CAS commands, and meta output guide.
 
 ## Reading phase details
 
-Each planner phase is identified by a content-hash and a title. To read a phase's full details (name, description, acceptance criteria), run:
+Each planner phase has a content-hash and title. Read full details with \`uncaged-workflow cas get <THREAD_ID> <HASH>\`.
 
-  uncaged-workflow cas get <THREAD_ID> <HASH>
-
-Replace \`<THREAD_ID>\` with the actual thread ID and \`<HASH>\` with the phase hash from the plan.
+The thread ID (26-char Crockford Base32) appears in the first message. If unsure, run \`uncaged-workflow thread list\`.
 
 ## Completing a phase
 

packages/workflow-template-develop/src/roles/index.ts

@@ -0,0 +1,10 @@
+export { type CoderMeta, coderMetaSchema, coderRole } from "./coder.js";
+export { type CommitterMeta, committerMetaSchema, committerRole } from "./committer.js";
+export {
+  type PlannerMeta,
+  phaseSchema,
+  plannerMetaSchema,
+  plannerRole,
+} from "./planner.js";
+export { type ReviewerMeta, reviewerMetaSchema, reviewerRole } from "./reviewer.js";
+export { type TesterMeta, testerMetaSchema, testerRole } from "./tester.js";

packages/workflow-template-develop/src/roles/planner.ts

@@ -14,27 +14,25 @@ export type PlannerMeta = z.infer<typeof plannerMetaSchema>;
 
 const PLANNER_SYSTEM = `You are a **planner** for a software task. Break the work into **sequential phases** the coder will execute one at a time.
 
-## Finding the current thread ID
-
-The thread ID is a 26-character Crockford Base32 string (e.g. \`06F03H5V6JTMDST6P3TVH42RWM\`). It appears in the first message of this conversation. If you are unsure, run:
-
-  uncaged-workflow threads
-
-and use the ID of the active thread.
+Run \`uncaged-workflow skill develop\` for thread ID lookup, CAS commands, and meta output guide.
 
 ## Storing phase details — MANDATORY
 
-For each phase you MUST store its full detail text in CAS using this exact CLI command:
+For each phase, store its full detail text in CAS via \`uncaged-workflow cas put <THREAD_ID> '<content>'\`. The command prints a content-hash — use that as the phase identifier.
 
-  uncaged-workflow cas put <THREAD_ID> '# <name>
+The thread ID (26-char Crockford Base32) appears in the first message. If unsure, run \`uncaged-workflow thread list\`.
 
-Description: <description>
+**Do NOT store phase details in any other way** — the CLI is the only supported storage mechanism.
 
-Acceptance: <acceptance>'
+## Phase granularity
 
-Replace \`<THREAD_ID>\` with the actual thread ID you found above. The command prints a content-hash to stdout — use that hash as the phase identifier.
+Match the number of phases to task complexity:
+- Trivial (add a config option, fix a typo, rename): 1 phase
+- Small (a new feature touching 2-3 files): 1-2 phases
+- Medium (cross-module refactor): 2-3 phases
+- Large (new subsystem, architectural change): 3-5 phases
 
-**Do NOT store phase details in any other way** (no temp files, no invented paths). The CLI command is the only supported storage mechanism.
+Fewer phases is always better. Each phase must justify its existence — if two phases would be tested together anyway, merge them.
 
 ## Output format
 

packages/workflow-template-develop/tsconfig.json

@@ -6,12 +6,5 @@
     "composite": true
   },
   "include": ["src/**/*.ts"],
-  "references": [
-    { "path": "../workflow" },
-    { "path": "../workflow-role-coder" },
-    { "path": "../workflow-role-committer" },
-    { "path": "../workflow-role-planner" },
-    { "path": "../workflow-role-reviewer" },
-    { "path": "../workflow-role-tester" }
-  ]
+  "references": [{ "path": "../workflow" }]
 }

packages/workflow-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -11,13 +11,10 @@ import {
   START,
   validateWorkflowDescriptor,
 } from "@uncaged/workflow";
-
-import type { PreparerMeta } from "@uncaged/workflow-role-preparer";
-import type { SubmitterMeta } from "@uncaged/workflow-role-submitter";
-
 import { buildSolveIssueDescriptor } from "../src/descriptor.js";
 import type { DeveloperMeta } from "../src/developer.js";
 import { createSolveIssueRun, solveIssueModerator } from "../src/index.js";
+import type { PreparerMeta, SubmitterMeta } from "../src/roles/index.js";
 import type { SolveIssueMeta } from "../src/roles.js";
 
 function jsonResponse(payload: Record<string, unknown>): Response {

packages/workflow-template-solve-issue/__tests__/submitter.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { submitterMetaSchema, submitterRole } from "../src/submitter.js";
+import { submitterMetaSchema, submitterRole } from "../src/roles/submitter.js";
 
 describe("submitterRole", () => {
   test("submitted sample validates against schema", () => {

packages/workflow-template-solve-issue/package.json

@@ -10,8 +10,6 @@
   },
   "dependencies": {
     "@uncaged/workflow": "workspace:*",
-    "@uncaged/workflow-role-preparer": "workspace:*",
-    "@uncaged/workflow-role-submitter": "workspace:*",
     "zod": "^4.0.0"
   }
 }

packages/workflow-template-solve-issue/src/index.ts

@@ -11,16 +11,6 @@ import {
 import { solveIssueModerator } from "./moderator.js";
 import { SOLVE_ISSUE_WORKFLOW_DESCRIPTION, type SolveIssueMeta, solveIssueRoles } from "./roles.js";
 
-export {
-  type PreparerMeta,
-  preparerMetaSchema,
-  preparerRole,
-} from "@uncaged/workflow-role-preparer";
-export {
-  type SubmitterMeta,
-  submitterMetaSchema,
-  submitterRole,
-} from "@uncaged/workflow-role-submitter";
 export { buildSolveIssueDescriptor } from "./descriptor.js";
 export {
   type DeveloperMeta,
@@ -28,6 +18,14 @@ export {
   developerRole,
 } from "./developer.js";
 export { solveIssueModerator } from "./moderator.js";
+export {
+  type PreparerMeta,
+  preparerMetaSchema,
+  preparerRole,
+  type SubmitterMeta,
+  submitterMetaSchema,
+  submitterRole,
+} from "./roles/index.js";
 export {
   SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
   type SolveIssueMeta,

packages/workflow-template-solve-issue/src/roles.ts

@@ -1,8 +1,7 @@
 import type { RoleDefinition } from "@uncaged/workflow";
-import { type PreparerMeta, preparerRole } from "@uncaged/workflow-role-preparer";
-import { type SubmitterMeta, submitterRole } from "@uncaged/workflow-role-submitter";
-
 import { type DeveloperMeta, developerRole } from "./developer.js";
+import { type PreparerMeta, preparerRole } from "./roles/preparer.js";
+import { type SubmitterMeta, submitterRole } from "./roles/submitter.js";
 
 export const SOLVE_ISSUE_WORKFLOW_DESCRIPTION =
   "Resolve an issue end-to-end by preparing the repo, delegating implementation to the develop workflow, and opening a pull request (preparer → developer → submitter).";

packages/workflow-template-solve-issue/src/roles/index.ts

@@ -3,3 +3,4 @@ export {
   preparerMetaSchema,
   preparerRole,
 } from "./preparer.js";
+export { type SubmitterMeta, submitterMetaSchema, submitterRole } from "./submitter.js";

packages/workflow-template-solve-issue/tsconfig.json

@@ -6,9 +6,5 @@
     "composite": true
   },
   "include": ["src/**/*.ts"],
-  "references": [
-    { "path": "../workflow" },
-    { "path": "../workflow-role-preparer" },
-    { "path": "../workflow-role-submitter" }
-  ]
+  "references": [{ "path": "../workflow" }]
 }

packages/workflow/workflow

@@ -0,0 +1 @@
+/home/azureuser/repos/uncaged-workflow/packages/workflow

tsconfig.json

@@ -19,13 +19,6 @@
   "references": [
     { "path": "packages/workflow" },
     { "path": "packages/workflow-agent-llm" },
-    { "path": "packages/workflow-role-committer" },
-    { "path": "packages/workflow-role-coder" },
-    { "path": "packages/workflow-role-planner" },
-    { "path": "packages/workflow-role-preparer" },
-    { "path": "packages/workflow-role-reviewer" },
-    { "path": "packages/workflow-role-submitter" },
-    { "path": "packages/workflow-role-tester" },
     { "path": "packages/workflow-agent-cursor" },
     { "path": "packages/workflow-agent-hermes" },
     { "path": "packages/workflow-util-agent" },