AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Coin Flip Agent Guide

Agent guide for single and batch coin flips with result counts.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Coin Flip in the alexandrai-tools project.

Project overview

This guide covers src/tools/coin-flip/index.ts. The tool flips one coin from a Web Crypto byte, clamps batch size to one through ten thousand, creates an array of Heads or Tails, counts heads, and derives tails from the total.

Primary source files

  • src/tools/coin-flip/index.ts defines meta, CoinSide, flip, FlipManyResult, and flipMany.
  • src/tools/coin-flip/index.test.ts covers valid single outputs, both outcomes over many flips, requested batch length, valid batch values, count totals, and lower clamp.
  • src/tools/coin-flip/Body.astro owns browser controls.
  • src/tools/coin-flip/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

  • Keep flip output limited to Heads and Tails.
  • Clamp flipMany count to one through ten thousand.
  • Keep heads plus tails equal to the clamped count.
  • Use Web Crypto as the random source.
  • Do not replace with Math.random.
  • If exact unbiased single-bit sampling is required, reject high byte values or draw bits directly with tests.
  • Do not persist flip history unless the UI adds it intentionally.

Testing

Test single output validity, both outcomes over repeated calls, batch length, batch value validity, heads plus tails, lower clamp, upper clamp, and any bias-removal change.

PR checklist

  • npm test passes for coin-flip.
  • Web Crypto remains the random source.
  • Input lists or generated values stay browser-local.
  • Current clamping and empty-input semantics remain documented.