Pipelines & the editor

A pipeline is a list of steps plus the settings they share: a workspace, variables, subagents and a concurrency limit. Each step is an agent (a prompt run on a harness and model), a shell command, or a human approval. Steps form a graph: by default each step runs after the previous one, and Runs after lets you branch and join. Steps can loop back on failure, retry, time out, run conditionally, or let the pipeline continue past them.

Step typesAgent, shell and approval steps, with every option.

TemplatesVariables, filters and conditionals for prompts and commands.

Built-in templatesDemo, Feature, Bug fix and Blank pipelines.

ExamplesComplete pipelines you can import.

The Pipelines page

Pipelines in the sidebar lists every pipeline as a card, grouped by project (pipelines without one are under No project). Each card shows the step count, the harnesses used, the workspace, how many triggers use it, status icons for the last eight runs, and a read-only graph. Card actions:

Button	What it does
Export JSON (download icon)	Copies the pipeline as JSON to the clipboard.
Duplicate (copy icon)	Creates a copy named <name> (copy).
Edit	Opens the editor (so does clicking the card).
Run	Opens the Start a run dialog for this pipeline.

The page header has New project and New pipeline. New pipeline opens a dialog with three ways to create one:

1. Describe it and let an agent build it: type what you want, pick a harness, click Build with AI. See Generating pipelines with AI.
2. Or start from a template: Demo (Simulator), Feature, Bug fix (fast lane) or Blank pipeline. See Built-in templates.
3. Or import a pipeline JSON: paste an export and click Import.

The editor

The editor has three areas:

• Left column: a Pipeline settings card and the list of Steps. Each step shows its number, type icon, name and a summary (harness and model, the command, or “human gate”). A ↺ icon marks steps with a loop-back. Drag steps to reorder them. Below the list, + Agent, + Shell and + Approval add a step after the selected one (or at the end).
• Graph (top): the step DAG, laid out left to right by dependency depth, with loop-back edges drawn underneath. Click a node to select that step.
• Main panel: the settings of whatever is selected.

The header shows the pipeline name, its project, the step count and saved / unsaved changes, with these actions:

Action	Notes
Delete pipeline (trash icon)	Asks for confirmation. Existing runs are kept. Refused while a trigger still uses the pipeline: “A trigger still uses this pipeline. Delete or re-point it first.”
New pipeline	Opens the New pipeline dialog.
Discard	Reverts unsaved changes.
Save	Also ⌘S / Ctrl+S. Disabled when nothing has changed, or while there are validation problems.
Run	Disabled while there are unsaved changes (“Save first”).

Problems found by validation are listed in a warning box above the settings. You can’t save until they’re fixed.

Pipeline settings

General

Field	Default	Notes
Name	from the template	Shown everywhere, and available as {{pipeline.name}} and $FACTORY_PIPELINE.
Color	from the template	One of seven swatches. Display only.
Description	from the template	Display only.
Project	No project	Joins a project, sharing its workspace, commands, variables and env.
Max concurrent runs	template-specific; 0 for Blank	How many runs of this pipeline can be active at once. 0 = limited only by the global setting (Settings → Max concurrent runs, default 3).

Workspace: the workspace mode and its settings: Existing folder, Git worktree, Fresh clone or Empty folder, with Folder / Local repository / Repository URL, Base branch and Branch name template as applicable. Inside a project, the Use the project’s workspace toggle decides whether the project’s or the pipeline’s own workspace is used. See Workspaces.

Variables: key/value pairs available as {{vars.NAME}} in prompts and commands, overridable per run. In a project, inherited values are listed first. See Variables & precedence.

Subagents: specialised agents that agent steps can delegate to. See Subagents.

Step settings

Selecting a step shows:

• Step: the type picker (Agent, Shell, Approval), Name and Step id, plus Move up, Move down, Duplicate step and Remove.
• Type-specific sections: Harness & model, Prompt (with an optional System prompt) and Subagents for agents; Command for shell steps; Approval for approval steps.
• Flow: Runs after, Timeout (minutes), Retries on failure, Run only if, and Continue the pipeline even if this step fails.
• Quality gate & feedback loop: Pass if output matches (regex), Fail if output matches (regex), On failure, loop back to, Max loops.
• Environment: extra environment variables for this step.

Every option is documented in Step types.

Editing conveniences:

• While a step’s id still equals the slug of its name (as it does for new steps), renaming the step updates the id too.
• Changing a step id updates every Runs after and loop back to reference to it.
• Removing a step rewires its dependents to depend on the removed step’s own dependencies, and clears loop-backs that pointed at it.
• Duplicate step inserts a copy after it with id <id>-copy and name <name> (copy).
• New steps get ids like agent, agent2, command, approval, and depend explicitly on the step they were added after.
• The prompt, command and approval editors show clickable chips for every available template value, including vars.* and steps.<id>.output for the other steps. Click a chip to insert it at the cursor.

Validation

A pipeline can’t be saved while any of these problems exist:

Rule	Message
Step ids start with a letter or _ and contain only letters, digits, -, _	Step N: id "x" must be letters, numbers, - or _
Step ids are unique	Duplicate step id "x"
Agent steps have a harness	Step "Name": choose a harness
Agent steps have a non-empty prompt	Step "Name": prompt is empty
Shell steps have a non-empty command	Step "Name": command is empty
Runs after references existing steps	Step "Name" depends on unknown step "x"
loop back to references an existing step	Step "Name" loops back to unknown step "x"
Pass/fail patterns are valid regexes	Step "Name": invalid regex …
Dependencies don’t form a cycle	Step dependencies contain a cycle
Subagent names are lowercase letters, digits, - (starting with a letter)	Subagent "x": name must be lowercase letters, numbers or -
Subagent names are unique	Duplicate subagent "x"
Subagents have a description and prompt	Subagent "x": description is empty / prompt is empty
Agent steps only attach defined subagents	Step "Name" uses unknown subagent "x"

Workspace problems (no folder, repository or URL set) don’t block saving, but they block starting a run. See Workspaces.

Note

Loops don’t count as cycles. A loop is expressed only with On failure, loop back to, never with Runs after.

Pipeline JSON

Export JSON produces the pipeline without its id and timestamps, tagged with "jimothyPipeline": 1. This is also the format Import accepts and the pipeline-builder skill produces.

{
  "jimothyPipeline": 1,
  "name": "Feature: Plan → Build → Review → PR",
  "description": "Multi-harness feature pipeline with cross-model review and a human gate.",
  "icon": "rocket",                 // rocket | bug | sparkles | workflow
  "color": "#60a5fa",
  "repo": {
    "mode": "worktree",             // inplace | worktree | clone | scratch
    "localPath": "/Users/me/code/app",
    "url": "",                      // clone mode
    "baseBranch": "main",
    "branchTemplate": "jimothy/{{issue.key | slug}}"
  },
  "projectId": "prj_…",             // optional
  "ownRepo": false,                 // optional, in a project: use this pipeline's own repo
  "concurrency": 2,
  "variables": { "testCommand": "npm test" },
  "subagents": [],                  // optional, see Subagents
  "steps": [ /* see Step types */ ]
}

On import:

• name and a steps array are required (“Not a pipeline export” otherwise), and the result must pass validation.
• A missing repo becomes an Empty folder (scratch) workspace.
• projectId is kept only if that project exists in this app. When you import from inside a project, the pipeline is placed in that project.
• Missing variables become {} and missing concurrency becomes 0.

Step fields in JSON match the editor: id, name, type, harnessId, model, prompt, systemPrompt, subagents, command, approvalMessage, dependsOn, timeoutMinutes, retries, continueOnError, passPattern, failPattern, loopBackTo, maxLoops, env, runIf. See Step types.