Floatboat iCalendar Automation Extension

Languages / 语言: English · 简体中文

FB-ICAL-AUTO

A set of X-FLOATBOAT-* extension properties layered on top of standard iCalendar (RFC 5545) that turn a calendar event into a sequence of AI-Agent tasks executed automatically at the right moments — without breaking display in any ordinary calendar client.

Version 0.2 · Status: Draft Standard · Profile: calendar-event-extension · Base: RFC 5545 / RFC 9074

---

What it is

iCalendar describes when something happens, not what should be done automatically when it does. This extension adds the latter: it makes a calendar event a portable carrier for an automation task, expressing the recurring skeleton found across real-world automation:

a date / event  →  count back into T−N / T+N stages  →  per-stage deliverables  →  push channels

Ordinary clients that ignore all extension properties still display the event correctly; only the Floatboat engine reads and executes them.

Repository layout

Path	Contents
SPEC.md	The specification (normative, authoritative): terminology, property definitions, triggering / recurrence / expansion / execution / security
SPEC.zh-CN.md	Chinese translation of the specification
examples/before.ics	Original expanded form (single trigger, inline objective)
examples/after.ics	Template-DRY rewrite, byte-for-byte equivalent to before.ics
examples/multi-stage.ics	Multi-stage VALARM example: a product launch, T−14 → T+1
tools/build_examples.py	Generates the examples and runs the equivalence regression test
CLAUDE.md	Repo development / pitfall conventions

Normative content lives in SPEC.md; this README is only a guide.

Quick start

# Regenerate examples and verify after.ics expands byte-for-byte to before.ics
uv run --no-project tools/build_examples.py

Expected output: each event prints [PASS], the run ends with an "all equivalent" summary, and no content line exceeds 75 octets.

Design highlights

• Three-layer separation — Presentation (standard iCal) / Automation (X-FLOATBOAT-*) / Source of Truth (server). The .ics is an export snapshot, not a database.
• Multi-stage triggering, dual-track binding — each T−N/T+N stage is a native VALARM (a client-visible reminder); stage metadata rides in X-* inside the VALARM (authoritative for the engine). The engine never depends on extension survival in clients.
• Recurrence incl. non-Gregorian — Gregorian uses RRULE; lunar and solar-term dates cannot be expressed natively, so the engine pre-computes them into RDATE while X-* preserves the semantics.
• The three essentials of automation — input (INPUT-*) / trigger / output (OUTPUT-CHANNEL), plus a separate failure ALERT-CHANNEL and observability (RETRY / DRY-RUN / TIMEOUT).
• Tiered execution modes — READONLY / ASSIST / AUTONOMOUS; the last is gated by default (explicit declaration + non-empty retry policy required).
• Security boundary (hard constraint) — secrets, signed webhook URLs, PII and runtime state never go into .ics; use {{placeholders}} with real values on the server; events are re-bound by UID after client edits.
• Standards-legal + backward-compatible — only RFC 5545-sanctioned x-prop; the v0.1 single trigger and AUTOMATION-OBJECTIVE are retained.

Compatibility & security (read SPEC §11–§12 first)

Extension properties survive a read-only import reasonably well, but reliability drops sharply after editing in Google/Outlook or round-tripping through CalDAV. Therefore the source of truth must live on the server and the .ics is only a snapshot. No secret may ever be written into a .ics.

Roadmap (see SPEC Appendix D)

• Reverse compressor: expanded form → auto-extract templates, emit multi-stage after
• Real-client compatibility testing; fill in the survival matrix
• Standardize the TRIGGER-CONDITION expression grammar
• Official JSCalendar (RFC 8984) export
• Finalize after aligning names with Floatboat's internal schema

Status

This is an independent draft, not yet submitted for official Floatboat review; field names are organized from the existing X-FLOATBOAT-* private schema. Implementations and feedback are welcome.