AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random Name Picker Agent Guide

Agent guide for unique winner selection from a list of names.

AGENTS.md

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

Project overview

This guide covers src/tools/random-name-picker/index.ts. The tool trims names, ignores blank entries, clamps winner count between zero and pool length, shuffles the pool with Web Crypto, and returns the first requested number of unique winners.

Primary source files

  • src/tools/random-name-picker/index.ts defines meta and pickWinners.
  • src/tools/random-name-picker/index.test.ts covers requested length, over-count behavior, membership, uniqueness, zero count, empty names, and blank-name filtering.
  • src/tools/random-name-picker/Body.astro owns browser textarea parsing.
  • src/tools/random-name-picker/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

  • Trim names and drop blank entries before picking.
  • Clamp count to zero through pool length.
  • Return an empty array when count is zero or no names remain.
  • Keep winners unique.
  • Use Web Crypto as the random source.
  • If exact unbiased shuffle indices are required, replace modulo indexing with rejection sampling.
  • Do not upload or persist entered names.

Testing

Test count less than length, count equal to length, over-count, zero count, empty list, blank entries, uniqueness, membership, duplicate input names if policy changes, and shuffle fairness if changed.

PR checklist

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