AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Energy Converter Agent Guide

Agent guide for joule-based energy conversion across J, kJ, cal, kcal, Wh, kWh, and BTU.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Energy Converter in the alexandrai-tools project.

Project overview

This guide covers src/tools/energy-converter/index.ts. The tool converts J, kJ, cal, kcal, Wh, kWh, and BTU through a joule factor table, returns identity conversions unchanged, and rounds converted finite values to seven significant figures while preserving zero and non-finite values in sigFig.

Primary source files

  • src/tools/energy-converter/index.ts defines meta, EnergyUnit, ENERGY_UNITS, TO_JOULE, sigFig, and convert.
  • src/tools/energy-converter/index.test.ts covers kcal, kWh, cal, J identity, kJ, Wh, BTU, J to kWh, J to kcal, and kWh to kcal.
  • src/tools/energy-converter/Body.astro owns browser controls.
  • src/tools/energy-converter/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Use joules as the base unit.
  • Keep kJ as 1000 J.
  • Keep cal as 4.184 J and kcal as 4184 J.
  • Keep Wh as 3600 J and kWh as 3600000 J.
  • Keep BTU as 1055.05585 J.
  • Round converted values with seven significant figures.
  • If display formatting changes, keep pure conversion constants and tests stable.

Testing

Test 1 kcal to 4184 J, 1 kWh to 3600000 J, 1 cal to 4.184 J, 1 kJ to 1000 J, 1 Wh to 3600 J, 1 BTU to about 1055.056 J, 3600000 J to 1 kWh, 4184 J to 1 kcal, kWh to kcal, identity, zero, and non-finite behavior if accepted by UI.

PR checklist

  • npm test passes for energy-converter.
  • Conversion constants remain traceable and tested.
  • Identity conversions and rounding behavior remain documented.
  • UI labels, unit arrays, and pure conversion logic stay in sync.