@bastani/atomic 0.5.34-0 → 0.6.0-0

package/src/sdk/define-workflow.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
+import { defineWorkflow, WorkflowBuilder, RESERVED_INPUT_NAMES } from "./define-workflow.ts";
 import type { WorkflowInput } from "./types.ts";
 
 describe("defineWorkflow", () => {
@@ -39,6 +39,7 @@ describe("WorkflowBuilder.run()", () => {
 describe("WorkflowBuilder.compile()", () => {
   test("produces a WorkflowDefinition with correct brand", () => {
     const def = defineWorkflow({ name: "test" })
+      .for("copilot")
       .run(async () => {})
       .compile();
     expect(def.__brand).toBe("WorkflowDefinition");
@@ -46,6 +47,7 @@ describe("WorkflowBuilder.compile()", () => {
 
   test("defaults inputs to an empty array when none are declared", () => {
     const def = defineWorkflow({ name: "test" })
+      .for("copilot")
       .run(async () => {})
       .compile();
     expect(def.inputs).toEqual([]);
@@ -70,6 +72,7 @@ describe("WorkflowBuilder.compile()", () => {
         },
       ],
     })
+      .for("opencode")
       .run(async () => {})
       .compile();
     expect(def.inputs).toHaveLength(2);
@@ -83,6 +86,7 @@ describe("WorkflowBuilder.compile()", () => {
       name: "test",
       inputs: [{ name: "foo", type: "string" }],
     })
+      .for("claude")
       .run(async () => {})
       .compile();
     expect(() => {
@@ -96,6 +100,7 @@ describe("WorkflowBuilder.compile()", () => {
         name: "bad",
         inputs: [{ name: "mode", type: "enum" }],
       })
+        .for("copilot")
         .run(async () => {})
         .compile(),
     ).toThrow("declares no `values`");
@@ -114,6 +119,7 @@ describe("WorkflowBuilder.compile()", () => {
           },
         ],
       })
+        .for("copilot")
         .run(async () => {})
         .compile(),
     ).toThrow(/not one of its declared values/);
@@ -125,6 +131,7 @@ describe("WorkflowBuilder.compile()", () => {
         name: "bad",
         inputs: [{ name: "1bad", type: "string" }],
       })
+        .for("copilot")
         .run(async () => {})
         .compile(),
     ).toThrow(/invalid/);
@@ -139,21 +146,25 @@ describe("WorkflowBuilder.compile()", () => {
           { name: "foo", type: "string" },
         ],
       })
+        .for("copilot")
         .run(async () => {})
         .compile(),
     ).toThrow(/duplicate input name/);
   });
 
-  test("preserves name and description", () => {
+  test("preserves name, description, and agent", () => {
     const def = defineWorkflow({ name: "my-wf", description: "A description" })
+      .for("claude")
       .run(async () => {})
       .compile();
     expect(def.name).toBe("my-wf");
     expect(def.description).toBe("A description");
+    expect(def.agent).toBe("claude");
   });
 
   test("defaults description to empty string", () => {
     const def = defineWorkflow({ name: "test" })
+      .for("opencode")
       .run(async () => {})
       .compile();
     expect(def.description).toBe("");
@@ -161,22 +172,104 @@ describe("WorkflowBuilder.compile()", () => {
 
   test("stores the run function", () => {
     const fn = async () => {};
-    const def = defineWorkflow({ name: "test" }).run(fn).compile();
+    const def = defineWorkflow({ name: "test" }).for("copilot").run(fn).compile();
     expect(def.run).toBe(fn);
   });
 
   test("throws if no run callback was provided", () => {
-    const builder = defineWorkflow({ name: "test" });
+    const builder = defineWorkflow({ name: "test" }).for("copilot");
     expect(() => builder.compile()).toThrow("has no run callback");
   });
+
+  test("throws if .for() was not called before compile()", () => {
+    const builder = defineWorkflow({ name: "test" }).run(async () => {});
+    expect(() => builder.compile()).toThrow("has no agent");
+  });
+});
+
+describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
+  test("RESERVED_INPUT_NAMES is exported and contains expected names", () => {
+    expect(RESERVED_INPUT_NAMES).toContain("name");
+    expect(RESERVED_INPUT_NAMES).toContain("agent");
+    expect(RESERVED_INPUT_NAMES).toContain("detach");
+    expect(RESERVED_INPUT_NAMES).toContain("list");
+    expect(RESERVED_INPUT_NAMES).toContain("help");
+    expect(RESERVED_INPUT_NAMES).toContain("version");
+  });
+
+  // Each reserved name must be rejected individually.
+  for (const reserved of RESERVED_INPUT_NAMES) {
+    test(`rejects reserved input name "${reserved}"`, () => {
+      expect(() =>
+        defineWorkflow({
+          name: "bad",
+          inputs: [{ name: reserved, type: "string" }],
+        })
+          .for("copilot")
+          .run(async () => {})
+          .compile(),
+      ).toThrow(reserved);
+    });
+  }
+
+  test("error message lists all reserved names", () => {
+    let message = "";
+    try {
+      defineWorkflow({
+        name: "bad",
+        inputs: [{ name: "name", type: "string" }],
+      })
+        .for("copilot")
+        .run(async () => {})
+        .compile();
+    } catch (e) {
+      message = (e as Error).message;
+    }
+    for (const reserved of RESERVED_INPUT_NAMES) {
+      expect(message).toContain(reserved);
+    }
+  });
+
+  test("non-reserved input name passes validation", () => {
+    expect(() =>
+      defineWorkflow({
+        name: "ok",
+        inputs: [{ name: "topic", type: "string" }],
+      })
+        .for("copilot")
+        .run(async () => {})
+        .compile(),
+    ).not.toThrow();
+  });
+
+  test("non-reserved name that is a prefix of a reserved name passes", () => {
+    expect(() =>
+      defineWorkflow({
+        name: "ok",
+        inputs: [{ name: "named", type: "string" }],
+      })
+        .for("copilot")
+        .run(async () => {})
+        .compile(),
+    ).not.toThrow();
+  });
 });
 
 describe("WorkflowBuilder.for()", () => {
-  test("returns the same builder instance (type-only narrowing)", () => {
+  test("returns a new builder with agent set", () => {
     const builder = defineWorkflow({ name: "test" });
-    const narrowed = builder.for<"copilot">();
-    // Same instance — .for() only changes the TypeScript type, not the value
-    expect(narrowed === (builder as unknown)).toBe(true);
+    const narrowed = builder.for("copilot");
+    // .for() returns a new builder instance
+    expect(narrowed).toBeInstanceOf(WorkflowBuilder);
+    expect(narrowed).not.toBe(builder as unknown);
+  });
+
+  test("stores agent on the compiled definition", () => {
+    const def = defineWorkflow({ name: "test" })
+      .for("copilot")
+      .run(async () => {})
+      .compile();
+    expect(def.agent).toBe("copilot");
   });
 
   test("chains with run and compile", () => {
@@ -184,7 +277,7 @@ describe("WorkflowBuilder.for()", () => {
       name: "test",
       inputs: [{ name: "greeting", type: "string" }],
     })
-      .for<"copilot">()
+      .for("copilot")
       .run(async () => {})
       .compile();
     expect(def.__brand).toBe("WorkflowDefinition");
@@ -205,7 +298,7 @@ describe("typed inputs (compile-time)", () => {
         { name: "style", type: "enum", values: ["formal", "casual"] },
       ],
     })
-      .for<"copilot">()
+      .for("copilot")
       .run(async (ctx) => {
         // Declared keys are valid
         const _g: string | undefined = ctx.inputs.greeting;
@@ -220,7 +313,7 @@ describe("typed inputs (compile-time)", () => {
 
   test("free-form workflows allow any key", () => {
     defineWorkflow({ name: "freeform-test" })
-      .for<"copilot">()
+      .for("copilot")
       .run(async (ctx) => {
         const _p: string | undefined = ctx.inputs.prompt;
         expect(true).toBe(true);

package/src/sdk/define-workflow.ts

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   defineWorkflow({ name: "my-workflow", inputs: [...] })
- *     .for<"copilot">()
+ *     .for("copilot")
  *     .run(async (ctx) => {
  *       await ctx.stage({ name: "research" }, {}, {}, async (s) => { ... });
  *       await ctx.stage({ name: "plan" }, {}, {}, async (s) => { ... });
@@ -21,6 +21,25 @@ import type {
 
 type AnyInputs = readonly WorkflowInput[];
 
+/**
+ * Flag and subcommand names reserved by the worker CLI that cannot be used as
+ * workflow input names. The first block (`name` / `agent` / `detach` / `list`
+ * / `help` / `version`) collides with Commander's own flags on the root
+ * command; the second block (`session` / `status`) collides with the auto-
+ * registered management subcommands added by `createWorkflowCli` when
+ * `includeManagementCommands` is left at its default (`true`).
+ */
+export const RESERVED_INPUT_NAMES = [
+  "name",
+  "agent",
+  "detach",
+  "list",
+  "help",
+  "version",
+  "session",
+  "status",
+] as const;
+
 /**
  * Validate a single declared workflow input, throwing on authoring
  * mistakes that would otherwise surface as confusing runtime errors
@@ -40,6 +59,12 @@ function validateWorkflowInput(input: WorkflowInput, workflowName: string): void
         `\`--${input.name}\` CLI flag).`,
     );
   }
+  if ((RESERVED_INPUT_NAMES as readonly string[]).includes(input.name)) {
+    throw new Error(
+      `defineWorkflow: input name "${input.name}" is reserved by the worker CLI. ` +
+        `Rename it. Reserved names: ${RESERVED_INPUT_NAMES.join(", ")}.`,
+    );
+  }
   if (input.type === "enum") {
     if (!Array.isArray(input.values) || input.values.length === 0) {
       throw new Error(
@@ -89,6 +114,7 @@ export class WorkflowBuilder<
   readonly __brand = "WorkflowBuilder" as const;
   private readonly options: WorkflowOptions<I>;
   private runFn: ((ctx: WorkflowContext<A, I>) => Promise<void>) | null = null;
+  private agentValue: AgentType | null = null;
 
   constructor(options: WorkflowOptions<I>) {
     this.options = options;
@@ -97,10 +123,9 @@ export class WorkflowBuilder<
   /**
    * Narrow the agent type for this workflow while preserving typed inputs.
    *
-   * Use `.for<"copilot">()` **before** `.run()` instead of passing the
-   * agent as a type parameter to `defineWorkflow`. This allows TypeScript
-   * to infer input names from the `inputs` array AND narrow the agent
-   * type for `stage()` callbacks.
+   * Pass the agent as a runtime string argument so the compiled
+   * {@link WorkflowDefinition} carries the `agent` field required by
+   * the registry.
    *
    * @example
    * ```typescript
@@ -108,7 +133,7 @@ export class WorkflowBuilder<
    *   name: "my-workflow",
    *   inputs: [{ name: "greeting", type: "string" }],
    * })
-   *   .for<"copilot">()
+   *   .for("copilot")
    *   .run(async (ctx) => {
    *     ctx.inputs.greeting; // ✓ typed
    *     ctx.inputs.prompt;   // ✗ compile error
@@ -116,8 +141,11 @@ export class WorkflowBuilder<
    *   .compile();
    * ```
    */
-  for<B extends AgentType>(): WorkflowBuilder<B, I> {
-    return this as unknown as WorkflowBuilder<B, I>;
+  for<B extends AgentType>(agent: B): WorkflowBuilder<B, I> {
+    const next = new WorkflowBuilder<B, I>(this.options as WorkflowOptions<I>);
+    next.agentValue = agent;
+    next.runFn = this.runFn as ((ctx: WorkflowContext<B, I>) => Promise<void>) | null;
+    return next;
   }
 
   /**
@@ -170,11 +198,19 @@ export class WorkflowBuilder<
     }
     const inputs = Object.freeze(
       declaredInputs.map((i) => Object.freeze({ ...i })),
-    ) as readonly WorkflowInput[];
+    ) as unknown as I;
+
+    if (this.agentValue === null) {
+      throw new Error(
+        `Workflow "${this.options.name}" has no agent. ` +
+          `Call .for("copilot") / .for("opencode") / .for("claude") before .compile().`,
+      );
+    }
 
     return {
       __brand: "WorkflowDefinition" as const,
       name: this.options.name,
+      agent: this.agentValue as A,
       description: this.options.description ?? "",
       inputs,
       minSDKVersion: this.options.minSDKVersion ?? null,
@@ -187,7 +223,7 @@ export class WorkflowBuilder<
  * Entry point for defining a workflow.
  *
  * Write the `inputs` array inline so TypeScript infers literal field
- * names and enforces them on `ctx.inputs`. Use `.for<Agent>()` to
+ * names and enforces them on `ctx.inputs`. Use `.for(agent)` to
  * narrow the agent type while keeping typed inputs:
  *
  * @example
@@ -201,7 +237,7 @@ export class WorkflowBuilder<
  *     { name: "greeting", type: "string", required: true },
  *   ],
  * })
- *   .for<"copilot">()
+ *   .for("copilot")
  *   .run(async (ctx) => {
  *     ctx.inputs.greeting; // ✓ string | undefined
  *     ctx.inputs.prompt;   // ✗ compile error — not declared

package/src/sdk/errors.test.ts

@@ -3,6 +3,7 @@ import {
   MissingDependencyError,
   WorkflowNotCompiledError,
   InvalidWorkflowError,
+  IncompatibleSDKError,
   errorMessage,
 } from "./errors";
 
@@ -42,6 +43,21 @@ describe("InvalidWorkflowError", () => {
   });
 });
 
+describe("IncompatibleSDKError", () => {
+  test("sets name, versions, and message", () => {
+    const err = new IncompatibleSDKError("/tmp/wf.ts", "2.0.0", "1.4.0");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("IncompatibleSDKError");
+    expect(err.path).toBe("/tmp/wf.ts");
+    expect(err.requiredVersion).toBe("2.0.0");
+    expect(err.currentVersion).toBe("1.4.0");
+    expect(err.message).toContain("/tmp/wf.ts");
+    expect(err.message).toContain("v2.0.0");
+    expect(err.message).toContain("v1.4.0");
+    expect(err.message).toContain("Update Atomic");
+  });
+});
+
 describe("errorMessage", () => {
   test("extracts message from Error", () => {
     expect(errorMessage(new Error("boom"))).toBe("boom");

package/src/sdk/index.ts

@@ -34,12 +34,12 @@ export type {
 // Workflow SDK (also available as atomic/workflows subpath)
 export { defineWorkflow } from "./define-workflow.ts";
 
-// Workflow discovery and execution
-export {
-  discoverWorkflows,
-  findWorkflow,
-} from "./runtime/discovery.ts";
-
-export { WorkflowLoader } from "./runtime/loader.ts";
+// Registry
+export type { Registry } from "./registry.ts";
+export { createRegistry } from "./registry.ts";
 
-export { executeWorkflow } from "./runtime/executor.ts";
+// WorkflowCli — the factory that drives workflow CLIs. Accepts a lone
+// workflow, an array of workflows, or a Registry for programmatic
+// composition. Ships with the interactive picker out of the box.
+export { createWorkflowCli } from "./workflow-cli.ts";
+export type { WorkflowCli, CreateWorkflowCliOptions } from "./types.ts";

package/src/sdk/management-commands.ts

@@ -0,0 +1,151 @@
+/**
+ * Session + status management subcommands for workflow CLIs.
+ *
+ * Shared by the atomic CLI root (`atomic session *`, `atomic workflow status`)
+ * and by SDK-built CLIs (`createWorkflowCli(...)`). Factoring this out means a
+ * user running `bun run src/claude-worker.ts session list` gets the identical
+ * command surface as `atomic session list`, without the SDK embedding its own
+ * diverging implementation. All queries go through the shared atomic tmux
+ * socket, so sessions spawned by SDK-built CLIs and by `atomic workflow -n …`
+ * show up interchangeably.
+ *
+ * Commander options are declared with the same names, descriptions, and
+ * behaviour as the atomic root CLI — keep them in sync when the root CLI
+ * grows a new option.
+ */
+
+import type { Command } from "@commander-js/extra-typings";
+import type { SessionScope } from "../commands/cli/session.ts";
+
+/** Commander collect helper: accumulates repeated `-a` values into an array. */
+function collectAgent(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+/**
+ * Attach the `session` subcommand group (`list` / `connect` / `kill`) to a
+ * parent Commander command. Returns the created `session` group so callers
+ * can attach additional children if they need to.
+ *
+ * @param parent The Commander command to mount `session` under.
+ * @param scope  Which session set the list/kill commands operate on. SDK CLIs
+ *               typically pass `"workflow"` to scope the picker to
+ *               `atomic-wf-*` sessions only; the atomic root uses `"all"`.
+ */
+export function addSessionSubcommand(
+  parent: Command,
+  scope: SessionScope = "all",
+): Command {
+  const sessionCmd = parent
+    .command("session")
+    .description("Manage running tmux sessions on the atomic socket");
+
+  sessionCmd
+    .command("list")
+    .description("List running sessions on the atomic tmux socket")
+    .option(
+      "-a, --agent <name>",
+      "Filter by agent backend (claude, copilot, opencode); repeatable",
+      collectAgent,
+      [] as string[],
+    )
+    .action(async (localOpts) => {
+      const { sessionListCommand } = await import(
+        "../commands/cli/session.ts"
+      );
+      const exitCode = await sessionListCommand(localOpts.agent, scope);
+      process.exit(exitCode);
+    });
+
+  sessionCmd
+    .command("connect")
+    .description("Attach to a running session (interactive picker when no id given)")
+    .argument("[session_id]", "Session name to connect to")
+    .option(
+      "-a, --agent <name>",
+      "Filter picker by agent backend (claude, copilot, opencode); repeatable",
+      collectAgent,
+      [] as string[],
+    )
+    .action(async (sessionId, localOpts) => {
+      if (sessionId) {
+        const { sessionConnectCommand } = await import(
+          "../commands/cli/session.ts"
+        );
+        const exitCode = await sessionConnectCommand(sessionId);
+        process.exit(exitCode);
+      } else {
+        const { sessionPickerCommand } = await import(
+          "../commands/cli/session.ts"
+        );
+        const exitCode = await sessionPickerCommand(localOpts.agent, scope);
+        process.exit(exitCode);
+      }
+    });
+
+  sessionCmd
+    .command("kill")
+    .description("Kill a running session (omit id to kill all in scope)")
+    .argument("[session_id]", "Session name to kill (omit to kill all)")
+    .option(
+      "-a, --agent <name>",
+      "Filter by agent backend (claude, copilot, opencode); repeatable",
+      collectAgent,
+      [] as string[],
+    )
+    .option("-y, --yes", "Skip the confirmation prompt (required for agent callers)")
+    .action(async (sessionId, localOpts) => {
+      const { sessionKillCommand } = await import(
+        "../commands/cli/session.ts"
+      );
+      const exitCode = await sessionKillCommand(
+        sessionId,
+        localOpts.agent,
+        scope,
+        undefined,
+        { yes: localOpts.yes === true },
+      );
+      process.exit(exitCode);
+    });
+
+  return sessionCmd;
+}
+
+/**
+ * Attach a top-level `status` subcommand for querying workflow status.
+ * Mirrors `atomic workflow status` — same overall-state contract
+ * (`in_progress` / `error` / `completed` / `needs_review`) and same JSON
+ * shape. Omit the id to list every running workflow on the socket.
+ */
+export function addStatusSubcommand(parent: Command): void {
+  parent
+    .command("status")
+    .description(
+      "Query workflow status (in_progress, error, completed, needs_review); omit id to list all",
+    )
+    .argument("[session_id]", "Workflow tmux session id (omit to list all)")
+    .option("--format <format>", "Output format: json | text", "json")
+    .action(async (sessionId, localOpts) => {
+      const { workflowStatusCommand } = await import(
+        "../commands/cli/workflow-status.ts"
+      );
+      const exitCode = await workflowStatusCommand({
+        id: sessionId,
+        format: localOpts.format === "text" ? "text" : "json",
+      });
+      process.exit(exitCode);
+    });
+}
+
+/**
+ * Convenience: attach both `session` and `status` subcommands in the order
+ * the SDK defaults use. Called by `createWorkflowCli` when
+ * `includeManagementCommands` is `true` (the default).
+ */
+export function addManagementCommands(
+  parent: Command,
+  scope: SessionScope = "workflow",
+): void {
+  addSessionSubcommand(parent, scope);
+  addStatusSubcommand(parent);
+}

package/src/sdk/registry.ts

@@ -0,0 +1,132 @@
+/**
+ * Workflow Registry — immutable, chainable registry of WorkflowDefinition objects.
+ *
+ * Key scheme: `${agent}/${name}` — each (agent, name) pair is unique.
+ * Registering the same key twice throws — no silent overwrites.
+ * `register()` is immutable: returns a new Registry, original is unchanged.
+ */
+
+import type { AgentType, Registry, RegistrableWorkflow, WorkflowDefinition } from "./types.ts";
+import { validateCopilotWorkflow } from "./providers/copilot.ts";
+import { validateOpenCodeWorkflow } from "./providers/opencode.ts";
+import { validateClaudeWorkflow } from "./providers/claude.ts";
+import type { ValidationWarning } from "./types.ts";
+
+// Registry type is declared in types.ts; re-export it from here for convenience.
+export type { Registry };
+
+// ─── Validator dispatch ──────────────────────────────────────────────────────
+
+/** Map agent type to its provider validator. */
+const providerValidators: Record<
+  AgentType,
+  (source: string) => ValidationWarning[]
+> = {
+  claude: validateClaudeWorkflow,
+  opencode: validateOpenCodeWorkflow,
+  copilot: validateCopilotWorkflow,
+};
+
+/**
+ * Run provider-specific source validation for a workflow definition.
+ *
+ * Derives source text from `wf.run.toString()` — the function body contains
+ * the SDK API calls the validators check via regex. Hard failures (thrown
+ * errors from the validator itself) propagate; warnings are returned.
+ */
+function runProviderValidation(wf: WorkflowDefinition): ValidationWarning[] {
+  const validator = providerValidators[wf.agent];
+  const source = wf.run.toString();
+  return validator(source);
+}
+
+/**
+ * Validate a single workflow definition at registration time.
+ * Throws on hard failures; logs warnings via console.warn with `[registry]` prefix.
+ */
+function validateAtRegistration(wf: WorkflowDefinition): void {
+  const warnings = runProviderValidation(wf);
+  for (const w of warnings) {
+    console.warn(
+      `[registry] workflow "${wf.agent}/${wf.name}" — ${w.rule}: ${w.message}`,
+    );
+  }
+}
+
+// ─── Implementation ──────────────────────────────────────────────────────────
+
+/**
+ * Internal implementation — typed separately from the public `Registry<T>`
+ * so the accumulating generic can be rebuilt on each `register()` call
+ * without leaking the implementation detail.
+ */
+class RegistryImpl<T extends Record<string, WorkflowDefinition>> {
+  /** Immutable snapshot of registered definitions, keyed by `${agent}/${name}`. */
+  private readonly map: ReadonlyMap<string, WorkflowDefinition>;
+
+  constructor(map: ReadonlyMap<string, WorkflowDefinition>) {
+    this.map = map;
+  }
+
+  register<W extends RegistrableWorkflow>(
+    wf: W,
+  ): Registry<T & Record<`${W["agent"]}/${W["name"]}`, W>> {
+    const key = `${wf.agent}/${wf.name}` as `${W["agent"]}/${W["name"]}`;
+
+    if (this.map.has(key)) {
+      throw new Error(
+        `[atomic] Duplicate workflow registration: "${key}" is already registered. ` +
+          `Each (agent, name) pair must be unique.`,
+      );
+    }
+
+    validateAtRegistration(wf);
+
+    const next = new Map(this.map);
+    next.set(key, wf);
+    return new RegistryImpl<T & Record<`${W["agent"]}/${W["name"]}`, W>>(next) as Registry<
+      T & Record<`${W["agent"]}/${W["name"]}`, W>
+    >;
+  }
+
+  get<K extends keyof T>(key: K): T[K] {
+    const entry = this.map.get(key as string);
+    if (!entry) {
+      throw new Error(`[atomic] Workflow "${String(key)}" is not registered.`);
+    }
+    return entry as T[K];
+  }
+
+  has(key: string): boolean {
+    return this.map.has(key);
+  }
+
+  list(): readonly WorkflowDefinition[] {
+    return Object.freeze(Array.from(this.map.values()));
+  }
+
+  resolve(name: string, agent: AgentType): WorkflowDefinition | undefined {
+    return this.map.get(`${agent}/${name}`);
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+/**
+ * Create an empty workflow registry.
+ *
+ * @example
+ * ```typescript
+ * import { createRegistry } from "@bastani/atomic/workflows";
+ * import { myWorkflow } from "./workflows/my-workflow.workflow";
+ *
+ * const registry = createRegistry()
+ *   .register(myWorkflow);
+ * ```
+ */
+export function createRegistry(): Registry<Record<string, never>> {
+  return new RegistryImpl<Record<string, never>>(new Map()) as Registry<Record<string, never>>;
+}
+
+// ─── Re-export validators for external use ───────────────────────────────────
+export { validateCopilotWorkflow, validateOpenCodeWorkflow, validateClaudeWorkflow };