AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Savings Goal Agent Guide

Agent guide for calculating months to reach a savings target from monthly deposits and interest.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Savings Goal in the alexandrai-tools project.

Project overview

This guide covers src/tools/savings-goal/index.ts. The tool calculates months needed to reach a target from a monthly deposit and annual rate, falls back to simple division at zero rate, breaks months into years and remaining months, and reports total contributed plus interest earned.

Primary source files

  • src/tools/savings-goal/index.ts defines meta, SavingsGoalResult, and calcSavingsGoal.
  • src/tools/savings-goal/index.test.ts covers zero-rate saving, positive-rate speedup, year breakdown, zero target, zero deposit, interest identity, and large goals.
  • src/tools/savings-goal/Body.astro owns browser inputs and display.
  • src/tools/savings-goal/i18n.ts owns localized copy.
  • src/lib/tools.ts auto-discovers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Return zeros when targetAmount or monthlyDeposit is non-positive.
  • Use simple ceiling division when annualRatePct is zero.
  • Use the annuity period formula when annualRatePct is non-zero.
  • Keep years and remainingMonths consistent with months.
  • Report totalContributed as monthlyDeposit times months.
  • Document that projections are estimates, not guaranteed returns.
  • If negative rates are supported later, define reachable and unreachable cases explicitly.

Testing

Test zero-rate months, positive interest, year-month decomposition, zero target, zero deposit, large goal, interest identity, high rates, and any negative-rate behavior if added.

PR checklist

  • npm test passes for savings-goal.
  • Pure calculation stays independent from UI formatting.
  • Browser-local behavior is preserved.
  • Copy does not present calculator output as personalized financial advice.