# Your first workflow

This page takes you from a fresh install to a running, inspectable workflow
in about five minutes. Run the workflow a fresh install shows first, then
inspect it and make it your own.

If any term below is unfamiliar, the [core concepts](/docs/getting-started/concepts)
page has the full glossary.

## 1. Seed the examples

If you haven't initialised Roscoe yet, do it now. This writes a set of
example workflows into `~/.roscoe/workflows/` so you have something to run.

```bash
roscoe init
```

You should see `~/.roscoe/workflows/demo-1-the-panel.workflow.yaml` among the
files it created. That's the one we'll use: hand a brain-teaser to five
solvers who work it independently, then watch the panel go with the answer
most of them land on.

## 2. Look at the workflow

Open it in any editor:

```bash
$EDITOR ~/.roscoe/workflows/demo-1-the-panel.workflow.yaml
```

```yaml
name: demo-1-the-panel
version: 1
description: >-
  Hand a brain-teaser to five solvers who work it independently, no comparing
  notes, then watch the panel go with the answer they mostly landed on.
initial: panel
spendingCap:
  usd: 5
inputs:
  - name: riddle
    type: string
    optional: true
    description: The puzzle for the panel to crack.
    default: >-
      You're on a game show with three doors. Behind one is a car; behind the
      other two, goats. You pick Door 1. The host, who knows what's behind
      every door, opens Door 3 to reveal a goat, then asks whether you'd like
      to switch to Door 2. What should you do to give yourself the best odds
      of winning?
states:
  panel:
    type: consensus
    label: Put it to the panel
    model: claude-haiku-4-5
    prompt: |
      Solve this puzzle. Reason it through carefully on your own, then commit
      to one answer.

        "{{ riddle }}"
    agentCount: 5
    quorum: 3
    validator:
      kind: answer
      choices:
        - Switch to Door 2
        - Stay with Door 1
        - It makes no difference
    on:
      decided: chair
      undecided: chair
  chair:
    type: ai_agent
    label: Explain the answer
    model: claude-sonnet-5
    prompt: |
      Five solvers just worked this puzzle independently: "{{ riddle }}"

      Where they landed: {{ panel.winningValue || "no clear answer" }}
      How the vote split: {{ panel.distribution }}

      Give the person a short, clear readout of the panel's answer.
    on:
      next: done
  done:
    type: end
    label: Answer in
    outcome: success
```

> The real seeded file also points two of the five solvers at a second
> model and sets a per-agent timeout. This trimmed version keeps the moving
> parts visible.

The structure to know:

- `initial: panel` sets where execution starts: the state called `panel`.
- `spendingCap: { usd: 5 }` stops the run once it's spent $5, so a first run
  can't surprise you.
- `inputs:` declares `riddle`, an optional string with a default. Run the
  workflow untouched and it solves the Monty Hall problem above; pass your
  own riddle to solve something else.
- `type: consensus` runs the same prompt through `agentCount` (5)
  independent model calls that don't see each other's reasoning, then
  checks whether at least `quorum` (3) of them landed on the same answer.
  `validator: kind: answer` restricts each solver to one of the listed
  `choices`. See [consensus](/docs/nodes/consensus).
- `on: decided / undecided` are the two transitions an `answer`-mode
  consensus node can emit. This workflow sends both to `chair`, so the
  panel gets an explanation whether or not it converged.
- `type: ai_agent` is a single model call, no voting. `chair` reads
  `panel.winningValue` (the majority answer) and `panel.distribution` (how
  the vote split) and writes the readout. See
  [ai_agent](/docs/nodes/ai-agent).
- `{{ riddle }}` and `{{ panel.winningValue }}` interpolate: each pulls a
  value, from an input or an earlier step's output, into a prompt before it
  runs. That's how data flows between nodes.
- `type: end` with `outcome: success` is a terminal state. The run finishes
  with a green check.

For the full schema, see [YAML structure](/docs/authoring/yaml-structure).

## 3. Run it

Make sure the server is up:

```bash
roscoe serve
```

Then in another terminal:

```bash
roscoe run demo-1-the-panel
```

Five solvers work the Monty Hall problem independently. Watch for a split:
some fall for the 50/50 trap, most don't. The majority answer routes to
`chair`, which writes a short explanation, and the run ends with a green
check.

## 4. Inspect the run

Open the web UI:

- Production install: <http://localhost:7777>
- Dev (`bun run dev`): <http://localhost:3000>

The **Runs** view lists every run, newest first. Click the one you just
triggered. You'll see:

- The **graph** of the workflow with the path that was taken highlighted.
- A **per-node trace** with each state's inputs and outputs, plus the
  transition key it emitted.
- The **structured result** each step returned: `panel`'s five individual
  votes and the winning answer, then `chair`'s readout.

This is the same trace you'll use to debug anything that goes wrong, so it's
worth poking around now. Notice how `panel`'s vote split threads into
`chair`'s prompt, and from there into the plain-language readout.

## 5. Make it your own

Swap in your own riddle without touching the file. Pass it as a named input
with `--input`:

```bash
roscoe run demo-1-the-panel --input riddle="Is it worth paying extra for the aisle seat on a two-hour flight?"
```

Re-run it a couple of times. Each solver reasons independently, so the vote
split moves around from puzzle to puzzle, and sometimes from run to run,
while `chair` keeps making sense of whatever the panel lands on.

## Where to next

- [YAML structure](/docs/authoring/yaml-structure) — every field, every
  type.
- [consensus](/docs/nodes/consensus) and [ai_agent](/docs/nodes/ai-agent) —
  full reference for the two node types you've used.
- [Core concepts](/docs/getting-started/concepts) — the vocabulary in one
  place.