Core concepts
These are the words the rest of the docs use without stopping to explain them. They’re in the order you meet them in the Quickstart.
Project
Section titled “Project”A project is a repository linked to Scarn, and the unit that owns your
pipelines, work items, and workers. scarn init reads your repository’s
origin remote and either finds the project that matches it or creates one,
then records it in .scarn/scarn.jsonc as owner/slug — the owner’s
username and the project slug, the same pair as its web URL — so later commands
don’t need it. See scarn init.
Work item
Section titled “Work item”A work item is one thing to do: an issue, a ticket, or a sentence you typed. Work items are synced from GitHub, Bitbucket or Jira, or created by hand — the designer creates one for you when you describe the work instead of picking an existing item. Every pipeline run is a run on one work item, and every design session is built around one. See Connect GitHub, Bitbucket or Jira.
Pipeline
Section titled “Pipeline”A pipeline is a graph of nodes; each node runs a step, waits for a human, or
ends the run with succeed or fail, and its transitions name what runs
next. Pipelines are TypeScript files in .scarn/pipeline-builder/, written
with definePipeline() and built into a JSON document that Scarn stores and
runs. See Building Pipelines.
Default pipeline
Section titled “Default pipeline”The default pipeline is the one every new pipeline-builder directory starts
with, and the one the designer adapts: bug-pipeline.ts. It scores whether a
bug report holds enough to act on, with a deliberately low bar, and asks the
reporter for what’s missing only when there is nothing to start from.
Otherwise it investigates and reproduces the bug with every tool you give it,
and reports a reproduction confidence. Only a confident reproduction goes on to
a failing test. It then proposes a fix and waits at a decision node until you
approve it, and only then applies the fix. The designer adapts the investigate
step to what your environment can reach. Each step passes its whole output to
the next. It is an opinionated starting point: change any of it.
A step is the unit of work: an agent prompt and a typed result. The agent reads the prompt, does the work, and returns a result that must match the step’s schema. Each step runs on the host or inside your devcontainer — see Runtime below. See Defining Steps.
Evidence and artifacts
Section titled “Evidence and artifacts”Evidence is what a step leaves behind so you can check its work. Some of it is
in the step’s result, such as the default pipeline’s investigation report.
The rest is files, uploaded as the step’s artifacts when it finishes. The
agent saves them with the scarn-submit-artifact tool, or writes them to
${scarn.artifactsDir}. A step can also declare a file as a result field,
such as a screen recording, so a pipeline can check it exists and a work item
comment can show it. In the dashboard, a step’s Output shows its result and
Artifacts lists its files. A Playwright trace gets a View trace button
that opens it in Playwright’s trace viewer. See
Attaching artifacts to comments.
Transition
Section titled “Transition”A transition is what happens after a node finishes. Usually that’s the next
node in its chain. A condition reads fields of earlier steps’ results to
branch, and a decision node waits for a human to pick an action, such as
approve or reject, before the run moves on. The default pipeline branches on its quality check and its
reproduction confidence, and waits for a decision before the fix. See
Transitions.
Default automation
Section titled “Default automation”The default automation is the project automation that picks a pipeline for
each work item when it becomes ready. It lives in
.scarn/pipeline-builder/default.ts, and the designer writes one wired to the
pipeline it builds. It is published disabled; nothing starts until you run
scarn automations enable default. See
Project Automations.
Worker
Section titled “Worker”A worker is a process on your machine that claims tasks, runs the agent, and
reports its result and artifacts back. A task is one attempt at one step for
one work item. Each machine runs one worker in the background, and it works
on every project you add to it: scarn work starts it and adds the project in
your current checkout. Nothing runs until a worker is up, and you can run one
on as many machines as you like, a laptop or a CI box. Manage it with
scarn worker. See Running Workers.
Runtime
Section titled “Runtime”A step’s runtime decides where its agent runs. Runtime.devcontainer() is the
default: the worker clones your repository and runs the agent inside the
container your .devcontainer/devcontainer.json describes, which needs
Docker. Runtime.host() runs the agent on the worker’s machine in an empty
scratch directory, with no clone and no Docker — the designer uses it for
steps that don’t need your code, such as classification, scoring, and triage.
A devcontainer is optional to start, and the designer writes one. If your
repository has none, the design session authors
.devcontainer/devcontainer.json before it writes any pipeline file, from
what it read of your repository: version pins, the lockfile’s package manager,
docker-compose.yml services, and CI install steps. It does not build the
image, so your first run is what verifies it — if that run fails early,
suspect the container before the pipeline. scarn init only reports a
missing devcontainer. A pipeline made only of host steps never needs one. See
Runtime, or
Set up a dev container to write one by
hand.
The designer
Section titled “The designer”The designer is scarn pipelines design: an agent session that interviews
you about one work item and adapts the default pipeline
to it. Before it starts, it lists the MCP servers and skills it finds in your
repository, so it can offer those tools to your steps. It runs on a
Scarn-managed OpenCode runtime, using an AI provider you connect once —
the same connection your steps use later. When the files typecheck, it pushes
them and offers to run the pipeline on that work item. See
scarn pipelines design.
The studio
Section titled “The studio”The studio is a browser tab the designer opens: a live graph of the files it
is writing, with validation issues. It is read-only and redraws every time a
file changes. You can also open it on its own. See
scarn pipelines studio.
Dashboard
Section titled “Dashboard”The dashboard, at app.scarn.io, is where runs, logs, and traces live. It’s also where you can start a run by hand from a work item’s executions drawer, and where you connect GitHub, Bitbucket or Jira under Project → Settings → Integrations.