nix/modules/home/programs/terminal/pi/config/AGENTS.md

AI Agent Guidelines

Be cognizant of context use; this file is loaded for all LLMs. Keep guidance concise and high-signal.

Critical Rules

1. Bash timeouts: Every bash tool call MUST specify a timeout.

   bash(command="some command", timeout=30)
   

2. File writing: Do NOT use cat with heredocs to write files. Use write for new/rewritten files and edit for targeted modifications.

3. Scratch files: Put temporary scripts, plans, notes, and reusable exploration artifacts in _scratch/. It is gitignored.

4. Missing commands: If a tool is not installed, prefer nix run instead of installing it.

   nix run nixpkgs#python3 -- script.py
   

Context Discipline

Prefer a search → targeted read pattern:

1. Search with rg -n / grep -n to find relevant line numbers.
2. Read only the needed range with read(path, offset, limit).

Full-file reads are fine when genuinely needed, but avoid them as the default reflex.

Principles

1. KISS / YAGNI: Keep solutions simple. Avoid abstractions, generics, or indirection unless there is a concrete need.

2. Maintain AGENTS.md: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.

3. Knowledge Capture: At task end, if you discovered non-obvious conventions, pitfalls, or repeatable workflows that would have saved time, briefly recommend adding them to AGENTS.md or a skill. Say whether each belongs in project-level context, global agent context, or a task-specific skill. Skip this when there is nothing meaningful.

Style

Comment Style

A logical block of code (not necessarily a language scope) should have a short Title Case comment above it:

// Map Component Results
for _, comp := range components {
    results[comp.Name] = comp.Result
}

If the block is more complicated or non-obvious, explain why after the title:

// Map Component Results - Downstream consumers expect a name-keyed lookup.
for _, comp := range components {
    results[comp.Name] = comp.Result
}