Project instructions and planning

Start in the correct directory

agent-cli --cwd /absolute/path/to/project

Tools operate relative to the session's working directory unless a tool call specifies another allowed location. Confirm the directory before requesting edits, especially when working with multiple checkouts.

Add project instructions

Put shared contributor guidance in AGENTS.md. The agent discovers and injects these instructions by default. /init asks it to create a contributor guide for the repository; review that file before relying on it.

Useful instructions include:

# Development

- Use the checked-in development environment.
- Run the focused test suite for the module being changed.
- Keep public API changes separate from internal refactoring.

# Review

- Explain any test failures that remain.
- Do not publish a release without explicit approval.

Instructions should state conventions that are not obvious from the code. Keep credentials and temporary task status out of this file.

An AGENTS.override.md takes precedence over AGENTS.md in the same directory. You can disable discovery for a particular launch with --no-agents-md. Instructions guide the model; they are not an operating-system security boundary.

Discovery order and directory scope

The harness finds the nearest ancestor containing a .git marker, then loads project instructions from that root down to the session's working directory. Both a Git directory and a worktree's .git file count as markers. Without a root marker, only the current directory is searched for project instructions. Global instructions are loaded before project files.

This is an ancestor-chain search, not a recursive scan of the repository. Starting in the repository root does not preload every package's instructions. Before changing a deeper directory, have the agent inspect its additional instruction files. State local exceptions explicitly; deeper instructions are intended to specialize the broader project guidance rather than repeat it.

The model's dialect selects this behavior; an endpoint being “OpenAI-compatible” does not by itself guarantee Codex instruction discovery. For portable guidance across dialects, prefer ~/.haskell-agent/AGENTS.md and repository AGENTS.md files.

Compatibility filenames and rules

Broader discovery reads the preferred AGENTS file, followed by these names in order:

Agents.md
Claude.md
CLAUDE.md
CLAUDE.local.md
AGENT.md
.claude/CLAUDE.md
.claude/CLAUDE.local.md

It then reads immediate Markdown files in .grok/rules, .claude/rules, and .cursor/rules, in that directory order. Entries within each rules directory are sorted by filename. Global compatibility homes use their immediate rules directory after their named files.

Rules discovery accepts files whose extension is .md (case-insensitive). It does not recursively descend into rules subdirectories and does not load .mdc files through this mechanism. Matching files are loaded as text; do not assume another tool's front-matter path filters are evaluated here. Duplicate paths resolving to the same file are deduplicated in broader discovery, keeping the first occurrence.

Overrides, empty files, and the size budget

A readable, non-empty AGENTS.override.md replaces AGENTS.md in its own directory. Under broader discovery it also suppresses the alternate Agents.md spelling, but does not suppress Claude files or rules directories. It does not replace instructions in every ancestor directory.

Whitespace-only files are skipped. An empty or unreadable override does not suppress a usable base file; unreadable existing files produce discovery warnings. Files are combined under a 32 KiB UTF-8 content budget across global and project instructions. Earlier files consume the budget first. The final fitting file may be truncated and later files omitted; multibyte characters count by encoded bytes, not by character count.

Keep global guidance especially short so it cannot crowd out repository-specific instructions. Put lengthy procedures in a skill or a referenced document that the agent can read when needed. Referencing a file in prose is not an automatic include directive.

Example: specialize a package's test instructions

Suppose your checkout contains:

project/
  .git/
  AGENTS.md
  packages/
    parser/
      AGENTS.md
      src/

Keep repository-wide review and environment rules in project/AGENTS.md. In packages/parser/AGENTS.md, state the actual package-specific test command, for example in a Nix/Cabal project whose package is named parser:

# Parser package

- Run `nix develop -c cabal test parser` after changing parser behavior.
- Add a regression case for every accepted or rejected syntax change.
- Preserve the public parse-error format unless the task explicitly changes it.

agent-cli --cwd /absolute/path/to/project/packages/parser

On a fresh launch, the root file is loaded before the parser file. Ask: “Before editing, summarize the repository and parser-package instructions that apply, and identify the test command.” Expect both scopes, with the package's specific testing requirement. If you instead start at the root and later request parser work, explicitly ask the agent to inspect packages/parser/AGENTS.md first.

When instructions appear to be missing

1. Verify the actual checkout and working directory with /copy-path. Another worktree does not automatically contain uncommitted instruction edits.
2. Check for a closer .git marker that changes the ancestor search boundary.
3. Check the active dialect and filename. A Claude compatibility file is not part of Codex's narrow project search.
4. Inspect AGENTS.override.md, empty files, permissions, and startup discovery warnings before assuming the base file was loaded.
5. Check total instruction size. Move long global procedures out of the automatic instruction payload so deeper files fit within 32 KiB.
6. Confirm launch did not use --no-agents-md. After editing instruction files, verify with a fresh launch or explicitly ask the current agent to reread the changed files; do not assume every existing conversation hot-reloads them.

Plan before making a broad change

/plan Replace the session search implementation while preserving its behavior.

Plan mode permits exploration but restricts edits to the session's plan.md. Review the proposed approach, request corrections if necessary, and approve it before implementation. /view-plan displays the saved plan.

For small, well-defined work, a direct request may be enough. For uncertain architecture or a cross-cutting change, agree on scope and acceptance checks before authorizing edits.

Review the result

For the search replacement example, ask the plan to identify the existing behavior, representative queries, and compatibility checks. Before approval, you should be able to answer which files will change and what evidence will show that result ordering and empty-query behavior remain correct.

Revise the plan to include regression tests for an empty query and multiple matches. Do not implement yet.

Expected result: a revised plan, not implementation edits. If the proposal assumes requirements you have not agreed on, correct the assumptions before approving it.

Ask the agent to explain what changed and which checks it actually ran. Then:

/diff
/review

Inspect both the diff and test output. A model-generated explanation does not replace tests or review.

Use a managed worktree when the task should not modify your existing checkout.