@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/src/extension/workflow-module-loader.ts

@@ -8,135 +8,150 @@
 
 import { createJiti } from "jiti/static";
 import * as typeboxModule from "typebox";
-import * as workflowsSdkSurface from "../sdk-surface.js";
-import { isBrandedWorkflowDefinition } from "../authoring/workflow.js";
-import deepResearchCodebase from "../../builtin/deep-research-codebase.js";
+import adversarialVerification from "../../builtin/adversarial-verification.js";
+import classifyAndAct from "../../builtin/classify-and-act.js";
+import fanOutAndSynthesize from "../../builtin/fan-out-and-synthesize.js";
+import generateAndFilter from "../../builtin/generate-and-filter.js";
 import goal from "../../builtin/goal.js";
+import loopUntilDone from "../../builtin/loop-until-done.js";
 import openClaudeDesign from "../../builtin/open-claude-design.js";
 import ralph from "../../builtin/ralph.js";
+import tournament from "../../builtin/tournament.js";
+import { isBrandedWorkflowDefinition } from "../authoring/workflow.js";
+import * as workflowsSdkSurface from "../sdk-surface.js";
 
 const WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
 const WORKFLOWS_BUILTIN_MODULE_SPECIFIER = `${WORKFLOWS_MODULE_SPECIFIER}/builtin`;
 const TYPEBOX_MODULE_SPECIFIER = "typebox";
 // Keep this in sync with index.ts through sdk-surface.ts.
 const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
-  ...workflowsSdkSurface,
+	...workflowsSdkSurface,
 };
 const WORKFLOWS_BUILTIN_MODULE: Record<string, unknown> = {
-  deepResearchCodebase,
-  goal,
-  openClaudeDesign,
-  ralph,
+	adversarialVerification,
+	classifyAndAct,
+	fanOutAndSynthesize,
+	generateAndFilter,
+	goal,
+	loopUntilDone,
+	openClaudeDesign,
+	ralph,
+	tournament,
 };
 const TYPEBOX_MODULE: Record<string, unknown> = {
-  ...typeboxModule,
+	...typeboxModule,
 };
 const WORKFLOWS_VIRTUAL_MODULES: Record<string, unknown> = {
-  [WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
-  [WORKFLOWS_BUILTIN_MODULE_SPECIFIER]: WORKFLOWS_BUILTIN_MODULE,
-  [TYPEBOX_MODULE_SPECIFIER]: TYPEBOX_MODULE,
-  [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/deep-research-codebase`]: { default: deepResearchCodebase },
-  [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/goal`]: { default: goal },
-  [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/open-claude-design`]: { default: openClaudeDesign },
-  [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/ralph`]: { default: ralph },
+	[WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
+	[WORKFLOWS_BUILTIN_MODULE_SPECIFIER]: WORKFLOWS_BUILTIN_MODULE,
+	[TYPEBOX_MODULE_SPECIFIER]: TYPEBOX_MODULE,
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/adversarial-verification`]: { default: adversarialVerification },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/classify-and-act`]: { default: classifyAndAct },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/fan-out-and-synthesize`]: { default: fanOutAndSynthesize },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/generate-and-filter`]: { default: generateAndFilter },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/goal`]: { default: goal },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/loop-until-done`]: { default: loopUntilDone },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/open-claude-design`]: { default: openClaudeDesign },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/ralph`]: { default: ralph },
+	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/tournament`]: { default: tournament },
 };
 
 const workflowModuleLoader = createJiti(import.meta.url, {
-  moduleCache: false,
-  // Keep workflow-file import semantics deterministic: jiti owns .ts/.js/.mjs/.cjs
-  // resolution instead of handing some imports back to native import().
-  tryNative: false,
-  // Resolve the @bastani/workflows SDK (and its builtin submodules) to in-memory
-  // surfaces in every runtime. This mirrors the compiled bun binary path and
-  // keeps discovery fast: aliasing the SDK to its on-disk package re-evaluated
-  // the entire SDK module graph once per workflow file (moduleCache stays false),
-  // which scaled discovery to multiple seconds on projects with many workflow
-  // files. Workflow files themselves are still evaluated fresh from disk, so
-  // `/workflow reload` continues to observe edits.
-  virtualModules: WORKFLOWS_VIRTUAL_MODULES,
+	moduleCache: false,
+	// Keep workflow-file import semantics deterministic: jiti owns .ts/.js/.mjs/.cjs
+	// resolution instead of handing some imports back to native import().
+	tryNative: false,
+	// Resolve the @bastani/workflows SDK (and its builtin submodules) to in-memory
+	// surfaces in every runtime. This mirrors the compiled bun binary path and
+	// keeps discovery fast: aliasing the SDK to its on-disk package re-evaluated
+	// the entire SDK module graph once per workflow file (moduleCache stays false),
+	// which scaled discovery to multiple seconds on projects with many workflow
+	// files. Workflow files themselves are still evaluated fresh from disk, so
+	// `/workflow reload` continues to observe edits.
+	virtualModules: WORKFLOWS_VIRTUAL_MODULES,
 });
 
 function materializeModuleObject(mod: object): Record<string, unknown> {
-  const materialized: Record<string, unknown> = {};
-
-  // jiti's callable API can return an interop namespace proxy. Its own property
-  // descriptors contain the authored export values, but property access may apply
-  // default-export conveniences (and even expose a throwing inherited `then`
-  // getter for `export default null`). Copy own descriptors into a plain object
-  // so candidate collection sees the exact authored exports.
-  for (const key of Object.getOwnPropertyNames(mod)) {
-    const descriptor = Object.getOwnPropertyDescriptor(mod, key);
-    if (descriptor === undefined) continue;
-
-    const value = "value" in descriptor ? descriptor.value : descriptor.get?.call(mod);
-    Object.defineProperty(materialized, key, {
-      value,
-      enumerable: descriptor.enumerable,
-      configurable: true,
-      writable: true,
-    });
-  }
-
-  return materialized;
+	const materialized: Record<string, unknown> = {};
+
+	// jiti's callable API can return an interop namespace proxy. Its own property
+	// descriptors contain the authored export values, but property access may apply
+	// default-export conveniences (and even expose a throwing inherited `then`
+	// getter for `export default null`). Copy own descriptors into a plain object
+	// so candidate collection sees the exact authored exports.
+	for (const key of Object.getOwnPropertyNames(mod)) {
+		const descriptor = Object.getOwnPropertyDescriptor(mod, key);
+		if (descriptor === undefined) continue;
+
+		const value = "value" in descriptor ? descriptor.value : descriptor.get?.call(mod);
+		Object.defineProperty(materialized, key, {
+			value,
+			enumerable: descriptor.enumerable,
+			configurable: true,
+			writable: true,
+		});
+	}
+
+	return materialized;
 }
 
 function normalizeWorkflowModule(mod: unknown): Record<string, unknown> {
-  if (mod !== null && typeof mod === "object") {
-    return materializeModuleObject(mod);
-  }
-  // CJS/default interop can return the exported value directly; wrap it so the
-  // candidate collector can handle it the same way as an ESM default export.
-  return { default: mod };
+	if (mod !== null && typeof mod === "object") {
+		return materializeModuleObject(mod);
+	}
+	// CJS/default interop can return the exported value directly; wrap it so the
+	// candidate collector can handle it the same way as an ESM default export.
+	return { default: mod };
 }
 
 export interface WorkflowModuleCandidate {
-  readonly value: unknown;
-  readonly exportKey: string;
+	readonly value: unknown;
+	readonly exportKey: string;
 }
 
 export function validateWorkflowDefinitionShape(value: unknown): string | null {
-  if (value === null || typeof value !== "object") {
-    return "export is not an object";
-  }
-  const d = value as Record<string, unknown>;
-
-  if (d["__piWorkflow"] !== true) {
-    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from workflow({...})";
-  }
-  if (!isBrandedWorkflowDefinition(value)) {
-    return "workflow definition is not produced by workflow({...}); hand-rolled __piWorkflow objects are not supported";
-  }
-  if (typeof d["name"] !== "string" || (d["name"] as string).trim().length === 0) {
-    return "name must be a non-empty string";
-  }
-  if (typeof d["normalizedName"] !== "string" || (d["normalizedName"] as string).trim().length === 0) {
-    return "normalizedName must be a non-empty string";
-  }
-  if (typeof d["run"] !== "function") {
-    return "run must be a function";
-  }
-  return null;
+	if (value === null || typeof value !== "object") {
+		return "export is not an object";
+	}
+	const d = value as Record<string, unknown>;
+
+	if (d.__piWorkflow !== true) {
+		return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from workflow({...})";
+	}
+	if (!isBrandedWorkflowDefinition(value)) {
+		return "workflow definition is not produced by workflow({...}); hand-rolled __piWorkflow objects are not supported";
+	}
+	if (typeof d.name !== "string" || (d.name as string).trim().length === 0) {
+		return "name must be a non-empty string";
+	}
+	if (typeof d.normalizedName !== "string" || (d.normalizedName as string).trim().length === 0) {
+		return "normalizedName must be a non-empty string";
+	}
+	if (typeof d.run !== "function") {
+		return "run must be a function";
+	}
+	return null;
 }
 
 export function loadWorkflowModule(filePath: string): Record<string, unknown> {
-  return normalizeWorkflowModule(workflowModuleLoader(filePath));
+	return normalizeWorkflowModule(workflowModuleLoader(filePath));
 }
 
 export function collectWorkflowModuleCandidates(mod: Record<string, unknown>): WorkflowModuleCandidate[] {
-  const candidates: WorkflowModuleCandidate[] = [];
-
-  // Default export first (RFC §5.12: check mod.default before named exports)
-  if ("default" in mod && mod["default"] !== undefined) {
-    candidates.push({ value: mod["default"], exportKey: "default" });
-  }
-
-  // Then all named exports (a file may export multiple workflow definitions)
-  for (const [key, val] of Object.entries(mod)) {
-    if (key === "default") continue;
-    if (val !== undefined) {
-      candidates.push({ value: val, exportKey: key });
-    }
-  }
-
-  return candidates;
+	const candidates: WorkflowModuleCandidate[] = [];
+
+	// Default export first (RFC §5.12: check mod.default before named exports)
+	if ("default" in mod && mod.default !== undefined) {
+		candidates.push({ value: mod.default, exportKey: "default" });
+	}
+
+	// Then all named exports (a file may export multiple workflow definitions)
+	for (const [key, val] of Object.entries(mod)) {
+		if (key === "default") continue;
+		if (val !== undefined) {
+			candidates.push({ value: val, exportKey: key });
+		}
+	}
+
+	return candidates;
 }

package/dist/builtin/workflows/src/extension/workflow-policy.ts

@@ -1,15 +1,13 @@
 import {
-  INTERACTIVE_WORKFLOW_POLICY,
-  NON_INTERACTIVE_WORKFLOW_POLICY,
-  type WorkflowExecutionPolicy,
+	INTERACTIVE_WORKFLOW_POLICY,
+	NON_INTERACTIVE_WORKFLOW_POLICY,
+	type WorkflowExecutionPolicy,
 } from "../shared/types.js";
 
 export const WORKFLOW_NON_INTERACTIVE_MESSAGE =
-  "Workflows are policy-gated in non-interactive (-p) mode; deterministic workflows can run headlessly while runtime human input remains unavailable.";
+	"Workflows are policy-gated in non-interactive (-p) mode; deterministic workflows can run headlessly while runtime human input remains unavailable.";
 
-export function workflowPolicyFromContext(ctx?: {
-  readonly hasUI?: boolean;
-}): WorkflowExecutionPolicy {
-  if (ctx?.hasUI === false) return NON_INTERACTIVE_WORKFLOW_POLICY;
-  return INTERACTIVE_WORKFLOW_POLICY;
+export function workflowPolicyFromContext(ctx?: { readonly hasUI?: boolean }): WorkflowExecutionPolicy {
+	if (ctx?.hasUI === false) return NON_INTERACTIVE_WORKFLOW_POLICY;
+	return INTERACTIVE_WORKFLOW_POLICY;
 }

package/dist/builtin/workflows/src/extension/workflow-ports.ts

@@ -1,41 +1,37 @@
 import type { WorkflowMcpPort, WorkflowPersistencePort } from "../shared/types.js";
-import { clearMcpScope, setMcpScope, type PiEventBus, type PiMcpExtensionAPI } from "./mcp.js";
+import { clearMcpScope, type PiEventBus, type PiMcpExtensionAPI, setMcpScope } from "./mcp.js";
 import type { ExtensionAPI } from "./public-types.js";
 
-export function makePersistencePort(
-  pi: ExtensionAPI,
-  persistRuns: boolean,
-): WorkflowPersistencePort | undefined {
-  if (!persistRuns) return undefined;
-  if (typeof pi.appendEntry !== "function") return undefined;
-  const port: WorkflowPersistencePort = {
-    appendEntry: (type, payload) => pi.appendEntry!(type, payload),
-  };
-  if (typeof pi.setLabel === "function") {
-    port.setLabel = (entryId, label) => pi.setLabel!(entryId, label);
-  }
-  if (typeof pi.appendCustomMessageEntry === "function") {
-    port.appendCustomMessageEntry = (content, meta) =>
-      pi.appendCustomMessageEntry!(content, meta);
-  }
-  return port;
+export function makePersistencePort(pi: ExtensionAPI, persistRuns: boolean): WorkflowPersistencePort | undefined {
+	if (!persistRuns) return undefined;
+	if (typeof pi.appendEntry !== "function") return undefined;
+	const port: WorkflowPersistencePort = {
+		appendEntry: (type, payload) => pi.appendEntry!(type, payload),
+	};
+	if (typeof pi.setLabel === "function") {
+		port.setLabel = (entryId, label) => pi.setLabel!(entryId, label);
+	}
+	if (typeof pi.appendCustomMessageEntry === "function") {
+		port.appendCustomMessageEntry = (content, meta) => pi.appendCustomMessageEntry!(content, meta);
+	}
+	return port;
 }
 
 export function makeMcpPort(pi: ExtensionAPI): WorkflowMcpPort | undefined {
-  if (typeof pi.events?.emit !== "function") return undefined;
-  const piForMcp: PiMcpExtensionAPI = {
-    events: { emit: pi.events.emit as PiEventBus["emit"] },
-  };
-  return {
-    setScope(stageId: string, allow: string[] | null, deny: string[] | null) {
-      setMcpScope(piForMcp, {
-        stageId,
-        allow: allow ?? undefined,
-        deny: deny ?? undefined,
-      });
-    },
-    clearScope(stageId: string) {
-      clearMcpScope(piForMcp, stageId);
-    },
-  };
+	if (typeof pi.events?.emit !== "function") return undefined;
+	const piForMcp: PiMcpExtensionAPI = {
+		events: { emit: pi.events.emit as PiEventBus["emit"] },
+	};
+	return {
+		setScope(stageId: string, allow: string[] | null, deny: string[] | null) {
+			setMcpScope(piForMcp, {
+				stageId,
+				allow: allow ?? undefined,
+				deny: deny ?? undefined,
+			});
+		},
+		clearScope(stageId: string) {
+			clearMcpScope(piForMcp, stageId);
+		},
+	};
 }

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -1,35 +1,59 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
-  "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
-  "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; " +
-  "discover with list/get/inputs, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
-  "send prompt answers or steering, pause/resume/interrupt/quit runs, and reload workflow resources. " +
-  "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
-  "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
-  "quote the exact path without rewriting separators (Windows backslashes are valid), " +
-  "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
+	"Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
+	"when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; " +
+	"discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
+	"send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. " +
+	"For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
+	"For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
+	"quote the exact path without rewriting separators (Windows backslashes are valid), " +
+	"then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. " +
+	"Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. " +
+	"When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.";
 
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-  `**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows; when the task needs a graph that is not installed, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
-  - Decide the execution mode before your first tool call on a new request and state it in one short line: inline (tiny, deterministic, low-risk) or workflow. Reconnaissance counts as inline execution, so an unstated "explore first" default must not silently commit you to an unbounded inline session.
+	`**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows; when the task needs a graph that is not installed, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
   - Workflow fit check: prefer a workflow for implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file, or docs/code changes with validation; and whenever there are multiple steps, dependencies, handoffs, uncertainty, review/validation needs, long-running work, measurable done criteria, or an outcome that needs evidence.
   - Treat loop or stop-condition wording as a strong workflow signal, especially "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names an approval gate or evidence requirement.
-  - Do not force-fit an installed workflow or builtin such as \`goal\` or \`ralph\`. When another graph better matches the task, write a task-specific TypeScript workflow inline. Use and combine the documented starter patterns: Classify-and-act for runtime routing, Fan-out-and-synthesize for independent slices, Adversarial verification for worker/reviewer/reducer repair, Generate-and-filter or Tournament for competing candidates, and Loop until done for bounded convergence. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
-  - Compose workflows instead of rebuilding every capability in one graph. Workflow definitions are normal TypeScript modules: import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, then call \`ctx.workflow(childDefinition, { inputs, stageName })\`. Imported children may nest more workflows up to \`maxDepth\`; their stages, HIL prompts, control, durability, and declared outputs remain part of the expanded parent graph. Pass definitions, not registry-name strings or paths.
-  - Composition examples: import \`deepResearchCodebase\`, then conditionally nest \`goal\` or \`ralph\` for implementation; wrap \`openClaudeDesign\` with project-specific approval/export stages; or build a reusable user-defined research child and import it into several parent workflows. Prefer composing a proven builtin or shared child over copying its prompt/graph.
+  - Do not force-fit an installed workflow. When another graph better matches the task, write a task-specific TypeScript workflow inline. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
+  - Before launching any workflow for a non-trivial task, perform a short workflow-architecture pass. Derive implementation lifecycle needs, whole-codebase research needs, independent slices, competing strategies, exact API/type/build contracts, schema or generated-artifact contracts, state transitions/lifecycle behavior, deterministic stop conditions, and required evidence. Use a compact internal coverage matrix: \`requirement/risk | required evidence | workflow/stage that produces it | gap\`. Add the topology row \`acyclic topology | node/edge sketch for branches and loops | architecture pass | unresolved back-edge\`. Unresolved material rows or back-edges must change the graph before launch.
+  - In that architecture pass, sketch each branch, loop, and nested workflow boundary. Identify which stages repeat, require distinct tracked work for every iteration, name the current frontier before each repeat, reject self-edges and ancestor edges, compose nested workflows through \`ctx.workflow(...)\` boundaries rather than recursive \`run\` invocation, and preserve stable per-iteration identity and call order for resume/replay.
+  - Compare candidate workflows by guarantees, not broad objectives: run one named workflow only when it covers the lifecycle and produces evidence for every material requirement/risk. A generic implementation workflow may cover the lifecycle without covering exact API/type/build contracts, schemas/generated artifacts, state transitions, or domain-specific gates. Do not treat "has reviewers" as proof that a task-specific risk is covered.
+  - Use these routing signals without adding decorative stages: broad repository uncertainty → Fan-out-and-synthesize with repository-focused branches; independent slices → Fan-out-and-synthesize; plausible-but-wrong contract risk → Adversarial verification or a task-specific verification stage; competing architectures or implementations → Generate-and-filter or Tournament; an explicit repeat-until condition → Loop until done; implementation lifecycle → a task-specific worker/reviewer loop; exact API/build/schema requirements → dedicated deterministic gates.
+  - For a request containing several implementation items, enumerate every item before launch and classify it as independent, dependent, or clustered. Inspect stated issue/PR/branch dependencies, whether prerequisites are already merged into each selected base, and likely shared files, API contracts, migrations, generated artifacts, decisions, approvals, and release effects.
+  - Do not infer a cross-item sequence from list order or from "create a PR after" when "after" naturally refers to that item's own implementation/review/check/PR lifecycle. Prove the dependency before serializing independent workflow items; if a material dependency remains unclear after research, ask one grouped clarification.
+  - Run independent implementation items as separate concurrent top-level named workflow runs with bounded concurrency. Give each item its own explicitly supported worktree path, branch, run ID, root lifecycle, and failure boundary, then report an item → run ID → worktree → branch → result/PR map. Compose or sequence only real dependencies; run independent clusters in parallel and preserve ordering inside each cluster.
+  - For a mixed queue with dependent A → B and unrelated C, compose only the A → B dependency cluster. Launch C as its own concurrent top-level named workflow with its own root failure boundary. One real cross-item dependency does not put the whole queue in one parent.
+  - A first item's review, repair, or check failure must not block unrelated items. Keep other top-level runs active, report the failed item separately, and fill an open dispatcher slot when policy permits. Several worktrees inside one sequential root provide checkout isolation, not concurrent top-level execution or independent root failure boundaries.
+  - A first named workflow launch commits the selected execution shape for the turn. For one task, end after the single launch. For an independent queue, issue the complete bounded wave of planned per-item top-level launches before ending the turn; do not casually chain unplanned unrelated launches. Each top-level run keeps an independent root lifecycle and failure boundary. When one task needs multiple capabilities or one dependency cluster needs ordered handoffs, design one custom parent before launch for that task or cluster, import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, and compose them with \`ctx.workflow(childDefinition, { inputs, stageName })\`. Keep unrelated queue items out of that parent. Imported children may nest more workflows up to \`maxDepth\`; their stages, HIL prompts, control, durability, and declared outputs remain part of the expanded parent graph and root failure boundary. Pass definitions, not registry-name strings or paths.
+  - Workflow definitions are normal TypeScript modules. Composition examples: nest \`fanOutAndSynthesize\` for repository mapping; wrap \`openClaudeDesign\` with project-specific approval/export stages; or build a reusable user-defined research child and import it into several parent workflows. Map typed inputs and consume only declared outputs.
+  - When plausible-but-wrong behavior is a material risk in an arbitrary task-specific workflow, prefer a bounded evidence-backed adversarial loop. Give a fresh-context grumpy/skeptical-but-fair reviewer the literal objective and require actionable, evidence-backed falsification probes without invented requirements. Have it emit a structured verifier plan containing each exact probe, inputs, command/assertion, expected success condition, and requirement/risk covered.
+  - Support both verifier shapes: for explicit known contracts, author direct task-specific \`ctx.tool(...)\` gates before launch; for risks requiring adversarial discovery, let the model select high-value probes through structured output, then execute the selected compile, test, schema generation/validation, runtime, or artifact-inspection checks authoritatively through durable \`ctx.tool(...)\` calls. Actual tool results—not model self-report—must feed skeptical evaluation, consolidated evidence-backed repair findings, and reruns after the implementation child repairs them.
+  - Define bounded pass, repair, failure, and iteration-limit conditions before launch. Use \`ctx.tool\` for workflow-owned external checks and side effects whose results should be durably checkpointed. Each \`ctx.tool\` call is tracked as a durable, non-chat graph node and may run before, between, after, or without model stages; a tool-only workflow is valid tracked execution; keep pure transformations as ordinary TypeScript, and do not wrap every model-stage action in a tool call.
+  - Choose the cheapest graph that covers every material coverage row. Avoid decorative composition and duplicated research or review loops. Prefer composing a proven builtin or shared child over copying its prompt/graph.
+  - Before the first launch, state the selected graph, why one broad builtin is sufficient or insufficient, the evidence each major stage produces, and the stop/repair conditions. A simple direct match may use one sentence; a composed graph must briefly name its children and task-specific gates. For a custom adversarial loop, also name the skeptical reviewer, deterministic \`ctx.tool\` verifier gates, how model-selected plans become tool executions, and how failures reach bounded repair.
   - Example custom shapes: classify a request and dispatch category-specific stages; fan out per package and synthesize artifact-backed results; implement, run fresh-context verifiers, reduce findings, and loop through repairs until approved; generate several plans and filter or tournament-rank them; or rerun checks and fixes until green with a progress ledger and max-iteration escape hatch.
   - Budget reconnaissance: once workflow fit is clear, keep pre-workflow exploration to a few quick reads that sharpen the objective and validation criteria. Put deep research, upstream/design comparison, and behavior probing inside the workflow. Pass large context through files/artifacts and \`reads\` rather than injecting it into prompts.
   - Course-correct instead of drifting: after roughly ten exploratory tool calls with no artifact, edit, or commit, or repeated "let me verify one more thing" loops, stop, write findings to a context file, and hand the task to the best-fit named or custom workflow. Sunk inline research transfers through files; it is not a reason to stay inline.
   - Only skip workflows for tiny, deterministic, low-risk answers or direct edits where stage tracking clearly costs more than it adds, typically a single-file/no-test/no-review change or a simple answer.`,
-  `**Workflow discovery and lifecycle**:
+	`**Workflow discovery and lifecycle**:
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
   - In interactive chat, named workflow launches run in the background. Run \`/workflow connect <run>\` to see agents working and chat with and steer each stage. Inspection and control calls (\`status\`, \`stages\`, \`stage\`, \`transcript\`, \`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`quit\`) remain available while work runs.
-  - Natural-language instructions to create or use a worktree do not enable runner isolation. A named workflow must declare and implement any worktree inputs it supports; inspect its inputs before launching it.
-  - Once you run a workflow, end the current turn and wait for user input or a lifecycle notice. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`quit\` only to answer, steer, or honor control requests.
+  - \`workflow send\` is nonterminal-only: once the authoritative root run has completed, failed, skipped, been cancelled or killed, or ended terminal-blocked, start a new workflow if tracked work remains. Proceed inline only when the remaining task is small, deterministic, and low risk. Use explicit \`/workflow attach <run> <stage>\` for user-driven post-mortem chat; it does not resume or modify workflow execution.
+  - Natural-language instructions to create or use a worktree do not enable runner isolation. A named workflow must declare and implement any worktree and feature-branch inputs it supports; inspect its inputs and pass a distinct path and branch for each concurrent item. Reusable \`baseBranch\` binding creates a missing target as a detached checkout from that base or reuses an existing same-repository worktree as-is; neither case checks out a separate feature-branch input.
+  - Once you have started the selected single run or every run in the selected bounded wave, end the current turn and wait for user input or lifecycle notices. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`quit\` only to answer, steer, or honor control requests.
   - For transcripts, avoid whole-file reads. Get \`sessionFile\`/\`transcriptPath\` from \`stages\` or \`stage\`, preserve the exact path and platform separators, search with \`rg\`/\`grep\`, and read small relevant ranges; use explicit \`tail\` or \`limit\` only for a bounded preview.`,
-  `**Workflow authoring and handoffs**:
+	`**Workflow authoring and handoffs**:
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
+  - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
+  - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done) when designing a stage graph.
   - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
+  - Atomic \`workflow({ run })\` definitions are imperative, dynamic TypeScript. Discovery validates module loading, imports, and definition shape, including schemas and the \`run\` function, but it does not compile \`run\` into a complete graph or prove acyclicity. Runtime inputs, branches, loops, files, network data, model or human output, helpers, and nested workflows determine the materialized graph during execution.
+  - Cyclic workflow graphs are unsupported. Workflow authors and coding agents MUST NOT create self-edges or dependency edges from the current frontier to an existing ancestor. Every materialized execution topology must remain a DAG. Redesign or stop before launch if a cycle cannot be removed.
+  - Bounded loops must create distinct tracked work for every iteration; never reopen an ancestor below its downstream work. If a retained session receives follow-up without new dependency work, keep it as non-topological activity metadata rather than adding a back-edge. Before launch, sketch nodes and dependencies for every branch and loop and reject any proposed parent edge to the node itself or an ancestor.
+  - Treat dynamic graph validation during execution, replay, and DBOS hydration as the authoritative cycle boundary. If runtime topology code changes, require incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace those runtime checks.
+  - Every workflow invocation automatically receives one stable, non-default Intercom group. Intercom-capable stages inherit it, nested workflows keep the top-level invocation group, and subagents inherit their launching stage's group. Do not mint or thread group names through ordinary workflow definitions. Use an explicit \`group\` only for an intentional override: a named group or \`group: true\` creates a subgroup, while \`group: "default"\` opts into the shared default group. Stages without Intercom access receive no group, and \`contact_supervisor\` still crosses group boundaries for authorized escalation.
+  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
   - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,

package/dist/builtin/workflows/src/extension/workflow-reload-coordinator.ts

@@ -1,25 +1,25 @@
 import type { WorkflowReloadReport } from "./workflow-reload-report.js";
 
 type ReloadBatch = {
-  readonly discoveryGeneration: number;
-  requestCount: number;
-  readonly promise: Promise<WorkflowReloadReport>;
-  readonly resolve: (report: WorkflowReloadReport) => void;
-  readonly reject: (error: Error) => void;
+	readonly discoveryGeneration: number;
+	requestCount: number;
+	readonly promise: Promise<WorkflowReloadReport>;
+	readonly resolve: (report: WorkflowReloadReport) => void;
+	readonly reject: (error: Error) => void;
 };
 
 export interface WorkflowReloadCoordinator {
-  request(discoveryGeneration: number): Promise<WorkflowReloadReport>;
+	request(discoveryGeneration: number): Promise<WorkflowReloadReport>;
 }
 
 function createBatch(discoveryGeneration: number): ReloadBatch {
-  let resolve: (report: WorkflowReloadReport) => void = () => undefined;
-  let reject: (error: Error) => void = () => undefined;
-  const promise = new Promise<WorkflowReloadReport>((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = (error) => rejectPromise(error);
-  });
-  return { discoveryGeneration, requestCount: 0, promise, resolve, reject };
+	let resolve: (report: WorkflowReloadReport) => void = () => undefined;
+	let reject: (error: Error) => void = () => undefined;
+	const promise = new Promise<WorkflowReloadReport>((resolvePromise, rejectPromise) => {
+		resolve = resolvePromise;
+		reject = (error) => rejectPromise(error);
+	});
+	return { discoveryGeneration, requestCount: 0, promise, resolve, reject };
 }
 
 /**
@@ -27,40 +27,40 @@ function createBatch(discoveryGeneration: number): ReloadBatch {
  * from the same session generation; generation boundaries remain ordered.
  */
 export function createWorkflowReloadCoordinator(
-  reload: (discoveryGeneration: number, coalescedRequests: number) => Promise<WorkflowReloadReport>,
+	reload: (discoveryGeneration: number, coalescedRequests: number) => Promise<WorkflowReloadReport>,
 ): WorkflowReloadCoordinator {
-  const pending: ReloadBatch[] = [];
-  let draining = false;
+	const pending: ReloadBatch[] = [];
+	let draining = false;
 
-  const drain = async (): Promise<void> => {
-    if (draining) return;
-    draining = true;
-    try {
-      while (pending.length > 0) {
-        const batch = pending.shift()!;
-        try {
-          const report = await reload(batch.discoveryGeneration, batch.requestCount);
-          batch.resolve(report);
-        } catch (error) {
-          batch.reject(error instanceof Error ? error : new Error(String(error)));
-        }
-      }
-    } finally {
-      draining = false;
-      if (pending.length > 0) void drain();
-    }
-  };
+	const drain = async (): Promise<void> => {
+		if (draining) return;
+		draining = true;
+		try {
+			while (pending.length > 0) {
+				const batch = pending.shift()!;
+				try {
+					const report = await reload(batch.discoveryGeneration, batch.requestCount);
+					batch.resolve(report);
+				} catch (error) {
+					batch.reject(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+		} finally {
+			draining = false;
+			if (pending.length > 0) void drain();
+		}
+	};
 
-  return {
-    request(discoveryGeneration): Promise<WorkflowReloadReport> {
-      let batch = pending.at(-1);
-      if (batch?.discoveryGeneration !== discoveryGeneration) {
-        batch = createBatch(discoveryGeneration);
-        pending.push(batch);
-      }
-      batch.requestCount += 1;
-      queueMicrotask(() => void drain());
-      return batch.promise;
-    },
-  };
+	return {
+		request(discoveryGeneration): Promise<WorkflowReloadReport> {
+			let batch = pending.at(-1);
+			if (batch?.discoveryGeneration !== discoveryGeneration) {
+				batch = createBatch(discoveryGeneration);
+				pending.push(batch);
+			}
+			batch.requestCount += 1;
+			queueMicrotask(() => void drain());
+			return batch.promise;
+		},
+	};
 }