feat: developer + submitter roles, solve-issue refactored to parent workflow

- Developer role (react extract): delegates to workflowAsAgent("develop")
- Submitter role: push branch + create PR
- solve-issue now 3-role parent: preparer → developer → submitter
- Removed direct planner/coder/reviewer/committer from solve-issue
- 188 tests passing

Fixes #59

packages/cli-workflow/__tests__/init-template.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCli } from "../src/cli-dispatch.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "../src/cmd-init.js";
+import { pathExists } from "../src/fs-utils.js";
+
+describe("init template", () => {
+  let parent: string;
+
+  beforeEach(async () => {
+    parent = join(
+      tmpdir(),
+      `wf-init-template-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(parent, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(parent, { recursive: true, force: true });
+  });
+
+  test("creates templates/<name> with expected files", async () => {
+    const ws = await cmdInitWorkspace(parent, "my-workflows");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+
+    const created = await cmdInitTemplate(root, "review-pr");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const tdir = join(root, "templates", "review-pr");
+    expect(created.value.templatePath).toBe(tdir);
+    expect(await pathExists(join(tdir, "package.json"))).toBe(true);
+    expect(await pathExists(join(tdir, "tsconfig.json"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "roles.ts"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "moderator.ts"))).toBe(true);
+    expect(await pathExists(join(tdir, "src", "index.ts"))).toBe(true);
+
+    const pkg = JSON.parse(await readFile(join(tdir, "package.json"), "utf8")) as {
+      name: string;
+      type: string;
+      dependencies: Record<string, string>;
+    };
+    expect(pkg.type).toBe("module");
+    expect(pkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(pkg.dependencies.zod).toBeDefined();
+    expect(pkg.name).toContain("review-pr");
+
+    const idx = await readFile(join(tdir, "src", "index.ts"), "utf8");
+    expect(idx).toContain("WorkflowDefinition");
+
+    const roles = await readFile(join(tdir, "src", "roles.ts"), "utf8");
+    expect(roles).not.toContain("interface ");
+    expect(roles).not.toContain("?:");
+    expect(roles).not.toContain("export default");
+
+    const moder = await readFile(join(tdir, "src", "moderator.ts"), "utf8");
+    expect(moder).not.toContain("export default");
+  });
+
+  test("finds workspace walking up from nested cwd", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+    const nested = join(root, "a", "b");
+    await mkdir(nested, { recursive: true });
+
+    const created = await cmdInitTemplate(nested, "nested-tpl");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+    expect(await pathExists(join(root, "templates", "nested-tpl", "src", "index.ts"))).toBe(true);
+  });
+
+  test("errors when not inside a workflow workspace", async () => {
+    const orphan = join(parent, "nowhere");
+    await mkdir(orphan, { recursive: true });
+    const r = await cmdInitTemplate(orphan, "x");
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("templates/*");
+    }
+  });
+
+  test("errors when template directory already exists", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+
+    const first = await cmdInitTemplate(root, "dup");
+    expect(first.ok).toBe(true);
+
+    const second = await cmdInitTemplate(root, "dup");
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error).toContain("already exists");
+    }
+  });
+
+  test("errors on invalid template name", async () => {
+    const ws = await cmdInitWorkspace(parent, "ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const bad = await cmdInitTemplate(ws.value.rootPath, "a/b");
+    expect(bad.ok).toBe(false);
+  });
+
+  test.serial("runCli init template uses cwd and succeeds in workspace", async () => {
+    const ws = await cmdInitWorkspace(parent, "cli-ws");
+    expect(ws.ok).toBe(true);
+    if (!ws.ok) {
+      return;
+    }
+    const root = ws.value.rootPath;
+    const prev = process.cwd();
+    try {
+      process.chdir(root);
+      const code = await runCli(join(parent, "_storage"), ["init", "template", "from-cli"]);
+      expect(code).toBe(0);
+      expect(await pathExists(join(root, "templates", "from-cli", "package.json"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

packages/cli-workflow/__tests__/init-workspace.test.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { formatCliUsage, runCli } from "../src/cli-dispatch.js";
+import { cmdInitWorkspace } from "../src/cmd-init.js";
+import { pathExists } from "../src/fs-utils.js";
+
+describe("init workspace", () => {
+  let parent: string;
+
+  beforeEach(async () => {
+    parent = join(tmpdir(), `wf-init-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(parent, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(parent, { recursive: true, force: true });
+  });
+
+  test("creates expected files and directories", async () => {
+    const created = await cmdInitWorkspace(parent, "my-workflows");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const root = created.value.rootPath;
+    expect(await pathExists(join(root, "package.json"))).toBe(true);
+    expect(await pathExists(join(root, "biome.json"))).toBe(true);
+    expect(await pathExists(join(root, "tsconfig.json"))).toBe(true);
+    expect(await pathExists(join(root, "AGENTS.md"))).toBe(true);
+    expect(await pathExists(join(root, "README.md"))).toBe(true);
+    expect(await pathExists(join(root, "templates"))).toBe(true);
+    expect(await pathExists(join(root, "templates", ".gitkeep"))).toBe(true);
+    expect(await pathExists(join(root, "workflows", "package.json"))).toBe(true);
+
+    const rootPkg = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
+      workspaces: string[];
+    };
+    expect(rootPkg.workspaces).toEqual(["templates/*", "workflows"]);
+
+    const wfPkg = JSON.parse(await readFile(join(root, "workflows", "package.json"), "utf8")) as {
+      type: string;
+      dependencies: Record<string, string>;
+    };
+    expect(wfPkg.type).toBe("module");
+    expect(wfPkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(wfPkg.dependencies.zod).toBeDefined();
+
+    const tsconfig = JSON.parse(await readFile(join(root, "tsconfig.json"), "utf8")) as {
+      compilerOptions: { strict: boolean; module: string; target: string };
+    };
+    expect(tsconfig.compilerOptions.strict).toBe(true);
+    expect(tsconfig.compilerOptions.module).toBe("ESNext");
+    expect(tsconfig.compilerOptions.target).toBe("ESNext");
+  });
+
+  test("AGENTS.md contains coding agent guide sections and terms", async () => {
+    const created = await cmdInitWorkspace(parent, "my-workflows");
+    expect(created.ok).toBe(true);
+    if (!created.ok) {
+      return;
+    }
+
+    const agentsPath = join(created.value.rootPath, "AGENTS.md");
+    const body = await readFile(agentsPath, "utf8");
+
+    for (const section of [
+      "项目结构",
+      "核心概念",
+      "开发流程",
+      "编码规范",
+      "Template",
+      "Build",
+      "常见陷阱",
+    ]) {
+      expect(body).toContain(section);
+    }
+
+    for (const term of [
+      "RoleDefinition",
+      "WorkflowDefinition",
+      "Moderator",
+      "AgentFn",
+      "ExtractFn",
+      "RoleMeta",
+    ]) {
+      expect(body).toContain(term);
+    }
+
+    expect(body).toMatch(/type[\s\S]*interface/i);
+    expect(body).toMatch(/function[\s\S]*class/i);
+    expect(body).toContain("Crockford Base32");
+    expect(body).toMatch(/no[\s\S]*default export/i);
+    expect(body).toMatch(/no[\s\S]*console/i);
+    expect(body).toMatch(/no[\s\S]*dynamic import/i);
+
+    expect(body).toContain("bun run check");
+    expect(body).toContain("bun test");
+    expect(body).toContain("uncaged-workflow");
+    expect(body).toContain("bun build");
+    expect(body).toContain("CLAUDE.md");
+    expect(body).toContain("docs/architecture.md");
+  });
+
+  test("errors when directory already exists", async () => {
+    const first = await cmdInitWorkspace(parent, "dup");
+    expect(first.ok).toBe(true);
+
+    const second = await cmdInitWorkspace(parent, "dup");
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error).toContain("already exists");
+    }
+  });
+
+  test("errors on invalid workspace name", async () => {
+    const slash = await cmdInitWorkspace(parent, "a/b");
+    expect(slash.ok).toBe(false);
+
+    const dots = await cmdInitWorkspace(parent, "..");
+    expect(dots.ok).toBe(false);
+
+    const empty = await cmdInitWorkspace(parent, "");
+    expect(empty.ok).toBe(false);
+  });
+
+  test("usage lists init subcommands", () => {
+    const u = formatCliUsage();
+    expect(u).toContain("uncaged-workflow init workspace <name>");
+    expect(u).toContain("uncaged-workflow init template <name>");
+  });
+
+  test("runCli rejects unknown init subcommand", async () => {
+    const code = await runCli(join(parent, "_storage"), ["init", "bogus", "name"]);
+    expect(code).toBe(1);
+  });
+
+  test.serial("runCli init workspace uses cwd", async () => {
+    const prev = process.cwd();
+    try {
+      process.chdir(parent);
+      const code = await runCli(join(parent, "_storage"), ["init", "workspace", "from-cli"]);
+      expect(code).toBe(0);
+      expect(await pathExists(join(parent, "from-cli", "workflows", "package.json"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

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

@@ -4,6 +4,7 @@ import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "./cmd-cas.js";
 import { cmdFork, parseForkArgv } from "./cmd-fork.js";
 import { cmdGc } from "./cmd-gc.js";
 import { cmdHistory } from "./cmd-history.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "./cmd-init.js";
 import { cmdKill } from "./cmd-kill.js";
 import { cmdList, formatListLines } from "./cmd-list.js";
 import { cmdPause } from "./cmd-pause.js";
@@ -17,7 +18,7 @@ import { cmdThreadRemove, cmdThreadShow } from "./cmd-thread.js";
 import { cmdThreads } from "./cmd-threads.js";
 import { parseRunArgv } from "./run-argv.js";
 
-function usage(): string {
+export function formatCliUsage(): string {
   return [
     "Usage:",
     "  uncaged-workflow add <name> <file.esm.js> [--types <path>]",
@@ -40,13 +41,47 @@ function usage(): string {
     "  uncaged-workflow cas put <thread-id> <content>",
     "  uncaged-workflow cas list <thread-id>",
     "  uncaged-workflow cas rm <thread-id> <hash>",
+    "  uncaged-workflow init workspace <name>",
+    "  uncaged-workflow init template <name>",
   ].join("\n");
 }
 
+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>`);
+    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;
+  }
+
+  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;
+  }
+
+  printCliError(`${formatCliUsage()}\n\nerror: unknown init subcommand: ${sub}`);
+  return 1;
+}
+
 async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseAddArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
   const result = await cmdAdd(storageRoot, parsed.value);
@@ -63,7 +98,7 @@ async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number>
 
 async function dispatchList(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: list takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: list takes no arguments`);
     return 1;
   }
   const result = await cmdList(storageRoot);
@@ -80,7 +115,7 @@ async function dispatchList(storageRoot: string, argv: string[]): Promise<number
 async function dispatchShow(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: show requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: show requires <name>`);
     return 1;
   }
   const result = await cmdShow(storageRoot, name);
@@ -95,7 +130,7 @@ async function dispatchShow(storageRoot: string, argv: string[]): Promise<number
 async function dispatchRemove(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: remove requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: remove requires <name>`);
     return 1;
   }
   const result = await cmdRemove(storageRoot, name);
@@ -110,7 +145,7 @@ async function dispatchRemove(storageRoot: string, argv: string[]): Promise<numb
 async function dispatchRun(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseRunArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
 
@@ -131,7 +166,7 @@ async function dispatchRun(storageRoot: string, argv: string[]): Promise<number>
 
 async function dispatchPs(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: ps takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: ps takes no arguments`);
     return 1;
   }
   for (const line of await cmdPs(storageRoot)) {
@@ -143,7 +178,7 @@ async function dispatchPs(storageRoot: string, argv: string[]): Promise<number>
 async function dispatchKill(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: kill requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: kill requires <thread-id>`);
     return 1;
   }
   const result = await cmdKill(storageRoot, threadId);
@@ -158,7 +193,7 @@ async function dispatchKill(storageRoot: string, argv: string[]): Promise<number
 async function dispatchHistory(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: history requires <name>`);
+    printCliError(`${formatCliUsage()}\n\nerror: history requires <name>`);
     return 1;
   }
   const result = await cmdHistory(storageRoot, name);
@@ -175,7 +210,7 @@ async function dispatchHistory(storageRoot: string, argv: string[]): Promise<num
 async function dispatchRollback(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 2) {
-    printCliError(`${usage()}\n\nerror: rollback requires <name> [hash]`);
+    printCliError(`${formatCliUsage()}\n\nerror: rollback requires <name> [hash]`);
     return 1;
   }
   const hashArg = argv[1];
@@ -191,7 +226,7 @@ async function dispatchRollback(storageRoot: string, argv: string[]): Promise<nu
 async function dispatchPause(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: pause requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: pause requires <thread-id>`);
     return 1;
   }
   const result = await cmdPause(storageRoot, threadId);
@@ -206,7 +241,7 @@ async function dispatchPause(storageRoot: string, argv: string[]): Promise<numbe
 async function dispatchResume(storageRoot: string, argv: string[]): Promise<number> {
   const threadId = argv[0];
   if (threadId === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: resume requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: resume requires <thread-id>`);
     return 1;
   }
   const result = await cmdResume(storageRoot, threadId);
@@ -233,7 +268,7 @@ async function dispatchThreads(storageRoot: string, argv: string[]): Promise<num
 async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
   const id = argv[0];
   if (id === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: thread requires <id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: thread requires <id>`);
     return 1;
   }
   const result = await cmdThreadShow(storageRoot, id);
@@ -248,7 +283,7 @@ async function dispatchThread(storageRoot: string, argv: string[]): Promise<numb
 async function dispatchThreadRm(storageRoot: string, argv: string[]): Promise<number> {
   const id = argv[0];
   if (id === undefined || argv.length > 1) {
-    printCliError(`${usage()}\n\nerror: thread rm requires <id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: thread rm requires <id>`);
     return 1;
   }
   const result = await cmdThreadRemove(storageRoot, id);
@@ -270,7 +305,7 @@ async function dispatchThreadBranch(storageRoot: string, rest: string[]): Promis
 
 async function dispatchGc(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
-    printCliError(`${usage()}\n\nerror: gc takes no arguments`);
+    printCliError(`${formatCliUsage()}\n\nerror: gc takes no arguments`);
     return 1;
   }
   const result = await cmdGc(storageRoot);
@@ -288,7 +323,7 @@ async function dispatchGc(storageRoot: string, argv: string[]): Promise<number>
 async function dispatchFork(storageRoot: string, argv: string[]): Promise<number> {
   const parsed = parseForkArgv(argv);
   if (!parsed.ok) {
-    printCliError(`${usage()}\n\nerror: ${parsed.error}`);
+    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
     return 1;
   }
   const result = await cmdFork(storageRoot, parsed.value.threadId, parsed.value.fromRole);
@@ -304,7 +339,7 @@ async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<numb
   const threadId = rest[0];
   const hash = rest[1];
   if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas get requires <thread-id> <hash>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas get requires <thread-id> <hash>`);
     return 1;
   }
   const result = await cmdCasGet(storageRoot, threadId, hash);
@@ -320,7 +355,7 @@ async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<numb
   const threadId = rest[0];
   const content = rest[1];
   if (threadId === undefined || content === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas put requires <thread-id> <content>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas put requires <thread-id> <content>`);
     return 1;
   }
   const result = await cmdCasPut(storageRoot, threadId, content);
@@ -335,7 +370,7 @@ async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<numb
 async function dispatchCasList(storageRoot: string, rest: string[]): Promise<number> {
   const threadId = rest[0];
   if (threadId === undefined || rest.length > 1) {
-    printCliError(`${usage()}\n\nerror: cas list requires <thread-id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas list requires <thread-id>`);
     return 1;
   }
   const result = await cmdCasList(storageRoot, threadId);
@@ -353,7 +388,7 @@ async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<numbe
   const threadId = rest[0];
   const hash = rest[1];
   if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usage()}\n\nerror: cas rm requires <thread-id> <hash>`);
+    printCliError(`${formatCliUsage()}\n\nerror: cas rm requires <thread-id> <hash>`);
     return 1;
   }
   const result = await cmdCasRm(storageRoot, threadId, hash);
@@ -378,12 +413,12 @@ const CAS_SUBCOMMAND_TABLE: Record<
 async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
   const sub = argv[0];
   if (sub === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown cas subcommand: (none)`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: (none)`);
     return 1;
   }
   const handler = CAS_SUBCOMMAND_TABLE[sub];
   if (handler === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown cas subcommand: ${sub}`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
     return 1;
   }
   return handler(storageRoot, argv.slice(1));
@@ -393,6 +428,7 @@ type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
 
 const COMMAND_TABLE: Record<string, DispatchFn> = {
   add: dispatchAdd,
+  init: dispatchInit,
   list: dispatchList,
   show: dispatchShow,
   remove: dispatchRemove,
@@ -412,18 +448,18 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length === 0) {
-    printCliError(usage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const command = argv[0];
   if (command === undefined) {
-    printCliError(usage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const rest = argv.slice(1);
   const dispatch = COMMAND_TABLE[command];
   if (dispatch === undefined) {
-    printCliError(`${usage()}\n\nerror: unknown command ${command}`);
+    printCliError(`${formatCliUsage()}\n\nerror: unknown command ${command}`);
     return 1;
   }
   return dispatch(storageRoot, rest);

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

@@ -0,0 +1,415 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { err, ok, type Result } from "@uncaged/workflow";
+
+import { pathExists } from "./fs-utils.js";
+
+export type CmdInitWorkspaceSuccess = {
+  rootPath: string;
+};
+
+export type CmdInitTemplateSuccess = {
+  templatePath: string;
+};
+
+function validateWorkspaceSegment(name: string): Result<void, string> {
+  if (name.length === 0) {
+    return err("workspace name must not be empty");
+  }
+  if (name === "." || name === "..") {
+    return err("invalid workspace name");
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    return err("workspace name must not contain path separators");
+  }
+  return ok(undefined);
+}
+
+function rootPackageJson(workspaceName: string): string {
+  return `${JSON.stringify(
+    {
+      name: workspaceName,
+      private: true,
+      type: "module",
+      workspaces: ["templates/*", "workflows"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function workflowsPackageJson(): string {
+  return `${JSON.stringify(
+    {
+      name: "workflows",
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function biomeJson(): string {
+  return `${JSON.stringify(
+    {
+      $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
+      files: {
+        includes: ["**", "!**/node_modules", "!**/dist"],
+      },
+      formatter: {
+        indentWidth: 2,
+      },
+      linter: {
+        enabled: true,
+        rules: {
+          recommended: true,
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function tsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        strict: true,
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        skipLibCheck: true,
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function agentsMd(): string {
+  return `# AGENTS — Workflow 工作区开发指南
+
+面向在本仓库中编写 workflow 的 coding agent。引擎层术语与架构细节与 **@uncaged/workflow** 上游文档一致，编写时可对照 \`CLAUDE.md\` 与 \`docs/architecture.md\`。
+
+## 1. 项目结构（workspace / template / workflow instance）
+
+| 层级 | 目录 / 产物 | 职责 |
+|------|----------------|------|
+| **Workspace** | 仓库根（\`package.json\` 含 \`workspaces: ["templates/*", "workflows"]\`） | Bun monorepo：统一管理本地模板包与 workflow 实例 |
+| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **Moderator**），**不绑定**具体 Agent |
+| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AgentFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
+
+Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下放绑定与打包入口。
+
+## 2. 核心概念
+
+- **RoleMeta**：\`Record<string, Record<string, unknown>>\`，角色名 → 该角色结构化 meta 的形状约定。
+- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`extractPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
+- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **Moderator**。
+- **Moderator**：\`(ctx: ModeratorContext<M>) => (角色名) | END\`。同步、纯函数，只做路由。
+- **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
+- **ExtractFn**：从上下文与 prompt 解析结构化数据（引擎与 Agent 都可使用）。
+
+引擎循环简述：**Moderator** → 选角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
+
+## 3. 开发流程
+
+1. **定义 RoleMeta**：为每个角色约定 meta 的 TypeScript 类型（与 Zod schema 对齐）。
+2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`extractPrompt\` / \`description\`。
+3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
+4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
+5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding, extract)\`（或项目约定的封装）绑定 **AgentFn** / **ExtractFn**。
+6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
+
+## 4. 编码规范
+
+与 **CLAUDE.md** 对齐，摘要如下：
+
+- **Functional-first**：优先 \`function\` + \`type\`，避免面向对象业务模型。
+- **type 而非 interface**：类型别名一律用 \`type\`，不要使用 \`interface\`。
+- **显式可空**：不要用 \`?:\`；可空字段写成 \`T | null\`。
+- **function 而非 class**：不用 class（第三方库要求或 \`Error\` 子类除外）。
+- **Crockford Base32**：日志 tag、bundle hash、thread id 等标识约定（引擎侧）；工作区内自定义日志若沿用引擎 logger，tag 为 8 字符 Crockford Base32，且每个调用点唯一。
+- **Named exports only**：不要使用 **default export**；workflow bundle 须 **export const run** 与 **export const descriptor**。
+- **No console.log**：库代码用结构化 logger；CLI 用户输出可按项目 Biome 规则例外标注。
+- **No dynamic import**：业务与 bundle 内禁止 \`import()\`；例外仅限「运行时路径由用户提供的 bundle 加载器」（引擎内部）。
+
+## 5. Template 复用
+
+- **已发布模板**：可通过 npm 依赖 \`@uncaged/workflow-template-*\` 等包，在 workflow 实例中 import 其 **WorkflowDefinition** 再绑定 Agent。
+- **本地模板**：放在本仓库 \`templates/<name>/\`，由 workspace 协议引用（如 \`"template-foo": "workspace:*"\` 或相对路径），便于同源修改与版本控制。
+
+选择模板时保持 **definition 与 agent 绑定分离**：模板只描述「做什么、顺序如何」，实例决定「谁执行、如何抽取 meta」。
+
+## 6. Build and Test
+
+日常命令：
+
+\`\`\`sh
+bun install
+bun run check    # Biome：lint + format
+bun test
+bun build        # 若包内配置了 build 脚本则用于产出 dist / bundle
+uncaged-workflow add <name> <path/to/bundle.esm.js>
+\`\`\`
+
+提交前至少运行 **bun run check** 与 **bun test**；registry 与本地运行流参见 README 与 CLI 文档。
+
+## 7. 常见陷阱
+
+- **No dynamic import**：bundle 须静态可分析；动态 \`import()\` 会破坏哈希与加载约束。
+- **No default export**：引擎只接受命名导出 \`run\` / \`descriptor\`。
+- **No console.log**：避免在可被 Biome \`noConsole\` 规则覆盖的代码路径直接使用 console。
+- **Single-file ESM bundle**：交付物是单一 \`.esm.js\`；静态 import 仅限 Node 内置（见 architecture 文档中的 Bundle Contract）。
+
+---
+
+编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ Moderator → 绑定 → 单文件 bundle**，再对照本节规范自检。
+`;
+}
+
+function readmeMd(workspaceName: string): string {
+  return `# ${workspaceName}
+
+Local workflow development workspace (Bun monorepo).
+
+## Layout
+
+- \`templates/\` — reusable workflow definition packages (roles + moderator), no agent binding
+- \`workflows/\` — workflow instances that bind templates to agents and export \`run\` + \`descriptor\`
+
+## Commands
+
+\`\`\`sh
+bun install
+bun run check   # after you add scripts / Biome
+uncaged-workflow add <name> <bundle.esm.js>
+uncaged-workflow run <name>
+\`\`\`
+
+Create this skeleton with:
+
+\`\`\`sh
+uncaged-workflow init workspace ${workspaceName}
+\`\`\`
+`;
+}
+
+export async function cmdInitWorkspace(
+  parentDir: string,
+  workspaceName: string,
+): Promise<Result<CmdInitWorkspaceSuccess, string>> {
+  const validated = validateWorkspaceSegment(workspaceName);
+  if (!validated.ok) {
+    return validated;
+  }
+
+  const rootPath = join(parentDir, workspaceName);
+  if (await pathExists(rootPath)) {
+    return err(`directory already exists: ${rootPath}`);
+  }
+
+  await mkdir(rootPath, { recursive: false });
+  await mkdir(join(rootPath, "templates"), { recursive: false });
+  await mkdir(join(rootPath, "workflows"), { recursive: false });
+
+  await Promise.all([
+    writeFile(join(rootPath, "package.json"), rootPackageJson(workspaceName), "utf8"),
+    writeFile(join(rootPath, "biome.json"), biomeJson(), "utf8"),
+    writeFile(join(rootPath, "tsconfig.json"), tsconfigJson(), "utf8"),
+    writeFile(join(rootPath, "AGENTS.md"), agentsMd(), "utf8"),
+    writeFile(join(rootPath, "README.md"), readmeMd(workspaceName), "utf8"),
+    writeFile(join(rootPath, "templates", ".gitkeep"), "", "utf8"),
+    writeFile(join(rootPath, "workflows", "package.json"), workflowsPackageJson(), "utf8"),
+  ]);
+
+  return ok({ rootPath });
+}
+
+function hasTemplatesWorkspaceGlob(workspaces: unknown): boolean {
+  return Array.isArray(workspaces) && workspaces.includes("templates/*");
+}
+
+async function readPackageJsonWorkspaces(dir: string): Promise<unknown | null> {
+  const pkgPath = join(dir, "package.json");
+  if (!(await pathExists(pkgPath))) {
+    return null;
+  }
+  let raw: string;
+  try {
+    raw = await readFile(pkgPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("workspaces" in parsed)) {
+    return null;
+  }
+  return (parsed as { workspaces: unknown }).workspaces;
+}
+
+/** Resolve uncaged-workflow workspace root (package.json with `templates/*` in `workspaces`). */
+async function findWorkflowWorkspaceRoot(startDir: string): Promise<Result<string, string>> {
+  let dir = resolve(startDir);
+  for (;;) {
+    const workspaces = await readPackageJsonWorkspaces(dir);
+    if (workspaces !== null && hasTemplatesWorkspaceGlob(workspaces)) {
+      return ok(dir);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return err(
+        'not inside a workflow workspace (no package.json with workspaces containing "templates/*")',
+      );
+    }
+    dir = parent;
+  }
+}
+
+function templatePackageJson(templateName: string): string {
+  return `${JSON.stringify(
+    {
+      name: `template-${templateName}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function templateTsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      extends: "../../tsconfig.json",
+      compilerOptions: {
+        rootDir: "src",
+        outDir: "dist",
+      },
+      include: ["src/**/*.ts"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function templateRolesTs(): string {
+  return `import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const HELLO_TEMPLATE_DESCRIPTION =
+  "Minimal starter template: one greeter role, then END.";
+
+export type HelloTemplateMeta = {
+  greeter: {
+    message: string;
+  };
+};
+
+const greeterMetaSchema = z.object({
+  message: z.string(),
+});
+
+export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
+  description: "Says hello — replace with your first role.",
+  systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
+  extractPrompt: "Extract the assistant's greeting as message.",
+  schema: greeterMetaSchema,
+  extractRefs: null,
+};
+`;
+}
+
+function templateModeratorTs(): string {
+  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
+
+import type { HelloTemplateMeta } from "./roles.js";
+
+export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
+  ctx: ModeratorContext<HelloTemplateMeta>,
+) => {
+  if (ctx.steps.length === 0) {
+    return "greeter";
+  }
+  return END;
+};
+`;
+}
+
+function templateIndexTs(): string {
+  return `import type { WorkflowDefinition } from "@uncaged/workflow";
+
+import { helloTemplateModerator } from "./moderator.js";
+import {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+
+export {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+export { helloTemplateModerator } from "./moderator.js";
+
+export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
+  description: HELLO_TEMPLATE_DESCRIPTION,
+  roles: {
+    greeter: greeterRole,
+  },
+  moderator: helloTemplateModerator,
+};
+`;
+}
+
+export async function cmdInitTemplate(
+  startDir: string,
+  templateName: string,
+): Promise<Result<CmdInitTemplateSuccess, string>> {
+  const validated = validateWorkspaceSegment(templateName);
+  if (!validated.ok) {
+    return validated;
+  }
+
+  const rootResult = await findWorkflowWorkspaceRoot(startDir);
+  if (!rootResult.ok) {
+    return rootResult;
+  }
+
+  const workspaceRoot = rootResult.value;
+  const templateDir = join(workspaceRoot, "templates", templateName);
+  if (await pathExists(templateDir)) {
+    return err(`template already exists: ${templateDir}`);
+  }
+
+  await mkdir(join(templateDir, "src"), { recursive: true });
+
+  await Promise.all([
+    writeFile(join(templateDir, "package.json"), templatePackageJson(templateName), "utf8"),
+    writeFile(join(templateDir, "tsconfig.json"), templateTsconfigJson(), "utf8"),
+    writeFile(join(templateDir, "src", "roles.ts"), templateRolesTs(), "utf8"),
+    writeFile(join(templateDir, "src", "moderator.ts"), templateModeratorTs(), "utf8"),
+    writeFile(join(templateDir, "src", "index.ts"), templateIndexTs(), "utf8"),
+  ]);
+
+  return ok({ templatePath: templateDir });
+}

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

@@ -21,12 +21,12 @@ export const committerMetaSchema = z.discriminatedUnion("status", [
 
 export type CommitterMeta = z.infer<typeof committerMetaSchema>;
 
-const COMMITTER_SYSTEM = `You are the git committer. Create a branch, commit the changes, and push.
+const COMMITTER_SYSTEM = `You are the git committer. Create a branch and commit the changes.
 Report the branch name and commit SHA. On failure, classify as recoverable or unrecoverable.
 Do not attempt to fix failures yourself.`;
 
 export const committerRole: RoleDefinition<CommitterMeta> = {
-  description: "Creates branch, commits, and pushes when review passes.",
+  description: "Creates a branch and commits changes.",
   systemPrompt: COMMITTER_SYSTEM,
   extractPrompt:
     "Extract the commit result: committed (with branch and SHA), recoverable failure, or unrecoverable failure. Include error details and log references if applicable.",

packages/workflow-role-submitter/__tests__/submitter.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+
+import { submitterMetaSchema, submitterRole } from "../src/submitter.js";
+
+describe("submitterRole", () => {
+  test("submitted sample validates against schema", () => {
+    const parsed = submitterMetaSchema.safeParse({
+      status: "submitted" as const,
+      prUrl: "https://github.com/example/repo/pull/42",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  test("failed sample validates against schema", () => {
+    const parsed = submitterMetaSchema.safeParse({
+      status: "failed" as const,
+      error: "gh not authenticated",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  test("rejects unknown status discriminant", () => {
+    const parsed = submitterMetaSchema.safeParse({
+      status: "queued",
+      prUrl: "https://example.com",
+    });
+    expect(parsed.success).toBe(false);
+  });
+
+  test("exposes submitter system prompt", () => {
+    expect(submitterRole.systemPrompt).toContain("submitter");
+    expect(submitterRole.systemPrompt).toContain("pull request");
+  });
+
+  test("uses single extract mode without refs", () => {
+    expect(submitterRole.extractMode).toBe("single");
+    expect(submitterRole.extractRefs).toBeNull();
+  });
+});

packages/workflow-role-submitter/package.json

@@ -0,0 +1,15 @@
+{
+  "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

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

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

@@ -0,0 +1,44 @@
+import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const submitterMetaSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("submitted"),
+    prUrl: z.string(),
+  }),
+  z.object({
+    status: z.literal("failed"),
+    error: z.string(),
+  }),
+]);
+
+export type SubmitterMeta = z.infer<typeof submitterMetaSchema>;
+
+const SUBMITTER_SYSTEM = `You are the **submitter**. Your job is to push the work branch to the remote and open a pull request.
+
+## Inputs
+
+Read the thread for context:
+- The **preparer**'s output gives you the absolute repo path and the default branch (and remote URL by inspecting the repo).
+- The **developer**'s output gives you the branch name that was committed and a list of files changed plus a summary of the work.
+
+## Procedure
+
+1. \`cd\` into the repo path from the preparer's output.
+2. Push the developer's branch to the remote: \`git push -u origin <branch>\`.
+3. Open a pull request (e.g. via \`gh pr create\`) targeting the default branch. The PR title should be short and describe the change. The PR description should summarize what changed (drawing from the developer's summary and filesChanged) and reference the original issue/task if applicable.
+4. Report the resulting PR URL.
+
+On any failure (push rejected, gh not authenticated, PR creation failed, etc.), report status="failed" with a short error message. Do not retry — surface the error so the moderator can decide.`;
+
+const SUBMITTER_EXTRACT_PROMPT =
+  "Extract the submission result. status='submitted' with prUrl on success, or status='failed' with a short error message on failure.";
+
+export const submitterRole: RoleDefinition<SubmitterMeta> = {
+  description: "Pushes the developer's branch to the remote and opens a pull request.",
+  systemPrompt: SUBMITTER_SYSTEM,
+  extractPrompt: SUBMITTER_EXTRACT_PROMPT,
+  schema: submitterMetaSchema,
+  extractRefs: null,
+  extractMode: "single",
+};

packages/workflow-role-submitter/tsconfig.json

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

packages/workflow-role-tester/package.json

@@ -0,0 +1,15 @@
+{
+  "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

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

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

@@ -0,0 +1,27 @@
+import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const testerMetaSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("passed"),
+    details: z.string(),
+  }),
+  z.object({
+    status: z.literal("failed"),
+    details: z.string(),
+  }),
+]);
+
+export type TesterMeta = z.infer<typeof testerMetaSchema>;
+
+const TESTER_SYSTEM = `You are a tester. Run the project's test suite, build, and lint commands. Check what commands are available from the preparer's output in the thread. Report pass/fail with details of what failed.`;
+
+export const testerRole: RoleDefinition<TesterMeta> = {
+  description: "Runs test, build, and lint commands and reports pass or fail with details.",
+  systemPrompt: TESTER_SYSTEM,
+  extractPrompt:
+    "Extract the verification result: passed with summary details, or failed with details of what broke.",
+  schema: testerMetaSchema,
+  extractRefs: null,
+  extractMode: "single",
+};

packages/workflow-role-tester/tsconfig.json

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

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

@@ -0,0 +1,260 @@
+import { describe, expect, test } from "bun:test";
+import {
+  END,
+  type ModeratorContext,
+  type RoleStep,
+  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 { DevelopMeta } from "../src/roles.js";
+
+const DEFAULT_PHASES: PlannerMeta["phases"] = [
+  {
+    hash: "4KNMR2PX",
+    title: "Do the work",
+  },
+];
+
+function makeStart(maxRounds: number): ModeratorContext<DevelopMeta>["start"] {
+  return {
+    role: START,
+    content: "Implement the feature",
+    meta: { maxRounds },
+    timestamp: 0,
+  };
+}
+
+function makeCtx(
+  maxRounds: number,
+  steps: ModeratorContext<DevelopMeta>["steps"],
+): ModeratorContext<DevelopMeta> {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    start: makeStart(maxRounds),
+    steps,
+  };
+}
+
+function plannerStep(phases: PlannerMeta["phases"] = DEFAULT_PHASES): RoleStep<DevelopMeta> {
+  return {
+    role: "planner",
+    contentHash: "STUBHASHPLANNER001",
+    meta: { phases },
+    refs: phases.map((p) => p.hash),
+    timestamp: 1,
+  };
+}
+
+function coderStep(completedPhase = "4KNMR2PX"): RoleStep<DevelopMeta> {
+  return {
+    role: "coder",
+    contentHash: "STUBHASHCODER00001",
+    meta: { completedPhase, filesChanged: ["a.ts"], summary: "implemented" },
+    refs: [completedPhase],
+    timestamp: 2,
+  };
+}
+
+function reviewerStep(approved: boolean): RoleStep<DevelopMeta> {
+  return {
+    role: "reviewer",
+    contentHash: "STUBHASHREVIEWER01",
+    meta: approved
+      ? { status: "approved" as const }
+      : { status: "rejected" as const, issues: ["needs fix"] },
+    refs: [],
+    timestamp: 3,
+  };
+}
+
+function testerStep(passed: boolean): RoleStep<DevelopMeta> {
+  return {
+    role: "tester",
+    contentHash: "STUBHASHTESTER01",
+    meta: passed
+      ? { status: "passed" as const, details: "all checks passed" }
+      : { status: "failed" as const, details: "lint failed" },
+    refs: [],
+    timestamp: 4,
+  };
+}
+
+function committerStep(meta: CommitterMeta): RoleStep<DevelopMeta> {
+  return {
+    role: "committer",
+    contentHash: "STUBHASHCOMMITTER1",
+    meta,
+    refs: [],
+    timestamp: 5,
+  };
+}
+
+describe("developModerator", () => {
+  test("routes initial → planner → coder → reviewer → tester → committer → END", () => {
+    expect(developModerator(makeCtx(20, []))).toBe("planner");
+    expect(developModerator(makeCtx(20, [plannerStep()]))).toBe("coder");
+    expect(developModerator(makeCtx(20, [plannerStep(), coderStep()]))).toBe("reviewer");
+    expect(developModerator(makeCtx(20, [plannerStep(), coderStep(), reviewerStep(true)]))).toBe(
+      "tester",
+    );
+    expect(
+      developModerator(
+        makeCtx(20, [plannerStep(), coderStep(), reviewerStep(true), testerStep(true)]),
+      ),
+    ).toBe("committer");
+    expect(
+      developModerator(
+        makeCtx(20, [
+          plannerStep(),
+          coderStep(),
+          reviewerStep(true),
+          testerStep(true),
+          committerStep({ status: "committed", branch: "feat/x", commitSha: "abc1234" }),
+        ]),
+      ),
+    ).toBe(END);
+  });
+
+  test("reviewer rejects → coder retry when budget allows", () => {
+    const steps: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(),
+      coderStep(),
+      reviewerStep(false),
+    ];
+    expect(developModerator(makeCtx(20, steps))).toBe("coder");
+  });
+
+  test("reviewer rejects → END when max rounds exhausted", () => {
+    const steps: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(),
+      coderStep(),
+      reviewerStep(false),
+    ];
+    expect(developModerator(makeCtx(4, steps))).toBe(END);
+  });
+
+  test("tester failed → coder retry when budget allows", () => {
+    const steps: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(),
+      coderStep(),
+      reviewerStep(true),
+      testerStep(false),
+    ];
+    expect(developModerator(makeCtx(20, steps))).toBe("coder");
+  });
+
+  test("tester failed → END when max rounds exhausted", () => {
+    const steps: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(),
+      coderStep(),
+      reviewerStep(true),
+      testerStep(false),
+    ];
+    expect(developModerator(makeCtx(5, steps))).toBe(END);
+  });
+
+  test("multiple planner phases → coder until all complete, then reviewer", () => {
+    const phases: PlannerMeta["phases"] = [
+      { hash: "AA000001", title: "first phase" },
+      { hash: "AA000002", title: "second phase" },
+    ];
+    expect(developModerator(makeCtx(20, [plannerStep(phases)]))).toBe("coder");
+    expect(developModerator(makeCtx(20, [plannerStep(phases), coderStep("AA000001")]))).toBe(
+      "coder",
+    );
+    expect(
+      developModerator(
+        makeCtx(20, [plannerStep(phases), coderStep("AA000001"), coderStep("AA000002")]),
+      ),
+    ).toBe("reviewer");
+  });
+
+  test("one-shot coder reports only last phase hash → reviewer (moderator treats as all phases done)", () => {
+    const phases: PlannerMeta["phases"] = [
+      { hash: "BB000001", title: "setup branch" },
+      { hash: "BB000002", title: "write tests" },
+      { hash: "BB000003", title: "verify" },
+      { hash: "BB000004", title: "polish" },
+    ];
+    expect(developModerator(makeCtx(20, [plannerStep(phases), coderStep("BB000004")]))).toBe(
+      "reviewer",
+    );
+  });
+
+  test("unrecognised completedPhase hash → coder retry when budget allows", () => {
+    const phases: PlannerMeta["phases"] = [
+      { hash: "CC000001", title: "first phase" },
+      { hash: "CC000002", title: "second phase" },
+    ];
+    expect(developModerator(makeCtx(20, [plannerStep(phases), coderStep("all-done")]))).toBe(
+      "coder",
+    );
+  });
+
+  test("incomplete phases → END when max rounds exhausted", () => {
+    const phases: PlannerMeta["phases"] = [
+      { hash: "DD000001", title: "first phase" },
+      { hash: "DD000002", title: "second phase" },
+    ];
+    const steps: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(phases),
+      coderStep("DD000001"),
+    ];
+    expect(developModerator(makeCtx(3, steps))).toBe(END);
+  });
+
+  test("committer → END for any committer meta status", () => {
+    const committed = committerStep({ status: "committed", branch: "f", commitSha: "x" });
+    const recoverable = committerStep({
+      status: "recoverable",
+      error: "merge conflict",
+      logRef: null,
+    });
+    const unrecoverable = committerStep({
+      status: "unrecoverable",
+      error: "repo missing",
+      logRef: "log1",
+    });
+    const base: ModeratorContext<DevelopMeta>["steps"] = [
+      plannerStep(),
+      coderStep(),
+      reviewerStep(true),
+      testerStep(true),
+    ];
+    expect(developModerator(makeCtx(20, [...base, committed]))).toBe(END);
+    expect(developModerator(makeCtx(20, [...base, recoverable]))).toBe(END);
+    expect(developModerator(makeCtx(20, [...base, unrecoverable]))).toBe(END);
+  });
+});
+
+describe("buildDevelopDescriptor", () => {
+  test("lists all roles with schemas that validate", () => {
+    const descriptor = buildDevelopDescriptor();
+    const validated = validateWorkflowDescriptor(descriptor);
+    expect(validated.ok).toBe(true);
+    if (!validated.ok) {
+      throw new Error(validated.error);
+    }
+    expect(Object.keys(validated.value.roles).sort()).toEqual([
+      "coder",
+      "committer",
+      "planner",
+      "reviewer",
+      "tester",
+    ]);
+    for (const key of ["planner", "coder", "reviewer", "tester", "committer"] as const) {
+      const role = validated.value.roles[key];
+      expect(role).toBeDefined();
+      expect(typeof role.schema).toBe("object");
+      expect(role.schema).not.toBeNull();
+      expect(Array.isArray(role.schema)).toBe(false);
+    }
+  });
+});

packages/workflow-template-develop/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@uncaged/workflow-template-develop",
+  "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:*",
+    "@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:*"
+  }
+}

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

@@ -0,0 +1,12 @@
+import { buildDescriptor } from "@uncaged/workflow";
+
+import { developModerator } from "./moderator.js";
+import { DEVELOP_WORKFLOW_DESCRIPTION, developRoles } from "./roles.js";
+
+export function buildDevelopDescriptor() {
+  return buildDescriptor({
+    description: DEVELOP_WORKFLOW_DESCRIPTION,
+    roles: developRoles,
+    moderator: developModerator,
+  });
+}

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

@@ -0,0 +1,60 @@
+import {
+  type AgentBinding,
+  createWorkflow,
+  type ExtractFn,
+  type LlmProvider,
+  type WorkflowDefinition,
+  type WorkflowFn,
+} from "@uncaged/workflow";
+
+import { developModerator } from "./moderator.js";
+import { DEVELOP_WORKFLOW_DESCRIPTION, type DevelopMeta, developRoles } from "./roles.js";
+
+export {
+  type CoderMeta,
+  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";
+export {
+  DEVELOP_WORKFLOW_DESCRIPTION,
+  type DevelopMeta,
+  type DevelopRoles,
+  developRoles,
+} from "./roles.js";
+
+export const developWorkflowDefinition: WorkflowDefinition<DevelopMeta> = {
+  description: DEVELOP_WORKFLOW_DESCRIPTION,
+  roles: developRoles,
+  moderator: developModerator,
+};
+
+export function createDevelopRun(
+  binding: AgentBinding,
+  extract: ExtractFn,
+  llmProvider: LlmProvider | null,
+): WorkflowFn {
+  return createWorkflow(developWorkflowDefinition, binding, extract, llmProvider);
+}

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

@@ -0,0 +1,89 @@
+import type { Moderator, ModeratorContext } from "@uncaged/workflow";
+import { END } from "@uncaged/workflow";
+
+import type { DevelopMeta } from "./roles.js";
+
+function coderFinishedAllPlannedPhases(
+  phases: ReadonlyArray<{ hash: string }>,
+  coderCompletedPhases: ReadonlyArray<string>,
+): boolean {
+  if (phases.length === 0) {
+    return true;
+  }
+  const plannedHashes = new Set(phases.map((p) => p.hash));
+  const lastHash = phases[phases.length - 1].hash;
+  const explicit = new Set(coderCompletedPhases.filter((h) => plannedHashes.has(h)));
+  if (phases.every((p) => explicit.has(p.hash))) {
+    return true;
+  }
+  if (coderCompletedPhases.some((h) => h === lastHash)) {
+    return true;
+  }
+  return false;
+}
+
+function nextAfterCoder(
+  ctx: ModeratorContext<DevelopMeta>,
+  maxRounds: number,
+): (keyof DevelopMeta & string) | typeof END {
+  const plannerStep = ctx.steps.find((s) => s.role === "planner");
+  if (plannerStep === undefined) {
+    return "reviewer";
+  }
+  const phases = plannerStep.meta.phases;
+  const coderCompletedPhases = ctx.steps
+    .filter((s) => s.role === "coder")
+    .map((s) => s.meta.completedPhase);
+  const allDone = coderFinishedAllPlannedPhases(phases, coderCompletedPhases);
+  if (allDone) {
+    return "reviewer";
+  }
+  if (ctx.steps.length < maxRounds - 1) {
+    return "coder";
+  }
+  return END;
+}
+
+export const developModerator: Moderator<DevelopMeta> = (ctx) => {
+  const maxRounds = ctx.start.meta.maxRounds;
+
+  if (ctx.steps.length === 0) {
+    return "planner";
+  }
+
+  const last = ctx.steps[ctx.steps.length - 1];
+
+  if (last.role === "planner") {
+    return "coder";
+  }
+
+  if (last.role === "coder") {
+    return nextAfterCoder(ctx, maxRounds);
+  }
+
+  if (last.role === "reviewer") {
+    if (last.meta.status === "approved") {
+      return "tester";
+    }
+    if (ctx.steps.length < maxRounds - 1) {
+      return "coder";
+    }
+    return END;
+  }
+
+  if (last.role === "tester") {
+    if (last.meta.status === "passed") {
+      return "committer";
+    }
+    if (ctx.steps.length < maxRounds - 1) {
+      return "coder";
+    }
+    return END;
+  }
+
+  if (last.role === "committer") {
+    return END;
+  }
+
+  return END;
+};

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

@@ -0,0 +1,29 @@
+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";
+
+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).";
+
+export type DevelopMeta = {
+  planner: PlannerMeta;
+  coder: CoderMeta;
+  reviewer: ReviewerMeta;
+  tester: TesterMeta;
+  committer: CommitterMeta;
+};
+
+export type DevelopRoles = {
+  [K in keyof DevelopMeta]: RoleDefinition<DevelopMeta[K]>;
+};
+
+export const developRoles: DevelopRoles = {
+  planner: plannerRole,
+  coder: coderRole,
+  reviewer: reviewerRole,
+  tester: testerRole,
+  committer: committerRole,
+};

packages/workflow-template-develop/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "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" }
+  ]
+}

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

@@ -12,41 +12,71 @@ import {
   validateWorkflowDescriptor,
 } from "@uncaged/workflow";
 
-import type { CoderMeta } from "@uncaged/workflow-role-coder";
-import type { PlannerMeta } from "@uncaged/workflow-role-planner";
 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 { SolveIssueMeta } from "../src/roles.js";
 
-const DEFAULT_PHASES: PlannerMeta["phases"] = [
-  {
-    hash: "4KNMR2PX",
-    title: "Do the work",
-  },
-];
+function jsonResponse(payload: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(payload), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
 
-const EXPECT_PLANNER_META: PlannerMeta = {
-  phases: [
-    {
-      hash: "7BQST3VW",
-      title: "placeholder phase",
-    },
-  ],
-};
+function readToolListFromBody(init: RequestInit | undefined): readonly Record<string, unknown>[] {
+  if (init === undefined || init.body === undefined || init.body === null) {
+    return [];
+  }
+  const body = JSON.parse(String(init.body)) as Record<string, unknown>;
+  const tools = body.tools;
+  if (!Array.isArray(tools)) {
+    return [];
+  }
+  return tools.filter((t): t is Record<string, unknown> => t !== null && typeof t === "object");
+}
 
-const EXPECT_CODER_META: CoderMeta = {
-  completedPhase: "7BQST3VW",
-  filesChanged: [],
-  summary: "",
-};
+function singleToolName(tools: readonly Record<string, unknown>[]): string {
+  if (tools.length === 0) {
+    return "extract";
+  }
+  const fn = tools[0].function as Record<string, unknown> | undefined;
+  return typeof fn?.name === "string" ? fn.name : "extract";
+}
+
+function buildSingleModeResponse(args: Record<string, unknown>, toolName: string): Response {
+  return jsonResponse({
+    choices: [
+      {
+        message: {
+          tool_calls: [
+            {
+              type: "function",
+              function: { name: toolName, arguments: JSON.stringify(args) },
+            },
+          ],
+        },
+      },
+    ],
+  });
+}
+
+function buildReactModeResponse(args: Record<string, unknown>): Response {
+  // reactExtract accepts a plain-JSON assistant message and validates it
+  // directly against the schema, so we skip the cas_get / extract tool dance.
+  return jsonResponse({
+    choices: [{ message: { content: JSON.stringify(args) } }],
+  });
+}
 
 function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unknown>>): () => void {
   const origFetch = globalThis.fetch;
   let i = 0;
   const mockFetch = async (
-    input: Parameters<typeof fetch>[0],
+    _input: Parameters<typeof fetch>[0],
     init?: RequestInit,
   ): Promise<Response> => {
     const args = sequence[i] ?? sequence[sequence.length - 1];
@@ -54,36 +84,11 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
       throw new Error("installMockChatCompletions: empty sequence");
     }
     i += 1;
-    void input;
-    const body = init?.body ? (JSON.parse(String(init.body)) as Record<string, unknown>) : {};
-    const tools = body.tools;
-    const firstTool =
-      Array.isArray(tools) && tools.length > 0 && tools[0] !== null && typeof tools[0] === "object"
-        ? (tools[0] as Record<string, unknown>)
-        : null;
-    const fn =
-      firstTool !== null ? (firstTool.function as Record<string, unknown> | undefined) : undefined;
-    const toolName = typeof fn?.name === "string" ? fn.name : "extract";
-    return new Response(
-      JSON.stringify({
-        choices: [
-          {
-            message: {
-              tool_calls: [
-                {
-                  type: "function",
-                  function: {
-                    name: toolName,
-                    arguments: JSON.stringify(args),
-                  },
-                },
-              ],
-            },
-          },
-        ],
-      }),
-      { status: 200, headers: { "Content-Type": "application/json" } },
-    );
+    const tools = readToolListFromBody(init);
+    if (tools.length > 1) {
+      return buildReactModeResponse(args);
+    }
+    return buildSingleModeResponse(args, singleToolName(tools));
   };
   globalThis.fetch = Object.assign(mockFetch, {
     preconnect: origFetch.preconnect.bind(origFetch),
@@ -134,152 +139,86 @@ function preparerStep(): RoleStep<SolveIssueMeta> {
   };
 }
 
-function plannerStep(phases: PlannerMeta["phases"] = DEFAULT_PHASES): RoleStep<SolveIssueMeta> {
+function developerStep(): RoleStep<SolveIssueMeta> {
   return {
-    role: "planner",
-    contentHash: "STUBHASHPLANNER001",
-    meta: { phases },
-    refs: phases.map((p) => p.hash),
+    role: "developer",
+    contentHash: "STUBHASHDEVELOPER1",
+    meta: {
+      branch: "feat/issue-1",
+      commitSha: "abc1234",
+      filesChanged: ["src/login.ts"],
+      summary: "Fixed flaky login test by stabilising async setup.",
+    },
+    refs: [],
     timestamp: 1,
   };
 }
 
-function coderStep(completedPhase = "4KNMR2PX"): RoleStep<SolveIssueMeta> {
+function submitterStep(meta: SubmitterMeta): RoleStep<SolveIssueMeta> {
   return {
-    role: "coder",
-    contentHash: "STUBHASHCODER00001",
-    meta: { completedPhase, filesChanged: ["a.ts"], summary: "fixed" },
-    refs: [completedPhase],
+    role: "submitter",
+    contentHash: "STUBHASHSUBMITTER1",
+    meta,
+    refs: [],
     timestamp: 2,
   };
 }
 
-function reviewerStep(approved: boolean): RoleStep<SolveIssueMeta> {
-  return {
-    role: "reviewer",
-    contentHash: "STUBHASHREVIEWER01",
-    meta: approved
-      ? { status: "approved" as const }
-      : { status: "rejected" as const, issues: ["needs fix"] },
-    refs: [],
-    timestamp: 3,
-  };
-}
-
-function committerStep(): RoleStep<SolveIssueMeta> {
-  return {
-    role: "committer",
-    contentHash: "STUBHASHCOMMITTER1",
-    meta: { status: "committed", branch: "feat/issue-1", commitSha: "abc1234" },
-    refs: [],
-    timestamp: 4,
-  };
-}
-
 const stubExtract = createExtract({
   baseUrl: "http://127.0.0.1:9",
   apiKey: "",
   model: "test",
 });
 
+const stubLlmProvider = {
+  baseUrl: "http://127.0.0.1:9",
+  apiKey: "",
+  model: "test",
+};
+
 describe("solveIssueModerator", () => {
-  test("routes preparer → planner → coder → reviewer → committer → END", () => {
+  test("routes initial → preparer → developer → submitter → END", () => {
     expect(solveIssueModerator(makeCtx(20, []))).toBe("preparer");
-    expect(solveIssueModerator(makeCtx(20, [preparerStep()]))).toBe("planner");
-    expect(solveIssueModerator(makeCtx(20, [preparerStep(), plannerStep()]))).toBe("coder");
-    expect(solveIssueModerator(makeCtx(20, [preparerStep(), plannerStep(), coderStep()]))).toBe(
-      "reviewer",
-    );
-    expect(
-      solveIssueModerator(
-        makeCtx(20, [preparerStep(), plannerStep(), coderStep(), reviewerStep(true)]),
-      ),
-    ).toBe("committer");
+    expect(solveIssueModerator(makeCtx(20, [preparerStep()]))).toBe("developer");
+    expect(solveIssueModerator(makeCtx(20, [preparerStep(), developerStep()]))).toBe("submitter");
     expect(
       solveIssueModerator(
         makeCtx(20, [
           preparerStep(),
-          plannerStep(),
-          coderStep(),
-          reviewerStep(true),
-          committerStep(),
+          developerStep(),
+          submitterStep({
+            status: "submitted",
+            prUrl: "https://github.com/example/repo/pull/1",
+          }),
         ]),
       ),
     ).toBe(END);
   });
 
-  test("reviewer rejects → coder retry when budget allows", () => {
-    const steps: ModeratorContext<SolveIssueMeta>["steps"] = [
-      plannerStep(),
-      coderStep(),
-      reviewerStep(false),
-    ];
-    expect(solveIssueModerator(makeCtx(20, steps))).toBe("coder");
-  });
-
-  test("reviewer rejects → END when max rounds exhausted", () => {
-    const steps: ModeratorContext<SolveIssueMeta>["steps"] = [
-      plannerStep(),
-      coderStep(),
-      reviewerStep(false),
-    ];
-    expect(solveIssueModerator(makeCtx(4, steps))).toBe(END);
-  });
-
-  test("multiple planner phases → coder until all complete, then reviewer", () => {
-    const phases: PlannerMeta["phases"] = [
-      {
-        hash: "AA000001",
-        title: "first phase",
-      },
-      {
-        hash: "AA000002",
-        title: "second phase",
-      },
-    ];
-    expect(solveIssueModerator(makeCtx(20, [plannerStep(phases)]))).toBe("coder");
-    expect(solveIssueModerator(makeCtx(20, [plannerStep(phases), coderStep("AA000001")]))).toBe(
-      "coder",
-    );
+  test("submitter failed → END", () => {
     expect(
       solveIssueModerator(
-        makeCtx(20, [plannerStep(phases), coderStep("AA000001"), coderStep("AA000002")]),
+        makeCtx(20, [
+          preparerStep(),
+          developerStep(),
+          submitterStep({ status: "failed", error: "gh not authenticated" }),
+        ]),
       ),
-    ).toBe("reviewer");
+    ).toBe(END);
   });
 
-  test("one-shot coder reports only last phase hash → reviewer (moderator treats as all phases done)", () => {
-    const phases: PlannerMeta["phases"] = [
-      { hash: "BB000001", title: "setup branch" },
-      { hash: "BB000002", title: "write tests" },
-      { hash: "BB000003", title: "verify" },
-      { hash: "BB000004", title: "commit and pr" },
-    ];
-    expect(solveIssueModerator(makeCtx(20, [plannerStep(phases), coderStep("BB000004")]))).toBe(
-      "reviewer",
-    );
-  });
-
-  test("unrecognised completedPhase hash → coder retry when budget allows", () => {
-    const phases: PlannerMeta["phases"] = [
-      { hash: "CC000001", title: "first phase" },
-      { hash: "CC000002", title: "second phase" },
-    ];
-    expect(solveIssueModerator(makeCtx(20, [plannerStep(phases), coderStep("all-done")]))).toBe(
-      "coder",
-    );
-  });
-
-  test("incomplete phases → END when max rounds exhausted", () => {
-    const phases: PlannerMeta["phases"] = [
-      { hash: "DD000001", title: "first phase" },
-      { hash: "DD000002", title: "second phase" },
-    ];
-    const steps: ModeratorContext<SolveIssueMeta>["steps"] = [
-      plannerStep(phases),
-      coderStep("DD000001"),
-    ];
-    expect(solveIssueModerator(makeCtx(3, steps))).toBe(END);
+  test("returns END for any unexpected last step (defensive)", () => {
+    // A submitter step with a pseudo-unknown future status would still be
+    // routed to END, since the moderator is a closed switch over known roles.
+    expect(
+      solveIssueModerator(
+        makeCtx(20, [
+          preparerStep(),
+          developerStep(),
+          submitterStep({ status: "submitted", prUrl: "https://example.com/pr/1" }),
+        ]),
+      ),
+    ).toBe(END);
   });
 });
 
@@ -296,7 +235,7 @@ describe("createSolveIssueRun", () => {
     }
   });
 
-  test("structured extraction yields preparer then planner meta from mocked chat completions", async () => {
+  test("structured extraction yields preparer meta from mocked chat completions", async () => {
     const EXPECT_PREPARER_META: PreparerMeta = {
       repoPath: "/home/user/repos/test",
       defaultBranch: "main",
@@ -308,12 +247,20 @@ describe("createSolveIssueRun", () => {
         buildCommand: "bun run build",
       },
     };
-    restoreFetch = installMockChatCompletions([EXPECT_PREPARER_META, EXPECT_PLANNER_META]);
+    restoreFetch = installMockChatCompletions([EXPECT_PREPARER_META]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
 
-    const run = createSolveIssueRun({ agent: async () => "" }, stubExtract, null);
+    // Override developer so the test does not spin up a child workflow.
+    const run = createSolveIssueRun(
+      {
+        agent: async () => "",
+        overrides: { developer: async () => "stub-root-hash" },
+      },
+      stubExtract,
+      stubLlmProvider,
+    );
     const gen = run(
       { prompt: "task", steps: [] },
       { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
@@ -325,14 +272,6 @@ describe("createSolveIssueRun", () => {
     }
     expect(first.value.role).toBe("preparer");
     expect(first.value.meta).toEqual(EXPECT_PREPARER_META);
-
-    const second = await gen.next();
-    expect(second.done).toBe(false);
-    if (second.done) {
-      throw new Error("expected yield");
-    }
-    expect(second.value.role).toBe("planner");
-    expect(second.value.meta).toEqual(EXPECT_PLANNER_META);
   });
 
   test("per-role agent overrides default", async () => {
@@ -342,11 +281,17 @@ describe("createSolveIssueRun", () => {
       conventions: null,
       toolchain: { packageManager: null, testCommand: null, lintCommand: null, buildCommand: null },
     };
-    restoreFetch = installMockChatCompletions([
-      PREPARER_META,
-      EXPECT_PLANNER_META,
-      EXPECT_CODER_META,
-    ]);
+    const DEVELOPER_META: DeveloperMeta = {
+      branch: "feat/x",
+      commitSha: "abc1234",
+      filesChanged: ["a.ts"],
+      summary: "did the work",
+    };
+    const SUBMITTER_META: SubmitterMeta = {
+      status: "submitted",
+      prUrl: "https://github.com/example/repo/pull/2",
+    };
+    restoreFetch = installMockChatCompletions([PREPARER_META, DEVELOPER_META, SUBMITTER_META]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
@@ -363,18 +308,18 @@ describe("createSolveIssueRun", () => {
             calls.push("preparer");
             return "";
           },
-          planner: async () => {
-            calls.push("planner");
-            return "";
+          developer: async () => {
+            calls.push("developer");
+            return "stub-root-hash";
           },
-          coder: async () => {
-            calls.push("coder");
+          submitter: async () => {
+            calls.push("submitter");
             return "";
           },
         },
       },
       stubExtract,
-      null,
+      stubLlmProvider,
     );
     const gen = run(
       { prompt: "task", steps: [] },
@@ -385,16 +330,65 @@ describe("createSolveIssueRun", () => {
 
     calls.length = 0;
     await gen.next();
-    expect(calls).toEqual(["planner"]);
+    expect(calls).toEqual(["developer"]);
 
     calls.length = 0;
     await gen.next();
-    expect(calls).toEqual(["coder"]);
+    expect(calls).toEqual(["submitter"]);
+  });
+
+  test("developer defaults to workflowAsAgent override (caller override still wins)", async () => {
+    const PREPARER_META: PreparerMeta = {
+      repoPath: "/tmp/r",
+      defaultBranch: "main",
+      conventions: null,
+      toolchain: { packageManager: null, testCommand: null, lintCommand: null, buildCommand: null },
+    };
+    const DEVELOPER_META: DeveloperMeta = {
+      branch: "feat/y",
+      commitSha: "def5678",
+      filesChanged: ["b.ts"],
+      summary: "more work",
+    };
+    restoreFetch = installMockChatCompletions([PREPARER_META, DEVELOPER_META]);
+
+    casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
+    const cas = createCasStore(casDir);
+
+    let developerInvocations = 0;
+    const run = createSolveIssueRun(
+      {
+        agent: async () => "",
+        overrides: {
+          developer: async () => {
+            developerInvocations += 1;
+            return "stub-root-hash";
+          },
+        },
+      },
+      stubExtract,
+      stubLlmProvider,
+    );
+    const gen = run(
+      { prompt: "task", steps: [] },
+      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+    );
+    // preparer
+    await gen.next();
+    // developer (caller override should be invoked, NOT workflowAsAgent default)
+    const devYield = await gen.next();
+    expect(devYield.done).toBe(false);
+    if (devYield.done) {
+      throw new Error("expected yield");
+    }
+    expect(devYield.value.role).toBe("developer");
+    expect(devYield.value.meta).toEqual(DEVELOPER_META);
+    expect(developerInvocations).toBe(1);
   });
 });
 
 describe("buildSolveIssueDescriptor", () => {
-  test("lists all roles with schemas that validate", () => {
+  test("lists preparer, developer, submitter with schemas that validate", () => {
     const descriptor = buildSolveIssueDescriptor();
     const validated = validateWorkflowDescriptor(descriptor);
     expect(validated.ok).toBe(true);
@@ -402,13 +396,11 @@ describe("buildSolveIssueDescriptor", () => {
       throw new Error(validated.error);
     }
     expect(Object.keys(validated.value.roles).sort()).toEqual([
-      "coder",
-      "committer",
-      "planner",
+      "developer",
       "preparer",
-      "reviewer",
+      "submitter",
     ]);
-    for (const key of ["preparer", "planner", "coder", "reviewer", "committer"] as const) {
+    for (const key of ["preparer", "developer", "submitter"] as const) {
       const role = validated.value.roles[key];
       expect(role).toBeDefined();
       expect(typeof role.schema).toBe("object");

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

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

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

@@ -0,0 +1,37 @@
+import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const developerMetaSchema = z.object({
+  branch: z.string(),
+  commitSha: z.string(),
+  filesChanged: z.array(z.string()),
+  summary: z.string(),
+});
+
+export type DeveloperMeta = z.infer<typeof developerMetaSchema>;
+
+const DEVELOPER_SYSTEM = `You are the **developer**. You delegate the implementation work to the \`develop\` workflow.
+
+The actual implementation (planning → coding → reviewing → testing → committing) is handled by a child workflow that runs in your place. Your output is the Merkle DAG root hash of that child thread.
+
+Pass through the task and let the child workflow do the work.`;
+
+const DEVELOPER_EXTRACT_PROMPT = `The agent output is the root CAS hash of a child workflow thread. Use the cas_get tool to traverse the Merkle DAG and extract the developer summary.
+
+Procedure:
+1. cas_get(<rootHash>) — the root node lists all child step hashes (planner, coder, reviewer, tester, committer).
+2. Find the committer step. cas_get its hash to read the committer's meta — extract branch and commitSha from there.
+3. Find every coder step. cas_get each to read the coder's filesChanged. Union all filesChanged across coder steps.
+4. Compose a short human-readable summary describing what the develop child workflow accomplished (drawn from the coder summaries, or a synthesis of them).
+
+Return: { branch, commitSha, filesChanged, summary }.`;
+
+export const developerRole: RoleDefinition<DeveloperMeta> = {
+  description:
+    "Delegates the actual implementation to the develop workflow (workflow-as-agent). Produces a summary by traversing the child thread's Merkle DAG.",
+  systemPrompt: DEVELOPER_SYSTEM,
+  extractPrompt: DEVELOPER_EXTRACT_PROMPT,
+  schema: developerMetaSchema,
+  extractRefs: () => [],
+  extractMode: "react",
+};

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

@@ -5,38 +5,28 @@ import {
   type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
+  workflowAsAgent,
 } from "@uncaged/workflow";
 
 import { solveIssueModerator } from "./moderator.js";
 import { SOLVE_ISSUE_WORKFLOW_DESCRIPTION, type SolveIssueMeta, solveIssueRoles } from "./roles.js";
 
-export {
-  type CoderMeta,
-  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 PreparerMeta,
   preparerMetaSchema,
   preparerRole,
 } from "@uncaged/workflow-role-preparer";
 export {
-  type ReviewerMeta,
-  reviewerMetaSchema,
-  reviewerRole,
-} from "@uncaged/workflow-role-reviewer";
+  type SubmitterMeta,
+  submitterMetaSchema,
+  submitterRole,
+} from "@uncaged/workflow-role-submitter";
 export { buildSolveIssueDescriptor } from "./descriptor.js";
+export {
+  type DeveloperMeta,
+  developerMetaSchema,
+  developerRole,
+} from "./developer.js";
 export { solveIssueModerator } from "./moderator.js";
 export {
   SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
@@ -51,10 +41,25 @@ export const solveIssueWorkflowDefinition: WorkflowDefinition<SolveIssueMeta> =
   moderator: solveIssueModerator,
 };
 
+/**
+ * Build the solve-issue {@link WorkflowFn}.
+ *
+ * The `developer` role always delegates to the registered `develop` workflow via
+ * {@link workflowAsAgent}; if the caller supplies their own `developer` override in
+ * `binding.overrides`, it takes precedence so tests and custom hosts can stub it.
+ */
 export function createSolveIssueRun(
   binding: AgentBinding,
   extract: ExtractFn,
   llmProvider: LlmProvider | null,
 ): WorkflowFn {
-  return createWorkflow(solveIssueWorkflowDefinition, binding, extract, llmProvider);
+  const developerOverride = binding.overrides?.developer ?? workflowAsAgent("develop");
+  const mergedBinding: AgentBinding = {
+    agent: binding.agent,
+    overrides: {
+      ...(binding.overrides ?? {}),
+      developer: developerOverride,
+    },
+  };
+  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding, extract, llmProvider);
 }

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

@@ -1,52 +1,9 @@
-import type { Moderator, ModeratorContext } from "@uncaged/workflow";
+import type { Moderator } from "@uncaged/workflow";
 import { END } from "@uncaged/workflow";
 
 import type { SolveIssueMeta } from "./roles.js";
 
-function coderFinishedAllPlannedPhases(
-  phases: ReadonlyArray<{ hash: string }>,
-  coderCompletedPhases: ReadonlyArray<string>,
-): boolean {
-  if (phases.length === 0) {
-    return true;
-  }
-  const plannedHashes = new Set(phases.map((p) => p.hash));
-  const lastHash = phases[phases.length - 1].hash;
-  const explicit = new Set(coderCompletedPhases.filter((h) => plannedHashes.has(h)));
-  if (phases.every((p) => explicit.has(p.hash))) {
-    return true;
-  }
-  if (coderCompletedPhases.some((h) => h === lastHash)) {
-    return true;
-  }
-  return false;
-}
-
-function nextAfterCoder(
-  ctx: ModeratorContext<SolveIssueMeta>,
-  maxRounds: number,
-): (keyof SolveIssueMeta & string) | typeof END {
-  const plannerStep = ctx.steps.find((s) => s.role === "planner");
-  if (plannerStep === undefined) {
-    return "reviewer";
-  }
-  const phases = plannerStep.meta.phases;
-  const coderCompletedPhases = ctx.steps
-    .filter((s) => s.role === "coder")
-    .map((s) => s.meta.completedPhase);
-  const allDone = coderFinishedAllPlannedPhases(phases, coderCompletedPhases);
-  if (allDone) {
-    return "reviewer";
-  }
-  if (ctx.steps.length < maxRounds - 1) {
-    return "coder";
-  }
-  return END;
-}
-
 export const solveIssueModerator: Moderator<SolveIssueMeta> = (ctx) => {
-  const maxRounds = ctx.start.meta.maxRounds;
-
   if (ctx.steps.length === 0) {
     return "preparer";
   }
@@ -54,31 +11,14 @@ export const solveIssueModerator: Moderator<SolveIssueMeta> = (ctx) => {
   const last = ctx.steps[ctx.steps.length - 1];
 
   if (last.role === "preparer") {
-    return "planner";
+    return "developer";
   }
 
-  if (last.role === "planner") {
-    return "coder";
+  if (last.role === "developer") {
+    return "submitter";
   }
 
-  if (last.role === "coder") {
-    return nextAfterCoder(ctx, maxRounds);
-  }
-
-  if (last.role === "reviewer") {
-    if (last.meta.status === "approved") {
-      return "committer";
-    }
-    if (ctx.steps.length < maxRounds - 1) {
-      return "coder";
-    }
-    return END;
-  }
-
-  if (last.role === "committer") {
-    if (last.meta.status === "recoverable" && ctx.steps.length < maxRounds - 1) {
-      return "coder";
-    }
+  if (last.role === "submitter") {
     return END;
   }
 

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

@@ -1,19 +1,16 @@
 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 PreparerMeta, preparerRole } from "@uncaged/workflow-role-preparer";
-import { type ReviewerMeta, reviewerRole } from "@uncaged/workflow-role-reviewer";
+import { type SubmitterMeta, submitterRole } from "@uncaged/workflow-role-submitter";
+
+import { type DeveloperMeta, developerRole } from "./developer.js";
 
 export const SOLVE_ISSUE_WORKFLOW_DESCRIPTION =
-  "Prepare repo context, plan phases, implement incrementally, review, and commit to resolve an issue end-to-end (preparer → planner → coder [repeat per phase] → reviewer → committer).";
+  "Resolve an issue end-to-end by preparing the repo, delegating implementation to the develop workflow, and opening a pull request (preparer → developer → submitter).";
 
 export type SolveIssueMeta = {
   preparer: PreparerMeta;
-  planner: PlannerMeta;
-  coder: CoderMeta;
-  reviewer: ReviewerMeta;
-  committer: CommitterMeta;
+  developer: DeveloperMeta;
+  submitter: SubmitterMeta;
 };
 
 export type SolveIssueRoles = {
@@ -22,8 +19,6 @@ export type SolveIssueRoles = {
 
 export const solveIssueRoles: SolveIssueRoles = {
   preparer: preparerRole,
-  planner: plannerRole,
-  coder: coderRole,
-  reviewer: reviewerRole,
-  committer: committerRole,
+  developer: developerRole,
+  submitter: submitterRole,
 };

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

@@ -8,9 +8,7 @@
   "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-preparer" },
+    { "path": "../workflow-role-submitter" }
   ]
 }

tsconfig.json

@@ -22,11 +22,15 @@
     { "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" },
     { "path": "packages/cli-workflow" },
-    { "path": "packages/workflow-template-solve-issue" }
+    { "path": "packages/workflow-template-solve-issue" },
+    { "path": "packages/workflow-template-develop" }
   ]
 }