--- name: truetime description: Ensure real-time accurate scheduling and planning across UTC, server time, NTP-sourced time, user local time, and arbitrary time zones. Use for timers, reminders, cron planning, in X minutes or months or years calculations, absolute timestamp conversion, Chinese lunar date awareness, and cross-timezone coordination. Enforce exact duration fidelity so user values are never replaced by example values, compute target times in UTC first, and verify deltas before execution. ---

TrueTime

Use this skill to avoid time mistakes caused by stale examples, wrong units, timezone drift, or DST confusion.

Non-Negotiable Rules

• Treat user-provided duration values as authoritative.
• Never copy numeric values from examples into real execution.
• Read current time from the runtime clock before calculating.
• Compute canonical target time in UTC first.
• Convert for display second (server timezone, user timezone, other timezone).
• Ask for clarification when timezone context is missing and outcome can change.

Required Workflow

1. Extract timing intent exactly.

- Capture literal phrase, value, unit, timezone hint, and target date/time. - Keep the original requested value unchanged (for example 1 minute stays 1 minute).

1. Read current real time.

- Use the bundled script for deterministic calculations: - Relative: node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai - Relative (calendar units): node {baseDir}/scripts/true_time.mjs --plus 1month2weeks --user-tz America/New_York --calendar-tz America/New_York - Absolute: node {baseDir}/scripts/true_time.mjs --target 2026-02-17T09:30:00 --target-tz Asia/Shanghai --user-tz America/Los_Angeles - NTP time source: node {baseDir}/scripts/true_time.mjs --plus 1h --time-source ntp

1. Parse the expression into one precise delta or one precise absolute timestamp.
2. Compute UTC target first.
3. Convert UTC target to server/user/other requested timezone for presentation.
4. Verify the result before execution.

- Confirm target_utc - now_utc equals requested delta. - Confirm timezone offset conversion is consistent.

1. Execute schedules using UTC unless the target scheduler explicitly needs local timezone.
2. Report both absolute and relative interpretation in the final response.

Relative Time Guardrails

• Accept explicit units only:

- milliseconds: ms, msec, msecs, millisecond, milliseconds - seconds: s, sec, second, seconds - minutes: m, min, minute, minutes - hours: h, hr, hour, hours - days: d, day, days - weeks: w, week, weeks - months: mo, mon, month, months - years: y, yr, year, years - decades: decade, decades - centuries: century, centuries

• Reject ambiguous units instead of guessing.
• All units support decimal values, including calendar units.

- Examples: 1.5m, 0.25h, 2.5day, 250.5ms, 1.5month, 0.1year, 0.5decade, 0.01century. - Decimal separator . is preferred; , is accepted as input and normalized.

• Fixed-unit decimals are computed to millisecond precision.
• Calendar-unit policy:

- month/year/decade/century are calendar-aware, not fixed seconds. - Calendar arithmetic uses --calendar-tz (fallback: user timezone -> server timezone). - Decimal calendar values are split into integer and fractional parts. - Integer months use calendar shift; fractional months use the shifted month length to compute milliseconds. - End-of-month handling clamps to the last valid day (for example Jan 31 + 1 month -> Feb 28/29).

• Keep verification examples explicit:

- 1.5m = 90s - 250ms = 0.25s - 1m = 60s - 1h30m = 5400s - 2d = 172800s - 1.5year = 18 months - 1decade = 10 years - 0.5decade = 5 years - 1century = 100 years - 0.01century = 1 year

Absolute Time Guardrails

• Prefer IANA timezone names (Asia/Shanghai, America/Los_Angeles, UTC).
• Avoid ambiguous abbreviations (CST, IST) unless user confirms meaning.
• If user gives a naive datetime with no timezone, ask once or apply an explicit assumption.
• For DST transition windows, state that the chosen timezone rules were applied.

Timezone Catalog and Customization

• List all available runtime timezones:

- node {baseDir}/scripts/true_time.mjs --list-timezones

• Filter common choices quickly:

- node {baseDir}/scripts/true_time.mjs --list-timezones | rg -i '^(UTC|Asia/(Shanghai|Tokyo|Kolkata)|America/(Los_Angeles|New_York)|Europe/(London|Paris|Berlin))$'

• User custom timezone:

- Accept any valid IANA timezone from --list-timezones. - Pass user timezone via --user-tz . - If user timezone is unknown, ask before executing time-sensitive actions.

Common timezones to use in examples and user-facing confirmations:

• UTC (no DST)
• Asia/Shanghai (Beijing time, UTC+08:00, no DST)
• Asia/Tokyo (Tokyo time, UTC+09:00, no DST)
• Asia/Kolkata (India time, UTC+05:30, no DST)
• America/Los_Angeles (US West: PST UTC-08:00 / PDT UTC-07:00, DST applies)
• America/New_York (US East: EST UTC-05:00 / EDT UTC-04:00, DST applies)
• America/Chicago (US Central: CST UTC-06:00 / CDT UTC-05:00, DST applies)
• America/Denver (US Mountain: MST UTC-07:00 / MDT UTC-06:00, DST applies)
• America/Phoenix (Arizona: MST UTC-07:00, typically no DST)
• America/Anchorage (Alaska: AKST UTC-09:00 / AKDT UTC-08:00, DST applies)
• Pacific/Honolulu (Hawaii: HST UTC-10:00, no DST)
• Europe/London (UK: GMT UTC+00:00 / BST UTC+01:00, DST applies)
• Europe/Paris (CET UTC+01:00 / CEST UTC+02:00, DST applies)
• Europe/Berlin (CET UTC+01:00 / CEST UTC+02:00, DST applies)
• Europe/Amsterdam (CET UTC+01:00 / CEST UTC+02:00, DST applies)

DST and Standard-Time Rules

• Never assume fixed offsets for DST regions (America/, many Europe/).
• Always compute with the actual target date, not "current offset."
• For DST fall-back overlaps (ambiguous local time), require explicit offset:

- 2026-11-01T01:30:00 in America/Los_Angeles is ambiguous. - Ask user to choose -07:00 (before fallback) or -08:00 (after fallback), or provide explicit offset in --target.

• For DST spring-forward gaps (invalid local time), require correction:

- 2026-03-08T02:30:00 in America/Los_Angeles does not exist. - Ask user to use a valid local time (for example 01:30 or 03:30).

• Prefer explicit-offset absolute targets when DST risk is high:

- --target 2026-11-01T01:30:00-07:00 - --target 2026-11-01T01:30:00-08:00

Chinese Lunar Calendar

• This tool outputs Chinese lunar datetime fields by default:

- lunar_timezone (default Asia/Shanghai, configurable via --lunar-tz) - now_lunar - target_lunar

• Use these fields when the user asks for Chinese lunar context.
• For execution/scheduling, still use Gregorian UTC fields as canonical.
• If a user gives only lunar date text and no Gregorian equivalent, ask for confirmation or a Gregorian target before execution.

Time Source Policy (Server vs NTP)

• Default time source is server clock (--time-source server).
• If user explicitly requests "do not use server time", switch to public NTP:

- --time-source ntp

• Optional NTP controls:

- --ntp-server (repeatable or comma-separated) - --ntp-timeout-ms

• NTP mode example:

- node {baseDir}/scripts/true_time.mjs --plus 30m --time-source ntp --ntp-server time.google.com

• If all NTP servers fail, stop and report failure instead of silently falling back to server time.

Mandatory Integration Points

Use TrueTime calculations before any of the following:

...