Guide the Agent From Your Repo

TL;DR

Keep coding conventions in CLAUDE.md or AGENTS.md; the Runtime reads that file natively in every Run. Add .zozo/agent.md when dispatched work needs project-specific process guidance; the Dispatcher appends it to every task prompt. Leave branch pushing, Pull Request creation, and label changes out of both files because the Dispatcher owns that flow.

Two things shape how the agent behaves in your repository, and they have different jobs:

• The memory file is CLAUDE.md or AGENTS.md at your repository root: the guidance file your Runtime already loads on its own in any coding session.
• The task prompt is the message the Dispatcher writes to start each dispatched Run, telling the agent which Issue to implement and how to conduct the attempt. Your optional .zozo/agent.md file is appended to it.

This page explains what reaches the agent through each channel and what to put where.

Two Channels Reach the Agent

The memory file. Each Runtime loads its own memory file from the repository root exactly as it would in interactive use: Claude Code reads CLAUDE.md, and Codex reads AGENTS.md. Zozo passes this file through untouched. It never reads, rewrites, or composes it, so everything the file does for you in a terminal session it also does inside a Run.

The task prompt. Every dispatched Run starts from a prompt the Dispatcher builds:

• the instruction to implement one named Issue, with the Issue body embedded verbatim as the authoritative spec
• a fixed set of process rules the loop depends on (see below)
• your optional .zozo/agent.md, appended verbatim as project-specific guidance when the file exists

The two channels divide the work: the memory file describes how code is written in your repository, and the task prompt describes how the attempt is conducted.

What Belongs in CLAUDE.md / AGENTS.md

Write it for any coding session, not just for Zozo:

• architecture and layout: where things live, what depends on what
• coding conventions: naming, style, patterns to follow or avoid
• commands: how to build, test, and lint
• gotchas: the things a newcomer gets wrong in their first week

Maintain the file that matches your Project's pinned Provider: CLAUDE.md for Claude Code, AGENTS.md for Codex. If you might switch Providers later, keep both files in sync, or make one a one-line pointer to the other. See Understanding Credentials for how the pin works.

The Process Rules Are Fixed

The Dispatcher's task prompt commits the agent to a fixed process, because the loop's own bookkeeping depends on it:

• work only in the provided working directory, never in another checkout
• keep the build and tests green, running them synchronously before finishing
• commit on the current branch, and leave pushing, Pull Request creation, and label changes to the Dispatcher
• end the Run to signal completion
• ask through Clarification when a load-bearing detail is genuinely missing

Keep process instructions out of the memory file

A memory file that tells the agent to push its branch, open a Pull Request, manage labels, or run tests in the background contradicts the task prompt. Zozo doesn't validate your files against the process rules, and a conflict doesn't produce an error; it produces a confused agent and flakier Runs. The fix is the division of labor above: keep the memory file about the code.

What Belongs in .zozo/agent.md

Use .zozo/agent.md for guidance that only applies when Zozo drives the work:

• cross-cutting completeness rules, such as "a change that adds an API route must update the API reference in the same change"
• boundaries, such as "never edit files under generated/"
• extra verification, such as "run the schema check after touching migrations/"

The Dispatcher reads the file from the working directory at dispatch time and appends its content verbatim, so it applies to commits that contain it and is reviewed like any other code change. The file is optional; most projects start without one and add it when a recurring miss shows up in Pull Request review.

Coding conventions still belong in the memory file. Duplicating them in .zozo/agent.md doubles your maintenance without changing behavior.

Write Self-Contained Issues

The Issue body travels inside the task prompt as the authoritative spec, and the agent works from that embedded copy. Write Issues to stand on their own: acceptance criteria, file pointers, and the decision already made. Repository guidance can teach the agent your conventions, but it can't supply a missing requirement. When a load-bearing detail is absent, the attempt pauses in Clarification and waits for your answer.

Related

• The Core Loop: how an idea becomes Issues, Runs, and a Pull Request.
• Work Model: how the Dispatcher watches Projects and turns Issues into Pull Requests.
• Declare a Toolchain: how a Run gets your repo's build and test toolchain.
• Understanding Credentials: which Runtime serves your Project's work.