AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Roman Numeral Converter Agent Guide

Agent guide for integer-to-Roman conversion, Roman-to-integer parsing, range checks, and canonical-form validation.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Roman Numeral Converter in the alexandrai-tools project.

Project overview

This guide covers src/tools/roman-numeral-converter/index.ts. The tool converts integers one through 3999 with descending subtractive pairs, parses Roman strings case-insensitively, rejects invalid characters and empty input, rejects totals outside range, and validates canonical form by round-tripping back through toRoman.

Primary source files

  • src/tools/roman-numeral-converter/index.ts defines meta, INT_TO_ROMAN, RomanResult, toRoman, ROMAN_VALUES, and fromRoman.
  • src/tools/roman-numeral-converter/index.test.ts covers common subtractive values, 1994, 3999, 2024, range errors, non-integers, lowercase input, invalid characters, empty input, non-canonical forms, and round trips.
  • src/tools/roman-numeral-converter/Body.astro owns browser controls.
  • src/tools/roman-numeral-converter/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

  • Accept only integer values from one through 3999 in toRoman.
  • Use descending value and symbol pairs for Roman construction.
  • Trim and uppercase Roman input before parsing.
  • Reject empty Roman input.
  • Reject characters outside I, V, X, L, C, D, and M.
  • Reject parsed totals outside one through 3999.
  • Reject non-canonical Roman strings by round-tripping through toRoman.

Testing

Test boundaries one and 3999, zero, 4000, negative values, non-integers, subtractive pairs, lowercase input, invalid characters, non-canonical forms, round trips across a range, and UI mode switching.

PR checklist

  • npm test passes for roman-numeral-converter.
  • Validation, formatting, and numeric precision behavior remain documented.
  • Pure helpers stay browser-local and side-effect free.
  • UI labels, metadata, and tests update together for behavior changes.