dotfiles/dot_pi/agent/AGENTS.md

Development Rules

Conversational Style

• Keep answers short and concise
• No emojis in commits, issues, PR comments, or code
• No fluff or cheerful filler text (e.g., Thanks @user not Thanks so much @user!)
• Technical prose only, be direct
• Use concise, clear, simple language. Define unavoidable jargon before using it.
• Explain non-trivial designs and problems as: problem, concrete example or short trace, then solution. State why the solution is necessary and distinguish it from optional complexity.
• Prefer concrete behavior and small illustrations over abstract summaries, dense terminology, or unexplained lists of changes.
• When the user asks a question, answer it first before making edits or running implementation commands.
• When responding to user feedback or an analysis, explicitly say whether you agree or disagree before saying what you changed.

Commands

• Always use git --no-pager diff instead of git diff to prevent the pager from blocking non-interactive commands.

Delegation

• Do not perform reconnaissance, behavior tracing, external documentation lookup, or design analysis directly in the main session when a matching agent exists. Inline bash/read/webfetch/websearch work is only acceptable for trivial lookups and for single-file, behavior-obvious changes.
• Default to worker for non-trivial implementation. Give it the desired outcome, constraints, and verification criteria; it may locate code, investigate nearby behavior, and make routine implementation decisions. Keep direct main-agent edits for trivial changes or work the worker cannot safely perform with its available tools.
• Prefer delegating to explore before editing any file not already read in full this session when the change touches more than one module, or when the root cause of a bug is not yet established.
• Prefer delegating to research before relying on any external API, CLI flag, protocol, or version-specific behavior that has not been confirmed in this session; do not answer such questions from memory or with direct webfetch/websearch.
• Prefer delegating to architect before multi-file changes, schema or API changes, migrations, or any non-trivial design decision; skip only for single-file, behavior-obvious edits.
• After explore, research, or architect resolves an uncertainty, hand implementation to worker rather than implementing the plan in the main session. Return reviewer findings to worker for fixes when possible. Escalate unresolved product decisions, cross-cutting design, or difficult root causes instead of forcing a worker to guess.
• Prefer delegating to reviewer for large or multi-file changes, and in particular when architect was involved in the design; for small or behavior-obvious changes, reviewer review is usually not worth the overhead.
• Unless currently acting as the delegated submitter agent, MUST delegate every requested Git commit, Git push, or Perforce submit to submitter through tasker after implementation and validation are complete.
• Unless currently acting as submitter, NEVER run git commit, git push, or p4 submit directly.
• When the user requests individual commits, implement and validate each unit, then invoke submitter sequentially before starting the next unit.
• The delegated submitter agent is authorized to stage, commit, push, or submit the validated changes requested in its task.

Code Quality

• Inspect relevant code before editing. Start with search, symbols, and targeted reads for trivial changes; for anything broader, follow the mandatory explore/architect delegation rules above instead of inspecting inline.
• Read a file in full before making wide-ranging changes to that file or when surrounding context affects correctness.
• For investigations and audits, read complete files only when needed to validate behavior; do not rely solely on search snippets.
• Avoid rereading unchanged content already present in the current context.