AGENTS.md for Pi

# Global agent instructions

## Scratchpad (under-the-hood planning)

Every **session** has its own scratchpad: `.pi/scratchpad-<session8>.md`
(first 8 chars of the session ID; created automatically if missing). Parallel
sessions in one project each own a separate file — no cross-session overwrites.

- For any non-trivial task — even without an explicit planning request — write a short plan
  into **your** scratchpad before starting work: the task in `## Task`, concrete steps
  as `- [ ]` checkmarks under `## Plan`.
- Tick items off (`- [x]`) as you complete them, and append new steps when the plan changes.
- On session start/restore, **your** scratchpad is injected into your system prompt —
  use it to resume exactly where a previous (possibly crashed) session left off.
- **Never edit other sessions' scratchpad files** (`.pi/scratchpad-*.md` with a different
  session id). If you need to hand work off, write a separate handoff file and tell the
  user — do not touch another session's plan.
- Scratchpad = **the current task only**. Durable project facts (environment, decisions,
  glossary) belong in the project AGENTS.md / skills, not in the scratchpad.

## Project orientation

- Your working directory (`cwd`) is the project root. Explore it with `ls`/`read`/`grep`
  before assuming you know the layout.
- Project-specific `AGENTS.md` files (working directory and parents) are auto-loaded into
  your system prompt; treat them as the authoritative description of the project.

## Memory & skills (how to maintain them)

Memory files: global `~/.pi/agent/AGENTS.md` (this file), per-project `AGENTS.md`
(working directory and parents), per-project skills in `.pi/skills/`.
They are **loaded into your system prompt at session start** — read them as the source of
truth, not as hints to verify from scratch.

- **Follow them first.** If a fact (password location, command, path, workflow) is recorded
  in memory, use it directly. Do not re-derive it by probing, searching, or trial-and-error.
- **Record durable findings as you go.** When you discover a reusable fact (a working
  command, a credential location, an environment quirk), add it to the appropriate memory
  file during the session — do not leave it only in chat.
- **Level of a fact:** repo-specific → project `AGENTS.md`; environment/VM/credentials →
  global `~/.pi/agent/AGENTS.md`; a repeatable multi-step workflow (3+ uses) → a skill in
  `.pi/skills/`.
- **Generality:** record patterns, not one-offs. A note is worth keeping only if it will
  be reused in future tasks.
- **Prune, don't accumulate.** When adding a note, check for stale or duplicate entries and
  merge/remove them. Memory files must stay short — every line costs context in every
  session.

## Tool safety

- Do not run any git command that changes the repo or history (commit, push, reset, rebase,
  merge, restore, checkout/switch, stash, tag, clean, etc.) unless explicitly asked.
- Do not install packages, dependencies, or global tools unless explicitly asked.
- Do not run heavy project-wide test suites unless explicitly asked.