World Builder’s Guide to V1 → V2 Migration

If you built a world for GM Harness 1, this guide is for you. GM Harness 2 changes how three things work: memory, instructions, and trackers. Here’s what changed, why, and what to do with your world.

Your world needs an upgrade

To get the benefits of Harness 2, you need to upgrade your world. Harness 2 reads instructions from a new place, and much of what worlds built for Harness 1, like memory and tracker files, now gets in its way. We’ve made upgrading as easy as we can:

• We’re offering a free AI upgrade wizard to help you easily update your world from V1 → V2
• Claude Code with the Craft CLI gives the best results. Claude Opus 5.5 is the smartest model available, and it’s much more cost effective to use a Claude Code subscription + Craft CLI than to use it directly, which is why we recommend doing so.
• Both handle saving a version of your world first, so you can always go back to Harness 1.

See Upgrading your world below for how each one works.

On November 15, 2026, any world that hasn’t been upgraded becomes unlisted, and it has to go through the upgrade before it can be listed again. Harness 1 games keep working. Nothing gets deleted. If you can’t upgrade by then, that’s fine: none of your data is lost, and you can still upgrade later.

Everything was a file

In GM Harness 1, everything was a file. Your rules were files. So were your GM instructions. If you wanted the GM to remember the campaign, you built memory files and told it to keep them up to date. If you wanted it to track a heist’s alarm or a faction’s mood, you made a tracker file and told it to update that too.

That gave you a lot of freedom, and you used it well. But it also caused problems:

• It was slow. The GM spent much of every turn reading and rewriting its own notes.
• The GM had too much to follow. On top of your instructions, it had to follow a long list of Craft’s own system instructions and processes.
• Instructions as files were hard to manage. They were confusing to organize and use, and they left us no good way to guide you toward instructions that work.
• Everyone had to build their own memory. It was interesting to see what you built, but most memory systems ended up looking alike. Memory is a platform-level job, and it wasn’t right to expect every world builder to do it. You should get to focus on how your game looks, feels, and plays. Memory should be our job.

In GM Harness 2, three of those things move into the GM itself:

• Memory is built in.
• Instructions have a new format.
• Trackers are built in.

Your rules, characters, places, and items stay files, exactly as they are. You also get player options: choices players make when they start a game, like difficulty or tone.

Before you start

• Players get Harness 2 only when you publish. New games start from your latest published version, so players keep Harness 1 until you publish a version on Harness 2.
• Games in progress stay on Harness 1. They move over only if their owner chooses to (see What happens to your players’ games below).
• Heads up for public worlds. Once your world is public, every version you save goes out to players right away. If a Harness 2 version ships broken, use Promote to Published on your last Harness 1 version to point players back at it.

Memory

Memory is one of the most important parts of a good GM. Creators tried all kinds of memory systems on Harness 1: campaign logs, world state files, session logs, chapter archives, memory fields on characters, and instructions like “re-read the campaign log before every reply.”

The problem was that file based memory would degrade over time faster than other memory systems, and to make memory work for extremely long running campaigns, we would need to implement a native memory system.

That’s why memory is now part of Craft itself. As a platform feature, it can use things files can’t, like vector embeddings, which let the GM search past play by meaning instead of exact words.

Here’s how it works in Harness 2:

• Recent play stays word for word. The GM reads the latest turns exactly as they happened.
• Older play becomes chapters. As a game goes on, earlier turns are folded into chapters, each with a title, a short synopsis, and a detailed account.
• The whole story stays in view. The GM keeps a running summary of the entire game.
• It looks things up. When something from long ago matters, like a key you picked up three hundred turns back, the GM searches the earlier chapters and your world’s files for it.

It works on its own, so there’s nothing for you to maintain.

What to do

Start by removing as much as you can, then add back only what you need. The memory system isn’t perfect, and it’ll keep getting better, but it likely already handles most of what you used to patch in yourself.

• Remove memory instructions. That means anything telling the GM to write, update, or re-read memory.
• Remove memory fields from your file types, like a Memory or Notes on the party field on characters.
• Hide memory files such as Campaign State, World State, Campaign Log, or Session Log. The upgrade’s Clean up step does this for you.

You can still have the GM update fields on files, or write new files, if your world really needs it. Maybe your world has a ship’s log the player is meant to read. That still works. We just don’t recommend using files as the GM’s memory anymore. Play a long game and see what the GM remembers before you add anything back.

Instructions

In Harness 1, worlds often packed in as many instructions as they could fit: dozens of pinned rules, long rule dumps, and procedures for every situation. The trouble is that it’s hard for a model to follow too many instructions at the same time. The more it carries on every turn, the worse it follows each one.

So Harness 2 has a new format with two kinds of instruction:

• Always on instructions work like your old pinned ones: the GM reads them on every turn.
• Situational instructions replace triggered ones. Each has a Triggered when… moment, and the GM only gets the instruction when that moment comes up. You can have up to 100, up from 20.

You’ll find both in your world’s Game Master settings, under Instructions. For the full guide to writing them, see Writing GM Instructions.

Here’s where your old instructions go:

In Harness 1	In Harness 2
Pinned instruction files	Always on, but only if the GM needs it on almost every turn
Narrative triggered instructions	Situational instructions
Tool triggered instructions	A situational instruction about the moment, or drop it
Several files about the same moment	One situational instruction

Context Visibility: Pinned and Partial are gone

In Harness 1 you could pin any file so the GM read it every turn, or set it to Partial so the GM only saw its name and description. Harness 2 doesn’t use either one. Every file is now Visible or Hidden. The GM can look up any visible file when it needs it, and it never sees hidden ones.

We found that worlds were pinning a lot of context the GM didn’t need, and all that extra text made it play worse. That’s why there’s no pinning in Harness 2, and why always on instructions, which go in the GM’s system prompt, have a strict 10,000 character limit.

This matters if you pinned your rules files, because they’re not in every prompt anymore. Harness 2 looks up the files it needs far more reliably than Harness 1 did. If the GM needs a rule on almost every turn, like your core roll, write it as a short always on instruction. Leave the full rules in your files. For a file the GM keeps missing, add a situational instruction that tells it when to look.

Write each instruction for its moment

The key is to write your instructions so they show up at the right time. The GM doesn’t need your death save procedure on every turn. It needs it when someone falls unconscious.

Triggered when: A character drops to 0 HP

What the Game Master does: They fall unconscious and make a death save at the start of each of their turns: roll a d20, and 10 or higher is a success. Three successes and they stabilize. Three failures and they die. A natural 20 brings them back with 1 HP.

A few more examples:

Instead of always carrying…	Make it situational
Initiative and turn order rules	When a fight starts
How spell slots and concentration work	When someone casts a spell
Short and long rest rules	When the party rests
Prices and haggling	When someone buys, sells, or haggles
Travel pace and supplies	When the party sets out on a journey

Before each turn, Craft reads the player’s move and picks the situational instructions that fit. Up to 5 can apply on a turn. Describe a moment, not a keyword, and put the ruling in the first sentence or two.

Keep always on instructions for what matters on every turn: your premise, your tone, and your core roll, plus a few standing rules. Shorter is followed more reliably, so aim to use about half of the room Craft’s defaults leave.

Remove

With so much of how the GM works changing, many of your old instructions no longer apply. Take these out, play test, and add back only what the GM doesn’t handle on its own:

• Memory systems. See Memory above.
• Tracker upkeep. Anything telling the GM to update a tracker file. Use a tracker instead (see Trackers below).
• Bookkeeping rules. “After every purchase, subtract the gold,” “always write the new HP to the sheet,” and lists of fields to update. The GM records changes as it narrates them.
• Map and token rules. Moving tokens, pinning new locations, and removing defeated enemies. The map follows the story on its own.
• Roll procedures. “Never resolve a roll yourself” and “wait for the player to roll.” Asking for a roll now ends the GM’s turn on its own. Keep your core roll (see Change below).
• Output formats. Anything about beats, JSON blocks, headings, lists of choices, or how to format dialogue. The GM writes plain prose with speaker lines, and the new game screen is built around that.
• Tool instructions. Anything about the bash tool, shell commands, or file paths. The GM knows its own tools.
• Copies of Craft’s defaults. Every world comes with Craft’s own instructions, trackers, and player options. You can edit or remove any of them, but there’s no need to write your own versions.

If your Harness 1 world had…	Harness 2 has…
“Never speak or act for the player”	The Player agency instruction
Rules about reply length	The Response length player option
“End every reply with a hook”	The Story pacing player option
Rules for skipping or playing out journeys	The Long-distance travel player option
An initiative tracker	The Combat tracker
A quest log	The Objectives tracker
A world clock	The Time tracker

Change

• Your dice. Put your core roll and its dice in an always on instruction. If your rules never use a d20, naming your dice there stops the GM from rolling one. Don’t write “never roll a d20,” because that names a d20. If you roll under a number or count successes, say how to read the result.
• Your calendar. If your world doesn’t use an ordinary calendar, describe yours in an always on instruction, or in the rules of Craft’s Time tracker: its months, its weeks, its holidays.
• Long rule dumps. Break big blocks of rules into situational instructions, one per moment, like the death save example above. Reference material such as a spell list or an equipment table can stay a file, and a situational instruction can point to it.
• Duplicates. Harness 1 worlds often grew several files about one moment. Merge them into one complete situational instruction.
• House-rule variants. If your instructions switch between ways of playing (“in hard mode…”), turn them into player options: questions players answer when they start a game, like difficulty, tone, or how lethal fights are. Each choice brings its own instructions. Pick a default that plays the way your world always has. A world can have 9 player options, Craft’s 3 included.

Trackers

If you built tracker files, Harness 2 has trackers built in.

Trackers are made for state that keeps changing: a heist’s alarm, a chase across the rooftops, how a faction feels about the party, the supplies left on a long road. A tracker keeps the current value up to date in the game’s current state, where players can see it change. It doesn’t save every change as a record, because you don’t need one. You just need to know where things stand right now. You don’t need every detail of a fight from 100 turns ago.

Files are still the place for things that should last: characters, places, items, and lore.

What a tracker can look like

• A number, shown as a plain number, a bar, dots, a clock that fills slice by slice, or a tug of war between two ends.
• A list, shown as a turn order, a table, a roster, or a checklist.
• Text and links for anything else.

When a tracker changes, the player sees it in the story: +1, 3 of 6, New objective…, Completed…

Making one

Open Game Master › Trackers and press Add tracker. Start from a Blank tracker or a template: Combat, Time, Supplies, Settlement, Harvest Calendar, Alarm, Wanted, Deadline, Chase, Reputation, Relationships, or Clues.

Then tell the GM three things:

• When it’s in play. It can appear at game start, on its first change, or when a moment happens (the Starts when field). It can go away when the party leaves the place, when the GM ends it, or never.
• When it updates (the Update when field). For example: the crew draws attention.
• What it means (the How GM uses field). For example: At 6, the Watch raids the hideout.

Up to 10 trackers can be in play at once, plus Time.

A few tips:

• Check Craft’s trackers first. Every world comes with Combat, Objectives, Party, Death saves, and Time. Many Harness 1 worlds built their own versions of these.
• Don’t copy stats into a tracker. HP and mana already live on character sheets. A tracker can show a stat from the sheet, so there’s nothing to keep in sync.
• Hide it if it’s a secret. A tracker can be hidden from the player, so only the GM sees it.

Moving a tracker file

1. Make a tracker for it, from a template if one fits.
2. Remove any instruction that told the GM to update the old file.
3. Hide the old file. The Clean up step offers to do this.

For example, a Heat Tracker file and an instruction saying “After every job, update Heat” become one tracker: Heat, shown as a 6-slice clock, updated when the crew draws attention, and At 6, the Watch raids the hideout.

Your old tracker files would still work on Harness 2 if you carried their instructions over, but we don’t recommend it. In testing, leftover tracker files led the GM to write changes into them instead of onto the character sheets where they belonged.

Relationship, bond, and reputation files that hold real story about your characters are content, not bookkeeping. Clean up never offers to hide them, and you can keep them.

Game starts and example files

• Game starts. Harness 2 doesn’t read a game start’s opening instructions. Move what they say into the game start’s Opening Scene (what the scene is for, the party’s first objectives, how your trackers start) and Opening notes (private to the GM). See Game Starts for details.
• Example files. When the GM creates a character, place, or item, it models it on your closest similar file. Keep one complete, good example of each type.

Upgrading your world

There are two ways to upgrade: the upgrade guide in Craft, or Claude Code with the Craft CLI. Both translate your instructions and switch your world to Harness 2. The guide in Craft is the quickest, and it’s free. Claude Code is the best way, because it lets you use the most capable models, like Claude Opus 5.5, for far less than API prices. It can also do the parts the guide leaves to you, like trackers, memory fields, and game starts, and you can talk through the choices with it as it goes.

In Craft: the upgrade guide

Open your world and press Upgrade on the banner (it’s also in Settings › Game Master). A short guide walks you through five steps. You can keep editing your world while it’s open.

1. What’s changing. A quick summary.
2. Save a version. This keeps your world exactly as it is today, on Harness 1. If you ever need to go back, restore that version from Version History.
3. Translate. It’s free (we cover the cost of GPT-6 Sol, the model it runs on) and takes a couple of minutes. Craft rewrites your GM instruction files as new instructions, drops what Harness 2 handles itself, and turns choices your world already offers into player options. The report tells you what happened to every file (kept, merged, rewritten, moved into a player option, or dropped) and why. It also flags anywhere an old instruction disagreed with your rule files, and your rule files win. In one world we upgraded, the instructions said Help gave +1, but the combat rules said +2. Treat the translation as a first draft and read it through.
4. Clean up. Craft finds the memory and tracker files Harness 2 doesn’t need and offers to hide them from the GM. Hiding is the safe choice: the files stay in your world, and you can show them again later. You can also move them to the trash, or skip the step. Small groups are ticked for you. Check larger ones before you tick them, because some files are shaped like trackers but are really content, like a world’s quests.
5. Review and publish. Players get Harness 2 from the version you publish.

A few things are still up to you afterward: trackers (the translation doesn’t make them), memory fields, game starts, and example files. Each is covered above.

With Claude Code and the Craft CLI (recommended)

If you’d rather have an agent do the whole migration, clone your world and ask Claude Code to upgrade it:

npm install -g @craftrpgs/cli@latest
craft login
craft clone <your world's URL>

Open the folder in Claude Code and ask it to upgrade the world to GM Harness 2. Every cloned world comes with our upgrade guide built in, as a skill Claude Code reads before it starts. Other coding agents find the same guide through the world’s AGENTS.md. If you cloned your world a while ago, run craft pull first to get the latest version of the guide.

Claude Code will:

1. Offer to publish a rollback version first, so you can always go back to Harness 1.
2. Translate your instruction files into your world’s new instructions and player options, and tell you wherever an old instruction disagreed with your rule files.
3. Switch the world to Harness 2 in the same push, so your new rules arrive with it.
4. Set up trackers for what your old tracker files did.
5. Remove memory fields from your file types, and hide your old memory and tracker files.
6. Move your game starts’ opening instructions into Opening Scene and Opening notes.
7. Check and push the world (craft check, then craft push).

Claude Code asks before it publishes anything. See Using the CLI with Coding Agents to get set up.

Test, then publish

Before you publish, check your work in Craft:

• System prompt shows exactly what the GM reads on every turn, for any set of player options.
• Instruction tester lets you type a player’s move and press Test to see which instructions, trackers, and player options it brings in.
• Compare choices, in a player option’s ⋯ menu, shows its choices side by side with the differences marked.

To play a game on Harness 2, you need a version on Harness 2, because test games start from your latest version just like players’ games do. The exception is a world you’ve never published: its games start from your workspace, so you can play on Harness 2 as soon as you upgrade. On a public world, remember that saving a version sends it to players.

What happens to your players’ games

Your old GM instruction files stay in your world, marked Deprecated. Harness 2 doesn’t read them, but games still on Harness 1 do, so leave them there while those games are being played.

Games already in progress keep playing on Harness 1. Once your published version is on Harness 2, a game’s owner can move their game over when they click Get Updates. The update shows GM Harness, V1 → V2. If they take it, the GM reads back through the story first (“Getting your story ready”) and then carries on from where Harness 1 left off. That takes about a minute for most games and a few minutes for very long ones. A game that moves can’t go back.

Before you upgrade, a game’s owner sees their options in the game: start a new game on a world that’s already on Harness 2, wait for your update, or move the game over now with a free AI upgrade. The AI upgrade translates the game’s own copy of your instructions on a smaller model than the upgrade guide uses, so your own upgrade usually plays better.

Either way, Craft recommends a fresh game for the best Harness 2 performance, because a game moved from Harness 1 doesn’t play as well as one started on Harness 2.

Checklist

1. Memory instructions and memory fields removed, and memory files hidden.
2. Always on instructions cover your premise, tone, and core roll, and use about half of the room Craft’s defaults leave.
3. Rules the GM needs every turn are always on instructions, not pinned files.
4. Every other rule is a situational instruction written for its moment.
5. Nothing repeats Craft’s defaults.
6. Variants are player options, with defaults that play like your world did before.
7. Tracker files are trackers, and the old files are hidden.
8. Game starts use Opening Scene and Opening notes.
9. One good example file of each type.
10. Checked with System prompt and the Instruction tester.
11. Published, with release notes.

Upgrade your world, start a game, and tell us how it plays.