Fuzzy Schedule Time Syntax Specification

Version: 1.2.0 Status: Draft Specification
Latest Version: fuzzy-schedule-specification
Editor: GitHub Agentic Workflows Team

---

Abstract

This specification defines the Fuzzy Schedule Time Syntax, a human-friendly scheduling language for GitHub Agentic Workflows that automatically distributes workflow execution times to prevent server load spikes. The syntax supports daily, hourly, weekly, and interval-based schedules with optional time constraints and timezone conversions. The specification includes a deterministic scattering algorithm that uses hash functions to assign consistent execution times to workflows based on their identifiers, ensuring predictable behavior across multiple compilations while distributing load across an organization’s infrastructure.

Status of This Document

This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time.

This document is governed by the GitHub Agentic Workflows project specifications process.

Table of Contents

1. Introduction
2. Conformance
3. Core Syntax
4. Time Specifications
5. Timezone Support
6. Scattering Algorithm
7. Cron Expression Generation
8. Safeguards
9. Error Handling
10. Compliance Testing
11. Sync Notes
12. Calendar Output Schema
13. Norms

---

1. Introduction

1.1 Purpose

The Fuzzy Schedule Time Syntax addresses the problem of server load spikes that occur when multiple workflows execute simultaneously using fixed-time schedules. Traditional cron expressions require explicit time specifications, leading developers to commonly use convenient times (e.g., midnight, on-the-hour) that create load concentration. This specification defines a natural language syntax that automatically distributes execution times while preserving schedule semantics.

1.2 Scope

This specification covers:

• Natural language schedule expressions for daily, hourly, weekly, and interval-based schedules
• Time constraint syntax using around and between modifiers
• Timezone conversion syntax for local-to-UTC time translation
• Deterministic scattering algorithm for execution time distribution
• Cron expression generation from fuzzy syntax
• Validation requirements and error handling

This specification does NOT cover:

• Standard cron expression syntax (handled by GitHub Actions)
• Monthly or yearly schedule patterns
• Dynamic schedule adjustment based on load metrics
• Schedule conflict resolution between workflows

1.3 Design Goals

This specification prioritizes:

1. Human readability: Natural language expressions that clearly communicate intent
2. Load distribution: Automatic scattering prevents simultaneous workflow execution
3. Determinism: Same workflow identifier always produces same execution time
4. Predictability: Execution times remain consistent across recompilations
5. Timezone awareness: Support for local time specifications with UTC conversion

---

2. Conformance

2.1 Conformance Classes

A conforming implementation is a parser that satisfies all MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements in this specification.

A conforming fuzzy schedule expression is a schedule string that conforms to the syntax grammar defined in Section 3 and produces a valid fuzzy cron placeholder.

A conforming scattering implementation is an implementation that satisfies all scattering algorithm requirements in Section 6.

2.2 Requirements Notation

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

2.3 Compliance Levels

Level 1 (Basic): Supports daily and weekly schedules without time constraints

Level 2 (Standard): Adds support for time constraints (around, between) and hourly schedules

Level 3 (Complete): Includes timezone conversion, interval schedules, and bi-weekly/tri-weekly patterns

---

3. Core Syntax

3.1 Grammar Definition

A fuzzy schedule expression MUST conform to the following ABNF grammar:

fuzzy-schedule  = daily-schedule / hourly-schedule / weekly-schedule / interval-schedule

daily-schedule  = "daily" [time-constraint]
weekly-schedule = "weekly" ["on" weekday] [time-constraint]
hourly-schedule = "hourly" / ("every" hour-interval)
interval-schedule = "every" (minute-interval / hour-interval / day-interval / week-interval)

time-constraint = around-constraint / between-constraint
around-constraint = "around" time-spec
between-constraint = "between" time-spec "and" time-spec

time-spec       = (hour-24 ":" minute) [utc-offset]
                / (hour-12 am-pm) [utc-offset]
                / time-keyword [utc-offset]

time-keyword    = "midnight" / "noon"
am-pm           = "am" / "pm"
utc-offset      = "utc" ("+" / "-") (hours / hours ":" minutes)

weekday         = "sunday" / "monday" / "tuesday" / "wednesday"
                / "thursday" / "friday" / "saturday"

hour-24         = 1*2DIGIT  ; 0-23
hour-12         = 1*2DIGIT  ; 1-12
minute          = 2DIGIT    ; 00-59
hours           = 1*2DIGIT
minutes         = 2DIGIT

minute-interval = 1*DIGIT ("m" / "minutes" / "minute")
hour-interval   = 1*DIGIT ("h" / "hours" / "hour")
day-interval    = 1*DIGIT ("d" / "days" / "day")
week-interval   = 1*DIGIT ("w" / "weeks" / "week")

3.2 Daily Schedules

3.2.1 Basic Daily Schedule

A basic daily schedule expression SHALL take the form:

daily

An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY * * *

The execution time SHALL be deterministically scattered across all 24 hours and 60 minutes of the day.

3.2.2 Daily Around Time

A daily around schedule expression SHALL take the form:

daily around <time-spec>

An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY_AROUND:HH:MM * * *

The execution time SHALL be scattered within a ±60 minute window around the specified time.

Example:

daily around 14:00
# Generates: FUZZY:DAILY_AROUND:14:0 * * *
# Scatters within window: 13:00 to 15:00

3.2.3 Daily Between Times

A daily between schedule expression SHALL take the form:

daily between <start-time> and <end-time>

An implementation MUST generate a fuzzy cron placeholder: FUZZY:DAILY_BETWEEN:START_H:START_M:END_H:END_M * * *

The execution time SHALL be scattered uniformly within the specified time range, including handling of midnight-crossing ranges.

Example:

daily between 9:00 and 17:00
# Generates: FUZZY:DAILY_BETWEEN:9:0:17:0 * * *
# Scatters within window: 09:00 to 17:00

daily between 22:00 and 02:00
# Generates: FUZZY:DAILY_BETWEEN:22:0:2:0 * * *
# Scatters within window: 22:00 to 02:00 (crossing midnight)

3.3 Weekly Schedules

3.3.1 Basic Weekly Schedule

A basic weekly schedule expression SHALL take the form:

weekly

An implementation MUST generate a fuzzy cron placeholder: FUZZY:WEEKLY * * *

The execution SHALL be scattered across all seven days of the week and all hours/minutes of each day.

3.3.2 Weekly with Day Specification

A weekly day schedule expression SHALL take the form:

weekly on <weekday>

An implementation MUST generate a fuzzy cron placeholder: FUZZY:WEEKLY:DOW * * DOW

Example:

weekly on monday
# Generates: FUZZY:WEEKLY:1 * * 1
# Scatters across all hours on Monday

3.3.3 Weekly with Time Constraints

A weekly schedule MAY include time constraints using around or between:

weekly on <weekday> around <time-spec>
weekly on <weekday> between <start-time> and <end-time>

Example:

weekly on friday around 17:00
# Generates: FUZZY:WEEKLY:5:AROUND:17:0 * * 5
# Scatters Friday 16:00-18:00

3.4 Hourly Schedules

3.4.1 Basic Hourly Schedule

A basic hourly schedule expression SHALL take the form:

hourly

An implementation MUST generate a fuzzy cron placeholder: FUZZY:HOURLY * * *

The minute offset SHALL be scattered across 0-59 minutes but remain consistent for each hour.

Example:

hourly
# Generates: FUZZY:HOURLY * * *
# Might scatter to: 43 * * * * (runs at minute 43 every hour)

3.4.2 Hour Interval Schedules

An hour interval schedule expression SHALL take the form: