AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Rock Paper Scissors Agent Guide

Agent guide for crypto-random CPU moves and complete rock-paper-scissors result rules.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Rock Paper Scissors in the alexandrai-tools project.

Project overview

This guide covers src/tools/rock-paper-scissors. randomMove picks rock, paper, or scissors using browser crypto randomness. determineResult evaluates the result from the user's perspective for all move pairs. play combines a random CPU move with determineResult.

Primary source files

  • src/tools/rock-paper-scissors/index.ts defines meta, Move, Result, PlayResult, MOVES, randomMove, determineResult, and play.
  • src/tools/rock-paper-scissors/index.test.ts covers all nine user/CPU move outcomes, valid CPU moves, result consistency, multiple CPU moves over repeated calls, and randomMove membership.
  • src/tools/rock-paper-scissors/Body.astro owns move buttons, score state, CPU move display, and round result.
  • src/tools/rock-paper-scissors/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 legal moves limited to rock, paper, and scissors.
  • Use crypto.getRandomValues for CPU moves.
  • Return draw when moves match.
  • Return win for rock over scissors, scissors over paper, and paper over rock.
  • Return lose for all remaining non-draw pairs.
  • Keep result semantics from the user's perspective.
  • Use determineResult as the single source of truth for play outcomes.

Testing

Test all nine outcomes, valid random moves, play consistency, score UI, repeated-call coverage, disabled states if added, and localization of result text.

PR checklist

  • npm test passes for rock-paper-scissors.
  • 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.