AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Magic 8 Ball Agent Guide

Agent guide for canonical 20-answer random selection using browser crypto randomness.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Magic 8 Ball in the alexandrai-tools project.

Project overview

This guide covers src/tools/magic-8-ball. ANSWERS contains the canonical 20 responses, and ask uses globalThis.crypto.getRandomValues to generate one random byte, takes modulo answer count, and returns one answer from the list.

Primary source files

  • src/tools/magic-8-ball/index.ts defines meta, ANSWERS, Answer, and ask.
  • src/tools/magic-8-ball/index.test.ts covers membership in the answer list, exact answer count, multiple distinct results over repeated calls, broad coverage over many calls, and canonical answer validation.
  • src/tools/magic-8-ball/Body.astro owns question input, answer display, and repeat interaction.
  • src/tools/magic-8-ball/i18n.ts owns localized labels.
  • src/lib/tools.ts registers the tool metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Keep exactly 20 canonical answers unless tests and copy are updated.
  • Use browser crypto randomness for answer selection.
  • Return only entries from ANSWERS.
  • Keep Answer type derived from ANSWERS.
  • Treat output as entertainment-only.
  • Avoid persisting questions.
  • If randomness is made injectable for tests, preserve production crypto behavior.

Testing

Test answer count, answer membership, repeated-call invariants, broad random coverage, entertainment copy, empty questions, and any future deterministic test seam.

PR checklist

  • npm test passes for magic-8-ball.
  • Randomness, math, lookup tables, or Unicode behavior is documented exactly.
  • Browser-local behavior and copy/output paths remain private.
  • Invalid inputs and edge cases are covered by tests.