You change how something should be done. A tone rule, a pricing line, the layout of a weekly report. You update it, and a week later one of your agents is still doing it the old way, because it read a different copy.
The fix I landed on is a split. Everything my agents read now sits on one of three levels: what's true, how the work gets done, and what happened. Each thing has one home on one level, and everything else points at that home instead of restating it. Here are the three levels, how to sort something new into them, and how I got there.
Level 1: What's True
This level holds the facts every job depends on. It points at nothing. Everything else points at it.
Decisions. Calls made once that every team and agent inherits. For us, that includes who each brand is for: LifeHack's videos speak to people in midlife, and this newsletter speaks to people building companies.
Brand basics. The voice, who the reader is, the logo. One folder per brand.
Standards for the work. What good output looks like. For us these are the visual looks for our images and videos, one folder per look with its prompt, its rules and a few approved samples. In your company it might be a report template, a contract clause library or a code review checklist.
The test for this level: it stays true no matter which job runs. If you changed every tool you use tomorrow, these would still hold.
Level 2: How the Work Gets Done
This level holds the doing. It points up, and it never restates what's above it.
Playbooks. The steps for a job. Ours for short videos explains how to cut a generated image into characters and assemble the video. Where it needs the look, it says one line: the look lives in its folder.
Agents. When something runs, which playbook it follows and what it's allowed to touch. Nothing else. Our video agent's setup is mostly a list of four places it may read: the brand folder, the video playbook, the look's folder and past videos. It has no craft of its own.
The test for this level: it would change if you changed how the work is done, but the facts above it wouldn't.
Level 3: What Happened
This level holds records: finished work and logs. Every video we've made has a folder with its script, the exact prompt it used that day and the final file.
Agents can read records. Our video agent checks past ones so it doesn't repeat itself. But nothing treats a record as an instruction. When a look changes, last month's prompt stays exactly as it was, because it's history, not a copy waiting to be updated.
The test for this level: it already happened.
Sorting Something New
When something new turns up, I ask three questions in order. Is it true no matter which job runs? Level 1. Is it how a job gets done, or when? Level 2. Did it already happen? Level 3.
Two habits keep the split clean. A lower level can name a higher one, never copy it. And a lesson lives with the thing it's about: if I learn something about how thumbnails should look, it goes in the thumbnail's folder on level 1, not in whichever playbook happened to be open.
These levels are about where a thing lives, not which one wins when two disagree. That's a different problem.
Why Agents Need the Split More Than People Do
When an agent builds a new skill or a new agent, the fastest way to make its own task work is to paste in what it needs. That's the reasonable move every single time, and it costs nothing. A person retyping a policy would at least feel the effort. An agent doesn't, so the copies pile up faster than anyone notices, and each one looked fine on the day it was made.
The cost shows up when you change the original. Every copy you didn't know about keeps producing the old version. Without levels, there's no rule that says where the original was supposed to live, so there's nothing to check the copies against.
How I Got Here
It started with images. At LifeHack, agents make most of our pictures: blog illustrations, social pins, video thumbnails, the cut-out characters in our short videos. Last week I set out to collect the looks in one shared folder and found I couldn't say where any of them lived. They were described across five different guides and one finished video's folder, each copy a little different. A template carried its own. One agent had its prompt typed straight into its code. Halfway through, I typed "seems there's no source of truth" to my coding agent. There were several, and they had started to disagree.
Moving the looks to level 1 taught me two things.
The first: what you remember using and what actually runs are two different lists. I told my coding agent I hadn't touched our old image guide in a while, so it could probably go. The agent that writes our blog posts had been using it all through September, most recently the day before. Check the run history before you retire anything.
The second: an agent's objection usually describes how things are wired today. My coding agent argued against the move because some agents weren't allowed to read the new folder. The fix was one permission line per agent. A home that some agent can't reach is exactly how the copying starts again.
A Prompt to Start With
Here's the prompt I'd hand a coding agent. Fill in the one thing you keep finding in too many places. Two things shaped it: searching for exact sentences missed most of our copies, because they'd been reworded, and one look's name showed up in 67 finished pieces that an agent told to "replace every copy" would have rewritten.
Our [brand voice / refund policy / report template / image
styles] are written out in several places: prompts, agent
files, code, templates and old project folders. I want one
home for each, with everything else pointing at it. Work in
two phases and stop between them.
PHASE 1: map it. Don't change any files.
1. List every version of the thing we use, by name.
2. For each, search everywhere for its name and its key
words, not just exact sentences. Copies get reworded.
3. Sort what you find into three levels:
- what's true: the content itself (this needs one home)
- how the work gets done: playbooks, agents and code
that use it (these should only point at the home)
- what happened: finished work and logs. Leave these
alone. They're history.
4. For anything you might retire, list which agents and
playbooks still use it. Check run logs if we have them.
Anything still used is load-bearing.
Show me a table: the thing, where each copy lives, its
level, and who depends on it.
PHASE 2: move it, after I approve.
5. Create one home per item.
6. Replace every copy with a one-line pointer to its home.
Where code hardcodes the content, make it read the home.
7. If an agent or tool can't read the new home, fix its
access. Don't leave a copy behind as the workaround.
8. Prove nothing changed: where something builds output
from these files, compare it before and after the move.
Run the existing tests. List what you couldn't test.What It Changed
The cleanup was mostly deletion, about 1,300 lines out and 800 in. Each look now has one folder. We've added two new looks since, and each one was a new folder and nothing else.
Our video agent now reads its prompt from the look's folder instead of its own code, and the prompt it sends is exactly the same as before. I also rebuilt our latest long YouTube film from its saved style, and every scene, timing and caption file matched the original.
The same folders double as a catalog our team browses, with twenty video formats, scenes and parts that play in place and every image look with its approved samples. A person picks a starting point there, and the agents read the very same folders. If your team browses one place and your agents read another, you have two homes again.
When a look needs to change now, there's one file to open, and every agent that uses it picks up the change on its next run.