dev AGENTS.md

AGENTS

This file provides guidance to coding agents (Claude Code, Codex) when working with code in this organization. It is the org-wide root file — every repository under the org loads it alongside its own AGENTS.md, so only org-wide guidance belongs here; repo-specific guidance belongs in each repository's own file.

Especially important points to keep in mind (each expanded in its section below):

• Questions are not edit requests. When a message asks a question without explicitly requesting a change, answer and stop (Communication).
• Write clear and concise English. Write clear, concise, plain English which can be quickly and easily parsed by the user - answer questions directly in short form unless elaboration is requested (Writing Style).
• Seek the best solution, not agreement. When you think the user is wrong, don't be afraid to say so — the right answer matters more than the path of least resistance (Pushing Back).

Workflow

Git Workflow

• Do not create git commits unless explicitly asked. Never auto-commit during implementations.
• Never touch the staging area or stash. Do not run git add, git reset, git stash, git checkout -- <file>, git restore, git clean, or any other command that stages, unstages, stashes, or discards changes. The user uses the staging area to track approved work — modifying it destroys their workflow. This applies even when debugging (e.g. do not stash to test original code — use git show HEAD:<file> or git diff HEAD to inspect the original state without modifying the working tree).
• Leave all committing to the user. Make code changes, run tests, run pre-commit, but stop before committing.
• No session identifiers or tool footers in anything published. Commit messages end at the co-author trailer (Co-Authored-By: ...) — never append session or conversation identifiers, links back into an agent harness, or trailers of that kind (e.g. Claude-Session:) to commits, PR or issue bodies, comments, release notes, or any committed file. Do not add "Generated with ..." footers or tool badges to PRs or issues either; the co-author trailer is the only attribution that belongs anywhere. Harness trailers found in existing git history are a defect being scrubbed, not a pattern to imitate.
• Exception for fractal. When running the /fractal skill or operating a fractal node, commit fractal's own setup/seed/config artifacts autonomously and without asking — fractal init's output (.fractal/ and the wiki scaffold it creates), the node seed, and the baseline and child config commits the fractal skill instructs you to make. Never ask the user whether to commit them. Ordinary project work in the user's main worktree still follows the rules above.