The agent-ready machine: generated context your agents can trust

Every coding agent session starts amnesiac. The fix the whole ecosystem converged on is context files: AGENTS.md for the rules, inventories for the environment, notes for the history. The fix has a failure mode of its own, though, and it's worse than the amnesia: context files are documentation, and documentation drifts. A stale instruction doesn't just stop helping, it actively misleads, sending the agent to paths that moved and tools that were renamed. Research backs the intuition from both directions: hand-written context that goes stale hurts, and LLM-generated context measurably hurts too, reducing task success rates while raising cost, because it restates what the repo already says and adds nothing the agent couldn't infer.

There is a third option between hand-written and model-written, and it's the one this post is about: generated from the data that builds the machine. If the same variables that provision a laptop also render its context files, the files cannot drift from reality, because they and the reality have one author. The machine describes itself.

The three questions every session asks

Watch an agent flail at the start of a session and the wasted turns cluster around three questions. Each gets a small generated file.

What tools do I have? TOOLING.md

Agents discover CLI tools by trying them, and a command not found early in a session teaches the agent the tool is absent for the rest of it, even when it was there under another name. Every apply scans the machine (command -v plus a version probe) and renders ~/.agents/TOOLING.md with only the tools verifiably present:

- `rg` 14.1.0 ripgrep, recursive regex search over directory trees, gitignore-aware and fast; prefer over `grep -r`
- `fd` 9.0.0 fast, friendly file finder; prefer over `find` for name lookups
- `ast-grep` 0.26.0 structural code search and rewrite over syntax trees

A tool that isn't installed is left out, so the inventory never advertises something that's missing. The pattern has a post of its own; it's the agents role's oldest trick.

Where does work live? PROJECTS.md

The tooling inventory tells agents what's installed; the project map tells them where work lives. When a task starts from the home directory, or spans repositories ("fix the pipeline template and bump it in the app repos"), the agent needs to know which repository a change belongs in before it touches anything.

The data already exists. The git role clones everything from one git_repositories tree whose nesting encodes the directory layout. Each apply renders that same tree, plus an optional per-repo description, into ~/.agents/PROJECTS.md:

git_repositories:
  baksteen:
    dotfiles:
      url: git@gitlab.com:baksteen/dotfilespro.git
      description: "Ansible collection managing machines and dotfiles (dotfiles.pro)"
    cookiecutters:
      url: git@gitlab.com:baksteen/cookiecutters.git
      description: "Project scaffolding templates; AGENTS.md boilerplate originates here"

- `~/projects/baksteen/dotfiles` Ansible collection managing machines and dotfiles (dotfiles.pro)
- `~/projects/baksteen/cookiecutters` Project scaffolding templates; AGENTS.md boilerplate originates here

Add a repository to the tree and the map updates on the same apply that clones it. Remove one, same story. The map cannot claim a checkout exists that doesn't, because the claim and the checkout come from the same variable.

What happened recently? The worklog

The third gap is time: yesterday's session decided something, and today's session doesn't know. A small append-only worklog (~/.agents/worklog/YYYY-MM-DD.md) closes it. Agents read the most recent days at session start and append one line per meaningful unit of work: a finished task, a non-obvious decision, a blocker. Routine edits stay out; the commit log already has those. This file is the one exception to "generated": history can't be derived from provisioning data, so the instructions ship with the machine and the agents write the entries.

One pointer each, loaded on demand

None of these files is pasted into the always-loaded instructions. The global AGENTS.md carries one pointer line per file:

- Always read `~/.agents/TOOLING.md` for the CLI tools installed on this machine.
- When a task spans repositories or you need to know where a change belongs, read `~/.agents/PROJECTS.md`.
- Keep a worklog per `~/.agents/worklog/README.md`.

This is progressive disclosure, and it's the load-bearing trick. Context files compete for a budget: every always-loaded line spends attention, and the research on instruction files keeps finding that beyond a modest size, more context makes agents worse, not better. A pointer costs one line per session; the detail costs tokens only in the sessions that need it.

Where the machine map ends

The machine-level map answers "which repository". Once the agent is inside one, the repository's own committed AGENTS.md takes over for "where inside this codebase", the build commands, and the team's conventions. The two layers compose exactly like the instruction hierarchy they belong to: nearest file wins, and neither duplicates the other. A machine map that tried to describe each repo's internals would just be a second, staler copy of the repo's own file.

What stays human

Generation has a boundary, and it matters. Existence and location are derived, so they're generated and can never lie. The one-line description on each repository is curated by a human, because that's exactly the content the research says models generate badly: generic summaries restate the obvious and waste the reader's budget. One honest sentence per repository, written once, carried in the same versioned variable as the URL. The division holds for TOOLING.md too: presence and versions are probed, the "prefer this over that" hints are written.

Provisioned, not maintained

Everything above is rendered by the agents role from variables in a dotfiles repository: agents_tooling for the inventory, git_repositories for the map, the worklog instructions as shipped files. The next laptop gets identical context on its first apply, and so does the twenty-person fleet, whose agents all wake up knowing the same three answers. Nothing to remember to update, nothing to review for staleness, nothing that can quietly rot.

An agent-ready machine isn't one with a long CLAUDE.md. It's one where the context is a build artifact.