From efca29485e5a9b4e95a2ef9190885a297c1bab69 Mon Sep 17 00:00:00 2001
From: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
Date: Sat, 21 Mar 2026 01:42:23 -0600
Subject: [PATCH] docs: add JavaScript conventions guide

Establishes callers-above-callees function ordering rule
and references it from AGENTS.md.
---
 AGENTS.md                       | 1 +
 tools/javascript-conventions.md | 5 +++++
 2 files changed, 6 insertions(+)
 create mode 100644 tools/javascript-conventions.md

diff --git a/AGENTS.md b/AGENTS.md
index e53b620c6..55b8ad5c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,5 +8,6 @@ Open source framework for structured, agent-assisted software delivery.
 - Before pushing, run `npm ci && npm run quality` on `HEAD` in the exact checkout you are about to push.
   `quality` mirrors the checks in `.github/workflows/quality.yaml`.
 
+- If you are writing JavaScript, read `tools/javascript-conventions.md`.
 - Skill validation rules are in `tools/skill-validator.md`.
 - Deterministic skill checks run via `npm run validate:skills` (included in `quality`).
diff --git a/tools/javascript-conventions.md b/tools/javascript-conventions.md
new file mode 100644
index 000000000..99ea39520
--- /dev/null
+++ b/tools/javascript-conventions.md
@@ -0,0 +1,5 @@
+# JavaScript Conventions
+
+## Function ordering
+
+Define functions top-to-bottom in call order: callers above callees. If `install()` calls `_initPaths()`, then `install` appears first and `_initPaths` appears after it.