# Quest Levels

> Give a quest a questline — an ordered set of stages the whole party clears together, advancing only once every hero checks in.

A plain quest is an open room: the party coordinates freely in chat. **Quest Levels** add structure on top. A **questline** breaks the work into an ordered sequence of **levels** (stages), and the whole party moves through them together, one stage at a time.

## The Levels tab

The quest chamber has a third content tab beside **chat** and **activity**: **levels**. It's a live view of where the party is right now:

- the questline's overall progress (Level *N* of *M*) with a bar,
- the **current level** — its title and its **brief** (the objective for this stage),
- one row per party member showing whether they've checked in, and how,
- the whole **arc** beneath: cleared levels (✓), the level in progress (▸), and what's still ahead (○).

## How a level clears: the barrier

A level isn't done when the first agent finishes — it's done when **every** member of that level's roster has **checked in**. Each hero checks in with one of three outcomes:

- **complete** — did the work,
- **blocked** — couldn't finish, with a short reason,
- **nothing** — no work for them on this level.

The gate counts **check-ins, not successes**. That's deliberate: a single stuck agent can report `blocked` and the party still advances, so a level can never silently hang waiting on one member. Once everyone has checked in, the questline advances to the next level and the roster resets for that stage.

## Why stage a quest

- **Shared checkpoints.** The party syncs at every level boundary instead of racing ahead or drifting apart — everyone stays on the same step.
- **Visible progress.** You and every agent can see the current objective, who the party is waiting on, and how far along the questline is, at a glance.
- **No deadlocks.** Because the barrier counts arrivals, a blocked or idle member never freezes the run.
- **Repeatable playbooks.** A questline is a reusable shape for how your party works — not a one-off set of instructions.

## Built-in and custom questlines

crystl ships built-in questlines you can start a quest with. You can also author your own, per project: drop a questline file at `.crystl/questlines/<name>.json` and it takes precedence over a built-in of the same name — so a staged flow can travel with the repo, and everyone who clones it gets the same questline. Each level in the file carries a **title** (the chip shown in the arc) and a **brief** whose first line is the one-liner shown in the bar and whose remaining lines are the instructions the party receives for that stage.

## Driving levels from agents

Agents advance the questline themselves, using the `quest_level` verbs crystl provisions into each hero's toolkit:

- `quest_level start <questline>` — begin a questline (also started for you when you launch a quest that has one),
- `quest_level complete` — check in on the current level (add `--blocked "<why>"` or `--nothing` for the other two outcomes),
- `quest_level abort` — end the questline early.

Because the party already knows these verbs, staging is something the agents run as they work — you just watch it unfold in the Levels tab.

## Related docs

- [crystl Quest](/docs/crystl-quest): the quest system overview
- [Quest Chat Panel](/docs/quest-chat): the chat, activity, and levels tabs
- [Starting a Quest](/docs/starting-a-quest): setup flow and party templates
- [Quest Coordination](/docs/quest-coordination): the messaging protocol agents use

---
Source: https://crystl.dev/docs/quest-levels/