Quest Levels · crystl Docs

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:

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:

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

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 are in the repo they’re committable, so the same staged flow is committed with the project and everyone who clones it gets it.

There are two ways to save one:

Launch a saved template two ways:

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 global custom 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:

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 a fixed questline does not allow it). 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.

Related docs