AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Random Color Generator Agent Guide

Agent guide for random hex color generation with lightness and saturation constraints.

AGENTS.md

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

Project overview

This guide covers src/tools/random-color-generator/index.ts. The tool generates random RGB bytes with crypto.getRandomValues, converts generated colors to hex, approximates HSL lightness and saturation for filtering, retries constrained generation up to a fixed attempt count, and provides randomMany for arrays of colors.

Primary source files

  • src/tools/random-color-generator/index.ts defines meta, RandomColorOptions, random byte generation, rgbToHsl, toHex, randomColor, and randomMany.
  • src/tools/random-color-generator/index.test.ts covers valid hex output, no-option generation, lightness and saturation constraints, lowercase hex, requested array length, zero count, and non-identical output.
  • src/tools/random-color-generator/Body.astro owns browser controls.
  • src/tools/random-color-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

  • Keep output as lowercase six-digit hex.
  • Use crypto.getRandomValues for random bytes.
  • Treat minLightness, maxLightness, and minSaturation as filters rather than direct color construction.
  • Keep the retry cap so impossible or rare constraints terminate.
  • Leave randomMany zero-count behavior as an empty array unless UI expectations change.
  • Do not persist generated colors without an explicit save feature.
  • If hue constraints are added, add tests that validate them directly.

Testing

Test hex format, lowercase output, options omitted, lightness constraints, saturation constraint, array lengths, zero count, randomness smoke checks, and any future hue filtering.

PR checklist

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