Quest Master · crystl Docs

Most quests start with a party. Planning-first quests start with a goal. You describe what you want done, and the Quest Master turns that goal into a sequence of titled levels your party clears together. It’s the front door for staged quests: instead of hand-writing a questline file, you talk it through.

The Quest Master is a special catalog hero, and it is deliberately not one of the adventurers. It never joins the party chat, never plays, and never assigns tasks to a named hero. It authors the arc, helps you pick a party, and then sits off to the side keeping watch. Think of it as the game master at a tabletop: it shapes the mission and adjudicates, it doesn’t roll dice for you.

What the Quest Master does

What it never does: enter the party chat (#quest), assign work to a specific hero, gate an individual hero, or take responsibility for the choices your heroes make. That boundary is the whole point. Keeping it out of the room stops it from becoming a coordinator by social gravity, and keeps the level barrier running with no standing orchestrator to stall the party.

Plan Quest

Open the planner from Quest → plan quest (Cmd+Shift+P), or from the plan quest row in the quest button’s menu. The quest window opens party-free, straight onto the quest master tab, and auto-summons the Quest Master for you. There’s no party yet, so nothing has been posted to any chat, you’re just talking to the Quest Master.

You’ll see its greeting, then you describe your goal. As you talk, it authors titled levels into the plan document at .crystl/quest/quest-plan.md, which opens in the workbench editor beside the conversation.

The plan and the conversation stay in sync both ways. Levels the Quest Master authors render into the doc; edits you make to the doc fold back into the questline. So you can steer the plan by talking, by editing the markdown directly, or both.

If your goal turns out to be a single-phase job, the Quest Master will say so (“this doesn’t need levels, just run the party”) rather than inventing structure that isn’t there. Levels are for goals with real sequential phases.

Beginning the quest

Planning and launching are two deliberate steps, so the Quest Master can never spin up agents on its own.

  1. Get ready. When the arc is shaped, tell the Quest Master you’re ready, or it will offer once the levels look complete. It stages the begin-quest panel for you, pre-filled with its suggested heroes and the open-or-sealed call already set.
  2. Begin the quest. The begin quest → button in the quest master tab opens that pre-filled panel. It glows once the Quest Master signals the arc is ready, so you know when there’s something to launch. The panel’s own begin quest button is the actual launch, and that click is always yours. The Quest Master fills the form; you press go.

The party then launches straight into the levels the Quest Master already authored, so the mission is present from the first turn, no need to prompt the heroes to start.

Save as template

Beside begin quest → is a save as template button. It saves the plan you’ve authored as a committable questline template under .crystl/questlines/, so you can launch the same shape again later, and everyone who clones the repo gets it. See quest levels for how templates work.

During a running quest

Every quest has a Quest Master, not just planned ones. When a quest starts (from Plan Quest, quick start, or continue), crystl auto-summons a Quest Master in a dormant state: spawned but idle. A dormant agent burns no tokens until something gives it input, so the only cost is one quiet background process.

The split keeps the roles clean: the reminder needs no judgment, so an automatic message handles it without waking an agent, and the Quest Master never contacts heroes, it authored the level, so an unclear brief is its to repair and the report to you stays a neutral referee’s.

Summoning it from the CLI

plan quest is the usual way in. If you want the Quest Master on its own, crystl quest master summons it headlessly:

crystl quest master                       # summon into the selected gem
crystl quest master --gem myapp
crystl quest master --model opus          # override its model for this summon

Level authoring is reasoning-heavy and low-volume, so it’s a good place to trade up to a higher-reasoning model with --model. After summoning, open plan quest to talk to it. See crystl quest for quest propose (pre-fill the begin-quest panel) and quest templates (save and list questline templates).

Related docs