Declarative Workflows

​

How the industry describes work

​

How Smithers does it

/** @jsxImportSource smithers-orchestrator */
import { createSmithers } from "smithers-orchestrator";
import { z } from "zod";

const { Workflow, Task, Sequence, Parallel, smithers, outputs } = createSmithers({
  input: z.object({ repo: z.string() }),
  analysis: z.object({ summary: z.string(), risk: z.enum(["low", "medium", "high"]) }),
  review: z.object({ verdict: z.string() }),
  report: z.object({ markdown: z.string() }),
});

export default smithers((ctx) => {
  const analysis = ctx.outputMaybe(outputs.analysis, { nodeId: "analyze" });

  return (
    <Workflow name="repo-review">
      <Sequence>
        <Task id="analyze" output={outputs.analysis} retries={2} timeoutMs={120_000}>
          {`Analyze ${ctx.input.repo} and assess migration risk.`}
        </Task>
        {analysis?.risk === "high" ? (
          <Parallel maxConcurrency={2}>
            <Task id="security-review" output={outputs.review}>Review for security regressions.</Task>
            <Task id="perf-review" output={outputs.review}>Review for performance regressions.</Task>
          </Parallel>
        ) : null}
        <Task id="report" deps={{ analyze: outputs.analysis }} output={outputs.report}>
          {(deps) => `Write the report. Summary: ${deps.analyze.summary}`}
        </Task>
      </Sequence>
    </Workflow>
  );
}, { output: outputs.report });

• createSmithers(schemas) registers Zod schemas as durable output relations and returns typed components plus outputs, so outputs.analsis is a compile error, not a runtime surprise.
• Dependencies are conditionals. ctx.outputMaybe(ref, { nodeId }) returns undefined until the upstream task completes, so the dependent subtree simply isn’t in the plan yet — the conditional is the edge. For the common one-upstream case, <Task deps={{ analyze: outputs.analysis }}> with a (deps) => ... children callback is the direct form. No ResultPath plumbing, no add_conditional_edges.
• The render loop. Each frame: render (pure), extract the tree into a GraphSnapshot of TaskDescriptors (id, ordinal, dependencies, schema, agent, retries, timeouts), dispatch ready tasks, persist validated outputs to per-schema tables, re-render against the new state. See How It Works.
• MDX prompts. A prompt can be a .smithers/prompts/*.mdx file taking {props.field} interpolations; the .tsx renders it at runtime, so prompt edits need no TypeScript. See MDX Workflow Authoring.
• The Effect API is the same runtime with a React-free surface: G.step("id", { needs: { analyze }, output, run }), composed with G.sequence/G.parallel/G.match/G.scope, finalized by G.from(...). needs is the explicit-edge counterpart of JSX’s conditionals. See Effect API.

​

Dynamic fan-out

const tickets = ctx.outputMaybe(outputs.tickets, { nodeId: "plan" });

<Parallel id="tickets" subtreeConcurrency={4}>
  {(tickets?.items ?? []).map((t) => (
    <Sequence key={t.id} label={t.title}>
      <Task id={`${t.id}-implement`} agent={coder} output={outputs.impl}>
        Implement {t.title}
      </Task>
    </Sequence>
  ))}
</Parallel>

​

The description is what everything else stands on

• Retries re-dispatch a TaskDescriptor, not “re-run the script.”
• Resume replays render against persisted state; completed tasks are in the state, so they never re-execute.
• Approvals suspend a node in a stored graph; the process can exit and the run survives until smithers approve.
• Hot reload (smithers up workflow.tsx --hot) re-renders edited source against the same persisted state on the next frame, diffs the plans, and continues — in-flight task state intact.
• UIs and time travel draw and fork frames because a frame is data, not a stack trace.

smithers graph workflow.tsx --input '{"repo":"acme/api"}'   # render the graph, execute nothing
smithers graph workflow.tsx --compact                        # structure only, no prompt bodies

​

Guarantees and limits

• Renders must be pure. Date.now() or fetch in the render body produces unstable plans. Side effects go in task bodies, which are durable and retried.
• IDs are the identity. Renaming a task id orphans its persisted output and creates a new node. Keep ids stable and data-derived (`${ticket.id}-implement`), especially under fan-out — same rule as Temporal’s workflow versioning, smaller blast radius.
• Hot reload is not resume. --hot applies edits within a running frame; resuming a stopped run validates the original source hash and fails with RESUME_METADATA_MISMATCH if the file changed. Edited workflow → fresh run.
• smithers graph validates shape, not semantics. It catches structural errors cheaply, but a deps key that doesn’t match any node id still fails at runtime, not at graph time.
• Frames aren’t free. Every frame writes a snapshot; unbounded loops grow the database. <ContinueAsNew> hands off to a fresh run with carried state.
• Where a visual builder genuinely fits — non-engineers wiring SaaS triggers — n8n or Zapier is the right tool; Smithers assumes the author (human or agent) writes code.

​

Operating it

smithers graph <workflow> [--input <json>] [--compact]   # render without executing
smithers up workflow.tsx --hot                           # run with hot reload while authoring
smithers workflow list                                   # discover .smithers/workflows
smithers tree <run-id>                                   # DevTools snapshot of a live run's tree
smithers inspect <run-id>                                # node-level state of the extracted graph

​

See also

• Why React? — the agent-experience argument for JSX as the surface.
• How It Works — render → extract → execute → persist, in depth.
• JSX API and Effect API — the two authoring surfaces.
• Components reference — every element and prop.
• <Parallel>, <Loop> — concurrency and iteration semantics.