I packaged my agent setup into a playbook you can run

I recently put a small repo online called agents-first-playbook. It is not a framework, and it does not install anything. It is a handful of documents, some pasteable prompts, and one read-only shell script, aimed at a single awkward moment: the day you notice you are running more than one AI coding agent, and their instructions have started to drift apart.

This is the build log. What is in it, how the one piece of code works, what surprised me, and what you can lift without reading the rest.

What it actually is

The repo is small on purpose:

README.md                          # the method
GREENFIELD.md                      # for a fresh setup
MIGRATION.md                       # for an existing, tangled setup
prompts/                           # pasteable prompts to point an agent at the job
templates/                         # generic AGENTS.md starting points
scripts/inspect-agent-config.sh    # read-only audit
skills/agents-first-setup/         # the same process, agent-executable

The idea underneath it is one line: keep your durable instructions in a shared AGENTS.md, and let each tool’s own file — CLAUDE.md, the Codex file, the Gemini file — become a thin adapter that points back to it. One source of truth, many doors.

I am not going to re-argue the why here; that is its own post. This is about the thing I actually shipped.

How the one piece of code works

The only executable in the repo is inspect-agent-config.sh, and the most important thing about it is what it refuses to do.

It reads. It does not write. It does not move a file, create a symlink, or print the contents of your instructions. It walks the usual locations — ~/.agents, ~/.claude, ~/.codex, and so on — and reports four things:

what files exist
which ones are real files and which are symlinks
where each symlink points, and whether the target is missing
the likely conflicts, where two tools disagree about who owns a file

You run it before you touch anything:

./scripts/inspect-agent-config.sh

and you get a map of your current setup with the broken links flagged. That is the whole job. It is the equivalent of checking which wires go where before you start unplugging things.

An example of the read-only inspector's terminal output. It lists each agent file as a real file, a symlink to the shared AGENTS.md, or a path it could not resolve, then prints a short summary and a note that nothing was changed. All paths are generic placeholders. — An example run, using placeholder paths. The inspector describes your setup and flags anything it cannot resolve — it never changes a file.

I made it read-only deliberately. Agent config is the kind of thing where an “obvious” automated fix can break the setup you use every day, and you will not notice until your slash commands stop loading three hours later. A script that only ever describes your system cannot do that to you.

What surprised me

Two things.

First, the inspector turned out to be the most useful part of the repo, and it is the least clever part. I expected the templates and prompts to carry the weight. In practice, the thing people reach for first is the read-only audit, because the hard part of this job is not knowing the pattern — it is seeing your own mess clearly before you change it.

Second, writing a public version forced a discipline the private version never had. The moment the repo had to be safe to share, I had to separate the method from my actual config: no real paths, no private repo names, no hints about what automation runs on my machine. That separation made my own setup cleaner too, because a surprising amount of what I had filed as “instructions” was really just runtime state wearing an instruction’s clothes.

What you can lift

You do not need the whole repo to get value from it.

If you take one thing, take the read-only-first rule: inspect and classify your agent config before you move a single file.
If you are starting fresh, GREENFIELD.md is the short path.
If you already have a tangle of .claude, .codex, and mixed symlinks, MIGRATION.md is the careful path, and the inspector is step zero.
If you want an agent to do the work, the prompts in prompts/ are written to be pasted in as-is, and they tell the agent not to change anything until you have reviewed the plan.

It is v1, and it deliberately does not ship an automatic migration script. Rewiring someone’s entire agent setup is not a job for a one-shot command. The repo is here: github.com/pelby/agents-first-playbook. Run the inspector, read the map, and decide for yourself.