# Quest Master

> Plan a quest by stating your goal. The Quest Master authors the levels your party moves through, suggests the heroes, and keeps watch while they work.

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](/docs/quest-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

- **Authors levels from your goal.** You describe the quest in plain language. The Quest Master breaks it into an ordered set of levels, each with a title and a brief (the objective for that stage), and writes them into the plan.
- **Suggests a party.** It reads your full [hero catalog](/docs/quest-heroes/) (local, custom, and built-in) and recommends real, summonable heroes for the work, plus whether the quest should run open or sealed. It recommends; you decide.
- **Answers your questions.** It can look up how quests, levels, and heroes work with `crystl docs`, and open the relevant doc right in your workbench editor rather than pasting a wall of text into the chat.
- **Stays on as a consultant.** Once the party is running, the Quest Master persists off to the side. It can adjust the briefs of levels the party hasn't reached yet, and it runs the stall nudge (below).

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](/docs/quest-levels/#how-a-level-clears-the-barrier) running with no standing orchestrator to stall the party.

## Plan Quest

Open the planner from **File → plan quest** (`Cmd+Shift+P`). 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](/docs/task-backlog/) 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](/docs/starting-a-quest/) 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](/docs/quest-levels/#questline-templates) under `.crystl/questlines/`, so you can launch the same shape again later, and everyone who clones the repo gets it. See [Quest Levels](/docs/quest-levels/#questline-templates) 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.

- **Amending downstream levels.** Reopen **plan quest** during a live quest to adjust the briefs of levels the party hasn't reached yet. The barrier engine and the already-cleared levels stay exactly as they are, you're only editing what's still ahead.
- **The stall nudge.** crystl watches for a roster member that's stuck on the current level (parked on a prompt, or idle past a threshold). It first delivers an automatic reminder straight into that hero's terminal: reach a terminal state, report [complete, blocked, or nothing](/docs/quest-levels/#how-a-level-clears-the-barrier) when you stop, so the party isn't left hanging. The reminder only asks the hero to decide, it never decides for it. If the hero stays stuck, crystl escalates to the Quest Master, whose two moves are judgment calls: review the level's brief and amend it if it's unclear or over-scoped (the stall cause it can actually fix), and surface the impediment to you ("rogue stuck on Level 2, idle 10m") rather than nudging forever.

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:

```bash
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`](/docs/cli/#quest) for `quest propose` (pre-fill the begin-quest panel) and `quest templates` (save and list questline templates).

## Related docs

- [Quest Levels](/docs/quest-levels/): the levels the Quest Master authors, the barrier, and questline templates
- [Starting a quest](/docs/starting-a-quest/): the begin-quest panel and party setup
- [crystl quest](/docs/crystl-quest/): the quest system overview
- [Quest Heroes](/docs/quest-heroes/): the hero catalog the Quest Master suggests from
- [crystl CLI](/docs/cli/#quest): `quest master`, `propose`, `templates`, and `start --template`

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