Core concepts

A factory has two kinds of function. A workflow function decides what happens next. A step function does the work. They run in different places, and the line between them is the one hard rule in jigs. This page starts with the words, then the rule, then what follows from it.

Term	Meaning
Factory	Your repository of workflows and configuration. It runs its own service.
Workflow	A Vercel Workflow SDK workflow: an async function whose first statement is "use workflow". It decides what happens next.
Step	One durable, recorded operation: a function marked "use step". It runs in a worker and does the work.
Routine	A function you call from a workflow. It runs steps and can wait for something outside the run.
Harness	An agent program jigs starts, such as Claude Code, Codex or Pi. It works with tools in a directory.
Agent	A named harness configuration playing a part in your workflow, such as a builder or a reviewer.
Agent session	One agent across several turns of a workflow, so each turn remembers the ones before it.
Session reference	The small piece of data a later step uses to resume the same harness session.
Run	One execution of a workflow, including any time it spends waiting.
Suspension	A run waiting on something outside it, such as a reply on a ticket or a pull-request review.
Wake	A nudge that makes a suspended run check its condition again. It does not answer the wait for you.
Binding	A name for a target repository, mapped to its remote URL.
Worktree	A Git working directory jigs cuts from its clone of a binding, one per run and branch.
Recipe	A complete workflow you copy into your factory and then own.
Model source	A model API that answers one request directly, such as OpenRouter.
Preflight	The checks jigs runs on a workflow's requires before it creates a run. A failure names its repair, and no run starts.
Jev	A decision call, askJev, that returns calibrated probabilities for named yes/no, choice or score questions.

The boundary

A step call is a message through the database, not a function call. When a workflow awaits a step, five things happen:

1. The workflow writes the argument to the database as JSON, and pauses.
2. A worker reads the argument, possibly in another process, possibly after a restart.
3. The worker runs the step's body: files, network, agents.
4. The worker writes the result to the database as JSON.
5. The workflow replays from its first line, and this time the await returns the stored result.

So an argument or a result has to be something that can be written down: strings, numbers, booleans, arrays and plain objects. A function has no written form, and neither does an object that holds a running process.

A harness descriptor crosses the boundary, because it is only data. A provider object does not: its methods are functions, and it holds a child process.

// Crosses: it is only data.
harnesses.claude({ model: "opus", effort: "high" });
// => { kind: "claude", model: "opus", effort: "high" }

// Does not: a provider from the AI SDK is made of functions.
claudeCode("opus");
// SerializationError: Failed to serialize step arguments at path "..."

That is why a workflow sends a description and the step builds the live thing from it. The same rule explains why prompts are rendered to strings before a step call, why a session reference is a small piece of data, and why your factory holds a generated step file at all.

Workflows decide, steps do the work

A workflow is replayed from its first line every time the run wakes. Steps that already finished return their recorded result instead of running again.

export async function hello(_input: WorkflowInputs<typeof inputs>) {
  "use workflow";
  return await createRunDirectory();
}

So a workflow, and every routine it calls, must be safe to run again. It reads no files, calls no network, runs no Git commands and reads no process.env. The workflow bundle has no Node built-ins, so an import that needs one fails the build.

That work belongs in steps. jigs provides steps for the common operations, and you can write your own in a steps.ts beside the workflow that uses it.

Routines compose steps

A routine is a function you call from a workflow. It calls steps for you and can wait for something outside the run, such as a reply on a ticket.

import { reviewTicket } from "#jigs/routines";

const handoff = await reviewTicket({ claim, snapshot, harness: agents.reviewer, cwd });

A routine has no directive and no recorded result of its own. Only the steps it calls are recorded, so a routine can change between jigs releases without stranding a waiting run.

Agents are named harnesses

An agent is a harness configuration with a name: the part it plays in your workflow. A workflow lists its agents in a plain object and declares them in requires.

import { defineWorkflow, harnesses } from "@jigs-ai/jigs";

const agents = {
  builder: harnesses.claude({ model: "opus", effort: "high" }),
  reviewer: harnesses.codex({ model: "gpt-5.6-sol" }),
};

export default defineWorkflow({
  inputs,
  requires: { agents, integrations: ["linear", "github"] },
  workflow: shipTicket,
});

The service checks each agent's harness when it starts, and preflight checks it before every run. A run chooses among the names; to change a model, edit its line in agents.

An agent session is one agent across several turns of a workflow: it resumes the harness session it holds, and starts fresh when it cannot. A session reference is the piece of data that makes the resume possible, small and plain enough to pass to a later step.

The factory holds generated code

The Workflow SDK gives each workflow and step a durable ID made from its file path and function name. A waiting run is tied to those IDs.

jigs generate writes two files into jigs/, and a workflow imports from them by name:

import { provisionWorktree, setTicketStatus } from "#jigs/steps";
import { reviewTicket, runAgent } from "#jigs/routines";

jigs/steps.ts holds every step jigs provides: small "use step" wrappers around jigs' operations. It is the only generated file with a directive, so every name in it is recorded and replayed.

jigs/routines.ts holds the routines, bound to those steps. runAgent, reviewTicket, watchPullRequest and pullRequestGate are routines.

Commit jigs/ and never edit it. jigs generate refreshes it from the installed jigs version, a build fails with that repair if it is out of date, and jigs upgrade regenerates it for you.

The directives live in your factory because the IDs have to stay put. If the "use step" functions lived inside the jigs package, every upgrade would move them and strand the runs that were waiting.

Renaming moves an ID

Moving or renaming a workflow file, a workflow function or a step changes its address. Finish or cancel the runs that use it before you deploy the rename.

The same holds for the generated files: a jigs release that moves jigs/steps.ts or renames a step in it moves those IDs, and says so in its release notes.

Two import sources

A workflow imports from two kinds of place. The library, @jigs-ai/jigs, holds types, constructors and pure functions such as defineWorkflow, harnesses and renderTicketSnapshot. #jigs/steps and #jigs/routines hold the durable operations generated for your factory.

import { defineWorkflow, harnesses } from "@jigs-ai/jigs";
import { reviewTicket } from "#jigs/routines";
import { provisionWorktree, setTicketStatus } from "#jigs/steps";
import { implementAndReview } from "./delivery/delivery.ts";

Import a workflow's own files with relative paths. The workflow loaders in jigs.config.ts stay relative too.

The split is there so you can see it. Every name from #jigs/steps is one recorded operation, and every name from #jigs/routines composes those.

Factory layout

jigs init writes these files:

File	What it is for
jigs.config.ts	Service ports, bindings, registered workflows, schedules and policy. See Configuration.
jigs.config.test.ts	Checks the registered workflows and the durable IDs the build emits.
jigs/steps.ts, jigs/routines.ts	The generated files described above.
workflows/hello/hello.ts	The first workflow. Each workflow gets its own directory under workflows/.
.env.example	The environment file template. Copy it to .env for secrets.
package.json	Pins jigs and maps #jigs/* to the files in jigs/.
nitro.config.ts, docker-compose.yml, tsconfig.json, vitest.config.ts, pnpm-workspace.yaml, .gitignore, README.md	Build, database and tooling settings.

A workflow keeps what it owns beside it. Its own "use step" functions go in a steps.ts in its directory, and its prompts and other files next to that.