Quest Levels

Updated July 25, 2026

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.

You don’t have to hand-write a questline. The easiest way to get one is to state your goal and let the quest master author the levels for you. This page covers how levels work underneath, and how to save and reuse a questline once you have one.

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 with 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.

Questline templates

A questline you’ll want again is worth saving as a template. Templates are plain markdown files at .crystl/questlines/<slug>.md, and because they live in the repo they’re committable, so the same staged flow travels with the project and everyone who clones it gets it.

There are two ways to save one:

  • From the planner. When you’ve shaped a questline with the quest master, press save as template in the quest master tab.
  • From the CLI. crystl quest templates save "<name>" saves the gem’s authored plan as a template. crystl slugifies the name for the filename; add --force to overwrite an existing template with the same slug.

Launch a saved template two ways:

  • From the begin-quest panel. The questline dropdown lists your templates alongside any planned questline and the built-in questlines. Pick one and begin.
  • From the CLI. crystl quest start --template <slug> launches on that questline. Adopting a template implies a fresh arc: crystl archives any in-progress quest first, then copies the template into the runtime plan, so the template file itself stays pristine.

crystl also ships built-in questlines you can start a quest with, and you can still hand-author a local questline as JSON. When names collide, precedence is markdown template, then local JSON questline, then a shipped questline. Each level 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. See crystl quest templates for listing and saving from the command line.

Driving levels from agents

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

  • quest_level status reads the live questline (add --json for raw state),
  • quest_level start <questline> begins a questline (also started for you when you launch a quest that has one),
  • quest_level complete checks in on the current level (add --blocked "<why>" or --nothing for the other two outcomes),
  • quest_level abort ends the questline early.

The quest master authors levels with two more verbs, quest_level add '<title>' '<brief>' to append a level (pass --brief-file <path> to read the brief from a file), and quest_level edit <index> to revise one (--title, --brief, or --brief-file), plus quest_level remove <index> to retract a queued level (freely while planning; during a live quest only levels after the current one may go, and fixed questlines refuse). It signals a planned arc is ready to launch with quest_level ready. You don’t run these yourself; the Quest Master does the authoring while you describe the goal.

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