AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Chinese Zodiac Agent Guide

Agent guide for Chinese zodiac animal and element lookup from Gregorian birth year.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Chinese Zodiac in the alexandrai-tools project.

Project overview

This guide covers src/tools/chinese-zodiac/index.ts. The tool uses 2020 as Rat and Metal base year, maps animals through a twelve-year modulo cycle, maps elements through a ten-year cycle with each element spanning two consecutive years, and returns the computed animal and element.

Primary source files

  • src/tools/chinese-zodiac/index.ts defines meta, ChineseAnimal, ChineseElement, ChineseZodiacResult, ANIMALS, ELEMENTS_FROM_2020, and getChineseZodiac.
  • src/tools/chinese-zodiac/index.test.ts covers 2024 Dragon, 2020 Rat, 2021 Ox, 2008 Rat, 1984 Rat, Metal and Wood elements, and full twelve-animal cycle coverage.
  • src/tools/chinese-zodiac/Body.astro owns browser controls.
  • src/tools/chinese-zodiac/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

  • Use 2020 as the Rat animal base.
  • Use 2020 as the Metal element base.
  • Normalize animal modulo results so years before 2020 work.
  • Normalize element modulo results so years before 2020 work.
  • Keep element sequence as Metal, Water, Wood, Fire, Earth with each element repeated twice.
  • Return only animal and element from pure logic.
  • If lunar-new-year precision is added, make it an explicit date-based mode and keep year-only behavior stable.

Testing

Test known animal years, known element years, years before 2020, negative modulo behavior, complete twelve-animal cycle, complete ten-year element cycle, invalid year handling if added, and any future lunar date mode.

PR checklist

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