Okhp3 Tradition Observance Calendar

---
name: okhp3-tradition-observance-calendar
description: >
  Fetch, compute, and format religious observance calendars for the three
  in-scope Abrahamic traditions of the Abrahamic Reference Engine: Judaism,
  Christianity, and Islam. Use this skill whenever an agent needs to retrieve
  religious holiday data, generate iCalendar (.ics) output, look up holiday
  descriptions for cross-tradition audiences, or produce a unified observance
  event list. Covers Hebcal API (Jewish), AlAdhan API (Islamic), TypeScript
  Computus algorithm (Christian -- Western and Orthodox), Wikipedia summary
  fetching for event descriptions, .ics file generation, emoji assignments,
  holiday filter lists, and session caching strategy. All data sources are
  free, public, and require no API key. Zero cost. MIT license. Also activate
  when a user asks to "add holidays to my calendar app", "download religious
  observances as .ics", "show Jewish/Islamic/Christian holidays for a year",
  or compute Easter dates -- including when they ask for "all three faiths"
  or any single tradition's observance list.
license: MIT
metadata:
  author: Jamie Hill (OverKill Hill P³)
  version: "1.2.0"
  category: interfaith-reference
  origin: okhp3/abrahamic-reference-engine
  homepage: https://overkillhill.com
  author-github: https://github.com/OKHP3
  app-url: https://okhp3.github.io/abrahamic-reference-engine
  spec-version: "agentskills-1.0"
  reviewed: "2026-07-21"
  in_scope: "Reference, comparison, lookup, and observance work for the named in-scope Abrahamic traditions and sources."
  out_of_scope: "Theological adjudication, pastoral direction, invented scripture text, or unsupported doctrinal claims."
compatibility: >
  TypeScript (browser or Node). Fetch API required. No API keys or accounts.
  Optional: sessionStorage for browser caching. Optional: FullCalendar.io for
  calendar UI rendering.

---

# okhp3-tradition-observance-calendar

**OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://github.com/OKHP3)

Fetch, compute, and format religious observance calendars for the Abrahamic Reference Engine.

Covers **Judaism** (Hebcal API), **Christianity** (Computus algorithm -- Western and Orthodox), and **Islam** (AlAdhan API). All sources are free and anonymous. No API key. No cost. Zero runtime dependencies beyond `fetch`.

## Execution contract

- Accept a target year and optional tradition or denomination filter. Validate
  the year before constructing provider URLs or date objects.
- Normalize every source into `ObservanceEvent` and retain the source,
  attribution, and caveat fields. Computed dates, provider dates, and missing
  dates must remain distinguishable.
- Use `Promise.allSettled` for independent provider or month requests so one
  outage does not discard successful results. Surface partial failure in the UI
  or return metadata rather than hiding it.
- Do not replace the deterministic Christian Computus path with a paid,
  credentialed, or unverified holiday API. Run the bundled Easter validator
  after algorithm changes.
- Treat Islamic dates as calendar estimates. State the local moon-sighting
  caveat, and never present an estimated date as universally authoritative.
- Fetch Wikipedia descriptions lazily, cache only non-sensitive results, and
  display the exact attribution string with the returned article URL.
- Escape user- or provider-derived values before inserting them into `.ics`.
  Follow the bundled RFC 5545 line-folding and date rules.

---

## Bundled reference files

Read these on demand -- only the file(s) you actually need for the current task:

| File | When to read |
|------|-------------|
| `references/api-reference.md` | Full API schemas and field details for Hebcal and AlAdhan; use when you need the complete response shape or want to understand all available query parameters |
| `references/computus.md` | Computus algorithm derivation, edge cases, century correction, and multi-century validation dates; use when troubleshooting Easter date accuracy |
| `references/holiday-data.md` | Extended `WIKIPEDIA_ARTICLE_MAP` entries and supplementary AlAdhan display name notes; use when adding a holiday not covered by the map in this file |
| `references/ics-spec.md` | ICS format specification, RFC 5545 line-folding rules, calendar client compatibility notes, and VTIMEZONE considerations |

The SKILL.md sections below are sufficient for most implementation tasks. Reach for the reference files when you need depth beyond what is documented here.

---

## 1. Scope Rules

A holiday is in scope if and only if it meets **both** criteria:

1. **Abrahamic lineage** -- traces its roots to the Abrahamic covenant
2. **US population threshold** -- practiced by a tradition representing ≥1% of the US population per Pew Research Center

| Tradition | US Share | In Scope |
|---|---|---|
| Christianity | ~63% | Yes -- five denominational lenses |
| Judaism | ~2% | Yes |
| Islam | ~1% | Yes |
| Hinduism | ~1% | **No** (not Abrahamic) |
| Buddhism | ~1% | **No** (not Abrahamic) |
| Baha'i | ~0.1% | **No** (Abrahamic but below threshold) |

Source: Pew Research Center -- https://www.pewresearch.org/religion/religious-landscape-study/

---

## 2. Unified Event Type

All holiday sources normalize to this shared interface:

```typescript
interface ObservanceEvent {
  id: string;           // "{tradition}-{rawName}-{year}-{startDateISO}"
  title: string;        // emoji-prefixed: "✡️ Rosh Hashanah"
  rawName: string;      // without emoji: "Rosh Hashanah"
  emoji: string;        // "✡️" | "✝️" | "☦️" | "☪️"
  tradition: 'judaism' | 'christianity' | 'islam';
  denomination: 'all' | 'catholic' | 'orthodox' | 'protestant' | 'evangelical' | 'restorationist';
  startDate: Date;
  endDate: Date;        // equals startDate for single-day events
  isMultiDay: boolean;
  hebrewName?: string;  // Jewish holidays only
  hijriDate?: string;   // Islamic holidays only, e.g., "1 Muharram 1448 AH"
  sourceUrl?: string;   // Hebcal permalink or Wikipedia URL
  source: 'hebcal' | 'aladhan' | 'algorithm';
  wikiArticle?: string; // Wikipedia article title for description fetch (Section 5)
}
```

---

## 3. Emoji Registry

```typescript
export const TRADITION_EMOJI = {
  judaism:               '✡️',   // U+2721 U+FE0F  Star of David
  christianity_western:  '✝️',   // U+271D U+FE0F  Latin Cross
  christianity_orthodox: '☦️',   // U+2626 U+FE0F  Orthodox Cross
  islam:                 '☪️',   // U+262A U+FE0F  Star and Crescent
} as const;
```

Use `✝️` for Catholic, Mainline Protestant, Evangelical, and Restorationist events.
Use `☦️` for Orthodox-specific events and dates.

---

## 4. Jewish Holidays -- Hebcal REST API

**No API key. CC BY 4.0. Free.**

### 4.1 Endpoint

```
GET https://www.hebcal.com/hebcal?v=1&cfg=json&year={year}&maj=on&min=off&nx=off&mf=off&ss=on&mod=on&i=off&lg=s&m=50
```

Parameters that matter:
- `maj=on` -- major holidays (required)
- `ss=on` -- special Shabbatot
- `mod=on` -- modern Israeli holidays (Yom HaShoah, Yom HaAtzmaut)
- `i=off` -- Diaspora rules (not Israeli rules -- ARE targets US audience)
- `min=off` -- minor holidays off by default (expose as optional filter)

### 4.2 Fetch pattern

```typescript
async function fetchJewishHolidays(year: number): Promise<ObservanceEvent[]> {
  const cacheKey = `are_hebcal_${year}`;
  const cached = sessionStorage?.getItem(cacheKey);
  if (cached) return JSON.parse(cached);

  const url = `https://www.hebcal.com/hebcal?v=1&cfg=json&year=${year}&maj=on&min=off&nx=off&mf=off&ss=on&mod=on&i=off&lg=s&m=50`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Hebcal fetch failed: ${res.status}`);
  const data = await res.json();

  const items: HebcalItem[] = (data.items || []).filter(
    (item: HebcalItem) => item.category === 'holiday'
  );

  const events = normalizeHebcalItems(items, year);
  sessionStorage?.setItem(cacheKey, JSON.stringify(events));
  return events;
}
```

### 4.3 Response item shape

```json
{
  "title": "Rosh Hashana 5787",
  "date": "2026-09-20",
  "hdate": "1 Tishrei 5787",
  "category": "holiday",
  "subcat": "major",
  "hebrew": "ראש השנה",
  "link": "https://www.hebcal.com/holidays/rosh-hashana-5787",
  "memo": "Jewish New Year"
}
```

### 4.4 Normalization rules

- Strip Hebrew year suffix from title for display: `"Rosh Hashana 5787"` → `"Rosh Hashana"`
- Detect multi-day events by grouping items with matching normalized base name across consecutive dates
- Set `endDate` to the last consecutive day with the same name; `isMultiDay = true` when span > 1
- Populate `hebrewName` from `hebrew` field
- Populate `sourceUrl` from `link` field
- Populate `wikiArticle` from `WIKIPEDIA_ARTICLE_MAP[normalizedName]` (see Section 5)
- Set `emoji = '✡️'`, `tradition = 'judaism'`, `denomination = 'all'`

### 4.5 Attribution

Display in UI: `"Calendar data via Hebcal.com (CC BY 4.0)"`
Link: https://www.hebcal.com

---

## 5. Islamic Holidays -- AlAdhan REST API

**No API key. Free. GPL-3.0.**

### 5.1 Strategy

AlAdhan embeds holiday data in each day of the Gregorian-to-Hijri calendar response. Fetch all 12 months in parallel; collect days where `date.hijri.holidays` is non-empty.

### 5.2 Endpoint (per month)

```
GET https://api.aladhan.com/v1/gToHCalendar/{month}/{year}
```

### 5.3 Fetch pattern

> **WARNING -- use Promise.allSettled, NOT Promise.all.**
> AlAdhan occasionally drops individual month requests.
> Promise.all fails fast and discards all 11 other successful months.
> Promise.allSettled continues and collects partial results gracefully.
> This is a hard requirement, not a suggestion.

```typescript
async function fetchIslamicHolidays(year: number): Promise<ObservanceEvent[]> {
  const cacheKey = `are_aladhan_${year}`;
  const cached = sessionStorage?.getItem(cacheKey);
  if (cached) return JSON.parse(cached);

  const months = Array.from({ length: 12 }, (_, i) => i + 1);
  const responses = await Promise.allSettled(
    months.map(m =>
      fetch(`https://api.aladhan.com/v1/gToHCalendar/${m}/${year}`)
        .then(r => r.ok ? r.json() : Promise.reject(r.status))
    )
  );

  const allDays: AladhanDay[] = responses.flatMap(result =>
    result.status === 'fulfilled' ? result.value.data || [] : []
  );

  const events = normalizeAladhanDays(allDays, year);
  sessionStorage?.setItem(cacheKey, JSON.stringify(events));
  return events;
}
```

### 5.4 Response day shape (relevant fields)

```json
{
  "gregorian": {
    "date": "20-03-2026",
    "year": "2026",
    "month": { "en": "March" },
    "day": "20"
  },
  "hijri": {
    "date": "01-09-1447",
    "year": "1447",
    "month": { "en": "Ramaḍān", "number": 9 },
    "day": "01",
    "holidays": ["Start of Ramadan"]
  }
}
```

### 5.5 Allowed holiday filter (US mainstream Sunni/general Islamic)

Only include days where at least one entry in `holidays[]` matches this allowed set:

```typescript
const ALADHAN_ALLOWED: Set<string> = new Set([
  "Arafat (Haj) Day",
  "Eid-ul-Adha",
  "Islamic New Year",
  "Ashura",
  "Mawlid al-Nabi",
  "Al Isra' Wal Mi'raj",
  "Start of Ramadan",
  "Laylat al Qadr",
  "Eid ul Fitr",
]);
```

Discard any holiday string not in this set. Discard days where `holidays` is empty.

### 5.6 Display name normalization

```typescript
const ALADHAN_DISPLAY_NAMES: Record<string, string> = {
  "Arafat (Haj) Day":    "Day of Arafah",
  "Eid-ul-Adha":         "Eid al-Adha",
  "Islamic New Year":    "Islamic New Year (Muharram 1)",
  "Ashura":              "Ashura",
  "Mawlid al-Nabi":      "Mawlid al-Nabi (Prophet's Birthday)",
  "Al Isra' Wal Mi'raj": "Isra and Mi'raj (Night Journey)",
  "Start of Ramadan":    "First Day of Ramadan",
  "Laylat al Qadr":      "Laylat al-Qadr (Night of Power)",
  "Eid ul Fitr":         "Eid al-Fitr",
};
```

### 5.7 Multi-day detection

Eid al-Adha and Eid al-Fitr may appear across 2–3 consecutive days. Group consecutive days with the same normalized display name into a single event. Set `endDate` to the last day; `isMultiDay = true`.

### 5.8 Moon sighting caveat

Always display alongside Islamic events:
> *"Islamic dates are calculated using the Umm al-Qura method. Actual observance may vary by one day based on local moon sighting."*

### 5.9 Attribution

Display in UI: `"Islamic calendar data via AlAdhan.com"`
Link: https://aladhan.com

---

## 6. Christian Holidays -- TypeScript Algorithm

No external API. Fully client-side. Zero dependencies.

### 6.1 Western Easter (Gregorian Computus)

```typescript
function computeWesternEaster(year: number): Date {
  const a = year % 19;
  const b = Math.floor(year / 100);
  const c = year % 100;
  const d = Math.floor(b / 4);
  const e = b % 4;
  const f = Math.floor((b + 8) / 25);
  const g = Math.floor((b - f + 1) / 3);
  const h = (19 * a + b - d - g + 15) % 30;
  const i = Math.floor(c / 4);
  const k = c % 4;
  const l = (32 + 2 * e + 2 * i - h - k) % 7;
  const m = Math.floor((a + 11 * h + 22 * l) / 451);
  const month = Math.floor((h + l - 7 * m + 114) / 31);
  const day = ((h + l - 7 * m + 114) % 31) + 1;
  return new Date(year, month - 1, day);
}
```

**Validation:** 2026 → April 5 | 2027 → March 28

### 6.2 Orthodox Easter (Julian Computus + Gregorian offset)

```typescript
function computeOrthodoxEaster(year: number): Date {
  const a = year % 4;
  const b = year % 7;
  const c = year % 19;
  const d = (19 * c + 15) % 30;
  const e = (2 * a + 4 * b - d + 34) % 7;
  const f = Math.floor((d + e + 114) / 31);
  const g = ((d + e + 114) % 31) + 1;
  // Julian result; add 13 days for 20th/21st century Gregorian conversion
  const result = new Date(year, f - 1, g + 13);
  return result;
}
```

**Validation:** 2026 → April 12 | 2027 → May 2

### 6.3 Holiday generation

Generate from the two Easter anchors, preserving denomination labels and
stable event IDs. Read `references/computus.md` for the complete deterministic
implementation, feast inventory, and validation dates.

---

## 7. Event Description -- Wikipedia REST API

**No API key. Free. CC BY-SA 3.0. No external cost.**

### 7.1 Endpoint

```
GET https://en.wikipedia.org/api/rest_v1/page/summary/{article_title}
```

### 7.2 Fetch pattern

Fetch on user interaction only and cache by article title. Read
`references/api-reference.md` for the error-safe fetch pattern and
`references/holiday-data.md` for the complete article map. Do not pre-fetch
all descriptions on calendar load.

### 7.4 Attribution

Always display in UI: `"Description via Wikipedia (CC BY-SA 3.0)"` with link to the Wikipedia article URL returned by the API.

---

## 8. iCalendar (.ics) Generation

Generate client-side only. Preserve RFC 5545 all-day `DATE` semantics, use an
exclusive end date, escape content, and include a stable `UID`. Read
`references/ics-spec.md` for the full implementation and interoperability
requirements.

---

## 9. Session Caching Strategy

| Data | Cache key | When to populate | When to invalidate |
|---|---|---|---|
| Hebcal annual result | `are_hebcal_{year}` | On first tab open for that year | Session end |
| AlAdhan annual result | `are_aladhan_{year}` | On first tab open for that year | Session end |
| Christian holidays | In-memory (computed) | On tab open | Never (deterministic) |
| Wikipedia description | `are_wiki_{articleTitle}` | On first event click | Session end |

Use `sessionStorage` in browser contexts. In Node/agent contexts, use a simple in-memory `Map`.

---

## 10. Attribution Requirements

Always include the following when presenting output from this skill:

| Source | Attribution text |
|---|---|
| Hebcal | "Calendar data via Hebcal.com (CC BY 4.0)" |
| AlAdhan | "Islamic calendar data via AlAdhan.com" |
| Algorithm | "Christian holiday dates computed per ecclesiastical calendar" |
| Wikipedia | "Description via Wikipedia (CC BY-SA 3.0)" |

---

## 11. Validation Reference

| Holiday | Year | Correct Date |
|---|---|---|
| Western Easter | 2026 | April 5 |
| Western Easter | 2027 | March 28 |
| Orthodox Easter | 2026 | April 12 |
| Orthodox Easter | 2027 | May 2 |
| Ash Wednesday | 2026 | February 18 |
| Good Friday | 2026 | April 3 |
| Pentecost | 2026 | May 24 |
| Orthodox Christmas | any | January 7 |
| Theophany | any | January 19 |
| Rosh Hashanah | 2026 | September 20–21 |
| Yom Kippur | 2026 | September 29 |

---

## 12. Usage Examples

**Fetch all observances for 2026:**
```typescript
const [jewish, islamic] = await Promise.allSettled([
  fetchJewishHolidays(2026),
  fetchIslamicHolidays(2026),
]);
const christian = generateChristianHolidays(2026);

const allEvents: ObservanceEvent[] = [
  ...(jewish.status === 'fulfilled' ? jewish.value : []),
  ...(islamic.status === 'fulfilled' ? islamic.value : []),
  ...christian,
].sort((a, b) => a.startDate.getTime() - b.startDate.getTime());
```

**Get description for a holiday:**
```typescript
const description = await getHolidayDescription('Rosh Hashanah');
if (description) {
  console.log(description.extract);   // Wikipedia text
  console.log(description.wikiUrl);   // Attribution link
}
```

**Generate and download a full-year .ics:**
```typescript
const icsContent = generateICS(allEvents, 'ARE Observances 2026');
downloadICS(icsContent, 'ARE-Observances-2026.ics');
```

**Filter by tradition:**
```typescript
const jewishOnly = allEvents.filter(e => e.tradition === 'judaism');
const orthodoxOnly = allEvents.filter(e => e.denomination === 'orthodox');
```

---

## Validation script

A date-accuracy validation script ships with this skill:

```bash
node .agents/skills/okhp3-tradition-observance-calendar/scripts/validate-easter.js
```

Validates Western and Orthodox Easter computation against 11 known-correct dates each (US Naval Observatory / Ecumenical Patriarchate). Exit 0 = clean. Run after any change to the Computus algorithm.

---

## About

Built by [Jamie Hill](https://overkillhill.com) · [OverKill Hill P³](https://overkillhill.com)
Published at [github.com/OKHP3](https://github.com/OKHP3)
Part of the [OKHP3/skillz](https://github.com/OKHP3/skillz) Agent Skill library.
MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.