AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Debt Payoff Calculator Agent Guide

Agent guide for debt amortization loops, insufficient-payment detection, and payoff totals.

AGENTS.md

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

Project overview

This guide covers src/tools/debt-payoff-calculator/index.ts. The tool simulates monthly amortization from balance, APR, and monthly payment, detects when payment does not cover initial monthly interest, caps the loop with a long-horizon guard, and returns payoff months, total interest, total paid, and never-payoff state.

Primary source files

  • src/tools/debt-payoff-calculator/index.ts defines meta, PayoffResult, and debtPayoff.
  • src/tools/debt-payoff-calculator/index.test.ts covers known payoff range, too-low payment, zero balance, payment equal to interest, and zero APR.
  • src/tools/debt-payoff-calculator/Body.astro owns browser inputs and warnings.
  • src/tools/debt-payoff-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

  • Return ok false for non-positive balance or non-positive monthly payment.
  • Return never true when payment is less than or equal to initial monthly interest.
  • At zero APR, reduce balance by payment with no interest.
  • Keep MAX_MONTHS as a guard against unexpected non-termination.
  • Use Math.min when applying principal payment so the final month does not overpay principal.
  • Do not call this debt advice; it is a calculator.
  • If extra payments or payoff methods are added, test them as separate strategies.

Testing

Test normal payoff, zero APR, zero balance, zero payment, payment below interest, payment equal to interest, high APR, final partial month, guard behavior, and totalPaid equal to balance plus interest.

PR checklist

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