chore: reorganize repo — legacy packages to legacy-packages/, templates to examples/

- Move 15 old workflow-* packages to legacy-packages/ (inactive, preserved for reference) - Rename templates/ → examples/ for clarity - Rewrite docs/architecture.md to reflect current uwf architecture - Active packages remain in packages/: cli-uwf, uwf-agent-hermes, uwf-agent-kit, uwf-moderator, uwf-protocol, workflow-util 小橘 🍊（NEKO Team）
2026-05-19 07:19:40 +00:00
parent 2a3a40b9d9
commit d63d58ccb5
373 changed files with 393 additions and 203 deletions
@@ -0,0 +1,80 @@
+# @uncaged/workflow-template-solve-issue
+
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.4
+- @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.3
+- @uncaged/workflow-runtime@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.2
+- @uncaged/workflow-runtime@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.5.0-alpha.0
+- @uncaged/workflow-runtime@0.5.0-alpha.0
+
+## 0.4.5
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.4.5
+- @uncaged/workflow-runtime@0.4.5
+
+## 0.4.4
+
+### Patch Changes
+
+- @uncaged/workflow-register@0.4.4
+- @uncaged/workflow-runtime@0.4.4
+
+## 0.4.3
+
+### Patch Changes
+
+- Include src/ in published packages so bun runtime can resolve the 'bun' exports condition.
+- Updated dependencies
+  - @uncaged/workflow-register@0.4.3
+  - @uncaged/workflow-runtime@0.4.3
+
+## 0.4.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution: use workspace:^ so published packages resolve to compatible versions instead of exact (non-existent) versions.
+- Updated dependencies
+  - @uncaged/workflow-register@0.4.2
+  - @uncaged/workflow-runtime@0.4.2
+
+## 0.4.0
+
+### Minor Changes
+
+- Fix package exports for published packages and adopt changesets for version management.
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-register@0.4.0
+  - @uncaged/workflow-runtime@0.4.0
@@ -0,0 +1,48 @@
+# @uncaged/workflow-template-solve-issue
+
+Reference **solve-issue** workflow template: prepare a repo, delegate implementation to the **develop** workflow, then submit (e.g. open a PR).
+
+This package exports a pure `WorkflowDefinition` (`solveIssueWorkflowDefinition`). Workflow instantiation (`createWorkflow(definition, binding)`) and any role-specific agent wiring (for example delegating `developer` to `workflowAsAgent("develop")`) are done in the workflow instance layer.
+
+## Install
+
+```bash
+bun add @uncaged/workflow-template-solve-issue @uncaged/workflow zod
+```
+
+In this monorepo: `workspace:*` for this package and `@uncaged/workflow`.
+
+## Usage
+
+```typescript
+import { createWorkflow } from "@uncaged/workflow";
+import { solveIssueWorkflowDefinition } from "@uncaged/workflow-template-solve-issue";
+
+const run = createWorkflow(solveIssueWorkflowDefinition, binding);
+```
+
+## Roles
+
+| Role | Purpose |
+|------|---------|
+| **preparer** | Set up context / repo state for the issue |
+| **developer** | Implementation; default runs the registered `develop` workflow as a sub-agent |
+| **submitter** | Finalize and submit the outcome (e.g. PR) |
+
+Also exported: `preparerRole`, `developerRole`, `submitterRole` and their Zod meta schemas, `SolveIssueMeta`, `solveIssueRoles`.
+
+## Moderator flow
+
+1. **Start** → `preparer`  
+2. After **preparer** → `developer`  
+3. After **developer** → `submitter`  
+4. After **submitter** → `END`
+
+## API overview
+
+| Export | Description |
+|--------|-------------|
+| `solveIssueWorkflowDefinition` | `description`, `roles`, `solveIssueModerator` |
+| `solveIssueModerator` | Linear `Moderator<SolveIssueMeta>` |
+| `buildSolveIssueDescriptor` | Descriptor helper for bundles |
+| `SOLVE_ISSUE_WORKFLOW_DESCRIPTION` | Human-readable one-liner |
@@ -0,0 +1,298 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { createExtract } from "@uncaged/workflow-execute";
+import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js";
+import { validateWorkflowDescriptor } from "@uncaged/workflow-register";
+import {
+  type AdapterFn,
+  createWorkflow,
+  END,
+  type ModeratorContext,
+  type RoleResult,
+  type RoleStep,
+  START,
+  type ThreadContext,
+  type WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+import type * as z from "zod/v4";
+import { buildSolveIssueDescriptor } from "../src/descriptor.js";
+import type { DeveloperMeta } from "../src/developer.js";
+import { solveIssueTable, solveIssueWorkflowDefinition } from "../src/index.js";
+import type { PreparerMeta, SubmitterMeta } from "../src/roles/index.js";
+import type { SolveIssueMeta } from "../src/roles.js";
+
+const solveIssueModerator = tableToModerator(solveIssueTable);
+
+function makeStart(): ModeratorContext<SolveIssueMeta>["start"] {
+  return {
+    role: START,
+    content: "Fix the flaky login test",
+    meta: {},
+    timestamp: 0,
+    parentState: null,
+  };
+}
+
+function makeCtx(
+  steps: ModeratorContext<SolveIssueMeta>["steps"],
+): ModeratorContext<SolveIssueMeta> {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    bundleHash: "TESTHASH00001",
+    start: makeStart(),
+    steps,
+  };
+}
+
+function preparerStep(): RoleStep<SolveIssueMeta> {
+  return {
+    role: "preparer",
+    contentHash: "STUBHASHPREPARER01",
+    meta: {
+      repoPath: "/home/user/repos/test",
+      defaultBranch: "main",
+      conventions: null,
+      toolchain: {
+        packageManager: "bun",
+        testCommand: "bun test",
+        lintCommand: null,
+        buildCommand: "bun run build",
+      },
+    },
+    refs: [],
+    timestamp: 0,
+  };
+}
+
+function developerStep(): 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: [],
+    timestamp: 1,
+  };
+}
+
+function submitterStep(meta: SubmitterMeta): RoleStep<SolveIssueMeta> {
+  return {
+    role: "submitter",
+    contentHash: "STUBHASHSUBMITTER1",
+    meta,
+    refs: [],
+    timestamp: 2,
+  };
+}
+
+function makeThread(prompt: string) {
+  return {
+    threadId: "01TEST000000000000000000TR",
+    depth: 0,
+    bundleHash: "TESTHASH00001",
+    start: {
+      role: START,
+      content: prompt,
+      meta: {},
+      timestamp: Date.now(),
+      parentState: null,
+    },
+    steps: [],
+  };
+}
+
+/** Creates an AdapterFn that returns a fixed sequence of meta values. */
+function createSequenceAdapter(sequence: ReadonlyArray<Record<string, unknown>>): AdapterFn {
+  let i = 0;
+  return <T>(_prompt: string, _schema: z.ZodType<T>) => {
+    return async (_ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const meta = sequence[i] ?? sequence[sequence.length - 1];
+      if (meta === undefined) {
+        throw new Error("createSequenceAdapter: empty sequence");
+      }
+      i += 1;
+      return { meta: meta as T, childThread: null };
+    };
+  };
+}
+
+/** Creates an AdapterFn that tracks calls and returns fixed meta. */
+function createTrackingAdapter(
+  name: string,
+  calls: string[],
+  meta: Record<string, unknown>,
+): AdapterFn {
+  return <T>(_prompt: string, _schema: z.ZodType<T>) => {
+    return async (_ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      calls.push(name);
+      return { meta: meta as T, childThread: null };
+    };
+  };
+}
+
+describe("solveIssueModerator", () => {
+  test("routes initial → preparer → developer → submitter → END", () => {
+    expect(solveIssueModerator(makeCtx([]))).toBe("preparer");
+    expect(solveIssueModerator(makeCtx([preparerStep()]))).toBe("developer");
+    expect(solveIssueModerator(makeCtx([preparerStep(), developerStep()]))).toBe("submitter");
+    expect(
+      solveIssueModerator(
+        makeCtx([
+          preparerStep(),
+          developerStep(),
+          submitterStep({
+            status: "submitted",
+            prUrl: "https://github.com/example/repo/pull/1",
+          }),
+        ]),
+      ),
+    ).toBe(END);
+  });
+
+  test("submitter failed → END", () => {
+    expect(
+      solveIssueModerator(
+        makeCtx([
+          preparerStep(),
+          developerStep(),
+          submitterStep({ status: "failed", error: "gh not authenticated" }),
+        ]),
+      ),
+    ).toBe(END);
+  });
+
+  test("returns END for any unexpected last step (defensive)", () => {
+    expect(
+      solveIssueModerator(
+        makeCtx([
+          preparerStep(),
+          developerStep(),
+          submitterStep({ status: "submitted", prUrl: "https://example.com/pr/1" }),
+        ]),
+      ),
+    ).toBe(END);
+  });
+});
+
+describe("solveIssueWorkflowDefinition + createWorkflow", () => {
+  let casDir: string | undefined;
+
+  afterEach(async () => {
+    if (casDir !== undefined) {
+      await rm(casDir, { recursive: true, force: true }).catch(() => {});
+      casDir = undefined;
+    }
+  });
+
+  test("adapter yields preparer meta directly", async () => {
+    const EXPECT_PREPARER_META: PreparerMeta = {
+      repoPath: "/home/user/repos/test",
+      defaultBranch: "main",
+      conventions: null,
+      toolchain: {
+        packageManager: "bun",
+        testCommand: "bun test",
+        lintCommand: null,
+        buildCommand: "bun run build",
+      },
+    };
+
+    casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
+    const cas = createCasStore(casDir);
+
+    const adapter = createSequenceAdapter([EXPECT_PREPARER_META]);
+    const run = createWorkflow(solveIssueWorkflowDefinition, {
+      adapter,
+      overrides: null,
+    });
+    const gen = run(makeThread("task"), {
+      cas,
+      extract: createExtract({ baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" }, { cas }),
+    });
+    const first = await gen.next();
+    expect(first.done).toBe(false);
+    if (first.done) {
+      throw new Error("expected yield");
+    }
+    expect(first.value.role).toBe("preparer");
+    expect(first.value.meta).toEqual(EXPECT_PREPARER_META);
+  });
+
+  test("per-role adapter overrides default", 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/x",
+      commitSha: "abc1234",
+      filesChanged: ["a.ts"],
+      summary: "did the work",
+    };
+    const SUBMITTER_META: SubmitterMeta = {
+      status: "submitted",
+      prUrl: "https://github.com/example/repo/pull/2",
+    };
+
+    casDir = await mkdtemp(join(tmpdir(), "solve-issue-cas-"));
+    const cas = createCasStore(casDir);
+
+    const calls: string[] = [];
+    const run = createWorkflow(solveIssueWorkflowDefinition, {
+      adapter: createTrackingAdapter("default", calls, PREPARER_META),
+      overrides: {
+        preparer: createTrackingAdapter("preparer", calls, PREPARER_META),
+        developer: createTrackingAdapter("developer", calls, DEVELOPER_META),
+        submitter: createTrackingAdapter("submitter", calls, SUBMITTER_META),
+      },
+    });
+    const gen = run(makeThread("task"), {
+      cas,
+      extract: createExtract({ baseUrl: "http://127.0.0.1:9", apiKey: "", model: "test" }, { cas }),
+    });
+    await gen.next();
+    expect(calls).toEqual(["preparer"]);
+
+    calls.length = 0;
+    await gen.next();
+    expect(calls).toEqual(["developer"]);
+
+    calls.length = 0;
+    await gen.next();
+    expect(calls).toEqual(["submitter"]);
+  });
+});
+
+describe("buildSolveIssueDescriptor", () => {
+  test("lists preparer, developer, submitter with schemas that validate", () => {
+    const descriptor = buildSolveIssueDescriptor();
+    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([
+      "developer",
+      "preparer",
+      "submitter",
+    ]);
+    expect(validated.value.graph.edges.length).toBe(4);
+    for (const key of ["preparer", "developer", "submitter"] 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);
+    }
+  });
+});
@@ -0,0 +1,34 @@
+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");
+  });
+});
@@ -0,0 +1,27 @@
+/**
+ * solve-issue bundle entry — 小橘 🍊
+ *
+ * preparer + submitter → hermes agent
+ * developer → workflow adapter (delegates to "develop" workflow)
+ */
+import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
+import { workflowAdapter } from "@uncaged/workflow-execute";
+import { createWorkflow } from "@uncaged/workflow-runtime";
+import { env } from "@uncaged/workflow-util";
+import { buildSolveIssueDescriptor, solveIssueWorkflowDefinition } from "./src/index.js";
+
+const adapter = createHermesAgent({
+  command: env("WORKFLOW_HERMES_COMMAND", "/home/azureuser/.local/bin/hermes"),
+  model: env("WORKFLOW_HERMES_MODEL", "") || null,
+  timeout: Number(env("WORKFLOW_HERMES_TIMEOUT", "0")) || null,
+});
+
+const wf = createWorkflow(solveIssueWorkflowDefinition, {
+  adapter,
+  overrides: {
+    developer: workflowAdapter("develop"),
+  },
+});
+
+export const descriptor = buildSolveIssueDescriptor();
+export const run = wf;
@@ -0,0 +1,33 @@
+{
+  "name": "@uncaged/workflow-template-solve-issue",
+  "version": "0.5.0-alpha.4",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@uncaged/workflow-register": "workspace:^",
+    "@uncaged/workflow-runtime": "workspace:^",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@uncaged/workflow-cas": "workspace:^",
+    "@uncaged/workflow-execute": "workspace:^",
+    "@uncaged/workflow-protocol": "workspace:^"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
@@ -0,0 +1,35 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@uncaged/workflow-register':
+        specifier: workspace:*
+        version: link:../workflow-register
+      '@uncaged/workflow-runtime':
+        specifier: workspace:*
+        version: link:../workflow-runtime
+      zod:
+        specifier: ^4.0.0
+        version: 4.4.3
+    devDependencies:
+      '@uncaged/workflow-cas':
+        specifier: workspace:*
+        version: link:../workflow-cas
+      '@uncaged/workflow-execute':
+        specifier: workspace:*
+        version: link:../workflow-execute
+
+packages:
+
+  zod@4.4.3:
+    resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
+
+snapshots:
+
+  zod@4.4.3: {}
@@ -0,0 +1,12 @@
+import { buildDescriptor } from "@uncaged/workflow-register";
+
+import { solveIssueTable } from "./moderator.js";
+import { SOLVE_ISSUE_WORKFLOW_DESCRIPTION, solveIssueRoles } from "./roles.js";
+
+export function buildSolveIssueDescriptor() {
+  return buildDescriptor({
+    description: SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
+    roles: solveIssueRoles,
+    table: solveIssueTable,
+  });
+}
@@ -0,0 +1,24 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+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.`;
+
+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,
+  schema: developerMetaSchema,
+};
@@ -0,0 +1,32 @@
+import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
+
+import { solveIssueTable } 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 { solveIssueTable } from "./moderator.js";
+export {
+  type PreparerMeta,
+  preparerMetaSchema,
+  preparerRole,
+  type SubmitterMeta,
+  submitterMetaSchema,
+  submitterRole,
+} from "./roles/index.js";
+export {
+  SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
+  type SolveIssueMeta,
+  type SolveIssueRoles,
+  solveIssueRoles,
+} from "./roles.js";
+
+export const solveIssueWorkflowDefinition: WorkflowDefinition<SolveIssueMeta> = {
+  description: SOLVE_ISSUE_WORKFLOW_DESCRIPTION,
+  roles: solveIssueRoles,
+  table: solveIssueTable,
+};
@@ -0,0 +1,12 @@
+import { END, type ModeratorTable, START } from "@uncaged/workflow-runtime";
+
+import type { SolveIssueMeta } from "./roles.js";
+
+const table: ModeratorTable<SolveIssueMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "preparer" }],
+  preparer: [{ condition: "FALLBACK", role: "developer" }],
+  developer: [{ condition: "FALLBACK", role: "submitter" }],
+  submitter: [{ condition: "FALLBACK", role: END }],
+};
+
+export { table as solveIssueTable };
@@ -0,0 +1,23 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+import { type DeveloperMeta, developerRole } from "./developer.js";
+import { type PreparerMeta, preparerRole } from "./roles/preparer.js";
+import { type SubmitterMeta, submitterRole } from "./roles/submitter.js";
+
+export const SOLVE_ISSUE_WORKFLOW_DESCRIPTION =
+  "Resolve an issue end-to-end by preparing the repo, delegating implementation to the develop workflow, and opening a pull request (preparer → developer → submitter).";
+
+export type SolveIssueMeta = {
+  preparer: PreparerMeta;
+  developer: DeveloperMeta;
+  submitter: SubmitterMeta;
+};
+
+export type SolveIssueRoles = {
+  [K in keyof SolveIssueMeta]: RoleDefinition<SolveIssueMeta[K]>;
+};
+
+export const solveIssueRoles: SolveIssueRoles = {
+  preparer: preparerRole,
+  developer: developerRole,
+  submitter: submitterRole,
+};
@@ -0,0 +1,6 @@
+export {
+  type PreparerMeta,
+  preparerMetaSchema,
+  preparerRole,
+} from "./preparer.js";
+export { type SubmitterMeta, submitterMetaSchema, submitterRole } from "./submitter.js";
@@ -0,0 +1,48 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+import * as z from "zod/v4";
+
+const toolchainSchema = z.object({
+  packageManager: z.union([z.string(), z.null()]),
+  testCommand: z.union([z.string(), z.null()]),
+  lintCommand: z.union([z.string(), z.null()]),
+  buildCommand: z.union([z.string(), z.null()]),
+});
+
+export const preparerMetaSchema = z.object({
+  repoPath: z.string(),
+  defaultBranch: z.string(),
+  conventions: z.union([z.string(), z.null()]),
+  toolchain: toolchainSchema,
+});
+
+export type PreparerMeta = z.infer<typeof preparerMetaSchema>;
+
+const PREPARER_SYSTEM = `You are a **preparer** for a software task. Your job is to locate (or clone) the target repository locally, ensure it is up to date, and gather project context before work begins.
+
+## Responsibilities
+
+1. Parse the issue/task prompt to identify the target repository (URL, org/repo, or name).
+2. Search for an existing local clone in these locations (in order):
+   - ~/Code/<repo-name>/
+   - ~/repos/<repo-name>/
+   - ~/Code/<org>/<repo-name>/
+   - ~/repos/<org>/<repo-name>/
+3. If not found locally, \`git clone\` it into ~/repos/<repo-name>/.
+4. \`git checkout main && git pull\` (or the default branch) to ensure latest.
+5. Read project conventions: \`CLAUDE.md\`, \`CONTRIBUTING.md\`, \`.cursor/rules/*.mdc\`, \`CONVENTIONS.md\`.
+6. Detect toolchain: package manager, test runner, linter, build system.
+
+## Output
+
+Report your findings as structured data:
+- **repoPath**: absolute path to the local repo
+- **defaultBranch**: the default branch name (e.g. "main")
+- **conventions**: a summary of project conventions found, or null if none
+- **toolchain**: detected commands for packageManager, testCommand, lintCommand, buildCommand (null if not detected)`;
+
+export const preparerRole: RoleDefinition<PreparerMeta> = {
+  description:
+    "Locates or clones the target repository, ensures it is up to date, and gathers project context (conventions, toolchain).",
+  systemPrompt: PREPARER_SYSTEM,
+  schema: preparerMetaSchema,
+};
@@ -0,0 +1,38 @@
+import type { RoleDefinition } from "@uncaged/workflow-runtime";
+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.`;
+
+export const submitterRole: RoleDefinition<SubmitterMeta> = {
+  description: "Pushes the developer's branch to the remote and opens a pull request.",
+  systemPrompt: SUBMITTER_SYSTEM,
+  schema: submitterMetaSchema,
+};
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../workflow-register" }, { "path": "../workflow-runtime" }]
+}