​

Reliable Workflow Design

​

Choosing an Execution Shape

Multi-item routing rule: Enumerate requested implementation items and prove their dependencies before launch. Run independent items as separate concurrent top-level workflow runs with bounded concurrency, one explicit worktree and root failure boundary per item. Preserve ordered composition only for real code, artifact, contract, decision, approval, or merged-result dependencies.

​

The self-prompt: pre-launch workflow architecture

requirement/risk | required evidence | workflow/stage that produces it | gap

acyclic topology | node/edge sketch for branches and loops | architecture pass | unresolved back-edge

1. Which stages may repeat?
2. Does each iteration create distinct tracked work?
3. What is the current frontier before each repeated stage?
4. Could any proposed parent edge target an ancestor or the node itself?
5. Are nested child workflows composed through boundaries rather than recursive run invocation?
6. Does resume/replay rely on stable per-iteration identity and call order?

1. Is the outcome provable? If success can be stated as evidence (tests green, artifact exists, behavior demonstrated, reviewer approves), the task fits a workflow. If no proof is possible or needed, inline is probably fine.
2. Is there structure? Multiple subtasks, dependencies, handoffs, or parallel slices rule out inline execution. A single focused evidence-gathering pass does not.
3. Is there a loop or gate? Any “until Y”, “fix until passing”, review/approval gate, or unknown-length repair cycle requires a workflow that enforces the stop condition, never an improvised inline retry loop or an overextended subagent call.
4. Is it one task or a queue of tasks? “Address all open issues” or “fix every ticket assigned to me” is a factory request, not one workflow. Enumerate and dependency-classify the items first, then follow Task queues and software factories: independent items become bounded concurrent top-level per-item runs; dependent items share one ordered composed graph; independent dependency clusters become separate top-level runs.
5. Does an installed graph supply complete coverage? Run a named workflow only if its objective, inputs, lifecycle, and produced evidence cover every material row. Do not force-fit a broad-but-partial match (When to Use Workflows).
6. What routing signals shape the graph? Broad repository uncertainty points to repository-focused Fan-out-and-synthesize; independent slices to Fan-out-and-synthesize; plausible-but-wrong contract risk to Adversarial verification or a task-specific verification stage; competing architectures or implementations to Generate-and-filter or Tournament; an explicit repeat-until condition to Loop until done; implementation work to a task-specific worker/reviewer loop; and exact API/build/schema requirements to dedicated deterministic gates.
7. Does a tested graph solve only part of the task? Author one custom parent and nest that definition with ctx.workflow(...), placing the missing research, verification, or deterministic gates around it instead of copying its prompts and gates.
8. Is it only specialist evidence-gathering? If the parent keeps control, no completion gate is needed, and the work is bounded (a debug pass, a parallel research fanout, one noisy investigation), inline subagents are enough—and cheaper than a workflow.
9. Is it truly tiny? Deterministic, low-risk, single-file/no-test/no-review—answer or edit inline and stop.

​

Stage model and thinking-level assignment

Stage | Model | Thinking | Role
map | <catalog fullId> | high | codebase mapping
approve | <catalog fullId> | max | final approval
report | <catalog fullId> | medium | final reporting
tests | — | — | deterministic check (tool node)

1. Give a fresh-context, grumpy/skeptical-but-fair reviewer the literal objective. It should aggressively seek realistic counterexamples without inventing requirements or accepting hand-waving and circular worker-authored evidence, then emit a structured verifier plan: exact probe, inputs, command/assertion, expected success condition, and requirement/risk covered.
2. For known contracts, author direct task-specific ctx.tool(...) gates up front. For adversarially discovered risks, let the model select high-value probes in structured output, but execute the selected compile, test, schema generation/validation, runtime, and artifact-inspection checks authoritatively through durable workflow-owned ctx.tool(...) calls. The model must not self-report outcomes.
3. Feed the actual tool results to a skeptical evaluation stage. It classifies failures and emits one consolidated, evidence-backed, bounded repair payload for the implementation child.
4. After repair, rerun the deterministic verifier tools until the declared pass condition succeeds or the iteration budget is exhausted. Define pass, repair, failure, and iteration-limit conditions before launch.

​

Judging task complexity

• Done-condition test: if the success condition does not fit in one sentence, the task is complex or underspecified — clarify before guessing.
• The “and” test: “fix X and update docs and add a test” is three tasks in one sentence; enumerate and classify each.
• Loop words: “until it passes”, “keep trying” make the task at least moderate — iteration is expected.
• Working-memory test: more than about three interacting constraints at once means complex.

1. Two or more distinct phases with a real handoff (research → implement, implement → verify), not just steps.
2. The done-condition needs proof — tests, builds, review, or a contract check. If “how do you know it works?” is a fair question, a verification stage is waiting to exist.
3. Iteration is expected — an anticipated repair loop, not a straight line.
4. Failure cost is high — even a one-line change gets adversarial verification.
5. The work outlives one attention span — losing mid-task state is a real risk.

​

Scoring rubric

• 0–3 total: inline. Adding stages creates more work than value.
• 4–6 total, Iteration ≤ 1, no gate: inline subagents when the parent should retain control, or a small named/custom workflow when tracking and artifacts matter.
• 7+ total, or Iteration = 2, or Verifiability = 2 with a review/approval gate: a real workflow. Prefer a named workflow when one fits the whole task; otherwise author a custom graph, nesting proven children where sub-problems overlap.
• Any single hard signal overrides the arithmetic: an explicit loop/stop condition, an approval or evidence gate, or a request for durable/background execution puts the task in workflow territory regardless of total score.

​

Task queues and software factories

1. Enumerate every requested item.
2. Inspect stated issue, PR, branch, and approval dependencies.
3. Check whether each prerequisite is already merged into the base each run will use. A merged prerequisite does not serialize current items when every base contains it. An unmerged prerequisite delays only the item or dependency cluster that consumes it; unrelated items remain eligible for separate concurrent workflow runs under the queue’s bound.
4. Check likely shared files, API contracts, migrations, generated artifacts, and release or deployment effects. A shared unmerged contract can create a dependency even when items edit different files.
5. Classify items as independent, dependent, or clustered.
6. Dispatch independent items or clusters concurrently with an explicit concurrency bound; preserve dependency order inside each cluster.
7. Report an item → run ID → worktree → branch → result/PR map. After each terminal lifecycle notice, inspect that run’s status detail before updating its result/PR fields.

// .atomic/workflows/issue-to-pr.ts
import { spawnSync } from "node:child_process";
import { workflow } from "@bastani/atomic/workflows";
import { Type, type Static } from "typebox";

const reviewDecision = Type.Object(
  {
    approved: Type.Boolean(),
    findings: Type.Array(Type.String()),
  },
  { additionalProperties: false },
);

function spawnCommand(argv: readonly string[], cwd: string) {
  const [command, ...args] = argv;
  if (command === undefined) throw new Error("spawnCommand requires a command");
  const result = spawnSync(command, args, { cwd, encoding: "utf8" });
  // A command that could not be spawned at all arrives on `error` with a null
  // status, so it has to be raised here or it reads as an ordinary failure.
  if (result.error) throw result.error;
  return result;
}

function runCommand(argv: readonly string[], cwd: string): string {
  const result = spawnCommand(argv, cwd);
  const stdout = (result.stdout ?? "").trim();
  const stderr = (result.stderr ?? "").trim();
  if (result.status !== 0) {
    throw new Error(`${argv.join(" ")} failed (${result.status})\n${stderr || stdout}`);
  }
  return stdout;
}

export default workflow({
  name: "issue-to-pr",
  description: "Implement, review, check, and open one issue PR in its own worktree.",
  inputs: {
    issue: Type.String(),
    git_worktree_dir: Type.String(),
    base_ref: Type.String({ default: "origin/main" }),
    pr_base: Type.String({ default: "main" }),
    branch: Type.String(),
    checks: Type.Array(Type.Array(Type.String(), { minItems: 1 }), { minItems: 1 }),
  },
  outputs: {
    result: Type.String(),
    pr_url: Type.String(),
    branch: Type.String(),
    worktree: Type.String(),
  },
  worktreeFromInputs: { gitWorktreeDir: "git_worktree_dir", baseBranch: "base_ref" },
  run: async (ctx) => {
    const { issue, branch, checks } = ctx.inputs;
    const cwd = ctx.cwd ?? ctx.inputs.git_worktree_dir;
    const baseRef = ctx.inputs.base_ref;

    await ctx.tool("select-feature-branch", { branch, base_ref: baseRef }, async () => {
      const probe = spawnCommand(
        ["git", "show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
        cwd,
      );
      if (probe.status === 0) return runCommand(["git", "switch", branch], cwd);
      if (probe.status !== 1) throw new Error((probe.stderr ?? "").trim());
      return runCommand(["git", "switch", "-c", branch, baseRef], cwd);
    });

    await ctx.task("implement", {
      context: "fork",
      prompt: [
        `Implement ${issue}.`,
        "Add or update tests, make the smallest correct change, and commit all changes.",
        "Do not create the PR; this workflow does that only after review and checks pass.",
      ].join("\n"),
    });

    let approved = false;
    for (let round = 1; round <= 2; round += 1) {
      const review = await ctx.task(`review-${round}`, {
        context: "fresh",
        schema: reviewDecision,
        prompt: [
          `Review the current ${branch} diff against ${baseRef} for ${issue}.`,
          "Inspect the code and tests. Approve only when the issue is fully met and the patch is safe.",
          "Return structured_output with approved and evidence-backed findings.",
        ].join("\n"),
      });
      const decision = review.structured as Static<typeof reviewDecision>;
      if (decision.approved) {
        approved = true;
        break;
      }
      if (round === 2) {
        throw new Error(`review bound exhausted: ${decision.findings.join("; ")}`);
      }
      await ctx.task(`repair-${round}`, {
        context: "fork",
        prompt: [
          `Repair ${issue} on ${branch}.`,
          ...decision.findings.map((finding) => `- ${finding}`),
          "Run relevant checks and commit the repair. Do not create a PR.",
        ].join("\n"),
      });
    }
    if (!approved) throw new Error("review did not approve the patch");

    await ctx.tool("require-clean-commit", { branch }, async () => {
      const pending = runCommand(["git", "status", "--porcelain"], cwd);
      if (pending !== "") throw new Error("implementation left uncommitted changes");
      return { commit: runCommand(["git", "rev-parse", "HEAD"], cwd) };
    });

    for (const [index, argv] of checks.entries()) {
      await ctx.tool(`check-${index + 1}`, { argv }, async () => runCommand(argv, cwd));
    }

    await ctx.tool("push-feature-branch", { branch }, async () =>
      runCommand(["git", "push", "--set-upstream", "origin", branch], cwd),
    );
    const prUrl = await ctx.tool("create-pr", { issue, branch, base: ctx.inputs.pr_base }, async () =>
      runCommand(
        ["gh", "pr", "create", "--base", ctx.inputs.pr_base, "--head", branch, "--title", issue, "--body", `Implements ${issue}.`],
        cwd,
      ),
    );

    return {
      result: `completed ${issue}`,
      pr_url: prUrl,
      branch,
      worktree: cwd,
    };
  },
});

workflow({
  action: "run",
  workflow: "issue-to-pr",
  inputs: {
    issue: "#2101 fix cache-key normalization",
    git_worktree_dir: "../atomic-issue-2101",
    base_ref: "origin/main",
    pr_base: "main",
    branch: "fix/2101-cache-key",
    checks: [["bun", "test", "test/unit/cache-key.test.ts"]],
  },
})

workflow({
  action: "run",
  workflow: "issue-to-pr",
  inputs: {
    issue: "#2102 correct CLI help output",
    git_worktree_dir: "../atomic-issue-2102",
    base_ref: "origin/main",
    pr_base: "main",
    branch: "fix/2102-cli-help",
    checks: [["bun", "test", "test/unit/cli-help.test.ts"]],
  },
})

workflow({ action: "status", runId: "<run-id-for-#2101>", format: "json" })
workflow({ action: "status", runId: "<run-id-for-#2102>", format: "json" })

​

Prompting the choice

• Name the shape or installed workflow. “Do this inline”, “use subagents to investigate”, or “write a custom workflow for this” overrides automatic scoring.
• State acceptance criteria. Verbatim criteria make the objective provable and define reviewer and reducer contracts.
• State the loop. “Iterate until tests pass” or “review and fix until approved” defines a hard workflow stop condition.
• State the evidence. A QA video, test output, generated artifact, or reviewer sign-off tells the graph which gates it needs.
• State the boundary. “Work in a separate worktree”, “do not create a PR”, or “stop after implementation” separates implementation from final actions.
• State the queue policy. Say how to split, order, isolate, and bound queued items; otherwise Atomic runs the dependency-triage and bounded-dispatch playbook before implementation. Ordinary list order and per-item “create a PR after” wording do not create a cross-item dependency.

​

The Run Contract

​

Only the user may change the contract

• You may amend it at any time. A mid-run message — steering, a follow-up, resume text — is authoritative. If you say “also handle the detached path,” that is a new requirement, and the run adopts it from that moment.
• Agents may not amend it at all. An implementer that notices a nearby bug, a cleaner abstraction, or a missing feature has found deferred work, not a new criterion. It records the observation and keeps building to the contract.

​

Amendments must reach the next stage

You steer the implementation stage to add a requirement. The implementer adopts it and builds it. The reviewers were launched with the original criteria, so they score the added work as unrequested scope and the original criteria as contradicted. The run then burns review loops arguing about a contract mismatch nobody can see.

• Restate every objective-relevant steering message in your report or handoff artifact, under an explicit Contract amendments received heading, verbatim when short.
• Keep user-authored amendments visibly separate from your own observations, so the next stage can tell a required clause from an agent proposal.
• Treat amendments inherited from an upstream stage as contract clauses. Cover them in acceptance and traceability work; never classify them as out-of-scope.
• Resolve ambiguity before implementing. Use intercom to ask the supervisor or originating stage when one is reachable; otherwise state the conflict and implement the narrowest reading consistent with the launch contract.
• Propagate nothing else this way. Tool preferences, working style, and your own ideas are not amendments.

import { withSteeringPropagationContext } from "@bastani/atomic/workflows/builtin/steering-context";

export default workflow({
  name: "my-workflow",
  // ...
  run: async (ctx) => await runMyWorkflow(withSteeringPropagationContext(ctx)),
});

​

Scope discipline

Before writing code, state the goal in one sentence and list the acceptance criteria. That list is the contract. Freeze it.

• Done means the contract, not “good.” When all criteria pass, stop. Polish, refactors, and “while I’m here” fixes are new work, not this work.
• Every addition must trace to a criterion. If you cannot point at the criterion a change serves, do not make it. Log it instead.
• Keep a deferred list, not a growing diff. When you notice a bug, smell, or missing feature outside the contract, write one line in a deferred note and move on. Surface it at the end.
• Distinguish blockers from improvements. Change scope only if a criterion is impossible or wrong as written — and say so explicitly before proceeding, rather than silently absorbing the work.
• Watch for the tells. “It would be cleaner if…”, “we should also…”, “this really ought to…” mean you are about to move the goalpost. Stop and check the contract.
• Prefer the smallest diff that satisfies the contract. Fewer files touched, fewer abstractions introduced, no speculative generality for futures nobody asked for.

​

Protect the contract from compaction

import { keepContext, workflow } from "@bastani/atomic/workflows";

const prompt = [
  keepContext("Research only. Do not implement code changes."),
  `Investigate: ${ctx.inputs.question}`,
].join("\n\n");

• role constraints that bound a stage to part of the work — “research only”, “review and report, do not repair”;
• acceptance criteria and immutable contracts a later stage is judged against;
• explicit prohibitions;
• identifiers a stage must not lose, such as a target branch, worktree path, or run ID.

​

Tagging is not only for workflow authors

workflow({ action: "run", workflow: "ralph", inputs: {
  prompt: "<keepContext>\nResearch and implement issue #2170. Do not touch the release pipeline.\n</keepContext>\n\n" + issueBody,
  acceptance_criteria: "<keepContext>\n1. ...\n2. ...\n</keepContext>",
}})

intercom({ action: "send", to: "workflow:<rootRunId>/<stage>", message:
  "<keepContext>\nNew requirement: the fix must not change the public API.\n</keepContext>" })

​

Practical consequences

• Steer freely — it is the supported amendment channel. You do not need to restart a run to add a requirement.
• Say what you mean as a requirement. “It would be nice if…” reads as guidance; “also handle X” reads as a clause. Stages are told to distinguish them.
• Expect amendments in the reports. If a stage received one and its report has no Contract amendments received section, the amendment did not propagate and downstream stages will not honor it.
• A growing diff with no new criteria is a defect. That is the tell that scope discipline slipped, and it is a legitimate reason to stop a run.

​

Scope-Guard Starter Pattern

​

Canonical scope contract

• the literal objective;
• required scope and allowed files or systems;
• explicit non-goals;
• stage boundaries and expected lifecycle order; and
• acceptance criteria and required evidence.

​

Decision contract and actions

​

Fallback policy

​

Lifecycle, topology, and context rules

• Keep the graph acyclic. A boundary guard is an ordinary downstream reviewer node. Live Intercom steering is activity inside already-running parallel stages, not a new graph edge.
• Never make a guard watch itself, recursively start another guard, reopen a terminal task, or add a dependency from the current frontier to an ancestor. Complete all turns on a retained guard before starting downstream dependency work.
• Messages admitted before a worker generation closes drain through that stage boundary. Late messages do not reopen or mutate its terminal workflow state. Give each live branch a bounded stop rule; ctx.parallel(...) releases downstream work only after all started branches settle, even when one finishes first.
• Persist decisions under stable keys. Pause/resume, model fallback, durable replay, and nested workflows then reread the artifact instead of sending duplicate interventions.
• Omit group for ordinary use. The worker, guard, nested workflows, and delegated subagents inherit the top-level workflow invocation’s stable Intercom group. Set an explicit group only for intentional isolation; an override isolates that stage from ordinary same-group peers while leaving it steerable from the invocation context, which retains directional list/send/live-ask control over the subgroups it owns.
• Use context: "fresh" for guards, reviewers, and judges. They should see only the contract, candidate, decision artifacts, and current files.
• Use context: "fork" plus forkFromSessionFile for implementation, debugging, and repair roles that need continuity with an owned earlier session. context: "fork" alone does not name a fork source; an initial worker with no prior lineage may start fresh. A later continuation should use the earlier worker’s sessionFile when available. Do not fork an independent guard from the worker it judges.
• Send a forked continuation only the delta after the fork point: new evidence, the decision artifact, any human answer, and the next action. Keep the full shared contract in its canonical file.

​

Runnable boundary-task example

// .atomic/workflows/scope-guard-boundary.ts
import { workflow } from "@bastani/atomic/workflows";
import { Type, type Static } from "typebox";

const decisionLogSchema = Type.Object(
  {
    decisions: Type.Array(
      Type.Object(
        {
          key: Type.String(),
          classification: Type.Union([
            Type.Literal("required"),
            Type.Literal("dependent"),
            Type.Literal("follow-up"),
            Type.Literal("unclear"),
          ]),
          evidence: Type.Array(Type.String(), { minItems: 1 }),
          action: Type.String(),
        },
        { additionalProperties: false },
      ),
      { maxItems: 20 },
    ),
  },
  { additionalProperties: false },
);

type DecisionLog = Static<typeof decisionLogSchema>;

function continueWorker(sessionFile: string | undefined) {
  return sessionFile === undefined
    ? { context: "fork" as const }
    : { context: "fork" as const, forkFromSessionFile: sessionFile };
}

export default workflow({
  name: "scope-guard-boundary",
  description: "Check scope at an implementation boundary.",
  inputs: {
    scope_contract: Type.String(),
    artifact_dir: Type.String({ default: ".atomic/workflows/runs/scope-guard-boundary" }),
  },
  outputs: {
    decision_log: Type.String(),
  },
  run: async (ctx) => {
    const contract = ctx.inputs.scope_contract;
    const candidate = `${ctx.inputs.artifact_dir}/candidate.md`;
    const decisionLog = `${ctx.inputs.artifact_dir}/scope-decisions.json`;

    const worker = await ctx.task("prepare candidate", {
      context: "fresh",
      reads: [contract],
      prompt: [
        `Read the immutable scope contract at ${contract}.`,
        "Implement only the required scope and summarize changed files and evidence.",
        "Do not implement valid adjacent findings; include them in the candidate summary.",
      ].join("\n"),
      output: candidate,
      outputMode: "file-only",
    });

    const checked = await ctx.task("scope boundary", {
      context: "fresh",
      reads: [contract, candidate],
      schema: decisionLogSchema,
      prompt: [
        `Read ${contract} and ${candidate}. Inspect the current candidate.`,
        "Classify each material expansion as required, dependent, follow-up, or unclear.",
        "Cite concrete evidence and state the action. Return at most 20 unique keys.",
        "Follow-up work must not block. Unclear expansion requires a human decision.",
        "Judge scope only; do not approve implementation correctness.",
      ].join("\n"),
      output: decisionLog,
      outputMode: "file-only",
    });

    if (checked.structured === undefined) throw new Error("scope guard returned no decision log");
    const decisions = checked.structured as DecisionLog;
    const unclear = decisions.decisions.filter((item) => item.classification === "unclear");
    const humanDecision = unclear.length === 0
      ? "No unclear scope decisions."
      : await ctx.ui.editor([
          "Resolve these scope decisions before the worker continues:",
          ...unclear.map((item) => `- ${item.key}: ${item.evidence.join("; ")}`),
        ].join("\n"));

    await ctx.task("continue worker", {
      ...continueWorker(worker.sessionFile),
      reads: [contract, decisionLog],
      prompt: [
        `Read the decision log at ${decisionLog}.`,
        `Human decision: ${humanDecision}`,
        "Apply only required and dependent actions. Record follow-up items without implementing them.",
        "The original contract and output rules remain unchanged.",
      ].join("\n"),
    });

    return { decision_log: decisionLog };
  },
});

​

Runnable retained-stage example

// .atomic/workflows/scope-guard-retained.ts
import { workflow } from "@bastani/atomic/workflows";
import { Type } from "typebox";

function continueWorker(sessionFile: string | undefined) {
  return sessionFile === undefined
    ? { context: "fork" as const }
    : { context: "fork" as const, forkFromSessionFile: sessionFile };
}

export default workflow({
  name: "scope-guard-retained",
  description: "Retain one independent checker for a bounded multi-turn review.",
  inputs: {
    scope_contract: Type.String(),
    artifact_dir: Type.String({ default: ".atomic/workflows/runs/scope-guard-retained" }),
  },
  outputs: {
    decision_log: Type.String(),
  },
  run: async (ctx) => {
    const contract = ctx.inputs.scope_contract;
    const candidate = `${ctx.inputs.artifact_dir}/candidate.md`;
    const decisionLog = `${ctx.inputs.artifact_dir}/scope-decisions.md`;

    const worker = await ctx.task("prepare candidate", {
      context: "fresh",
      reads: [contract],
      prompt: `Read ${contract}, prepare the scoped candidate, and summarize evidence.`,
      output: candidate,
      outputMode: "file-only",
    });

    const guard = ctx.stage("retained scope guard", { context: "fresh" });
    await guard.prompt([
      `Read the immutable contract at ${contract} and candidate at ${candidate}.`,
      "Classify each material proposal as required, dependent, follow-up, or unclear.",
      "Write one deduplicated row per stable key, at most 20 rows, with evidence and action.",
      "Follow-up means record only; unclear means request a human decision.",
      "Judge scope only, not implementation correctness.",
    ].join("\n"), { output: decisionLog, outputMode: "file-only" });
    await guard.sendUserMessage([
      `Recheck the complete candidate against ${contract}.`,
      `If evidence changes a classification, use the write tool to replace ${decisionLog}.`,
      "Keep the artifact complete, deduplicated, and bounded to 20 rows; do not return a delta.",
      "If no decision changes, leave the artifact unchanged and say so.",
    ].join("\n"));


    const humanDecision = await ctx.ui.editor(
      `Review ${decisionLog}. Resolve each unclear row, or state that none remain.`,
    );

    await ctx.task("apply retained decision", {
      ...continueWorker(worker.sessionFile),
      reads: [contract, decisionLog],
      prompt: [
        `Read ${decisionLog}.`,
        `Human decision: ${humanDecision}`,
        "Apply required and dependent actions only. Do not implement follow-up rows.",
      ].join("\n"),
    });

    return { decision_log: decisionLog };
  },
});

​

Runnable live-parallel example

// .atomic/workflows/scope-guard-live.ts
import { workflow } from "@bastani/atomic/workflows";
import { Type, type Static } from "typebox";

const coordinationSchema = Type.Object(
  {
    status: Type.Union([
      Type.Literal("available"),
      Type.Literal("unavailable"),
      Type.Literal("off"),
    ]),
    evidence: Type.String(),
  },
  { additionalProperties: false },
);

type Coordination = Static<typeof coordinationSchema>;

function workerContext(sessionFile: string | undefined) {
  return sessionFile === undefined
    ? { context: "fresh" as const }
    : { context: "fork" as const, forkFromSessionFile: sessionFile };
}

export default workflow({
  name: "scope-guard-live",
  description: "Run a worker with a live same-group scope peer.",
  inputs: {
    scope_contract: Type.String(),
    worker_session_file: Type.Optional(Type.String({
      description: "Earlier worker session to continue; omit when no worker lineage exists.",
    })),
    fallback_policy: Type.Union([
      Type.Literal("warn"),
      Type.Literal("block"),
      Type.Literal("off"),
    ], { default: "warn" }),
    artifact_dir: Type.String({ default: ".atomic/workflows/runs/scope-guard-live" }),
  },
  outputs: {
    decision_log: Type.String(),
    review: Type.String(),
  },
  run: async (ctx) => {
    const contract = ctx.inputs.scope_contract;
    const fallbackPolicy = ctx.inputs.fallback_policy;
    const candidate = `${ctx.inputs.artifact_dir}/candidate.md`;
    const coordinationPath = `${ctx.inputs.artifact_dir}/scope-coordination.json`;
    const decisionLog = `${ctx.inputs.artifact_dir}/scope-decisions.md`;

    const branches = await ctx.parallel(
      [
        {
          name: "worker",
          ...workerContext(ctx.inputs.worker_session_file),
          reads: [contract],
          prompt: [
            `Read the immutable scope contract at ${contract}.`,
            `The declared Intercom fallback policy is ${fallbackPolicy}.`,
            "Unless policy is off, connect to Intercom and find the scope-guard peer in this workflow group.",
            "Before material expansion, send at most 20 blocking asks with a stable key and evidence.",
            "Apply required or dependent replies only. Record follow-up findings without implementing them.",
            "For an unclear reply, wait for human input instead of widening scope.",
            "If Intercom is unavailable: warn forbids expansion, block stops before expansion, and off keeps the original scope without a guard.",
            "Return the complete candidate summary; do not send a late ready notice.",
          ].join("\n"),
          output: candidate,
          outputMode: "file-only",
        },
        {
          name: "scope guard",
          context: "fresh",
          reads: [contract],
          schema: coordinationSchema,
          prompt: [
            `Read the immutable scope contract at ${contract}.`,
            `The declared fallback policy is ${fallbackPolicy}.`,
            "If policy is off, do not connect; return status off with evidence.",
            "Otherwise call intercom status once and return available or unavailable with evidence.",
            "When a later blocking ask reopens this conversation, classify its stable key as required, dependent, follow-up, or unclear.",
            "Reply with concrete evidence and one action. Do not approve implementation correctness.",
            "Never originate another guard or send a normal late message.",
          ].join("\n"),
          output: coordinationPath,
          outputMode: "file-only",
        },
      ],
      { concurrency: 2, failFast: true },
    );

    const guardResult = branches[1];
    if (guardResult?.structured === undefined) throw new Error("scope guard returned no coordination status");
    const coordination = guardResult.structured as Coordination;
    const guardTranscript = coordination.status === "available"
      ? guardResult.sessionFile
      : undefined;
    const transcriptReads = guardTranscript === undefined ? [] : [guardTranscript];
    const effectiveStatus = fallbackPolicy === "off"
      ? "off"
      : coordination.status === "available" && guardTranscript !== undefined
        ? "available"
        : "unavailable";
    const humanDecision = effectiveStatus === "unavailable" && fallbackPolicy === "block"
      ? await ctx.ui.editor("Intercom is unavailable. Resolve scope before any blocked expansion continues.")
      : "No fallback human decision required.";

    if (fallbackPolicy === "off") {
      await ctx.task("record scope guard off", {
        context: "fresh",
        prompt: "Record that the scope guard was explicitly off and that no expansion was approved.",
        output: decisionLog,
        outputMode: "file-only",
      });
    } else {
      await ctx.task("persist scope decisions", {
        context: "fresh",
        reads: [contract, candidate, coordinationPath, ...transcriptReads],
        prompt: [
          `Read ${contract}, ${candidate}, ${coordinationPath}, and any supplied guard transcript.`,
          `Effective coordination status: ${effectiveStatus}. Fallback policy: ${fallbackPolicy}.`,
          `Fallback human decision: ${humanDecision}`,
          "Persist one complete decision log with at most 20 unique stable keys.",
          "Classify each expansion as required, dependent, follow-up, or unclear with evidence and action.",
          "When warn has no transcript, perform the fresh boundary scope check here.",
          "Follow-up does not block. Unclear remains blocked unless the human decision resolves it.",
        ].join("\n"),
        output: decisionLog,
        outputMode: "file-only",
      });
    }

    const review = await ctx.task("independent correctness review", {
      context: "fresh",
      reads: [contract, candidate, decisionLog],
      prompt: [
        `Read ${contract}, ${candidate}, and ${decisionLog}.`,
        "Inspect the current files and run the required checks.",
        "Review correctness independently; do not turn follow-up scope findings into blockers.",
      ].join("\n"),
    });

    return { decision_log: decisionLog, review: review.text };
  },
});

​

Fast inference for workflow stages

await ctx.task({
  name: "triage",
  model: "openai-codex/gpt-5.6-sol-fast:medium",
  fallbackModels: ["openai-codex/gpt-5.6-sol:medium"],
  prompt: "…",
});

​

Context Engineering

​

Locally Scoped Stage Prompts

• the stage’s current objective and what is out of scope for this stage
• the exact files, artifacts, child outputs, or user inputs it may use; put long inputs before the final instruction
• context-dependent tool routes and permission boundaries, without describing tools the stage cannot call
• the expected output format and length, or the schema it must return when the workflow item is schema-enabled
• the checks, tools, or deterministic commands it should run when relevant, plus evidence required for progress or completion claims
• the success criteria and blocker conditions that let this stage stop

​

Context-Mode-Aware Prompt Text

• Never describe the stage’s own context mode. Sentences like “you are running in a fresh context window”, “your context is clean/non-forked”, or “this is a forked session” add tokens without changing behavior. State the concrete action, inputs, and success criteria instead.
• Fresh stages must not reference invisible context. A fresh stage has no “previous conversation”, cannot see sibling stages, and does not know the surrounding graph, so instructions like “compare against previous workflow reasoning” or “this runs in parallel with the locator pass” do not help and may confuse the model. Phrase the same intent stage-locally (“compare the working tree against the baseline branch”; “do your own scan; do not assume any other stage’s output is available”) and pass any state the stage needs through files, declared outputs, and reads.
• Forked continuation prompts send only the delta. A forked stage already carries the role, contracts, guidance, and output format from its own earlier prompts, so repeating them uses more tokens and can make the two copies diverge. Send what changed since the fork point — new artifacts, updated state, the next action — plus a one-line pointer back (“the contracts and report format established earlier in this thread still apply unchanged”) instead of re-injecting the full text.
• Keep one canonical copy of shared contracts. When fresh and forked variants of a stage share guidance, render the full contract only in the prompt that first establishes it and reference it from continuations. If a continuation needs a contract restated (for example, after a schema change), that is a new contract version, not a repeat.

​

Context Fundamentals

• System instructions: persistent behavior and guardrails.
• User inputs: workflow inputs and human-in-the-loop decisions.
• Retrieved documents: files, search results, logs, API responses, and artifacts.
• Message history: useful for continuity, but grows quickly in long-running stages.
• Tool outputs: often the largest source of context bloat.

​

Context Degradation Patterns

​

Compression and Artifact Handoffs

• objective and current status
• decisions already made
• files, symbols, commands, and artifact paths with evidence
• open questions and known risks
• rejected alternatives when they matter
• next action expected from the downstream stage

1. One owner per artifact. The runner writes the stage’s final assistant message to output after the stage ends, automatically writes the companion transcript outside the repository tree, and appends one instruction telling the model that its final message becomes the artifact. Your prompt does not need to restate any of that — describe the deliverable, not the plumbing. If a late admitted turn displaces the intended content, search the transcript with rg rather than assuming the curated artifact holds every later turn. A prompt may write other files freely; only the declared output path is runner-owned and overwritten at stage end.
2. Do not read an artifact back just to return it. outputMode: "file-only" exists so the parent receives a compact reference. Calling readFile on that artifact and returning its text as a workflow output cancels the saving and drops the whole report into the caller’s context window. Return the reference and a *_path output instead.
3. Return paths from the workflow. Declared outputs are consumed by the calling session, so a workflow’s result should be a reference plus explicit *_path outputs. Callers that need the body read the path; callers that only need the outcome pay nothing for it. When a detail is missing from the curated artifact, search its companion transcript with rg and inspect a narrow range.

const researchPath = ".atomic/workflows/runs/context-demo/research.md";
await ctx.task("researcher", {
  task: "Map the subsystem and return the complete report as your final message.",
  output: researchPath,
  outputMode: "file-only",
});

const review = await ctx.task("reviewer", {
  task: [
    `Research artifact: ${researchPath}`,
    `Read the file at ${researchPath} incrementally and inspect only the sections needed for this review.`,
  ].join("\n"),
  reads: [researchPath],
});

​

Multi-Agent and Parallel Patterns

• locator / mapper: where relevant files and systems live
• analyzer: how the current implementation works
• pattern finder: how similar code is written elsewhere
• external researcher: what upstream docs or APIs require
• reviewer/evaluator: whether outputs satisfy the validation contract

​

Filesystem Context

.atomic/workflows/runs/<run-name>/
  research.md
  reviews/
    correctness.md
    docs.md
  artifacts/
    raw-log.txt
    summary.json

• write large tool outputs to files and return concise references
• store plans, state, and reviewer findings in structured markdown or JSON
• pass artifact paths via reads; prompt agents with Read the file at <path>... rather than pasting artifacts into {previous}
• for review loops, pass the latest review-round artifact first and let a ledger/index point to older rounds only when needed
• give parallel branches separate output paths to avoid write conflicts
• use grep, globbing, and line-range reads instead of loading entire logs
• clean scratch files or keep them under run-specific directories

​

Evaluation and Quality Gates

• deterministic checks: tests, typechecks, linters, schema validation, command exit codes
• rubric checks: completeness, correctness, evidence quality, risk coverage, user fit
• reviewer stages: fresh-context reviewers that inspect artifacts and current files
• LLM-as-judge stages: direct scoring, pairwise comparison, or rubric-based grading for subjective outputs

​

Tools, MCP, Memory, and Hosted Execution

​

Task Fit and Project Design

​

Design Checklist

• Purpose and fit: What concrete outcome should the workflow produce? Is the task naturally multi-stage, parallel, resumable, or reusable? What is out of scope?
• Inputs: Which values should be declared as inputs? What is the narrowest schema type? Which defaults are safe?
• Common pattern: Which common workflow pattern best matches the task, and where does the actual design intentionally diverge?
• Stage decomposition: For each stage, what question does it answer, what context does it need, what output should it return, and what model/tool/MCP requirements does it have?
• Local stage contract: Can this stage prompt stand alone with its current objective, inputs/artifacts, expected outputs, tools/checks, and success criteria, without unexplained workflow internals or future-stage assumptions?
• Prompt vocabulary: Do stage, reviewer, and reducer prompts describe the concrete action, available evidence, and success criteria that the stage can see locally, instead of assuming the model knows the workflow graph’s name or surrounding context? Avoid phrasing like “the create-PR workflow stage” or “this Foo workflow” unless that name is explicitly supplied as user-visible context or materially affects behavior.
• Information flow: For every edge between stages, is previous enough, or should the handoff use structured returns, files, reads, output, or outputMode?
• Output contract: Which outputs should be declared in outputs, which stage/task/child results should run return for those keys, and what runtime type must each value have? If another workflow may call this workflow as a child, which non-default outputs should the parent rely on?
• Context size: Can downstream stages succeed from the handoff alone? Should large transcripts, logs, or research bundles be summarized or saved as artifacts?
• Control flow: Should the workflow use ctx.chain, ctx.parallel, ctx.ui, bounded loops, failFast, or fallbackModels?
• Acyclic topology: What node and dependency shape can each branch, bounded loop, and nested workflow boundary materialize? Which stages repeat, does each iteration create distinct tracked work with stable identity and call order, and what is the current frontier before each repeat? Could any proposed parent edge target the node itself or an ancestor? Are nested children composed through ctx.workflow(...) boundaries rather than recursive run invocation? Redesign or stop before launch if any self-edge or back-edge remains.
• Scope control: Could valid adjacent findings expand the patch? If so, where will a fresh scope guard read the immutable contract, how will it classify and persist bounded decisions, which warn/block/off fallback applies, and which worker session owns any forked continuation?
• User experience: Are stage names readable in status and graph views? Is the final output compact? Are important artifacts saved with stable paths?
• Validation: What success criteria, review gates, deterministic checks, or evaluator stages prove the workflow did the right thing? Are model gates schema-backed instead of regex/prose-matched, and do adaptive gates run as focused model stages with explicit tool/check instructions?
• Final actions: Does the workflow distinguish implementation/review convergence from post-approval final actions such as PR/MR/review creation, release tagging, deployment, or publication? Are reviewers and reducers prompted to approve and hand off when implementation and validation criteria are proven and only an explicitly authorized final action remains?

​

Common Mistakes

• Do not invent workflow names; list first.
• Do not guess input keys; inspect with inputs or get first.
• Do not call create, update, or delete on the workflow tool; definitions are code-authored.
• Do not use legacy workflow tool fields like agent, stage, or run-control name.
• Do not pass strings or path objects to ctx.workflow(...); import the workflow definition from @bastani/atomic/workflows/builtin or another TypeScript module first.
• Do not create a self-edge or a dependency edge from the current frontier to an existing ancestor. Cyclic workflow graphs are unsupported; redesign or stop before launch when a cycle cannot be removed.
• Do not model a bounded loop by reopening an earlier node beneath its downstream work. Create distinct tracked work per iteration and keep retained-session follow-up as non-topological activity when it adds no dependency work.
• Do not claim TypeScript or workflow discovery proves a dynamic workflow acyclic. Discovery diagnoses imports and definition shape; execution, replay, and DBOS hydration are the runtime topology boundary.
• Do not rely on undeclared child outputs; returning a key that is not declared in outputs fails the run. Declare every child-workflow field you expose in outputs — including result — and return values matching those schemas from run (see Outputs).
• Do not expect to select or rename child outputs at the call site; parent workflows receive the child’s declared output contract as child.outputs after checking child.exited === false, and a partial declared-output map when child.exited === true.
• Do not expect named workflow runs to block the chat turn; they are background tasks.
• Use interrupt or pause when the user asks to pause specific live work resumably; use quit for a graceful run-level process boundary.
• Keep stage names readable because they appear in workflow status and UI.
• Do not ask a stage to reason from workflow or stage names that are only orchestration labels. Model stages see their local prompt, artifacts, tools, and reads; describe the concrete action and evidence instead of referring to an implementation-specific nickname.
• Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described (Locally Scoped Stage Prompts).
• Do not parse model gate decisions from ad-hoc prose with regular expressions; configure schema on a focused workflow item and consume result.structured.
• Do not make reviewers fail an implementation gate solely because an authorized final action has not run yet. Represent that remainder as a post-approval next action (for example finalActionRemaining / nextAction) and let the final stage perform it.
• Do not let scope guards approve correctness or turn follow-up findings into blockers. Keep scope decisions separate from code review and deterministic validation, and do not reject expected pre-publication state assigned to a later lifecycle stage.
• Return compact structured decisions and save large artifacts to files; artifact handoffs should still use files when the next stage does not need the whole payload in context.

​

Workflow Best Practices

​

The core loop

Objective -> Scope -> Done criteria -> Run -> Inspect -> Steer -> Validate -> Summarize

1. Define the end state.
2. Constrain the blast radius.
3. State what counts as done.
4. Run the agent or workflow.
5. Inspect status before reading details.
6. Steer only when the run is off track, blocked, or missing criteria.
7. Require evidence before accepting the result.
8. Ask for a summary, handoff, or next-step plan.

​

Prompt anatomy

​

Objective

Implement `[specific behavior]` in `[component]`.

​

Context

This is needed because `[reason]`. The relevant code likely lives near `[area]`.

​

Scope

Only touch files directly required for `[behavior]`.

​

Non-goals

Do not redesign `[subsystem]`, refactor unrelated code, or change public behavior outside `[case]`.

​

Done criteria

Done means:
- `[new behavior]` works.
- `[existing behavior]` is unchanged.
- `[test command]` passes.
- The final response includes changed files, validation results, and remaining risks.

​

Stop conditions

If this requires changing `[public API/security behavior/data migration]`, stop and ask first.

​

Core principles

​

1. Start with the end state

Look into the login issue.

Fix the login redirect regression. Done means users who sign in from `[page]` return to `[expected destination]`, and `[test command]` passes.

​

2. Keep scope tight

• Only touch files required for this behavior.
• Do not refactor unrelated code.
• Preserve existing behavior for [case].
• Make the smallest correct change.

​

3. Separate implementation from validation

• a targeted test,
• a broader regression test,
• a smoke command,
• a typecheck or lint command,
• a structured output contract check,
• or a clear manual verification step.

​

4. Prefer evidence over speculation

Treat the failing assertion as the source of truth. Do not guess from nearby code alone.

​

5. Use staged thinking

Investigate -> identify root cause -> propose fix -> implement -> validate -> summarize

​

6. Steer, do not micromanage

​

7. Treat failed validation as the next task

Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.

​

8. Interrupt stale or wrong work

​

9. Inspect at the right level

1. overall status,
2. current stage,
3. blocker or failure reason,
4. relevant stage details only if needed.

​

10. Ask for synthesis before handoff

Summarize root cause, proposed fix, files involved, validation plan, and remaining risks.

​

Common Workflow Patterns

​

Pattern diagrams

1. Classify-and-act

┌─ 1  Classify-and-act ────────────────────────────────────┐
│                                                          │
│                             ┌───────┐                    │
│                         ╭──▸│agent A│                    │
│                         │   └───────┘                    │
│  ┌────┐  ┌──────────┐   │   ┌───────┐                    │
│  │task│─▸│classifier│───┼──▸│agent B│ ◂ chosen           │
│  └────┘  └──────────┘   │   └───────┘                    │
│                         │   ┌───────┐                    │
│                         ╰──▸│agent C│                    │
│                             └───────┘                    │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Make the classifier return a structured category and confidence, not free-form prose.
• Keep each action branch isolated with the minimum tools and context it needs.
• Add a fallback or human-input branch for low-confidence classifications.

2. Fan-out-and-synthesize

┌─ 2  Fan-out-and-synthesize ──────────────────────────────┐
│                                                          │
│            ┌───────┐                                     │
│          ╭▸│agent 1│──╮                                  │
│          │ └───────┘  │                                  │
│          │ ┌───────┐  │                                  │
│          ├▸│agent 2│──┤                                  │
│  ┌────┐  │ └───────┘  │ ┌───────┐  ┌──────────┐          │
│  │task│──┤ ┌───────┐  ├▸│barrier│─▸│synthesize│          │
│  └────┘  ├▸│agent 3│──┤ └───────┘  └──────────┘          │
│          │ └───────┘  │                                  │
│          │ ┌───────┐  │                                  │
│          ╰▸│agent 4│──╯                                  │
│            └───────┘                                     │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Partition by files, sources, claims, candidates, or work items that can be evaluated independently.
• Save each branch to a separate artifact and pass paths with reads instead of inlining all branch output.
• Treat synthesis as a barrier: it waits for every branch, deduplicates, resolves conflicts, and cites evidence.

3. Adversarial verification

┌─ 3  Adversarial verification ────────────────────────────┐
│                                                          │
│                                                          │
│  ┌──────┐       ┌──────────┐                             │
│  │worker│───╮──▸│verifier A│──╮                          │
│  └──────┘   │   └──────────┘  │                          │
│             │   ┌──────────┐  │   ┌───────┐              │
│             ├──▸│verifier B│──┼──▸│reducer│              │
│             │   └──────────┘  │   └───────┘              │
│             │   ┌──────────┐  │                          │
│             ╰──▸│verifier C│──╯                          │
│                 └──────────┘                             │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Give verifiers fresh context and a concrete rubric with pass/fail evidence requirements. For task-specific contract risk, use a grumpy/skeptical-but-fair persona that seeks realistic counterexamples, stays within the literal objective, rejects hand-waving and circular worker-authored evidence, and reports only actionable evidence-backed defects.
• Separate adversarial probe design from authoritative execution. Require a structured verifier plan with each exact probe, inputs, command/assertion, expected success condition, and covered requirement/risk; then run selected compile, test, schema generation/validation, runtime, or artifact checks through durable workflow-owned ctx.tool(...) calls. Actual tool results—not model self-report—feed judgment and consolidated repair.
• Known contracts may use direct task-specific ctx.tool(...) gates designed before launch; uncertain risks may use model-selected probes executed by those deterministic tools. Rerun the tools after repair until the declared pass condition or iteration limit.
• Ask verifiers to find blockers and not rewrite the candidate unless you explicitly assign them to repair it. Keep pure transformations as ordinary TypeScript rather than wrapping every model-stage action in ctx.tool.
• Decompose the rubric into named criteria and score each in its own call. Compound rubrics can latch onto one salient factor; the reference scan reports 76.4% for the best single criterion versus 78.3% for a three-criterion ensemble (§4.3).
• Aggregate by mean plus an explicit veto for genuinely disqualifying findings, never a unanimity AND across verifiers: unanimity makes false-reject grow as 1−(1−p)^K while the false-accept it buys only decays as (1−p)^K. See Verification scaling.
• The shipped adversarial-verification builtin accepts criteria as a record of criterion names to descriptions or as a criteria.md Markdown string; the shared verification-criteria module also canonicalizes string lists and CriterionInput lists. Its public doors are parse_rubric, normalize_criteria, select_criteria, and decide_verification, using the Criterion, CriterionInput, CriterionScore, and Finding shapes; NoCriteria and EmptyCriterion are explicit rubric errors.
• A criteria.md rubric may have a # title, an optional ## section whose heading contains ground truth (normally ## Ground Truth Note; the first such section wins), and must include a ## section whose heading contains criteri (normally ## Criteria) whose ### Name {#id} headings own non-empty criterion bodies. HTML comments are ignored; an omitted {#id} is slugged to lowercase alphanumeric/underscore text (up to 40 characters), with a fallback criterion id and encounter-order _2/_3 deduplication. parse_rubric rejects a rubric with no criterion headings or an empty criterion body.
• VERIFICATION_SCALE anchors integer scores from 1 (certainly fails) through 20 (verified correct). select_criteria preserves the requested id order and rejects unknown ids; decide_verification accepts only with quorum, a mean at or above the policy threshold, and no veto finding, while an invalid report remains metadata rather than a score.
• Keep a scoring family in the SHARED HEAD ‖ VARYING TAIL layout from verification-prompts: the byte-identical head contains the task, ground-truth note, candidate bodies (or caller-provided read paths), and scale anchors in that order; the tail contains only the criterion name and description plus the output-format instruction. Candidate-specific bodies stay in the shared head, not the varying tail, so sibling criteria can reuse the cached prefix.
• Inline the whole candidate family only while every body is at most 32 * 1024 UTF-8 bytes (MAX_INLINE_CANDIDATE_BYTES). If any body is larger, switch the whole family to caller-bound paths, preserving path order and duplicates; an oversized pathless family is rejected rather than guessed.
• warm_first_fan_out schedules the first-seen step for each prefix before releasing the remaining steps, establishing the provider’s warm prefix before sibling criteria or pair slots vary. Warm failures are observed without fail-fast, the remaining phase is still attempted before the error is rethrown, and successful results return in input order.
• The builtin input defaults are verifier_count=3, max_repairs=2, accept_mean=14 on the 1–20 scale, and reask_limit=1; omitted criteria uses the task_fit, evidence, and completeness record. A round expects one schema-valid score for every criterion/verifier cell, and the normal call shape is criteria length multiplied by verifier count.
• Invalid criterion reports are written as invalid artifacts and re-asked in bounded waves up to reask_limit; an invalid or missing report is counted in invalidCount only and is never converted into a fail vote or included in the mean. If the required quorum is still missing after the re-asks, the round is indeterminate rather than silently narrowing the decision.
• score_table_path names the durable verification-summary-<round>.json for the final round. Its object contains scores (criterion_id, integer score, evidence, and findings with finding plus severity), mean, invalidCount, the decision (accept, repair, or indeterminate with its corresponding mean/findings or missing count), and folded usage; review_report_path carries repair guidance or quorum evidence.

4. Generate-and-filter

┌─ 4  Generate-and-filter ─────────────────────────────────┐
│                                                          │
│                                                          │
│  ┌─────┐   ┌────┐                      ┌────┐            │
│  │gen A│──▸│idea│───╮              ╭──▸│best│            │
│  └─────┘   └────┘   │              │   └────┘            │
│  ┌─────┐   ┌────┐   │  ┌──────┐    │   ┌────┐            │
│  │gen B│──▸│idea│───┼─▸│filter│────┼──▸│best│            │
│  └─────┘   └────┘   │  └──────┘    │   └────┘            │
│  ┌─────┐   ┌────┐   │              │   ┌╌╌╌╌╌╌╌╌╌┐       │
│  │gen C│──▸│idea│───╯              ╰──▸╎discarded╎       │
│  └─────┘   └────┘                      └╌╌╌╌╌╌╌╌╌┘       │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Generate more candidates than you need, then filter hard by an explicit rubric.
• Dedupe before judging so near-identical candidates do not dominate the shortlist.
• Use this for exploration, naming, design options, hypotheses, and lightweight eval ideas.
• When the filter ranks candidates rather than applying a threshold, use the same judge guidance as Tournament: graded per-criterion integer scores rather than binary keep/drop, a Bradley–Terry preference from the score gap so near-ties stay near-ties, and K repeats with candidates swapped between the A and B slots. See Verification scaling.
• For a custom ranking filter, reuse the shared verification-criteria module and its criteria.md parser rather than inventing a binary keep/drop rubric; stable criterion ids let the judge select the same criteria in each comparison. See Adversarial verification for the accepted shapes and score decision.

5. Tournament

┌─ 5  Tournament ──────────────────────────────────────────┐
│                                                          │
│  ┌─────────┐                                             │
│  │attempt A│──╮  ┌───────┐                               │
│  └─────────┘  ├─▸│judge 1│───╮                           │
│  ┌─────────┐  │  └───────┘   │                           │
│  │attempt B│──╯              │   ┌─────┐  ┌──────┐       │
│  └─────────┘                 ├──▸│final│─▸│winner│       │
│  ┌─────────┐                 │   └─────┘  └──────┘       │
│  │attempt C│──╮  ┌───────┐   │                           │
│  └─────────┘  ├─▸│judge 2│───╯                           │
│  ┌─────────┐  │  └───────┘                               │
│  │attempt D│──╯                                          │
│  └─────────┘                                             │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Use pairwise comparison when absolute scores are noisy or subjective.
• Randomize or balance presentation order where possible to reduce order bias.
• Keep the judge rubric short and require rationale tied to observable criteria.
• Have judges emit graded per-criterion integer scores rather than a binary winner, then derive a Bradley–Terry preference from the score gap so near-ties stay near-ties.
• Repeat each pair K times with the candidates swapped between the A and B slots; the swap cancels positional bias within the pair and variance falls as O(1/K). In the reference scan’s discrete-judge study, 26.7% of pairs tied at K=1; with slot swaps, the reported K=1→16 result moved from 74.7% to 77.5%.
• See Verification scaling for score granularity and call-budget trade-offs.
• The shipped tournament inputs use num_attempts=4 and max_concurrency=4; n_evaluations=2 repeats each criterion/directed pair, pivots=1 selects the second comparison phase’s pivot candidates, and seed=0 drives the deterministic schedule. criteria is optional and accepts a markdown rubric, a string-to-description record, a string list, or a CriterionInput list; omission uses the shipped three-criterion Correctness, Completeness, and Evidence and task fit rubric. Optional ordered models ids are assigned round-robin to attempt slots.
• comparisons_path points to comparisons.json, whose ledger records the task and seed, params (n, pivots, n_evaluations, and normalized criteria), per-job comparisons rows (a, b, phase, criterion id, repeat, slot-swap flag, scores or an invalid marker, preference, and judge artifact path), aggregate pairs, weights/counts, the complete ranking, and optional model assignment. Its budget records planned versus executed judge stages, including re-asks; invalid reports remain auditable rows and an all-invalid pair remains marked invalid rather than becoming a score.

6. Loop until done

┌─ 6  Loop until done ─────────────────────────────────────┐
│                                                          │
│  ┌───────┐   ┌─────────────┐  no   ┌────┐                │
│  │agent 1│──▸│new findings?│──────▸│done│                │
│  └───────┘   └──────┬──────┘       └────┘                │
│                     │ yes, spawn distinct work           │
│                     ▾                                    │
│                 ┌───────┐   ┌────────────┐               │
│                 │agent 2│──▸│next check …│               │
│                 └───────┘   └────────────┘               │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Define both success and escape conditions before the loop starts.
• Keep a durable ledger of attempted work, findings, failures, and validation evidence.
• Bound loops by iterations, budget, or convergence criteria so exhausting a bound produces an inspectable failure instead of letting the loop continue indefinitely.
• Materialize every iteration as distinct tracked work with stable iteration identity and call order. Never represent repetition by a self-edge, a back-edge to an ancestor, or reopening an ancestor below its downstream work.
• Record a progress magnitude in the ledger beside the boolean stop bit; a flat or decreasing series is the stall signal that the loop is burning iterations without moving.
• Treat the trend as a monitoring and escalate-to-human signal, never a kill switch: the explicit stop condition remains authoritative. See Verification scaling.
• The builtin defaults max_iterations=5, progress_scoring=true, and progress_repeats=1; set progress_scoring false to omit advisory scoring, while progress_repeats is the repeat count passed to the scoring primitive. Each scored iteration adds a progress entry to progress-ledger.json with score, perRepeat (null for an invalid repeat), trend, and the classifier window; the ledger also emits progress_curve, final_trend, and progress_disclaimer.
• Progress scores use the anchored 1–20 scale and average valid repeat scores per checkpoint. classify_trend uses window=3, riseDelta=1.5, and fallDelta=-1.5; it compares equal leading/trailing halves of the trailing two windows, drops an odd middle sample, and classifies inclusive threshold crossings as rising, flat, or regressing. A short series is flat evidence.
• The trend is monitoring and escalation evidence only: it never kills, terminates, or approves a loop, and the explicit evaluator stop condition remains authoritative. progress_curve, final_trend, and progress_disclaimer are advisory outputs, not alternate closure signals.

7. Constructive quorum

┌─ 7  Constructive quorum ──────────────────────────────────┐
│                                                          │
│  ┌──────────────┐   ┌──────────────┐                    │
│  │reviewer A    │   │reviewer B    │   independent       │
│  │preliminary   │   │preliminary   │   assessments        │
│  │verdict       │   │verdict       │                    │
│  └──────┬───────┘   └──────┬───────┘                    │
│         ╰──── Intercom: one evidence round ────╮        │
│                share · challenge · correct     │        │
│                         ┌──────────────────────┘        │
│                         ▾                               │
│              ┌──────────────────┐   ┌───────────────┐   │
│              │final structured  │──▸│deterministic  │   │
│              │verdicts + change │   │reducer counts │   │
│              │evidence          │   │votes          │   │
│              └──────────────────┘   └───────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘

• Give every reviewer an independent preliminary assessment before it reads sibling findings or verdicts.
• Run exactly one bounded evidence-exchange round. Share concrete findings and evidence, challenge blocking claims, and stop rather than opening a second round.
• Change a verdict only through evidence, never deference. Each reviewer emits its own final structured verdict and records whether deliberation changed it and which evidence caused the change.
• Let the existing deterministic reducer count the final votes; deliberation shapes votes but does not replace quorum counts or the stop_review_loop contract.

Stacked implementation slices starter pattern

┌─ Stacked implementation slices ─────────────────────────────┐
│ plan → prepare branch/worktree → child slice 1 → gates      │
│                                      │ verified              │
│                                      ▼                       │
│              prepare branch from slice 1's verified branch  │
│                                      ▼                       │
│                         child slice 2 → gates              │
│                                      │ failed → stop/report │
└─────────────────────────────────────────────────────────────┘

import { spawnSync } from "node:child_process";
import { resolve } from "node:path";
import { Type } from "typebox";
import { workflow } from "@bastani/atomic/workflows";
import { goal } from "@bastani/atomic/workflows/builtin";

function spawnCommand(argv: readonly string[], cwd: string) {
  const [command, ...args] = argv;
  if (command === undefined) throw new Error("spawnCommand requires a command");
  const result = spawnSync(command, args, { cwd, encoding: "utf8" });
  // A command that could not be spawned at all arrives on `error` with a null
  // status, so it has to be raised here or it reads as an ordinary failure.
  if (result.error) throw result.error;
  return result;
}

function runCommand(argv: readonly string[], cwd: string): string {
  const result = spawnCommand(argv, cwd);
  const stdout = (result.stdout ?? "").trim();
  const stderr = (result.stderr ?? "").trim();
  if (result.status !== 0) {
    throw new Error(`${argv.join(" ")} failed (${result.status})\n${stderr || stdout}`);
  }
  return stdout;
}

export default workflow({
  name: "stacked-slices",
  inputs: {
    slice1_branch: Type.String({ default: "stacked/slice-1" }),
    slice2_branch: Type.String({ default: "stacked/slice-2" }),
  },
  outputs: {},
  run: async (ctx) => {
    const repoRoot = runCommand(["git", "rev-parse", "--show-toplevel"], ctx.cwd ?? process.cwd());
    const slice1Branch = ctx.inputs.slice1_branch;
    const slice2Branch = ctx.inputs.slice2_branch;
    if (slice1Branch === slice2Branch) {
      return ctx.exit({ status: "blocked", reason: "slice branches must be distinct" });
    }

    const prepareSliceWorktree = async (
      toolName: string,
      branch: string,
      gitWorktreeDir: string,
      baseBranch: string,
    ) => {
      const worktreePath = resolve(repoRoot, gitWorktreeDir);
      await ctx.tool(
        toolName,
        { branch, base_branch: baseBranch, git_worktree_dir: gitWorktreeDir },
        async () => {
          const current = spawnCommand(
            ["git", "-C", worktreePath, "branch", "--show-current"],
            repoRoot,
          );
          if (current.status === 0) {
            const checkedOutBranch = (current.stdout ?? "").trim();
            if (checkedOutBranch !== branch) {
              throw new Error(`${worktreePath} is checked out on ${checkedOutBranch || "detached HEAD"}, expected ${branch}`);
            }
            return { branch, worktree: worktreePath };
          }

          const branchProbe = spawnCommand(
            ["git", "show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
            repoRoot,
          );
          if (branchProbe.status === 0) {
            runCommand(["git", "worktree", "add", worktreePath, branch], repoRoot);
          } else if (branchProbe.status === 1) {
            runCommand(["git", "worktree", "add", "-b", branch, worktreePath, baseBranch], repoRoot);
          } else {
            throw new Error((branchProbe.stderr ?? "").trim() || `could not inspect branch ${branch}`);
          }
          return { branch, worktree: worktreePath };
        },
      );
    };

    await prepareSliceWorktree("prepare-slice-1-branch", slice1Branch, "../slice-1", "origin/main");
    const slice1 = await ctx.workflow(goal, {
      inputs: {
        objective: "Implement the first independently verified concern.",
        acceptance_criteria: "The first concern builds, passes its focused tests, and commits all changes on the current feature branch.",
        base_branch: "origin/main",
        git_worktree_dir: "../slice-1",
        create_pr: false,
      },
      stageName: "slice 1",
    });
    if (slice1.exited === true || slice1.outputs.approved !== true) {
      return ctx.exit({ status: "blocked", reason: "slice 1 is unverified" });
    }

    await prepareSliceWorktree("prepare-slice-2-branch", slice2Branch, "../slice-2", slice1Branch);
    const slice2 = await ctx.workflow(goal, {
      inputs: {
        objective: "Implement the next concern on the verified slice-1 branch.",
        acceptance_criteria: "The second concern builds, passes its focused tests, preserves slice 1, and commits all changes on the current feature branch.",
        base_branch: slice1Branch,
        git_worktree_dir: "../slice-2",
        create_pr: false,
      },
      stageName: "slice 2",
    });
    if (slice2.exited === true || slice2.outputs.approved !== true) {
      return ctx.exit({ status: "blocked", reason: "slice 2 is unverified; slice 1 remains verified" });
    }

    return {};
  },
});

​

Verification scaling

• Use an anchored 1–20 integer scale as the default score granularity.
• Providers expose no token logprobs, so a K-sample average is the substitute; K=16 parity costs roughly 16× the call cost, making K a budget decision.
• Treat pool diversity as a bet on the selector’s oracle ceiling. In the reference scan’s pivot tournament, best-of-3 selection reached 86.5% ±1.1 against 79.4% pass@1 with a 92.1% oracle ceiling, while best-of-5 reached 88.0% ±0.6 against 78.7% pass@1 with a 96.6% oracle ceiling. A chance-level selector can make a more diverse pool worse, so widen the pool only once the judge beats chance.
• Self-verification—having the same model judge its own rollouts—still gained +7.1 over pass@1 in the best-of-3 comparison (86.5% versus 79.4%) and +9.3 in the best-of-5 comparison (88.0% versus 78.7%).
• For a cheap operating point, an author can use one pivot and K=2 repeats for a best-of-3-shaped comparison budget; this is an authoring recipe, not a shipped default.
• For the shipped primitive references, see Adversarial verification for criteria parsing, warm-first scoring, re-asks, and score summaries; Tournament for inputs and comparisons.json; Loop until done for progress ledger/trend outputs; and Goal/Ralph for re-verification and convergence evidence.

​

Choosing a common workflow pattern

• Pick classify-and-act when routing correctness matters more than breadth.
• Pick fan-out-and-synthesize when the work divides cleanly into independent slices.
• Pick adversarial verification when the main risk is a plausible but wrong answer.
• Pick generate-and-filter when output quality depends on exploring a large option space.
• Pick tournament when multiple whole-solution strategies should compete under one rubric.
• Pick loop until done when the workflow should continue until evidence says it is finished, not until a preselected number of stages completes.
• Pick constructive quorum when several fresh-context verifiers judge one artifact and a simple tally could hide a defect or preserve one verifier’s misreading; use one bounded evidence exchange before each verifier emits its own final vote.
• Pick scope guard when valid adjacent findings could expand a worker or repair stage beyond its immutable contract; choose a boundary task by default and live parallel steering only when timing requires it.
• Pick stacked implementation slices when one dependent implementation objective needs ordered, independently verified layers. Keep the 100–500 line range as a default with atomic-change escapes; create or check out each named branch before its child, create each next branch from the previous verified branch, pass that previous branch as base_branch, use a distinct git_worktree_dir, and stop at the first failed gate.

​

Steering patterns

​

Tighten scope

Narrow this to `[specific behavior]` in `[component]`. Do not refactor unrelated code or change `[adjacent area]`. Done means `[specific acceptance criteria]`.

​

Add missing done criteria

Use these done criteria:
1. `[behavior]` works.
2. `[regression]` remains unchanged.
3. `[test command]` passes.
4. Report files changed and validation results.

​

Redirect an off-track stage

Stop pursuing `[wrong direction]`. The relevant signal is `[error/test/user behavior]`. Re-focus on `[target area]` and continue from there.

​

Respond to a blocked prompt

Choose `[option]`. Continue only if `[condition]`; otherwise stop and report the blocker.

​

Turn failed validation into the next task

Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.

​

Ask for synthesis

Synthesize the current findings into: root cause, proposed fix, files likely involved, validation plan, and remaining risks.

​

Pause, stop, or rerun

Pause this run; it has been superseded by `[new context]`. Resume only with `[updated objective]`, or stop and summarize current state.

​

Copy-paste templates

​

Start a workflow

Objective:
Implement/fix `[specific behavior]` in `[component]`.

Context:
`[short context about why this matters or where to look]`

Scope:
- Only touch files required for `[behavior]`.
- Do not refactor unrelated code.
- Preserve existing behavior for `[existing case]`.

Done criteria:
- `[new behavior]` works.
- `[regression case]` still works.
- `[test command]` passes.
- Report changed files, validation results, and any risks.

Stop conditions:
- If this requires `[risky decision]`, stop and ask first.

​

Tighten scope

Tighten scope to `[specific target]`.

Do not work on:
- `[excluded area 1]`
- `[excluded area 2]`
- broad cleanup or unrelated refactors

Continue only on the path needed to satisfy:
`[acceptance criterion]`.

​

Add acceptance criteria

Add these acceptance criteria before continuing:

1. User can `[action]`.
2. System handles `[edge case]`.
3. Existing behavior `[existing behavior]` is unchanged.
4. `[test command]` passes.
5. Final response includes validation evidence.

​

Redirect a stage

This stage is off track.

Stop investigating `[wrong area]`.
The relevant signal is `[error/output/requirement]`.
Refocus on `[correct area]`.

Next:
1. Reproduce or inspect `[signal]`.
2. Identify root cause.
3. Make the smallest fix.
4. Run `[validation command]`.

​

Handle failed validation

Validation failed:

Command:
`[command]`

Failure:
`[short sanitized failure summary]`

Treat this as the source of truth.
Fix only the root cause.
Rerun the failing command.
If it still fails, summarize the blocker and stop.

​

Ask for synthesis

Synthesize current progress into:

- What was attempted
- What changed
- What evidence supports the result
- What remains uncertain
- Recommended next steps
- Exact validation commands run

​

Turn findings into implementation steps

Convert the findings into an implementation plan:

1. Files/components to change
2. Order of changes
3. Tests to add or update
4. Validation commands
5. Risks or edge cases
6. Stop conditions

​

Prepare a release gate

Prepare `[version]` as a `[release kind]` release.

Requirements:
- Verify changelog entries are complete.
- Run `[test command]`.
- Run `[build/package command]`.
- Do not publish unless all validation passes.
- If any gate fails, stop and report blockers.

Final response should include:
- Version
- Checks run
- Results
- Files changed
- Publish readiness

​

Concrete examples

​

Example 1: Fixing a failing test

Fix the failing `[unit test]`. Do not rewrite the module. Done means the test passes and nearby tests still pass.

Stop exploring unrelated failures. Focus only on the assertion mismatch in `[test file]`.

​

Example 2: Repairing a workflow definition

Validate `[workflow]` and fix its output contract. Done means the smoke run returns `[required fields]`.

Treat the missing output field as the root issue. Do not change unrelated stage prompts.

​

Example 3: Investigating before implementing

Investigate `[bug]`, identify root cause, and propose the smallest fix. Do not implement until the cause is clear.

Synthesize findings first: root cause, affected path, proposed fix, and validation plan.

​

Anti-patterns

​

Quick reference

• Objective
• Context
• Scope
• Non-goals
• Done criteria
• Validation command
• Reporting requirements
• Stop conditions
• Queue dependency classification, concurrency bound, and item → run/worktree/branch map (when several implementation items are requested)

• What changed?
• Why was this the right fix?
• What evidence supports it?
• Which commands were run?
• What still might be risky?
• Is anything blocked or unresolved?