AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Age Calculator Agent Guide

Agent guide for calendar age calculation, total UTC day counts, and order-independent absolute day differences.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Age Calculator in the alexandrai-tools project.

Project overview

This guide covers src/tools/age-calculator/index.ts. The tool parses YYYY-MM-DD values, computes total days through UTC epoch days, rejects age calculations where the as-of date is before the birth date, and derives years, months, and days with calendar borrow logic. It also exposes an order-independent absolute daysBetween helper.

Primary source files

  • src/tools/age-calculator/index.ts defines meta, AgeResult, parseISO, isoToEpochDay, ageOn, and daysBetween.
  • src/tools/age-calculator/index.test.ts covers exact birthdays, month borrow, as-of before birth, same-day age zero, totalDays over leap years, invalid input, order-independent daysBetween, symmetry, and same-date differences.
  • src/tools/age-calculator/Body.astro owns browser controls.
  • src/tools/age-calculator/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 YYYY-MM-DD format in pure parsing.
  • Use UTC epoch-day arithmetic for totalDays.
  • Return ok false when the as-of date is before the birth date.
  • Borrow days from the previous month of the as-of date when needed.
  • Borrow months from years when needed.
  • Keep daysBetween absolute and order-independent.
  • If strict calendar validation is added, update parse expectations for month and day overflow.

Testing

Test exact birthdays, same-day birth, as-of before birth, month borrow, year borrow, leap-year totalDays, Feb 29 birthdays, invalid formats, overflow date policy, daysBetween symmetry, and order independence.

PR checklist

  • npm test passes for age-calculator.
  • Timezone, date, and cycle assumptions remain documented.
  • Invalid-input behavior is covered by tests.
  • UI labels, metadata, and pure logic stay in sync.