Bulk work
Note
Written for AI agents. Orbit and coding agents follow this page when they work on your world. You don't need it to use Craft, but it shows how an agent will approach the job.
Some jobs touch many files: a new field filled in across every item, a description pass over a folder of characters, a rename across a type, a whole world built from a brief. Done one file at a time, with every file read first, they are slow, cost a lot, and drift: the fortieth file comes out unlike the first. The way that works is the same everywhere: look at a few files, decide the change exactly once, hand the work out in batches (or script it), then check a few results.
When it is bulk work
- Five or more files with the same kind of change is bulk work. Plan it before you touch anything.
- A handful of tightly linked files (a faction and its three leaders) is not. Edit them directly; splitting the job costs more than it saves.
- A whole world is the largest kind: plan it in waves (below).
- Too big to do well at once: hundreds or thousands of new files, or turning a whole rulebook or PDF into files. Don't start it. Say so plainly, and recommend a first slice to try (one region, one chapter), then batches once it works.
1. Scope from the structure
Plan from what the world already tells you, not from every file's contents:
- List the folder or type. File names and counts are often enough to plan the job.
- Read the file type's schema for the field names and shapes.
- Open one to three typical files to learn their shape, tone and conventions. That is the sample. Stop there: don't read every file you are about to change.
2. Write the recipe once
Decide the change precisely before any file is touched. The recipe is what every batch follows, so the fortieth file matches the first:
- The exact fields to set, and where they go.
- The fewest inputs. Name the fields a value is worked out from. Often it is one: a materials list needs only each item's description, not the whole file.
- Values and vocabulary. A fixed list of allowed values ("Steel", "Leather", "Oak") or a clear rule keeps results the same across files and across helpers working in parallel.
- Edge cases. Which files to skip, and what to do when data is missing or disagrees.
- Schema first. If the change needs a new field, change the file type first, then fill the field in.
3. Do the work
Pick the way that fits the change:
- Hand it out when each file needs judgment: writing descriptions, tagging by meaning, inferring a value from prose. Split the files into batches and give each helper the recipe and its own list.
- Script it when the change is mechanical: renaming a key, setting a default, copying one field into another, working a value out from numbers. Code does it exactly, every time, at no model cost.
- Small batches yourself when neither is available: about five files at a time. For each batch, read only those fields of each file, then change only the fields the change touches. Don't read a file again after changing it; the result already said what changed.
Helpers see only the recipe and their own task, never the conversation, so the two together must say everything. Give each helper a fixed list of files no other helper has. Deletes, project settings, file types, images and maps stay with you, after the helpers report.
Ask Orbit for the whole change in one message. For more than about ten files it hands the job to subagents, shown as rows under its message, when Subagents is on in Orbit's settings (it is by default).
4. Check and report
- Spot-check, don't re-read. Open one or two changed files to confirm the recipe landed, plus any file a helper said it couldn't do.
- Report counts, not contents: how many changed, which were skipped and why, and what failed. Don't echo files back.
- Validate before it counts. Each change is checked against its file type as it is saved.
Auditing a world
An audit checks the files against each other and against the rules, and changes nothing until the creator picks fixes.
- Do it in one pass. One script (or one search per question) checks every file and returns how many were checked, the counts, and the problems with their evidence.
- Read the rules this turn. The GM instructions, the handbooks and the types' schemas are what the files are checked against.
- Check the world's words. Collect the terms the world defines: stats, conditions, saves, resources, currencies. A term exists when a field, a computed field's expression or a rule defines it. Then check each term the rules and the files' text use. A term from another game ("frightened" in a world whose fear condition is Shaken) or a name with nothing behind it is a problem.
- Look both ways. What is missing (a class without the features the sheet shows, a place no one can reach) as well as what is wrong.
- Split a big world. Check one kind or folder per helper, each with the same list of what to compare, then merge the findings and remove repeats yourself.
Lore against itself
A world's facts drift as it grows: one file says the war lasted ten years, another says thirty. Compare:
- Dates and the order of events. A founding, a war, a death: the same date and the same order in every file that names it.
- Who is alive, and where. A character dead in one file and ruling a city in another, or in two places at once.
- Ties. Faction membership, who leads what, family and rivals. Both sides should agree: a faction's leader is a member of that faction.
- Titles and ranks. One person, one title at a time.
- Names. One person spelled two ways, or two files for one thing ("The Red Hand" and "Red Hand").
- Numbers that recur. A city's population, a war's length, the distance between two towns.
- One fact in several files. Name every copy. Suggest one file as its home and point the others at it.
- Rules that disagree. The GM instructions, the handbooks, the types' fields and computed fields, and the scripts must say the same thing. A rule only in a handbook is a rule the GM never sees: the GM doesn't read the handbooks.
- Leftovers. Starter and scratch files (see cleaning up).
To find them, list each kind of fact first (every character's status and faction, every dated event) with a script or a search on the fields that hold it. Then find the files that mention each one, by name and by meaning, since a file can state the same fact in other words, and compare.
Report first
- Both sides, quoted. Each problem gives the conflicting text from each file, with the file names.
- A suggested answer. Say which version you would keep and why: the file that is the fact's home, or the one most files agree with.
- What you didn't check (hidden files, scripts, a folder you skipped), and every problem, or the first 20 with the count.
- Fix only what the creator picks. If the fixes touch many files, they are a bulk job of their own.
Building a whole world
A new world, or a game system with its content, is the biggest bulk job. Its parts depend on each other, so it is done in waves, and one planner keeps the decisions:
- Design before handing out. Write down the premise, tone, naming rules and quality bar; the game system's core rules and numbers; the folders and file types with their fields and references; and the list of files by type, with how many of each and how they link. Helpers never invent these on their own: give each the same written brief.
- Settle the foundation. Project settings and file types first. Batches written against a schema that is still changing come out incompatible.
- Fill in waves. Things others point at come first (factions, places, rules), then what points at them (characters, items), then what needs stable names (cross-links, GM instructions, the game start), then what attaches to finished files (images, maps, flows). Wait for every batch in a wave and fix what it got wrong before the next.
- Split by kind, not by file. One helper for the characters, one for the places, and so on, each with a fixed list of files. Never two helpers on one file, and never one guessing a file another hasn't written yet.
- Pull it together yourself. Check each wave for duplicate names, missing files, broken references, tone drift and rules that contradict each other. At the end, check the whole list against the plan.
See Building a world for what a finished world needs.
Doing it well
- The recipe is the work. Most bulk jobs go wrong in the plan, not in the edits. A vague recipe gives forty slightly different results.
- Fixed vocabularies beat free text for any value you will filter, count or compare later.
- Name what to read. Tell each helper exactly which fields to read, not only what to change. Small reads leave room for the edits.
- Keep the chat clean. Batches and helpers keep forty files out of the conversation, so everything after the job stays cheap and focused.
- Script what is exact, hand out what needs judgment. Arithmetic and renames don't need a model.
Mistakes
- Reading every file first. It fills the context, costs the most, and leaves less attention for the change itself.
- Working out each file's value yourself, then handing it out. It doubles the cost. Let each helper read its own files.
- Rewriting whole files for a field change. It risks losing fields you didn't mean to touch. Moving files to a new schema is the exception: see changing a type.
- Filling a field the type doesn't have yet. Change the schema first.
- Two helpers on overlapping files. One overwrites the other.
- Handing out work that needs the conversation or a decision halfway through. Helpers see only what they were told. Do that part yourself.
- Echoing results into the chat. Report counts, skips and failures.
- Picking a side yourself in an audit. The creator may know which version is right. Report both, suggest one, and fix what they pick.
- Checking a handbook only against itself. A handbook can agree with itself and still disagree with the GM instructions and the types.