---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-agent-ready-repos"
title: "Make the repository agent-ready"
---

# Make the repository agent-ready

A background workflow is only useful when the agent can **prove what it changed**. Start by giving the repo a **verification loop**. Then move repeated, narrow jobs into tiny tool-shaped agents that carry only the context they need.

## Budget The Intelligence

The point is not to throw every task at the biggest possible context window. Decide where broad planning belongs, then **keep the local work loop focused** on files, commands, checks, and saved decisions.

## Use Goals For Long Work

Long-running work needs a plan that can survive time away from the keyboard. Ask for the **full step list first**, then plan each step before implementation. The local agent should execute one step, verify it, and leave enough context for the next step to make sense.

## Make Done Observable

An agent-ready repo lets an agent **read the code, write the change, and verify the result**. If the app lacks browser-style debugging, logs, snapshots, smoke tests, performance hooks, or a reliable local command, build the feedback loop before trusting automation.

> The agent needs to be able to read the code, write the code, and verify the code.
>
> — John Lindquist

## Keep The Terminal Thread Small

Custom terminal workflows matter because the agent needs a reliable surface for invoking repeatable project actions. Keep detailed [zsh](https://zsh.sourceforge.io/Doc/Release/Functions.html), shortcut, and orchestration setup in tool-specific docs until the commands are verified.

## Use Imps For Narrow Jobs

An **[imp](https://github.com/johnlindquist/codex-imps)** is a small, tool-shaped agent for a repeated job. It should know the **exact tool, examples, files, and conventions** it needs. It should not carry every skill, memory, search tool, and integration by default.

> You give it as much context as you want, so that it's as smart as you need it, like, out of the gate.
>
> — John Lindquist

## Strip The Extras

A narrow imp can **turn off broad features** until the task actually needs them. That keeps the context window pointed at the job instead of at the whole operating system.

## Do Not Improvise Secrets

Credential and token isolation is a **security design item, not a copy-paste recipe**. Keep account state, vault layout, token names, subscription details, local storage, and private setup notes out of public instructions until they have been reviewed deliberately.

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/#agent-ready-repos)
- [Resource directory and portable download](/topics/codex-resources/)
- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)

## Original references

- [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#agent-ready-repos)
- [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)
