AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random Team Generator Agent Guide

Agent guide for cryptographic shuffling and round-robin balanced team assignment.

AGENTS.md

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

Project overview

This guide covers src/tools/random-team-generator/index.ts. The tool shuffles names with Web Crypto, validates teamCount, creates one-based team records, and distributes shuffled members round-robin so team sizes differ by at most one.

Primary source files

  • src/tools/random-team-generator/index.ts defines meta, Team, cryptoShuffle, and makeTeams.
  • src/tools/random-team-generator/index.test.ts covers every name placed once, balanced team sizes, no duplicates, repeated invariant checks, over-count errors, and one-based indices.
  • src/tools/random-team-generator/Body.astro owns browser input parsing and validation.
  • src/tools/random-team-generator/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

  • Throw when teamCount is less than one or greater than names length.
  • Keep team indices one-based.
  • Shuffle before assignment.
  • Distribute members round-robin to balance team sizes.
  • Preserve every input name exactly once.
  • If blank-name trimming is added, define whether it belongs in Body.astro or pure logic.
  • Do not upload or persist team lists.

Testing

Test all names placed, no duplicates, team-size spread, one-based indices, too many teams, zero teams, blank-name policy, repeated random runs, and exact-bias changes if shuffle indexing is modified.

PR checklist

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