AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random Decision Agent Guide

Agent guide for picking a random option and producing Yes or No outcomes.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Random Decision in the alexandrai-tools project.

Project overview

This guide covers src/tools/random-decision/index.ts. The tool picks one item from an array using Web Crypto, returns an empty string for an empty array, and exposes a yesNo helper that returns Yes or No.

Primary source files

  • src/tools/random-decision/index.ts defines meta, pickOne, and yesNo.
  • src/tools/random-decision/index.test.ts covers membership, empty arrays, single-item arrays, broad coverage over repeated picks, valid Yes or No output, and both outcomes over many calls.
  • src/tools/random-decision/Body.astro owns browser input parsing.
  • src/tools/random-decision/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

  • Return an empty string for empty item arrays.
  • Keep a single-item array deterministic by returning its only element.
  • Use Web Crypto as the random source.
  • Do not trim or parse multiline text in pure pickOne; keep input preparation in the UI if that is where it lives.
  • If exact unbiased selection is required for arbitrary lengths, replace modulo selection with rejection sampling and update tests.
  • Do not store pasted option lists.
  • Keep yesNo output limited to Yes and No.

Testing

Test empty arrays, one item, membership, repeated coverage, Yes or No validity, both outcomes, input parsing in Body.astro, and unbiased selection if rejection sampling is added.

PR checklist

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