{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-agent-ready-repos",
  "slug": "agent-ready-repos",
  "title": "Make the repository agent-ready",
  "summary": "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.",
  "category": "Verification",
  "tags": [
    "observability",
    "imps",
    "verification"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#agent-ready-repos"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Budget The Intelligence",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Use Goals For Long Work",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Make Done Observable",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Keep The Terminal Thread Small",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Use Imps For Narrow Jobs",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Strip The Extras",
    "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Do Not Improvise Secrets",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#agent-ready-repos",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "verification",
  "wordCount": 399,
  "url": "/topics/codex-agent-ready-repos/",
  "markdownUrl": "/markdown/codex-agent-ready-repos.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-agent-ready-repos.json",
  "headings": [
    {
      "id": "budget-the-intelligence",
      "text": "Budget The Intelligence",
      "level": 2
    },
    {
      "id": "use-goals-for-long-work",
      "text": "Use Goals For Long Work",
      "level": 2
    },
    {
      "id": "make-done-observable",
      "text": "Make Done Observable",
      "level": 2
    },
    {
      "id": "keep-the-terminal-thread-small",
      "text": "Keep The Terminal Thread Small",
      "level": 2
    },
    {
      "id": "use-imps-for-narrow-jobs",
      "text": "Use Imps For Narrow Jobs",
      "level": 2
    },
    {
      "id": "strip-the-extras",
      "text": "Strip The Extras",
      "level": 2
    },
    {
      "id": "do-not-improvise-secrets",
      "text": "Do Not Improvise Secrets",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Make the repository agent-ready\n\nA 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.\n\n## Budget The Intelligence\n\nThe 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.\n\n## Use Goals For Long Work\n\nLong-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.\n\n## Make Done Observable\n\nAn 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.\n\n> The agent needs to be able to read the code, write the code, and verify the code.\n>\n> — John Lindquist\n\n## Keep The Terminal Thread Small\n\nCustom 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.\n\n## Use Imps For Narrow Jobs\n\nAn **[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.\n\n> You give it as much context as you want, so that it's as smart as you need it, like, out of the gate.\n>\n> — John Lindquist\n\n## Strip The Extras\n\nA 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.\n\n## Do Not Improvise Secrets\n\nCredential 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.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#agent-ready-repos)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
