AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Pomodoro Timer Agent Guide

Agent guide for work/break phase switching, configurable duration seconds, and countdown formatting.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Pomodoro Timer in the alexandrai-tools project.

Project overview

This guide covers src/tools/pomodoro-timer. nextPhase alternates work and break, phaseDurationSeconds multiplies the configured phase minutes by 60, and formatCountdown floors fractional seconds, clamps negative values to zero, and formats the result as MM:SS with two-digit minutes and seconds.

Primary source files

  • src/tools/pomodoro-timer/index.ts defines meta, CyclePhase, CycleConfig, nextPhase, phaseDurationSeconds, and formatCountdown.
  • src/tools/pomodoro-timer/index.test.ts covers phase switching, default work and break seconds, custom config, zero formatting, 25-minute formatting, 1:30 formatting, negative clamping, and second padding.
  • src/tools/pomodoro-timer/Body.astro owns timer state, start/pause/reset controls, configurable durations, and phase display.
  • src/tools/pomodoro-timer/i18n.ts owns localized labels.
  • 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

  • Switch work to break and break to work.
  • Calculate phase duration from the selected phase only.
  • Convert minutes to seconds by multiplying by 60.
  • Floor fractional seconds before formatting.
  • Clamp negative countdown values to zero.
  • Format countdown as MM:SS with padded fields.
  • Keep long-session hour formatting out unless the UI adds hour support.

Testing

Test phase switching, default durations, custom durations, zero and negative countdowns, fractional seconds, padding, UI start/pause/reset state, auto-switch behavior, and settings changes mid-cycle.

PR checklist

  • npm test passes for pomodoro-timer.
  • 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.