AGENTS.md: scripting runtime rule (node, not python) and never edit files by script #24

Problem

Agents default to Python for ad-hoc scripting in bash calls. In a 30-day scan of pi sessions (16,033 sessions, 378k bash calls), Python appeared in 10.8% of bash calls and Node in 1.9%. By model, the share was GPT-6.1 Sol 17.7%, Sonnet 20.2% and Opus 5.4%.

45% of the 33k inline Python snippets edit or write files by script, for example s.replace(a, b); open(p, 'w').write(s). That skips the edit tool's exact-match check and any write guard bound to the edit/write tools.

Python is not guaranteed where we work: macOS ships only the Command Line Tools stub, and Windows has only the Store alias. Node, on the other hand, always exists, because pi itself runs on Node.

Change

1. Global AGENTS.md, under "Bounded, task-focused work":

• Scripting runtime. Do not default to Python. For ad-hoc logic in bash calls, use the dedicated tools first (edit/write/read for files, rg, gh --jq/jq for JSON); beyond that use node -e / node --input-type=module - <<'EOF'. Never edit files by script (python3/node/sed -i rewrites); use the edit tool so exact matching and write guards apply. New tooling scripts are Node (.mjs/.ts, stdlib only), or C# file-based apps where .NET libraries are needed. Use Python only in Python projects.

2. Add one line to the prompts of implementer, careful-implementer, opus-implementer, grunt and general-purpose (agents/*.md): "Ad-hoc scripts: node, not python; edit files with the edit tool, never by script."
3. Leave existing Python CLIs in bin/ (pi-phase, pi-cleanup, dev-doctor and the rest) as they are; write new tools in Node.
4. Publish with the next pi-setup release.
5. One week later, rerun the session scan (ai-usage.mjs, kept in L49's research directory) to check the effect. Target: Python under 3% of bash calls.

Done when

• The AGENTS.md text and the agent prompt lines are in a pi-setup release.
• The follow-up measurement is recorded on this issue.

Status

State: Paused — Delivered in v2026.10.23.22: AGENTS.md scripting rule plus the prompt line in 5 agents. Remaining only: the 2026-10-30 ai-usage rerun (target: Python under 3% of bash calls, baseline 10.8%). Close after recording it.
Branch: -
Scope: AGENTS.md scripting rule and the agent prompt line; release next; follow-up measurement on 2026-10-30.
Delivered: Nothing yet.
Remaining: To be confirmed.
Follow-ups: None.