Commit 5bd19a0c680d

@@ -1,32 +1,42 @@
-# Global Pi Agent Instructions
+# Global Agent Instructions
 
-This file is loaded by pi-coding-agent for all projects.
+Canonical global instructions shared across all AI coding agents (pi, Claude,
+Codex, Copilot, Gemini, opencode, ...). Symlinked into each agent's expected
+instruction file by `dots/Makefile`.
 
 ## Core Principles
 
-Apply the same principles as defined in Claude Code skills:
-
 1. **Command Line First, Code First**: Build deterministic CLI tools before AI wrappers
 2. **Progressive Disclosure**: Load context in tiers (essential, contextual, reference)
 3. **Structured Communication**: Get to the point, use scannable formatting
 4. **Honesty and Uncertainty**: Say "I don't know" when uncertain
 
+## Write the Laziest Code That Works
+
+Lazy means efficient, not careless. The best code is the code never written.
+Understand the problem and trace the real flow first, then stop at the first
+rung that holds:
+
+1. **Does this need to exist at all?** Speculative need → skip it, say so. (YAGNI)
+2. **Already in this codebase?** Reuse the helper/util/type/pattern. Look before you write.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** (`<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.)
+5. **Already-installed dependency solves it?** Use it. Never add a new dep for what a few lines do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+- Bug fix = root cause, not symptom. Grep every caller; fix once where they route through.
+- No unrequested abstractions, no speculative scaffolding; deletion over addition, boring over clever, fewest files.
+- **Never simplify away:** trust-boundary validation, error handling that prevents data loss, security, accessibility, or anything explicitly requested. If the user insists on the full version, build it — no re-arguing.
+- Never be lazy about *understanding*; the ladder shortens the solution, never the reading.
+- Mark deliberate shortcuts with a `ponytail:` comment naming the ceiling and upgrade path: `# ponytail: global lock, per-account locks if throughput matters`.
+
 ## Git Safety
 
 - **ALWAYS use explicit refspecs for git push**: `git push origin branch:branch`
 - **NEVER use bare `git push`** - branch tracking can push to unexpected branches
 - **Before pushing, verify the tracking branch** with `git status`
 
-## Skills
-
-Skills from `~/.config/claude/skills/` are compatible with pi. Key skills:
-
-- **CORE**: Operating principles and behaviors
-- **Git**: Version control workflows
-- **Nix**: NixOS configuration
-- **Org**: Note-taking, journaling, TODOs
-- **Homelab**: NixOS infrastructure
-
 ## Stack Preferences
 
 - **Package managers:** uv for Python (NOT pip)

@@ -51,7 +51,7 @@ claude-compat : ~/.claude
 # Sessions are special: redirected to ai-sync for syncthing sharing.
 
 all += pi-agent pi-agent-settings pi-agent-auth
-pi-agent : ~/.pi/agent/extensions ~/.pi/agent/agents ~/.pi/agent/AGENTS.md ~/.pi/agent/README.md ~/.pi/agent/keybindings.json ~/.pi/agent/modes.json ~/.pi/agent/models.json ~/.pi/agent/sessions
+pi-agent : ~/.pi/agent/extensions ~/.pi/agent/agents ~/.pi/agent/README.md ~/.pi/agent/keybindings.json ~/.pi/agent/modes.json ~/.pi/agent/models.json ~/.pi/agent/sessions
 pi-agent-settings : pi-agent
 	@$(dotfiles)/pi/agent/ensure-settings.sh
 pi-agent-auth : pi-agent
@@ -197,6 +197,17 @@ aichat-config : ~/.config/aichat/config.yaml
 	@mkdir -p ~/.config/aichat
 	@$(dotfiles)/config/aichat/genconf.py > $@ 2>/dev/null
 
+##@ Global Agent Instructions
+# One canonical instructions file symlinked to each agent's expected filename.
+all += agent-instructions
+CANON_AGENTS := $(dotfiles)/agents/AGENTS.md
+AGENT_INSTRUCTION_FILES := ~/.pi/agent/AGENTS.md ~/.claude/CLAUDE.md ~/.codex/AGENTS.md ~/.copilot/copilot-instructions.md ~/.gemini/GEMINI.md ~/.config/opencode/AGENTS.md
+agent-instructions : $(AGENT_INSTRUCTION_FILES)
+$(AGENT_INSTRUCTION_FILES) : $(CANON_AGENTS) force
+	@echo "→ Linking $< → $@"
+	@mkdir -p $(@D)
+	@ln -snf $< $@
+
 ##@ Meta
 
 all : $(all) pi-extensions-install