ToFu: Instructions file for Codex

Repository guidance

This file is the single source of repository-wide rules for every coding agent; read it completely before changing code. Keep task quality as the primary objective, then minimize model turns and raw context growth without weakening verification.

• Use isolated worktrees for sustained changes in a shared checkout. Never reset, clean, or replace the shared tree to prepare a task. When other (uncommitted or in-flight) work exists in the workspace, NEVER run workspace-destroying commands such as git checkout --, git checkout <branch>, git switch, git restore, git stash, git reset --hard, or git clean: they can silently discard concurrent edits. Create each worktree with git -C <shared-checkout> worktree add <path> -b <branch> <shared-current-branch>, never from the platform task workspace's HEAD, which may be a task-input snapshot. Commits made in an isolated worktree never reach the current branch by themselves: the executing agent (the model — never the human user) must land them itself, immediately once the worktree work is finished and verified, not later and never as a hand-off: run python3 scripts/git_land.py <branch> from the shared checkout. Unlike git merge, it does not refuse when other writers have uncommitted edits in the same files; it carries those edits forward with a three-way merge, then removes the worktree and deletes the branch. Known generated outputs are rebuilt from merged sources; uncommitted sources and their outputs stay uncommitted. Do not reset generated files to unblock it. If it refuses, nothing was changed; follow its printed instruction (merge the current branch into the worktree branch to resolve a real conflict, or rerun after another writer's overlapping lines are committed). A task is not complete until its worktree commits are merged into the current branch. The merge commit's first parent is the pre-integration backup; the tool prints it, so record that SHA in the final answer instead of creating backup/* branches.
• Start unfamiliar work with one bounded discovery batch over the owning modules, contracts, tests, and current changes: use rg/rg --files and targeted ranges instead of repeatedly reading one file at a time. Do not dump the whole dirty worktree, full diffs, generated bundles, or large logs. On this host's FUSE mount, prefer git ls-files and git grep over find/ grep -r: deep find walks intermittently return empty.
• Use docs/README.md as the first-hop map to the owning module and contract; docs/catalog.json is the machine-readable documentation inventory. Change the authority first, then derive generated clients and bundles. Edit retained browser code in frontend/src/runtime/sections/, never the generated app-runtime.js. Edit styles in frontend/src/styles/{application,settings}/, never generated files under static/.
• Repo-root local trees that are untracked on purpose (gitignored): promo/ (marketing HTML/PNGs) and codex/ (a local vendored Codex CLI checkout used for comparison/evaluation). Neither is a runtime dependency of tracked code: lib/oauth/codex* and lib/skills/paths.py spawn a codex binary and scan .codex/skills by name only. Do not track or delete these trees.
• Generated Python modules follow the package-local generated_*.py (or *_generated.py where the name predates the convention) prefix, never loose hand-mixed names in a package root. See CONTRIBUTING.md “Generated files”.
• Batch independent read-only inspections with the live tools' documented batching or parallel-call interface. Tool schemas, not repository examples, define the available names, arguments, and execution semantics. Return only evidence needed for the next judgment.
• Background long commands with run_command(background=true) when useful. The receipt and the tool description say whether the completion reaches you automatically: only a task that owns its conversation turn is woken with it. A swarm worker or other delegated run collects its handle with poll before it finishes; a leaf worker's poll and kill reach only the bg_* commands it started. A headless API request runs every command in the foreground. Use poll with a bounded wait only when no useful work remains. Never busy-poll or infer success from an absent session. Keep user progress updates within 60 seconds.
• Add or update the smallest executable specification for the behavior, then use a test ladder: smallest relevant tests first, then neighboring contracts, then broad gates once the worktree is stable. Do not rerun an unchanged suite. With concurrent writers, report that a full-suite result is a moving target.
• Update the owning current-state document with the change; delete superseded plans instead of leaving an archive beside authoritative documentation.
• Batch mechanical edits, but inspect and test semantic boundaries separately. Preserve fault injection, rollback, authority, and user-visible error behavior.
• Before finishing a tool-heavy task, run python3 audit_codex_session.py <rollout.jsonl> when a session path is available. Treat fewer calls as a win only when the same correctness checks and required evidence still pass.