AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Week Number Agent Guide

Agent guide for ISO 8601 week number, ISO year, and weekday calculation with UTC arithmetic.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Week Number in the alexandrai-tools project.

Project overview

This guide covers src/tools/week-number/index.ts. The tool parses YYYY-MM-DD input, computes ISO weekday from UTC epoch days, uses the Thursday of the current ISO week to determine ISO year, finds week one from January fourth, and returns ISO week, ISO year, weekday number, and weekday name.

Primary source files

  • src/tools/week-number/index.ts defines meta, WeekNumberResult, WEEKDAY_NAMES, and getWeekNumber.
  • src/tools/week-number/index.test.ts covers first ISO week days, second week, year-end wrapping, week 53 years, mid-year weekdays, 1970 baseline, and invalid format.
  • src/tools/week-number/Body.astro owns browser controls.
  • src/tools/week-number/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 YYYY-MM-DD format.
  • Use UTC arithmetic, not local timezone or Intl.
  • Use ISO weekday numbering where Monday is one and Sunday is seven.
  • Use the Thursday rule to determine ISO year.
  • Use January fourth to find week one.
  • Return weekday names from the fixed Monday-first array.
  • If strict date validation is added, cover overflow dates explicitly.

Testing

Test Jan 1, Jan 4, Jan 7, Jan 8, Dec 31, ISO year wrapping, week 53 years, 1970 baseline, every weekday name, invalid format, overflow date policy, and UTC independence.

PR checklist

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