AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Paycheck Calculator Agent Guide

Agent guide for simplified take-home pay estimates across annual, monthly, and biweekly pay periods.

AGENTS.md

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

Project overview

This guide covers src/tools/paycheck-calculator. calcPaycheck validates finite positive annual gross pay and a deduction percentage from zero up to but not including one hundred, computes annual net pay from the deduction percentage, divides gross and net pay by period count for annual, monthly, or biweekly views, and returns deduction amount per period.

Primary source files

  • src/tools/paycheck-calculator/index.ts defines meta, PayPeriod, PaycheckResult, PERIODS_PER_YEAR, and calcPaycheck.
  • src/tools/paycheck-calculator/index.test.ts covers annual output, monthly split, biweekly split, zero deduction, non-positive gross, negative deduction, 100 percent or larger deduction, and non-finite inputs.
  • src/tools/paycheck-calculator/Body.astro owns gross salary, deduction percentage, period selection, currency, and result display.
  • src/tools/paycheck-calculator/i18n.ts owns localized labels and simplified-estimate copy.
  • src/lib/tools.ts registers the tool metadata.

Setup commands

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

Change rules

  • Return null for non-finite gross pay.
  • Return null for non-finite deduction percentage.
  • Return null for gross pay less than or equal to zero.
  • Return null for deduction percentage below zero.
  • Return null for deduction percentage greater than or equal to one hundred.
  • Use 1, 12, and 26 periods per year for annual, monthly, and biweekly.
  • Keep tax-specific logic out of this generic estimate helper.

Testing

Test every pay period, zero deduction, invalid gross, invalid deduction, non-finite inputs, per-period deduction math, annual consistency, currency display, and tax-advice disclaimer copy.

PR checklist

  • npm test passes for paycheck-calculator.
  • Pure helper behavior and UI state remain aligned.
  • Invalid input and edge cases are documented and tested.
  • Privacy and estimate-scope copy stays visible where relevant.