docs: record extension startup performance rules
74b669fdc63a9c512b07afbd1b3c09a55e960de2
Oliver Krylow <o.krylow@isp-insoft.de> · 2026-08-24 10:30 UTC
unverifiable SSH 1 parent
repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
Changed files (1)
AGENTS.md
ready@@ -52,6 +52,17 @@
escalate to a human.
Do not work around `mise` or add ad-hoc scripts.
+## Startup performance
+
+- Treat every Win32 process spawn as expensive; prefer native Node APIs and defer unavoidable spawns to first use.
+- Keep entry modules thin; lazy-load command and tool implementations on first use.
+- Gate optional domain work with cheap relevance checks before importing implementations.
+- Never block startup or reload on subprocess probes, broad filesystem scans, or Git status.
+- Abort asynchronous startup work on reload and ignore stale results.
+- Check executable presence through native PATH access, not version subprocesses.
+- Preserve registration, validation, rendering, and first-use behavior when deferring work.
+- Measure performance only with the complete extension set on Win32 and WSL.
+
## Tool Widget Rendering
Tool widgets must match Pi built-ins: compact by default, expanded details on `app.tools.expand` (`ctrl+o` by default).