feat(cli): complete AGENTS.md generation (#36 Phase 3)

- Replace placeholder with comprehensive coding agent instructions
- Covers: project structure, core concepts, dev workflow, coding
  conventions, template reuse, build/test, common pitfalls
- Add test coverage for AGENTS.md sections and terms

Testing: #48

README.md

@@ -1,71 +0,0 @@
-# @uncaged/workflow
-
-A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32).
-
-## Core Concepts
-
-| Concept | Description |
-|---------|-------------|
-| **Workflow** | A single-file ESM module exporting `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash. |
-| **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
-| **Thread** | A single execution of a workflow, identified by a ULID. Persisted as `.data.jsonl` + `.info.jsonl`. |
-| **Role** | A named actor within a workflow. Each role produces output with typed `meta`. Roles live inside template packages (`src/roles/`). |
-| **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
-| **CAS** | Content-Addressed Storage — bundles are immutable and addressed by hash. |
-
-## Monorepo Packages
-
-```
-packages/
-  workflow/                      # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
-  cli-workflow/                  # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
-  workflow-template-develop/     # @uncaged/workflow-template-develop — develop workflow template (includes roles)
-  workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
-  workflow-agent-hermes/         # @uncaged/workflow-agent-hermes — Hermes agent adapter
-  workflow-agent-cursor/         # @uncaged/workflow-agent-cursor — Cursor agent adapter
-  workflow-agent-llm/            # @uncaged/workflow-agent-llm — LLM agent adapter
-  workflow-util-agent/           # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
-```
-
-Managed with **bun workspace** using the `workspace:*` protocol.
-
-## Quick Start
-
-```bash
-# Install dependencies
-bun install
-
-# Build all packages
-bun run build
-
-# Register a workflow bundle
-uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
-
-# Run a workflow
-uncaged-workflow run solve-issue --prompt "Fix bug #42"
-```
-
-## CLI Usage
-
-```bash
-uncaged-workflow help              # Show all commands
-uncaged-workflow workflow list     # List registered workflows
-uncaged-workflow run <name>        # Start a workflow thread
-uncaged-workflow thread list       # List all threads
-uncaged-workflow thread show <id>  # Inspect a thread
-uncaged-workflow skill             # Agent-consumable reference docs
-```
-
-See `uncaged-workflow help` for the full command reference.
-
-## Development
-
-```bash
-bun run check    # Biome lint + format check
-bun run format   # Auto-format with Biome
-bun test         # Run tests
-```
-
-## Architecture
-
-See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.

docs/architecture.md

@@ -17,8 +17,11 @@ A workflow engine that executes single-file ESM bundles. Each workflow is a self
 | `workflow-agent-cursor` | `@uncaged/workflow-agent-cursor` | Cursor CLI agent (extracts workspace from ctx) |
 | `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | Hermes CLI agent |
 | `workflow-agent-llm` | `@uncaged/workflow-agent-llm` | OpenAI-compatible LLM agent |
-| `workflow-template-develop` | `@uncaged/workflow-template-develop` | Develop workflow template (roles in `src/roles/`) |
-| `workflow-template-solve-issue` | `@uncaged/workflow-template-solve-issue` | Solve-issue workflow template (roles in `src/roles/`) |
+| `workflow-role-planner` | `@uncaged/workflow-role-planner` | Pure data: phased planning prompt + schema |
+| `workflow-role-coder` | `@uncaged/workflow-role-coder` | Pure data: coding prompt + schema |
+| `workflow-role-reviewer` | `@uncaged/workflow-role-reviewer` | Pure data: code review prompt + schema |
+| `workflow-role-committer` | `@uncaged/workflow-role-committer` | Pure data: git commit prompt + schema |
+| `workflow-template-solve-issue` | `@uncaged/workflow-template-solve-issue` | Composes roles + moderator into a complete workflow |
 | `workflow-util-agent` | `@uncaged/workflow-util-agent` | `buildAgentPrompt` + `spawnCli` utilities |
 
 Monorepo with **bun workspace**, `workspace:*` protocol.

packages/cli-workflow/__tests__/fixtures/live/logs/C9NMV6V2TQT81/01LIVECMPLT01DDDDDDDDDDDDG.data.jsonl

@@ -1,4 +0,0 @@
-{"name":"demo-live","hash":"C9NMV6V2TQT81","threadId":"01LIVECMPLT01DDDDDDDDDDDDG","parameters":{"prompt":"hello","options":{"maxRounds":5,"depth":0}},"timestamp":1714963400000}
-{"role":"planner","contentHash":"FF7YQ5W3S2EV6","meta":{"phase":"plan","flags":[1,2]},"refs":[],"timestamp":1714963201000}
-{"role":"coder","contentHash":"EN34XX1W4WAFJ","meta":{},"refs":[],"timestamp":1714963202000}
-{"returnCode":0,"summary":"fixture completed"}

packages/cli-workflow/__tests__/fixtures/live/logs/C9NMV6V2TQT81/01LIVECMPLT01DDDDDDDDDDDDG.info.jsonl

@@ -1,2 +0,0 @@
-{"tag":"DEBUGTAG1","content":"bundle loaded","timestamp":1714963400050}
-{"tag":"DEBUGTAG2","content":"multi\nline","timestamp":1714963400500}

packages/cli-workflow/__tests__/fixtures/live/logs/C9NMV6V2TQT81/01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl

@@ -1,2 +0,0 @@
-{"name":"demo-live","hash":"C9NMV6V2TQT81","threadId":"01LIVEINFLY01DDDDDDDDDDDDG","parameters":{"prompt":"hello","options":{"maxRounds":5,"depth":0}},"timestamp":1714963200000}
-{"role":"planner","contentHash":"P6M9FHE1GSBN0","meta":{"x":1},"refs":[],"timestamp":1714963201000}

packages/cli-workflow/__tests__/fixtures/live/logs/C9NMV6V2TQT81/01LIVEOLDER01DDDDDDDDDDDDG.data.jsonl

@@ -1,2 +0,0 @@
-{"name":"demo-live-old","hash":"C9NMV6V2TQT81","threadId":"01LIVEOLDER01DDDDDDDDDDDDG","parameters":{"prompt":"old","options":{"maxRounds":5,"depth":0}},"timestamp":1714963000000}
-{"returnCode":0,"summary":"older thread"}

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

@@ -111,7 +111,7 @@ describe("cli fork", () => {
     const sourceData = join(storageRoot, "logs", hash, `${sourceId}.data.jsonl`);
     const sourceRunning = join(storageRoot, "logs", hash, `${sourceId}.running`);
     await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilMinDataLines(sourceData, 4);
 
     const forked = await cmdFork(storageRoot, sourceId, "planner");
     expect(forked.ok).toBe(true);
@@ -122,22 +122,22 @@ describe("cli fork", () => {
     const newData = join(storageRoot, "logs", hash, `${newId}.data.jsonl`);
     const newRunning = join(storageRoot, "logs", hash, `${newId}.running`);
     await waitUntilRunningAbsent(newRunning);
-    await waitUntilMinDataLines(newData, 5);
+    await waitUntilMinDataLines(newData, 4);
 
     const text = await readFile(newData, "utf8");
     const lines = text
       .trim()
       .split("\n")
       .filter((l) => l !== "");
-    expect(lines.length).toBe(5);
+    expect(lines.length).toBe(4);
     const start = JSON.parse(lines[0] ?? "{}") as Record<string, unknown>;
     expect(start.threadId).toBe(newId);
     expect(start.forkFrom).toEqual({ threadId: sourceId });
 
-    const lastRoleLine = JSON.parse(lines[lines.length - 2] ?? "{}") as Record<string, unknown>;
-    expect(lastRoleLine.role).toBe("reviewer");
+    const last = JSON.parse(lines[lines.length - 1] ?? "{}") as Record<string, unknown>;
+    expect(last.role).toBe("reviewer");
     const cas = createCasStore(getGlobalCasDir(storageRoot));
-    expect(await getContentMerklePayload(cas, String(lastRoleLine.contentHash))).toBe("rev-1");
+    expect(await getContentMerklePayload(cas, String(last.contentHash))).toBe("rev-1");
   });
 
   test("fork without --from-role retries last role", async () => {
@@ -162,7 +162,7 @@ describe("cli fork", () => {
     const sourceData = join(storageRoot, "logs", hash, `${sourceId}.data.jsonl`);
     const sourceRunning = join(storageRoot, "logs", hash, `${sourceId}.running`);
     await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilMinDataLines(sourceData, 4);
 
     const forked = await cmdFork(storageRoot, sourceId, null);
     expect(forked.ok).toBe(true);
@@ -173,23 +173,23 @@ describe("cli fork", () => {
     const newData = join(storageRoot, "logs", hash, `${newId}.data.jsonl`);
     const newRunning = join(storageRoot, "logs", hash, `${newId}.running`);
     await waitUntilRunningAbsent(newRunning);
-    await waitUntilMinDataLines(newData, 5);
+    await waitUntilMinDataLines(newData, 4);
 
     const text = await readFile(newData, "utf8");
     const lines = text
       .trim()
       .split("\n")
       .filter((l) => l !== "");
-    expect(lines.length).toBe(5);
+    expect(lines.length).toBe(4);
 
     const replayCoder = JSON.parse(lines[2] ?? "{}") as Record<string, unknown>;
     expect(replayCoder.role).toBe("coder");
     const cas = createCasStore(getGlobalCasDir(storageRoot));
     expect(await getContentMerklePayload(cas, String(replayCoder.contentHash))).toBe("c1");
 
-    const lastRoleLine = JSON.parse(lines[lines.length - 2] ?? "{}") as Record<string, unknown>;
-    expect(lastRoleLine.role).toBe("reviewer");
-    expect(await getContentMerklePayload(cas, String(lastRoleLine.contentHash))).toBe("rev-2");
+    const last = JSON.parse(lines[lines.length - 1] ?? "{}") as Record<string, unknown>;
+    expect(last.role).toBe("reviewer");
+    expect(await getContentMerklePayload(cas, String(last.contentHash))).toBe("rev-2");
   });
 
   test("fork rejects unknown role with available names", async () => {
@@ -213,7 +213,7 @@ describe("cli fork", () => {
     const sourceData = join(storageRoot, "logs", added.value.hash, `${sourceId}.data.jsonl`);
     const sourceRunning = join(storageRoot, "logs", added.value.hash, `${sourceId}.running`);
     await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilMinDataLines(sourceData, 4);
 
     const bad = await cmdFork(storageRoot, sourceId, "ghost-role");
     expect(bad.ok).toBe(false);

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

@@ -129,10 +129,7 @@ describe("gc cli and garbageCollectCas", () => {
     });
 
     const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawnSync(process.execPath, [cliEntryPath, "cas", "gc"], {
-      env,
-      encoding: "utf8",
-    });
+    const proc = spawnSync(process.execPath, [cliEntryPath, "gc"], { env, encoding: "utf8" });
     expect(proc.status).toBe(0);
     expect(String(proc.stdout).trim()).toBe("scanned 1 threads, 2 active refs, deleted 1 entries");
   });

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

@@ -1,245 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { formatCliUsage, 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("# uncaged-workflow skill");
-    expect(idx).not.toContain("# uncaged-workflow help --skill");
-    expect(idx).toContain("cli");
-    expect(idx).toContain("develop");
-    expect(idx).toContain("author");
-    expect(idx).toContain("skill <topic>");
-  });
-});
-
-describe("formatCliUsage", () => {
-  test("has tagline, grouped sections, help hint, and env vars", () => {
-    const u = formatCliUsage();
-    expect(u.startsWith("uncaged-workflow — workflow engine CLI")).toBe(true);
-    expect(u).toContain("Workflow registry:");
-    expect(u).toContain("Thread execution:");
-    expect(u).toContain("Content-addressable storage:");
-    expect(u).toContain("Development:");
-    expect(u).toContain("Shortcuts:");
-    expect(u).toContain("Reference:");
-    expect(u).toContain("skill [topic]");
-    expect(u).toContain("Agent-consumable docs");
-    expect(u).toContain("Use <command> --help for subcommand details.");
-    expect(u).toContain("Environment variables:");
-    expect(u).toContain("WORKFLOW_STORAGE_ROOT");
-    expect(u).toContain("UNCAGED_WORKFLOW_STORAGE_ROOT");
-  });
-
-  test("lists commands from registry with descriptions", () => {
-    const u = formatCliUsage();
-    expect(u).toContain("workflow add");
-    expect(u).toContain("Register a workflow bundle in the registry");
-    expect(u).toContain("thread run");
-    expect(u).toContain("Start a new thread executing a workflow");
-    expect(u).toContain("cas gc");
-    expect(u).toContain("Garbage-collect unreferenced CAS entries");
-  });
-});
-
-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__/init-workspace.test.ts

@@ -129,9 +129,8 @@ describe("init workspace", () => {
 
   test("usage lists init subcommands", () => {
     const u = formatCliUsage();
-    expect(u).toContain("init workspace <name>");
-    expect(u).toContain("init template <name>");
-    expect(u).toContain("Development:");
+    expect(u).toContain("uncaged-workflow init workspace <name>");
+    expect(u).toContain("uncaged-workflow init template <name>");
   });
 
   test("runCli rejects unknown init subcommand", async () => {

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

@@ -1,369 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { spawn, spawnSync } from "node:child_process";
-import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { createCasStore, getGlobalCasDir, putContentMerkleNode } from "@uncaged/workflow";
-
-import {
-  formatLiveDebugLine,
-  formatLiveTimeLabel,
-  LIVE_CONTENT_MAX_LINES,
-  type LiveRoleRow,
-  renderLiveRoleStepLines,
-} from "../src/cmd-live.js";
-import { parseLiveArgv } from "../src/live-argv.js";
-
-const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
-const fixtureRoot = fileURLToPath(new URL("./fixtures/live", import.meta.url));
-
-/** Bodies for Merkle content nodes; hashes must match `.data.jsonl` fixtures. */
-const LIVE_FIXTURE_PLANNER_BODY =
-  "alpha\nbeta\ngamma\nLINE4\nLINE5\nLINE6\nLINE7\nLINE8\nLINE9\nLINE10\nLINE11";
-
-describe("live helpers", () => {
-  test("formatLiveTimeLabel pads HH:MM:SS", () => {
-    const label = formatLiveTimeLabel(new Date("2024-06-01T09:08:07.000Z").getTime());
-    expect(label).toMatch(/^\d{2}:\d{2}:\d{2}$/);
-  });
-
-  test("formatLiveDebugLine flattens newlines in message", () => {
-    const line = formatLiveDebugLine(0, "TAG1", "a\nb");
-    expect(line).toContain("[TAG1]");
-    expect(line).toContain("a b");
-    expect(line).not.toContain("\n");
-  });
-
-  test("renderLiveRoleStepLines truncates content to LIVE_CONTENT_MAX_LINES", () => {
-    const lines = Array.from({ length: LIVE_CONTENT_MAX_LINES + 3 }, (_, i) => `L${i + 1}`);
-    const row: LiveRoleRow = {
-      role: "r",
-      content: lines.join("\n"),
-      meta: { k: "v" },
-      timestamp: 0,
-    };
-    const out = renderLiveRoleStepLines(row, "r");
-    const body = out.filter((l) => l.startsWith("  L"));
-    expect(body.length).toBe(LIVE_CONTENT_MAX_LINES);
-    expect(out.some((l) => l.includes("more line"))).toBe(true);
-    expect(out.some((l) => l.startsWith("  meta: "))).toBe(true);
-  });
-});
-
-describe("parseLiveArgv", () => {
-  test("parses thread id and flags in any order", () => {
-    const a = parseLiveArgv(["01ABC", "--debug", "--role", "planner"]);
-    expect(a.ok).toBe(true);
-    if (a.ok) {
-      expect(a.value.threadId).toBe("01ABC");
-      expect(a.value.latest).toBe(false);
-      expect(a.value.debug).toBe(true);
-      expect(a.value.role).toBe("planner");
-    }
-    const b = parseLiveArgv(["--latest", "--role", "x"]);
-    expect(b.ok).toBe(true);
-    if (b.ok) {
-      expect(b.value.latest).toBe(true);
-      expect(b.value.threadId).toBe(null);
-      expect(b.value.role).toBe("x");
-    }
-  });
-
-  test("rejects --latest with thread id", () => {
-    const r = parseLiveArgv(["--latest", "01ABC"]);
-    expect(r.ok).toBe(false);
-  });
-});
-
-describe("live CLI", () => {
-  let prevEnv: string | undefined;
-  let storageRoot: string;
-
-  beforeEach(async () => {
-    prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-live-"));
-    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
-    await mkdir(join(storageRoot, "logs", "C9NMV6V2TQT81"), { recursive: true });
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.data.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.info.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.info.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVEOLDER01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVEOLDER01DDDDDDDDDDDDG.data.jsonl"),
-    );
-
-    const cas = createCasStore(getGlobalCasDir(storageRoot));
-    await putContentMerkleNode(cas, LIVE_FIXTURE_PLANNER_BODY);
-    await putContentMerkleNode(cas, "patch");
-    await putContentMerkleNode(cas, "still running");
-  });
-
-  afterEach(async () => {
-    if (prevEnv === undefined) {
-      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    } else {
-      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = prevEnv;
-    }
-    await rm(storageRoot, { recursive: true, force: true });
-  });
-
-  test("prints role steps and summary for a completed thread", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).toContain("coder");
-    expect(stdout).toContain("meta:");
-    expect(stdout).toContain('"phase":"plan"');
-    expect(stdout).toContain("LINE10");
-    expect(stdout).not.toContain("LINE11");
-    expect(stdout).toContain("more line");
-    expect(stdout).toContain("completed: returnCode=0");
-    expect(stdout).toContain("fixture completed");
-  });
-
-  test("--latest tails the newest thread by start timestamp", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "--latest"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("fixture completed");
-    expect(stdout).not.toContain("older thread");
-  });
-
-  test("--debug prints .info.jsonl records after data output", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG", "--debug"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("[DEBUGTAG1]");
-    expect(stdout).toContain("bundle loaded");
-    expect(stdout).toContain("[DEBUGTAG2]");
-    expect(stdout).toContain("multi line");
-  });
-
-  test("--role filters out non-matching roles", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG", "--role", "planner"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).not.toContain("patch");
-    expect(stdout).toContain("completed: returnCode=0");
-  });
-
-  test("--latest --debug --role combine", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "--latest", "--debug", "--role", "planner"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("[DEBUGTAG1]");
-    expect(stdout).toContain("planner");
-    expect(stdout).not.toContain("patch");
-    expect(stdout).toContain("fixture completed");
-  });
-
-  test("unknown thread id exits 1", () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const r = spawnSync(process.execPath, [cliEntryPath, "live", "01UNKNOWNXXXXXXXXXXXXXXXXX"], {
-      env,
-      encoding: "utf8",
-    });
-    expect(r.status).toBe(1);
-    expect(String(r.stderr ?? "")).toContain("thread not found");
-  });
-
-  test("follows file until WorkflowResult is appended", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const dataPath = join(
-      storageRoot,
-      "logs",
-      "C9NMV6V2TQT81",
-      "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl",
-    );
-
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "01LIVEINFLY01DDDDDDDDDDDDG"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    await new Promise((r) => setTimeout(r, 120));
-    const prior = await readFile(dataPath, "utf8");
-    await writeFile(
-      dataPath,
-      `${prior.replace(/\s*$/, "")}\n${JSON.stringify({ returnCode: 0, summary: "caught up" })}\n`,
-      "utf8",
-    );
-
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).toContain("completed: returnCode=0");
-    expect(stdout).toContain("caught up");
-  });
-});
-
-describe("live --latest with empty storage", () => {
-  let prevEnv: string | undefined;
-  let emptyRoot: string;
-
-  beforeEach(async () => {
-    prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    emptyRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-live-empty-"));
-    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = emptyRoot;
-  });
-
-  afterEach(async () => {
-    if (prevEnv === undefined) {
-      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
-    } else {
-      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = prevEnv;
-    }
-    await rm(emptyRoot, { recursive: true, force: true });
-  });
-
-  test("exits 1 when no threads exist", () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: emptyRoot };
-    const r = spawnSync(process.execPath, [cliEntryPath, "live", "--latest"], {
-      env,
-      encoding: "utf8",
-    });
-    expect(r.status).toBe(1);
-    expect(String(r.stderr ?? "")).toContain("no threads");
-  });
-});

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

@@ -1,54 +0,0 @@
-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/__tests__/thread-cli.test.ts

@@ -250,16 +250,13 @@ describe("cli thread commands", () => {
 
   test("cli entrypoint dispatches threads / ps (spawn)", () => {
     const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const threads = spawnSync(process.execPath, [cliEntryPath, "thread", "list"], {
+    const threads = spawnSync(process.execPath, [cliEntryPath, "threads"], {
       env,
       encoding: "utf8",
     });
     expect(threads.status).toBe(0);
 
-    const ps = spawnSync(process.execPath, [cliEntryPath, "thread", "ps"], {
-      env,
-      encoding: "utf8",
-    });
+    const ps = spawnSync(process.execPath, [cliEntryPath, "ps"], { env, encoding: "utf8" });
     expect(ps.status).toBe(0);
   });
 
@@ -326,7 +323,7 @@ describe("cli thread commands", () => {
       .trim()
       .split("\n")
       .filter((l) => l !== "");
-    expect(lines.length).toBe(3);
+    expect(lines.length).toBe(2);
 
     const runningPath = join(dirname(dataPath), `${threadId}.running`);
     expect(await pathExists(runningPath)).toBe(false);
@@ -365,8 +362,8 @@ describe("cli thread commands", () => {
     const resumed = await cmdResume(storageRoot, threadId);
     expect(resumed.ok).toBe(true);
 
-    await waitUntilMinDataLines(dataPath, 4, 120);
-    expect(await countDataJsonlLines(dataPath)).toBe(4);
+    await waitUntilMinDataLines(dataPath, 3, 120);
+    expect(await countDataJsonlLines(dataPath)).toBe(3);
 
     const runningPath = join(dirname(dataPath), `${threadId}.running`);
     await waitUntilRunningFileAbsent(runningPath, 100);

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

@@ -3,17 +3,10 @@ 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,
-  getSkillTopics,
-} from "./cmd-help.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 { cmdLive } from "./cmd-live.js";
 import { cmdPause } from "./cmd-pause.js";
 import { cmdPs } from "./cmd-ps.js";
 import { cmdRemove } from "./cmd-remove.js";
@@ -23,52 +16,66 @@ import { cmdRun } from "./cmd-run.js";
 import { cmdShow, formatShowYaml } from "./cmd-show.js";
 import { cmdThreadRemove, cmdThreadShow } from "./cmd-thread.js";
 import { cmdThreads } from "./cmd-threads.js";
-import { parseLiveArgv } from "./live-argv.js";
 import { parseRunArgv } from "./run-argv.js";
 
-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 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;
-  }
-  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;
+export function formatCliUsage(): string {
+  return [
+    "Usage:",
+    "  uncaged-workflow add <name> <file.esm.js> [--types <path>]",
+    "  uncaged-workflow list",
+    "  uncaged-workflow show <name>",
+    "  uncaged-workflow remove <name>",
+    "  uncaged-workflow run <name> [--prompt <text>] [--max-rounds N]",
+    "  uncaged-workflow ps",
+    "  uncaged-workflow kill <thread-id>",
+    "  uncaged-workflow history <name>",
+    "  uncaged-workflow rollback <name> [hash]",
+    "  uncaged-workflow pause <thread-id>",
+    "  uncaged-workflow resume <thread-id>",
+    "  uncaged-workflow threads [name]",
+    "  uncaged-workflow thread <id>",
+    "  uncaged-workflow thread rm <id>",
+    "  uncaged-workflow fork <thread-id> [--from-role <role>]",
+    "  uncaged-workflow gc",
+    "  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 init workspace <name>",
+    "  uncaged-workflow init template <name>",
+  ].join("\n");
 }
 
-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>`);
+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;
   }
-  const result = await cmdInitTemplate(process.cwd(), name);
-  if (!result.ok) {
-    printCliError(result.error);
-    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;
   }
-  printCliLine(`initialized template at ${result.value.templatePath}`);
-  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> {
@@ -183,15 +190,6 @@ async function dispatchKill(storageRoot: string, argv: string[]): Promise<number
   return 0;
 }
 
-async function dispatchLive(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseLiveArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
-    return 1;
-  }
-  return cmdLive(storageRoot, parsed.value);
-}
-
 async function dispatchHistory(storageRoot: string, argv: string[]): Promise<number> {
   const name = argv[0];
   if (name === undefined || argv.length > 1) {
@@ -255,7 +253,7 @@ async function dispatchResume(storageRoot: string, argv: string[]): Promise<numb
   return 0;
 }
 
-async function dispatchThreadList(storageRoot: string, argv: string[]): Promise<number> {
+async function dispatchThreads(storageRoot: string, argv: string[]): Promise<number> {
   const result = await cmdThreads(storageRoot, argv);
   if (!result.ok) {
     printCliError(result.error);
@@ -267,10 +265,10 @@ async function dispatchThreadList(storageRoot: string, argv: string[]): Promise<
   return 0;
 }
 
-async function dispatchThreadShow(storageRoot: string, argv: string[]): Promise<number> {
+async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
   const id = argv[0];
   if (id === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: thread show requires <id>`);
+    printCliError(`${formatCliUsage()}\n\nerror: thread requires <id>`);
     return 1;
   }
   const result = await cmdThreadShow(storageRoot, id);
@@ -297,6 +295,14 @@ async function dispatchThreadRm(storageRoot: string, argv: string[]): Promise<nu
   return 0;
 }
 
+async function dispatchThreadBranch(storageRoot: string, rest: string[]): Promise<number> {
+  const sub = rest[0];
+  if (sub === "rm") {
+    return dispatchThreadRm(storageRoot, rest.slice(1));
+  }
+  return dispatchThread(storageRoot, rest);
+}
+
 async function dispatchGc(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length > 0) {
     printCliError(`${formatCliUsage()}\n\nerror: gc takes no arguments`);
@@ -329,8 +335,6 @@ async function dispatchFork(storageRoot: string, argv: string[]): Promise<number
   return 0;
 }
 
-// ── CAS subcommand table ───────────────────────────────────────────────
-
 async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<number> {
   const threadId = rest[0];
   const hash = rest[1];
@@ -396,382 +400,67 @@ async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<numbe
   return 0;
 }
 
-// ── 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",
-  },
+const CAS_SUBCOMMAND_TABLE: Record<
+  string,
+  (storageRoot: string, rest: string[]) => Promise<number>
+> = {
+  get: dispatchCasGet,
+  put: dispatchCasPut,
+  list: dispatchCasList,
+  rm: dispatchCasRm,
 };
 
-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,
-      })),
-    },
-  ];
-}
-
-// ── Auto-generated CLI usage ───────────────────────────────────────────
-
-const USAGE_SECTION_BY_GROUP: Record<string, string> = {
-  workflow: "Workflow registry:",
-  thread: "Thread execution:",
-  cas: "Content-addressable storage:",
-  init: "Development:",
-};
-
-function formatUsageCommandLines(
-  rows: ReadonlyArray<{ prefix: string; description: string }>,
-): string[] {
-  const maxPrefix = rows.reduce((max, row) => Math.max(max, row.prefix.length), 0);
-  const gap = 2;
-  return rows.map((row) => {
-    const pad = " ".repeat(maxPrefix - row.prefix.length + gap);
-    return `  ${row.prefix}${pad}${row.description}`;
-  });
-}
-
-export function formatCliUsage(): string {
-  const groups = getCommandRegistry();
-  const lines: string[] = ["uncaged-workflow — workflow engine CLI", ""];
-
-  for (const group of groups) {
-    const sectionTitle = USAGE_SECTION_BY_GROUP[group.name];
-    if (sectionTitle === undefined) {
-      throw new Error(`BUG: missing usage section title for group "${group.name}"`);
-    }
-    lines.push(sectionTitle);
-    const rows = group.commands.map((cmd) => {
-      const args = cmd.args ? ` ${cmd.args}` : "";
-      return {
-        prefix: `${group.name} ${cmd.name}${args}`,
-        description: cmd.description,
-      };
-    });
-    lines.push(...formatUsageCommandLines(rows));
-    lines.push("");
-  }
-
-  lines.push("Shortcuts:");
-  lines.push(
-    ...formatUsageCommandLines([
-      { prefix: "run <name> [...]", description: "→ thread run" },
-      { prefix: "live <id> [...]", description: "→ thread live" },
-    ]),
-  );
-  lines.push("");
-
-  lines.push("Reference:");
-  const skillTopicNames = getSkillTopics()
-    .map((t) => t.name)
-    .join(", ");
-  lines.push(
-    ...formatUsageCommandLines([
-      {
-        prefix: "skill [topic]",
-        description: `Agent-consumable docs (${skillTopicNames})`,
-      },
-    ]),
-  );
-  lines.push("");
-  lines.push("Use <command> --help for subcommand details.");
-  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 === "remove") {
-    printDeprecation("workflow remove", "workflow rm");
-    return dispatchRemove(storageRoot, argv.slice(1));
-  }
-  printCliError(`${formatCliUsage()}\n\nerror: unknown workflow subcommand: ${sub}`);
-  return 1;
-}
-
-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];
-  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()}`);
+  if (sub === undefined) {
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: (none)`);
     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;
+  const handler = CAS_SUBCOMMAND_TABLE[sub];
+  if (handler === undefined) {
+    printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
+    return 1;
   }
-  printCliLine(formatCliUsage());
-  return 0;
+  return handler(storageRoot, argv.slice(1));
 }
 
-// ── Top-level command table (Phase 3) ──────────────────────────────────
+type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
 
 const COMMAND_TABLE: Record<string, DispatchFn> = {
-  // Grouped commands (primary)
-  workflow: dispatchWorkflow,
-  thread: dispatchThread,
-  cas: dispatchCas,
+  add: dispatchAdd,
   init: dispatchInit,
-  help: dispatchHelp,
-  skill: dispatchSkill,
-
-  // Top-level shortcuts (no deprecation)
+  list: dispatchList,
+  show: dispatchShow,
+  remove: dispatchRemove,
   run: dispatchRun,
-  live: dispatchLive,
-};
-
-// Deprecated flat commands that delegate to grouped commands
-const DEPRECATED_ALIASES: Record<string, { newCmd: string; handler: DispatchFn }> = {
-  add: { newCmd: "workflow add", handler: dispatchAdd },
-  list: { newCmd: "workflow list", handler: dispatchList },
-  show: { newCmd: "workflow show", handler: dispatchShow },
-  remove: { newCmd: "workflow rm", handler: dispatchRemove },
-  ps: { newCmd: "thread ps", handler: dispatchPs },
-  kill: { newCmd: "thread kill", handler: dispatchKill },
-  pause: { newCmd: "thread pause", handler: dispatchPause },
-  resume: { newCmd: "thread resume", handler: dispatchResume },
-  threads: { newCmd: "thread list", handler: dispatchThreadList },
-  fork: { newCmd: "thread fork", handler: dispatchFork },
-  gc: { newCmd: "cas gc", handler: dispatchGc },
-  history: { newCmd: "workflow history", handler: dispatchHistory },
-  rollback: { newCmd: "workflow rollback", handler: dispatchRollback },
+  ps: dispatchPs,
+  kill: dispatchKill,
+  history: dispatchHistory,
+  rollback: dispatchRollback,
+  pause: dispatchPause,
+  resume: dispatchResume,
+  threads: dispatchThreads,
+  thread: dispatchThreadBranch,
+  fork: dispatchFork,
+  gc: dispatchGc,
+  cas: dispatchCas,
 };
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {
   if (argv.length === 0) {
-    printCliLine(formatCliUsage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const command = argv[0];
   if (command === undefined) {
-    printCliLine(formatCliUsage());
+    printCliError(formatCliUsage());
     return 1;
   }
   const rest = argv.slice(1);
-
   const dispatch = COMMAND_TABLE[command];
-  if (dispatch !== undefined) {
-    return dispatch(storageRoot, rest);
+  if (dispatch === undefined) {
+    printCliError(`${formatCliUsage()}\n\nerror: unknown command ${command}`);
+    return 1;
   }
-
-  const deprecated = DEPRECATED_ALIASES[command];
-  if (deprecated !== undefined) {
-    printDeprecation(command, deprecated.newCmd);
-    return deprecated.handler(storageRoot, rest);
-  }
-
-  printCliError(`${formatCliUsage()}\n\nerror: unknown command ${command}`);
-  return 1;
+  return dispatch(storageRoot, rest);
 }

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

@@ -1,238 +0,0 @@
-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 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/cmd-live.ts

@@ -1,463 +0,0 @@
-import { watch } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import {
-  type CasStore,
-  createCasStore,
-  getContentMerklePayload,
-  getGlobalCasDir,
-  tryParseRoleStepRecord,
-  tryParseWorkflowResultRecord,
-  type WorkflowCompletion,
-} from "@uncaged/workflow";
-
-import { printCliError, printCliLine } from "./cli-output.js";
-import { pathExists } from "./fs-utils.js";
-import type { ParsedLiveArgv } from "./live-argv.js";
-import { findLatestThreadDataPath, resolveThreadDataPath } from "./thread-scan.js";
-
-export const LIVE_CONTENT_MAX_LINES = 10;
-
-export type LiveRoleRow = {
-  role: string;
-  content: string;
-  meta: Record<string, unknown>;
-  timestamp: number;
-};
-
-export function formatLiveTimeLabel(timestampMs: number): string {
-  const d = new Date(timestampMs);
-  const hh = String(d.getHours()).padStart(2, "0");
-  const mm = String(d.getMinutes()).padStart(2, "0");
-  const ss = String(d.getSeconds()).padStart(2, "0");
-  return `${hh}:${mm}:${ss}`;
-}
-
-function shouldUseColor(): boolean {
-  return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-}
-
-function highlightLiveRole(name: string): string {
-  if (!shouldUseColor()) {
-    return name;
-  }
-  return `\x1b[1m\x1b[36m${name}\x1b[0m`;
-}
-
-function dimGreyLine(line: string): string {
-  if (!shouldUseColor()) {
-    return line;
-  }
-  return `\x1b[2m\x1b[90m${line}\x1b[0m`;
-}
-
-export function formatLiveDebugLine(timestampMs: number, tag: string, message: string): string {
-  const label = `[${formatLiveTimeLabel(timestampMs)}] [${tag}] ${message.replace(/\n/g, " ")}`;
-  return dimGreyLine(label);
-}
-
-export function renderLiveRoleStepLines(row: LiveRoleRow, roleDisplay: string): string[] {
-  const header = `[${formatLiveTimeLabel(row.timestamp)}] ▶ ${roleDisplay}`;
-  const lines: string[] = [header];
-  const parts = row.content.split("\n");
-  const shown = parts.slice(0, LIVE_CONTENT_MAX_LINES);
-  for (const ln of shown) {
-    lines.push(`  ${ln}`);
-  }
-  const omitted = parts.length - shown.length;
-  if (omitted > 0) {
-    lines.push(`  … (${omitted} more line${omitted === 1 ? "" : "s"})`);
-  }
-  lines.push(`  meta: ${JSON.stringify(row.meta)}`);
-  return lines;
-}
-
-function printSummary(result: WorkflowCompletion): void {
-  printCliLine(`completed: returnCode=${result.returnCode} — ${result.summary}`);
-}
-
-type LiveSessionState = {
-  sawStart: boolean;
-  completed: boolean;
-  carry: string;
-  contentOffset: number;
-};
-
-type InfoLiveState = {
-  carry: string;
-  contentOffset: number;
-};
-
-function tryParseInfoRecord(obj: Record<string, unknown>): {
-  tag: string;
-  content: string;
-  timestamp: number;
-} | null {
-  const tag = obj.tag;
-  const content = obj.content;
-  const timestamp = obj.timestamp;
-  if (
-    typeof tag !== "string" ||
-    typeof content !== "string" ||
-    typeof timestamp !== "number" ||
-    !Number.isFinite(timestamp)
-  ) {
-    return null;
-  }
-  return { tag, content, timestamp };
-}
-
-async function handleJsonlLine(
-  rawLine: string,
-  state: LiveSessionState,
-  roleFilter: string | null,
-  cas: CasStore,
-): Promise<{ parseError: string | null; workflowResult: WorkflowCompletion | null }> {
-  const trimmed = rawLine.trim();
-  if (trimmed === "") {
-    return { parseError: null, workflowResult: null };
-  }
-
-  let rec: unknown;
-  try {
-    rec = JSON.parse(trimmed) as unknown;
-  } catch {
-    return { parseError: "invalid JSON in thread data file", workflowResult: null };
-  }
-  if (rec === null || typeof rec !== "object") {
-    return { parseError: "invalid record in thread data file", workflowResult: null };
-  }
-  const obj = rec as Record<string, unknown>;
-
-  if (!state.sawStart) {
-    state.sawStart = true;
-    return { parseError: null, workflowResult: null };
-  }
-
-  const wf = tryParseWorkflowResultRecord(obj);
-  if (wf !== null) {
-    state.completed = true;
-    return { parseError: null, workflowResult: wf };
-  }
-
-  const roleRow = tryParseRoleStepRecord(obj);
-  if (roleRow === null) {
-    return {
-      parseError: "unrecognized record in thread data (expected role step or result)",
-      workflowResult: null,
-    };
-  }
-
-  if (roleFilter !== null && roleRow.role !== roleFilter) {
-    return { parseError: null, workflowResult: null };
-  }
-
-  const payload = await getContentMerklePayload(cas, roleRow.contentHash);
-  const content =
-    payload !== null ? payload : `(content not in CAS; contentHash=${roleRow.contentHash})`;
-
-  const row: LiveRoleRow = {
-    role: roleRow.role,
-    content,
-    meta: roleRow.meta,
-    timestamp: roleRow.timestamp,
-  };
-  for (const outLine of renderLiveRoleStepLines(row, highlightLiveRole(row.role))) {
-    printCliLine(outLine);
-  }
-  return { parseError: null, workflowResult: null };
-}
-
-async function pumpNewContent(
-  dataPath: string,
-  state: LiveSessionState,
-  roleFilter: string | null,
-  cas: CasStore,
-): Promise<number | null> {
-  let text: string;
-  try {
-    text = await readFile(dataPath, "utf8");
-  } catch {
-    return null;
-  }
-
-  if (text.length < state.contentOffset) {
-    state.contentOffset = 0;
-    state.carry = "";
-  }
-
-  const chunk = text.slice(state.contentOffset);
-  state.contentOffset = text.length;
-  state.carry += chunk;
-
-  const parts = state.carry.split("\n");
-  state.carry = parts.pop() ?? "";
-
-  for (const line of parts) {
-    const { parseError, workflowResult } = await handleJsonlLine(line, state, roleFilter, cas);
-    if (parseError !== null) {
-      printCliError(parseError);
-      return 1;
-    }
-    if (workflowResult !== null) {
-      printSummary(workflowResult);
-      return 0;
-    }
-  }
-
-  return null;
-}
-
-async function pumpNewInfoContent(infoPath: string, state: InfoLiveState): Promise<void> {
-  let text: string;
-  try {
-    text = await readFile(infoPath, "utf8");
-  } catch {
-    return;
-  }
-
-  if (text.length < state.contentOffset) {
-    state.contentOffset = 0;
-    state.carry = "";
-  }
-
-  const chunk = text.slice(state.contentOffset);
-  state.contentOffset = text.length;
-  state.carry += chunk;
-
-  const parts = state.carry.split("\n");
-  state.carry = parts.pop() ?? "";
-
-  for (const line of parts) {
-    const trimmed = line.trim();
-    if (trimmed === "") {
-      continue;
-    }
-    let rec: unknown;
-    try {
-      rec = JSON.parse(trimmed) as unknown;
-    } catch {
-      continue;
-    }
-    if (rec === null || typeof rec !== "object") {
-      continue;
-    }
-    const parsed = tryParseInfoRecord(rec as Record<string, unknown>);
-    if (parsed === null) {
-      continue;
-    }
-    printCliLine(formatLiveDebugLine(parsed.timestamp, parsed.tag, parsed.content));
-  }
-}
-
-type WatchPumpTask = {
-  path: string;
-  pump: () => Promise<number | null>;
-};
-
-async function runWatchPumpStep(
-  settled: () => boolean,
-  pump: () => Promise<number | null>,
-  closeAll: () => void,
-  finish: (code: number) => void,
-): Promise<void> {
-  if (settled()) {
-    return;
-  }
-  try {
-    const code = await pump();
-    if (code !== null) {
-      closeAll();
-      finish(code);
-    }
-  } catch (e) {
-    closeAll();
-    throw e instanceof Error ? e : new Error(String(e));
-  }
-}
-
-function watchLivePaths(params: { tasks: WatchPumpTask[]; signal: AbortSignal }): Promise<number> {
-  const { tasks, signal } = params;
-
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const finish = (code: number): void => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      resolve(code);
-    };
-
-    const pumpChains = new Map<string, Promise<void>>();
-    for (const t of tasks) {
-      pumpChains.set(t.path, Promise.resolve());
-    }
-
-    const watchers: ReturnType<typeof watch>[] = [];
-
-    const closeAll = (): void => {
-      for (const w of watchers) {
-        w.close();
-      }
-    };
-
-    function schedulePump(path: string, pump: () => Promise<number | null>): void {
-      const prev = pumpChains.get(path) ?? Promise.resolve();
-      const next = (async () => {
-        await prev;
-        await runWatchPumpStep(() => settled, pump, closeAll, finish);
-      })();
-      pumpChains.set(path, next);
-    }
-
-    for (const { path, pump } of tasks) {
-      const watcher = watch(path, (eventType) => {
-        if (eventType === "rename") {
-          return;
-        }
-        schedulePump(path, pump);
-      });
-      watchers.push(watcher);
-      watcher.on("error", (err: Error) => {
-        closeAll();
-        reject(err);
-      });
-    }
-
-    const onAbort = (): void => {
-      closeAll();
-      finish(0);
-    };
-    signal.addEventListener("abort", onAbort, { once: true });
-
-    for (const { path, pump } of tasks) {
-      schedulePump(path, pump);
-    }
-  });
-}
-
-type LiveThreadTarget = {
-  threadId: string;
-  dataPath: string;
-};
-
-async function resolveLiveThreadTarget(
-  storageRoot: string,
-  parsed: ParsedLiveArgv,
-): Promise<LiveThreadTarget | null> {
-  if (parsed.latest) {
-    const found = await findLatestThreadDataPath(storageRoot);
-    if (found === null) {
-      printCliError("live: no threads found");
-      return null;
-    }
-    return found;
-  }
-
-  const id = parsed.threadId;
-  if (id === null) {
-    printCliError("live: internal error: missing thread id");
-    return null;
-  }
-  const resolved = await resolveThreadDataPath(storageRoot, id);
-  if (resolved === null) {
-    printCliError(`thread not found: ${id}`);
-    return null;
-  }
-  return { threadId: id, dataPath: resolved };
-}
-
-async function buildLiveWatchTasks(params: {
-  dataPath: string;
-  infoPath: string;
-  debug: boolean;
-  dataState: LiveSessionState;
-  infoState: InfoLiveState;
-  roleFilter: string | null;
-  cas: CasStore;
-}): Promise<WatchPumpTask[]> {
-  const { dataPath, infoPath, debug, dataState, infoState, roleFilter, cas } = params;
-  const tasks: WatchPumpTask[] = [
-    {
-      path: dataPath,
-      pump: () => pumpNewContent(dataPath, dataState, roleFilter, cas),
-    },
-  ];
-
-  if (debug && (await pathExists(infoPath))) {
-    tasks.push({
-      path: infoPath,
-      pump: async () => {
-        await pumpNewInfoContent(infoPath, infoState);
-        return null;
-      },
-    });
-  }
-
-  return tasks;
-}
-
-export async function cmdLive(storageRoot: string, parsed: ParsedLiveArgv): Promise<number> {
-  const target = await resolveLiveThreadTarget(storageRoot, parsed);
-  if (target === null) {
-    return 1;
-  }
-
-  const { threadId, dataPath } = target;
-  const roleFilter = parsed.role;
-  const infoPath = join(dirname(dataPath), `${threadId}.info.jsonl`);
-  const cas = createCasStore(getGlobalCasDir(storageRoot));
-
-  const dataState: LiveSessionState = {
-    sawStart: false,
-    completed: false,
-    carry: "",
-    contentOffset: 0,
-  };
-
-  const infoState: InfoLiveState = {
-    carry: "",
-    contentOffset: 0,
-  };
-
-  const controller = new AbortController();
-  const onSigInt = (): void => {
-    controller.abort();
-  };
-  process.on("SIGINT", onSigInt);
-
-  try {
-    const firstData = await pumpNewContent(dataPath, dataState, roleFilter, cas);
-    if (firstData === 1) {
-      return 1;
-    }
-
-    if (parsed.debug && (await pathExists(infoPath))) {
-      await pumpNewInfoContent(infoPath, infoState);
-    }
-
-    if (firstData === 0 || dataState.completed) {
-      return 0;
-    }
-
-    const tasks = await buildLiveWatchTasks({
-      dataPath,
-      infoPath,
-      debug: parsed.debug,
-      dataState,
-      infoState,
-      roleFilter,
-      cas,
-    });
-
-    return await watchLivePaths({ tasks, signal: controller.signal });
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    printCliError(`live: ${message}`);
-    return 1;
-  } finally {
-    process.off("SIGINT", onSigInt);
-  }
-}

packages/cli-workflow/src/live-argv.ts

@@ -1,75 +0,0 @@
-import { err, ok, type Result } from "@uncaged/workflow";
-
-export type ParsedLiveArgv = {
-  threadId: string | null;
-  latest: boolean;
-  debug: boolean;
-  role: string | null;
-};
-
-type LiveArgvScan = {
-  latest: boolean;
-  debug: boolean;
-  role: string | null;
-  threadId: string | null;
-};
-
-function applyLiveArgvToken(argv: string[], i: number, s: LiveArgvScan): Result<number, string> {
-  const a = argv[i];
-  if (a === "--latest") {
-    s.latest = true;
-    return ok(i + 1);
-  }
-  if (a === "--debug") {
-    s.debug = true;
-    return ok(i + 1);
-  }
-  if (a === "--role") {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) {
-      return err("missing value for --role");
-    }
-    s.role = v;
-    return ok(i + 2);
-  }
-  if (a.startsWith("--")) {
-    return err(`unknown live flag: ${a}`);
-  }
-  if (s.threadId !== null) {
-    return err("unexpected extra argument");
-  }
-  s.threadId = a;
-  return ok(i + 1);
-}
-
-export function parseLiveArgv(argv: string[]): Result<ParsedLiveArgv, string> {
-  const s: LiveArgvScan = {
-    latest: false,
-    debug: false,
-    role: null,
-    threadId: null,
-  };
-
-  let i = 0;
-  while (i < argv.length) {
-    const step = applyLiveArgvToken(argv, i, s);
-    if (!step.ok) {
-      return step;
-    }
-    i = step.value;
-  }
-
-  if (s.latest && s.threadId !== null) {
-    return err("live --latest does not take <thread-id>");
-  }
-  if (!s.latest && s.threadId === null) {
-    return err("live requires <thread-id> or --latest");
-  }
-
-  return ok({
-    threadId: s.threadId,
-    latest: s.latest,
-    debug: s.debug,
-    role: s.role,
-  });
-}

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

@@ -1,21 +1,10 @@
 import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
 
-/**
- * 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`)
- */
+/** Resolve storage root, honoring `UNCAGED_WORKFLOW_STORAGE_ROOT` for tests/tools. */
 export function resolveWorkflowStorageRoot(): string {
-  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;
+  const override = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (override !== undefined && override !== "") {
+    return override;
   }
   return getDefaultWorkflowStorageRoot();
 }

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

@@ -1,4 +1,4 @@
-import { readdir, stat } from "node:fs/promises";
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 
 import { pathExists, readTextFileIfExists } from "./fs-utils.js";
@@ -15,28 +15,6 @@ export type HistoricalThreadRow = {
   workflowName: string | null;
 };
 
-async function readThreadStartTimestampMs(dataPath: string): Promise<number | null> {
-  const text = await readTextFileIfExists(dataPath);
-  if (text === null) {
-    return null;
-  }
-  const firstLine = text.split("\n")[0];
-  if (firstLine === undefined || firstLine.trim() === "") {
-    return null;
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(firstLine) as unknown;
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return null;
-  }
-  const ts = (parsed as Record<string, unknown>).timestamp;
-  return typeof ts === "number" && Number.isFinite(ts) ? ts : null;
-}
-
 async function readWorkflowNameFromDataJsonl(dataPath: string): Promise<string | null> {
   const text = await readTextFileIfExists(dataPath);
   if (text === null) {
@@ -146,50 +124,6 @@ export async function listHistoricalThreads(
   return out;
 }
 
-/**
- * Picks the thread whose `.data.jsonl` is newest by start-record `timestamp`,
- * falling back to file `mtime` when the timestamp is missing.
- * Tie-breaker: larger `mtime` wins when start timestamps are equal.
- */
-export async function findLatestThreadDataPath(
-  storageRoot: string,
-): Promise<{ threadId: string; dataPath: string } | null> {
-  const threads = await listHistoricalThreads(storageRoot, null);
-  if (threads.length === 0) {
-    return null;
-  }
-
-  let best: {
-    threadId: string;
-    dataPath: string;
-    primary: number;
-    secondary: number;
-  } | null = null;
-
-  for (const t of threads) {
-    const dataPath = join(storageRoot, "logs", t.hash, `${t.threadId}.data.jsonl`);
-    let mtimeMs = 0;
-    try {
-      const st = await stat(dataPath);
-      mtimeMs = st.mtimeMs;
-    } catch {
-      continue;
-    }
-    const startTs = await readThreadStartTimestampMs(dataPath);
-    const primary = startTs !== null ? startTs : mtimeMs;
-    const secondary = mtimeMs;
-    if (
-      best === null ||
-      primary > best.primary ||
-      (primary === best.primary && secondary > best.secondary)
-    ) {
-      best = { threadId: t.threadId, dataPath, primary, secondary };
-    }
-  }
-
-  return best === null ? null : { threadId: best.threadId, dataPath: best.dataPath };
-}
-
 export async function resolveThreadDataPath(
   storageRoot: string,
   threadId: string,

packages/workflow-role-coder/package.json

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

@@ -11,13 +11,21 @@ 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.
 
-Run \`uncaged-workflow skill develop\` for thread ID lookup, CAS commands, and meta output guide.
+## 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.
 
 ## Reading phase details
 
-Each planner phase has a content-hash and title. Read full details with \`uncaged-workflow cas get <THREAD_ID> <HASH>\`.
+Each planner phase is identified by a content-hash and a title. To read a phase's full details (name, description, acceptance criteria), run:
 
-The thread ID (26-char Crockford Base32) appears in the first message. If unsure, run \`uncaged-workflow thread list\`.
+  uncaged-workflow cas get <THREAD_ID> <HASH>
+
+Replace \`<THREAD_ID>\` with the actual thread ID and \`<HASH>\` with the phase hash from the plan.
 
 ## Completing a phase
 

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

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

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

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

packages/workflow-role-committer/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@uncaged/workflow-template-develop",
+  "name": "@uncaged/workflow-role-committer",
   "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",

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 and commit the changes.
+const COMMITTER_SYSTEM = `You are the git committer. Create a branch, commit the changes, and push.
 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 a branch and commits changes.",
+  description: "Creates branch, commits, and pushes when review passes.",
   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-committer/src/index.ts

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

packages/workflow-role-committer/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-planner/package.json

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

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

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

@@ -14,25 +14,27 @@ 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.
 
-Run \`uncaged-workflow skill develop\` for thread ID lookup, CAS commands, and meta output guide.
+## 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.
 
 ## Storing phase details — MANDATORY
 
-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.
+For each phase you MUST store its full detail text in CAS using this exact CLI command:
 
-The thread ID (26-char Crockford Base32) appears in the first message. If unsure, run \`uncaged-workflow thread list\`.
+  uncaged-workflow cas put <THREAD_ID> '# <name>
 
-**Do NOT store phase details in any other way** — the CLI is the only supported storage mechanism.
+Description: <description>
 
-## Phase granularity
+Acceptance: <acceptance>'
 
-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
+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.
 
-Fewer phases is always better. Each phase must justify its existence — if two phases would be tested together anyway, merge them.
+**Do NOT store phase details in any other way** (no temp files, no invented paths). The CLI command is the only supported storage mechanism.
 
 ## Output format
 

packages/workflow-role-planner/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-preparer/package.json

@@ -0,0 +1,15 @@
+{
+  "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/src/index.ts

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

packages/workflow-role-preparer/tsconfig.json

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

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

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

packages/workflow-role-reviewer/package.json

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

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

packages/workflow-role-reviewer/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

@@ -1,257 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  END,
-  type ModeratorContext,
-  type RoleStep,
-  START,
-  validateWorkflowDescriptor,
-} from "@uncaged/workflow";
-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"] = [
-  {
-    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/src/descriptor.ts

@@ -1,12 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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 { buildDevelopDescriptor } from "./descriptor.js";
-export { developModerator } from "./moderator.js";
-export {
-  type CoderMeta,
-  type CommitterMeta,
-  coderMetaSchema,
-  coderRole,
-  committerMetaSchema,
-  committerRole,
-  type PlannerMeta,
-  phaseSchema,
-  plannerMetaSchema,
-  plannerRole,
-  type ReviewerMeta,
-  reviewerMetaSchema,
-  reviewerRole,
-  type TesterMeta,
-  testerMetaSchema,
-  testerRole,
-} from "./roles/index.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

@@ -1,89 +0,0 @@
-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

@@ -1,29 +0,0 @@
-import type { RoleDefinition } from "@uncaged/workflow";
-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).";
-
-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/src/roles/index.ts

@@ -1,10 +0,0 @@
-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/tester.ts

@@ -1,27 +0,0 @@
-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-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -11,69 +11,42 @@ import {
   START,
   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 { 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 {
-  return new Response(JSON.stringify(payload), {
-    status: 200,
-    headers: { "Content-Type": "application/json" },
-  });
-}
+const DEFAULT_PHASES: PlannerMeta["phases"] = [
+  {
+    hash: "4KNMR2PX",
+    title: "Do the work",
+  },
+];
 
-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_PLANNER_META: PlannerMeta = {
+  phases: [
+    {
+      hash: "7BQST3VW",
+      title: "placeholder phase",
+    },
+  ],
+};
 
-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) } }],
-  });
-}
+const EXPECT_CODER_META: CoderMeta = {
+  completedPhase: "7BQST3VW",
+  filesChanged: [],
+  summary: "",
+};
 
 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];
@@ -81,11 +54,36 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
       throw new Error("installMockChatCompletions: empty sequence");
     }
     i += 1;
-    const tools = readToolListFromBody(init);
-    if (tools.length > 1) {
-      return buildReactModeResponse(args);
-    }
-    return buildSingleModeResponse(args, singleToolName(tools));
+    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" } },
+    );
   };
   globalThis.fetch = Object.assign(mockFetch, {
     preconnect: origFetch.preconnect.bind(origFetch),
@@ -136,86 +134,152 @@ function preparerStep(): RoleStep<SolveIssueMeta> {
   };
 }
 
-function developerStep(): RoleStep<SolveIssueMeta> {
+function plannerStep(phases: PlannerMeta["phases"] = DEFAULT_PHASES): RoleStep<SolveIssueMeta> {
   return {
-    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: [],
+    role: "planner",
+    contentHash: "STUBHASHPLANNER001",
+    meta: { phases },
+    refs: phases.map((p) => p.hash),
     timestamp: 1,
   };
 }
 
-function submitterStep(meta: SubmitterMeta): RoleStep<SolveIssueMeta> {
+function coderStep(completedPhase = "4KNMR2PX"): RoleStep<SolveIssueMeta> {
   return {
-    role: "submitter",
-    contentHash: "STUBHASHSUBMITTER1",
-    meta,
-    refs: [],
+    role: "coder",
+    contentHash: "STUBHASHCODER00001",
+    meta: { completedPhase, filesChanged: ["a.ts"], summary: "fixed" },
+    refs: [completedPhase],
     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 initial → preparer → developer → submitter → END", () => {
+  test("routes preparer → planner → coder → reviewer → committer → END", () => {
     expect(solveIssueModerator(makeCtx(20, []))).toBe("preparer");
-    expect(solveIssueModerator(makeCtx(20, [preparerStep()]))).toBe("developer");
-    expect(solveIssueModerator(makeCtx(20, [preparerStep(), developerStep()]))).toBe("submitter");
+    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(),
-          developerStep(),
-          submitterStep({
-            status: "submitted",
-            prUrl: "https://github.com/example/repo/pull/1",
-          }),
+          plannerStep(),
+          coderStep(),
+          reviewerStep(true),
+          committerStep(),
         ]),
       ),
     ).toBe(END);
   });
 
-  test("submitter failed → END", () => {
-    expect(
-      solveIssueModerator(
-        makeCtx(20, [
-          preparerStep(),
-          developerStep(),
-          submitterStep({ status: "failed", error: "gh not authenticated" }),
-        ]),
-      ),
-    ).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("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.
+  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",
+    );
     expect(
       solveIssueModerator(
-        makeCtx(20, [
-          preparerStep(),
-          developerStep(),
-          submitterStep({ status: "submitted", prUrl: "https://example.com/pr/1" }),
-        ]),
+        makeCtx(20, [plannerStep(phases), coderStep("AA000001"), coderStep("AA000002")]),
       ),
-    ).toBe(END);
+    ).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: "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);
   });
 });
 
@@ -232,7 +296,7 @@ describe("createSolveIssueRun", () => {
     }
   });
 
-  test("structured extraction yields preparer meta from mocked chat completions", async () => {
+  test("structured extraction yields preparer then planner meta from mocked chat completions", async () => {
     const EXPECT_PREPARER_META: PreparerMeta = {
       repoPath: "/home/user/repos/test",
       defaultBranch: "main",
@@ -244,20 +308,12 @@ describe("createSolveIssueRun", () => {
         buildCommand: "bun run build",
       },
     };
-    restoreFetch = installMockChatCompletions([EXPECT_PREPARER_META]);
+    restoreFetch = installMockChatCompletions([EXPECT_PREPARER_META, EXPECT_PLANNER_META]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
 
-    // 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 run = createSolveIssueRun({ agent: async () => "" }, stubExtract, null);
     const gen = run(
       { prompt: "task", steps: [] },
       { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
@@ -269,6 +325,14 @@ 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 () => {
@@ -278,17 +342,11 @@ describe("createSolveIssueRun", () => {
       conventions: null,
       toolchain: { packageManager: null, testCommand: null, lintCommand: null, buildCommand: null },
     };
-    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]);
+    restoreFetch = installMockChatCompletions([
+      PREPARER_META,
+      EXPECT_PLANNER_META,
+      EXPECT_CODER_META,
+    ]);
 
     casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
     const cas = createCasStore(casDir);
@@ -305,18 +363,18 @@ describe("createSolveIssueRun", () => {
             calls.push("preparer");
             return "";
           },
-          developer: async () => {
-            calls.push("developer");
-            return "stub-root-hash";
+          planner: async () => {
+            calls.push("planner");
+            return "";
           },
-          submitter: async () => {
-            calls.push("submitter");
+          coder: async () => {
+            calls.push("coder");
             return "";
           },
         },
       },
       stubExtract,
-      stubLlmProvider,
+      null,
     );
     const gen = run(
       { prompt: "task", steps: [] },
@@ -327,65 +385,16 @@ describe("createSolveIssueRun", () => {
 
     calls.length = 0;
     await gen.next();
-    expect(calls).toEqual(["developer"]);
+    expect(calls).toEqual(["planner"]);
 
     calls.length = 0;
     await gen.next();
-    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);
+    expect(calls).toEqual(["coder"]);
   });
 });
 
 describe("buildSolveIssueDescriptor", () => {
-  test("lists preparer, developer, submitter with schemas that validate", () => {
+  test("lists all roles with schemas that validate", () => {
     const descriptor = buildSolveIssueDescriptor();
     const validated = validateWorkflowDescriptor(descriptor);
     expect(validated.ok).toBe(true);
@@ -393,11 +402,13 @@ describe("buildSolveIssueDescriptor", () => {
       throw new Error(validated.error);
     }
     expect(Object.keys(validated.value.roles).sort()).toEqual([
-      "developer",
+      "coder",
+      "committer",
+      "planner",
       "preparer",
-      "submitter",
+      "reviewer",
     ]);
-    for (const key of ["preparer", "developer", "submitter"] as const) {
+    for (const key of ["preparer", "planner", "coder", "reviewer", "committer"] as const) {
       const role = validated.value.roles[key];
       expect(role).toBeDefined();
       expect(typeof role.schema).toBe("object");

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

@@ -1,39 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import { submitterMetaSchema, submitterRole } from "../src/roles/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-template-solve-issue/package.json

@@ -10,6 +10,10 @@
   },
   "dependencies": {
     "@uncaged/workflow": "workspace:*",
-    "zod": "^4.0.0"
+    "@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:*"
   }
 }

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

@@ -1,37 +0,0 @@
-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,27 +5,39 @@ 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 { buildSolveIssueDescriptor } from "./descriptor.js";
 export {
-  type DeveloperMeta,
-  developerMetaSchema,
-  developerRole,
-} from "./developer.js";
-export { solveIssueModerator } from "./moderator.js";
+  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,
-  type SubmitterMeta,
-  submitterMetaSchema,
-  submitterRole,
-} from "./roles/index.js";
+} from "@uncaged/workflow-role-preparer";
+export {
+  type ReviewerMeta,
+  reviewerMetaSchema,
+  reviewerRole,
+} from "@uncaged/workflow-role-reviewer";
+export { buildSolveIssueDescriptor } from "./descriptor.js";
+export { solveIssueModerator } from "./moderator.js";
 export {
   SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
   type SolveIssueMeta,
@@ -39,25 +51,10 @@ 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 {
-  const developerOverride = binding.overrides?.developer ?? workflowAsAgent("develop");
-  const mergedBinding: AgentBinding = {
-    agent: binding.agent,
-    overrides: {
-      ...(binding.overrides ?? {}),
-      developer: developerOverride,
-    },
-  };
-  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding, extract, llmProvider);
+  return createWorkflow(solveIssueWorkflowDefinition, binding, extract, llmProvider);
 }

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

@@ -1,9 +1,52 @@
-import type { Moderator } from "@uncaged/workflow";
+import type { Moderator, ModeratorContext } 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";
   }
@@ -11,14 +54,31 @@ export const solveIssueModerator: Moderator<SolveIssueMeta> = (ctx) => {
   const last = ctx.steps[ctx.steps.length - 1];
 
   if (last.role === "preparer") {
-    return "developer";
+    return "planner";
   }
 
-  if (last.role === "developer") {
-    return "submitter";
+  if (last.role === "planner") {
+    return "coder";
   }
 
-  if (last.role === "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";
+    }
     return END;
   }
 

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

@@ -1,15 +1,19 @@
 import type { RoleDefinition } from "@uncaged/workflow";
-import { type DeveloperMeta, developerRole } from "./developer.js";
-import { type PreparerMeta, preparerRole } from "./roles/preparer.js";
-import { type SubmitterMeta, submitterRole } from "./roles/submitter.js";
+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";
 
 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).";
+  "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).";
 
 export type SolveIssueMeta = {
   preparer: PreparerMeta;
-  developer: DeveloperMeta;
-  submitter: SubmitterMeta;
+  planner: PlannerMeta;
+  coder: CoderMeta;
+  reviewer: ReviewerMeta;
+  committer: CommitterMeta;
 };
 
 export type SolveIssueRoles = {
@@ -18,6 +22,8 @@ export type SolveIssueRoles = {
 
 export const solveIssueRoles: SolveIssueRoles = {
   preparer: preparerRole,
-  developer: developerRole,
-  submitter: submitterRole,
+  planner: plannerRole,
+  coder: coderRole,
+  reviewer: reviewerRole,
+  committer: committerRole,
 };

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

@@ -1,44 +0,0 @@
-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-template-solve-issue/tsconfig.json

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

packages/workflow/__tests__/fork-thread.test.ts

@@ -87,26 +87,6 @@ describe("fork-thread", () => {
     expect(r.value.runOptions).toEqual({ maxRounds: 5, depth: 0 });
   });
 
-  test("parseThreadDataJsonl ignores trailing WorkflowResult line", () => {
-    const text = `${sampleDataJsonl.trim()}\n{"returnCode":0,"summary":"done"}\n`;
-    const r = parseThreadDataJsonl(text);
-    expect(r.ok).toBe(true);
-    if (!r.ok) {
-      return;
-    }
-    expect(r.value.roleSteps.length).toBe(3);
-    expect(r.value.roleSteps[2]?.role).toBe("reviewer");
-  });
-
-  test("parseThreadDataJsonl errors when WorkflowResult is not last", () => {
-    const text = `{"name":"demo","hash":"H","threadId":"01ZZZZZZZZZZZZZZZZZZZZZZ","parameters":{"prompt":"p","options":{"maxRounds":3}},"timestamp":1}
-{"returnCode":0,"summary":"early"}
-{"role":"planner","content":"x","meta":{},"timestamp":2}
-`;
-    const r = parseThreadDataJsonl(text);
-    expect(r.ok).toBe(false);
-  });
-
   test("parseThreadDataJsonl reads explicit depth from start record", () => {
     const text = `{"name":"demo","hash":"H","threadId":"01ZZZZZZZZZZZZZZZZZZZZZZ","parameters":{"prompt":"p","options":{"maxRounds":3,"depth":2}},"timestamp":1}
 {"role":"planner","contentHash":"HP0000000000000000000099","meta":{},"refs":[],"timestamp":2}

packages/workflow/__tests__/worker.test.ts

@@ -125,7 +125,7 @@ describe("worker process", () => {
           .trim()
           .split("\n")
           .filter((l) => l !== "").length,
-      ).toBe(4);
+      ).toBe(3);
     } finally {
       await rm(root, { recursive: true, force: true });
     }
@@ -187,7 +187,7 @@ describe("worker process", () => {
         .trim()
         .split("\n")
         .filter((l) => l !== "");
-      expect(lines.length).toBe(4);
+      expect(lines.length).toBe(3);
       const start = JSON.parse(lines[0] ?? "{}") as Record<string, unknown>;
       expect(start.forkFrom).toEqual({ threadId: srcId });
       const replay = JSON.parse(lines[1] ?? "{}") as Record<string, unknown>;
@@ -195,8 +195,6 @@ describe("worker process", () => {
       expect(replay.timestamp).toBe(555);
       const coder = JSON.parse(lines[2] ?? "{}") as Record<string, unknown>;
       expect(coder.role).toBe("coder");
-      const done = JSON.parse(lines[3] ?? "{}") as Record<string, unknown>;
-      expect(done.returnCode).toBe(0);
     } finally {
       await rm(root, { recursive: true, force: true });
     }

packages/workflow/src/fork-thread.ts

@@ -1,6 +1,6 @@
 import { normalizeRefsField } from "./refs-field.js";
 import { err, ok, type Result } from "./result.js";
-import type { RoleOutput, WorkflowCompletion } from "./types.js";
+import type { RoleOutput } from "./types.js";
 
 /** Role steps replayed from `.data.jsonl`, including persisted timestamps. */
 export type ForkHistoricalStep = RoleOutput & { timestamp: number };
@@ -14,56 +14,33 @@ export type ParsedThreadStartRecord = {
   depth: number;
 };
 
-/** Recognizes a persisted workflow completion line (no `role`; has numeric `returnCode` and string `summary`). Omits `rootHash` when absent. */
-export function tryParseWorkflowResultRecord(
+function parseRoleLine(
   obj: Record<string, unknown>,
-): WorkflowCompletion | null {
-  if (obj.role !== undefined) {
-    return null;
-  }
-  const returnCode = obj.returnCode;
-  const summary = obj.summary;
-  if (typeof returnCode !== "number" || typeof summary !== "string") {
-    return null;
-  }
-  return { returnCode, summary };
-}
-
-export function tryParseRoleStepRecord(obj: Record<string, unknown>): ForkHistoricalStep | null {
+  lineIndex: number,
+): Result<ForkHistoricalStep, string> {
   const role = obj.role;
   const contentHash = obj.contentHash;
   const meta = obj.meta;
   const timestamp = obj.timestamp;
   if (typeof role !== "string") {
-    return null;
+    return err(`invalid role record at line ${lineIndex}: missing role`);
   }
   if (typeof contentHash !== "string") {
-    return null;
+    return err(`invalid role record at line ${lineIndex}: missing contentHash`);
   }
   if (meta === null || typeof meta !== "object") {
-    return null;
+    return err(`invalid role record at line ${lineIndex}: missing meta`);
   }
   if (typeof timestamp !== "number") {
-    return null;
+    return err(`invalid role record at line ${lineIndex}: missing timestamp`);
   }
-  return {
+  return ok({
     role,
     contentHash,
     meta: meta as Record<string, unknown>,
     refs: normalizeRefsField(obj.refs),
     timestamp,
-  };
-}
-
-function parseRoleLine(
-  obj: Record<string, unknown>,
-  lineIndex: number,
-): Result<ForkHistoricalStep, string> {
-  const parsed = tryParseRoleStepRecord(obj);
-  if (parsed === null) {
-    return err(`invalid role record at line ${lineIndex}`);
-  }
-  return ok(parsed);
+  });
 }
 
 function parseStartRecordLine(firstLine: string): Result<ParsedThreadStartRecord, string> {
@@ -132,15 +109,7 @@ function parseFollowingRoleLines(lines: string[]): Result<ForkHistoricalStep[],
     if (rec === null || typeof rec !== "object") {
       return err(`invalid record at line ${i + 1}`);
     }
-    const recObj = rec as Record<string, unknown>;
-    const wf = tryParseWorkflowResultRecord(recObj);
-    if (wf !== null) {
-      if (i !== lines.length - 1) {
-        return err("WorkflowResult record must be the final line in `.data.jsonl`");
-      }
-      break;
-    }
-    const parsed = parseRoleLine(recObj, i + 1);
+    const parsed = parseRoleLine(rec as Record<string, unknown>, i + 1);
     if (!parsed.ok) {
       return parsed;
     }

packages/workflow/src/index.ts

@@ -25,8 +25,6 @@ export {
   type ParsedThreadStartRecord,
   parseThreadDataJsonl,
   selectForkHistoricalSteps,
-  tryParseRoleStepRecord,
-  tryParseWorkflowResultRecord,
 } from "./fork-thread.js";
 export { type GcResult, garbageCollectCas } from "./gc.js";
 export { stringifyWorkflowDescriptor } from "./generate-descriptor.js";

packages/workflow/src/worker.ts

@@ -1,4 +1,4 @@
-import { appendFile, mkdir, unlink, writeFile } from "node:fs/promises";
+import { mkdir, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
 import { importWorkflowBundleModule } from "./bundle-import-env.js";
@@ -11,7 +11,7 @@ import { normalizeRefsField } from "./refs-field.js";
 import { err, ok, type Result } from "./result.js";
 import { getGlobalCasDir } from "./storage-root.js";
 import { createThreadPauseGate, type ThreadPauseGate } from "./thread-pause-gate.js";
-import type { RoleOutput, WorkflowFn, WorkflowResult } from "./types.js";
+import type { RoleOutput, WorkflowFn } from "./types.js";
 
 const bootLog = createLogger({ sink: { kind: "stderr" } });
 
@@ -404,7 +404,7 @@ async function main(): Promise<void> {
         });
       }
 
-      const runResult = await executeThread(
+      await executeThread(
         workflowFn,
         cmd.workflowName,
         { prompt: cmd.prompt, steps: cmd.steps },
@@ -418,12 +418,9 @@ async function main(): Promise<void> {
         io,
         logger,
       );
-      await appendFile(dataJsonlPath, `${JSON.stringify(runResult)}\n`, "utf8");
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       bootLog("Q3MN8YKW", `thread ${threadId} failed: ${message}`);
-      const failure: WorkflowResult = { returnCode: 1, summary: message, rootHash: "" };
-      await appendFile(dataJsonlPath, `${JSON.stringify(failure)}\n`, "utf8").catch(() => {});
     } finally {
       threads.delete(threadId);
       await unlink(runningPath).catch(() => {});

packages/workflow/workflow

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

tsconfig.json

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