AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Budget Calculator Agent Guide

Agent guide for the 50/30/20 monthly income split calculator.

AGENTS.md

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

Project overview

This guide covers src/tools/budget-calculator/index.ts. The tool splits monthly after-tax income into needs, wants, and savings using fixed 50 percent, 30 percent, and 20 percent multipliers. It intentionally keeps the logic small and leaves formatting to the UI.

Primary source files

  • src/tools/budget-calculator/index.ts defines meta, BudgetSplit, and calcBudget.
  • src/tools/budget-calculator/index.test.ts covers the split values, sum identity, zero income, and needs percentage.
  • src/tools/budget-calculator/Body.astro owns browser input and result display.
  • src/tools/budget-calculator/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

  • Keep the fixed split at 50, 30, and 20 unless the tool is explicitly redesigned for custom ratios.
  • Keep needs plus wants plus savings equal to monthlyIncome before display rounding.
  • Do not clamp or reject negative income in pure logic unless UI validation changes with tests.
  • Keep formatting separate from calculation.
  • Do not present the split as universally appropriate financial advice.
  • If custom categories are added, preserve the current simple mode or migrate tests deliberately.
  • Keep calculation browser-local.

Testing

Test standard income, zero income, decimal income, sum identity, each category percentage, negative input behavior if retained, and display rounding if changed.

PR checklist

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