Floatboat iCalendar Automation Extension Specification

Languages / 语言: English · 简体中文

This English version is the authoritative (normative) specification. The translation is provided for convenience; in case of any discrepancy, the English text governs.

Field	Value
Document	`FB-ICAL-AUTO`
Specification version	0.2
Profile identifier	`calendar-event-extension` (`X-FLOATBOAT-PROFILE-VERSION:2`)
Document status	Draft Standard — not yet submitted for official Floatboat review
Date	2026-05-29
Base standards	RFC 5545 (iCalendar), RFC 9074 (VALARM Extensions)
Requirements input	Automation-task research (13 scenario and framework documents)
Language	English (authoritative); Chinese translation available

Abstract

This specification defines, on top of iCalendar [RFC5545], a set of extension properties prefixed with X-FLOATBOAT-, together with same-prefixed sub-properties carried inside the VALARM alarm component, to declare a standard calendar event (VEVENT) as one or more tasks executed automatically by an AI Agent at specified moments.

This specification uses only the extension point (x-prop) explicitly permitted by RFC 5545; it introduces no new top-level component. An ordinary calendar client MAY ignore all extension properties without affecting normal display of the event. The specification covers: reusable prompt templates and references, multi-stage (T−N / T+N) triggering bound to VALARM, handling of recurring events (including lunar and solar-term dates), declaration of input and output channels, execution modes and observability, character encoding, and security considerations.

This specification establishes that a .ics file is an export snapshot of a server-side source of truth; extension properties MAY be lost after a .ics is edited or synchronized by a calendar client, and a conforming implementation MUST NOT rely on the round-trip integrity of extension properties to preserve critical state.

Introduction
Terminology and Conventions
Architecture
Conformance
Property Definitions
Multi-Stage Triggering
Recurrence
Templating and Expansion
Execution Semantics
Encoding
Security Considerations
Interoperability and Client Compatibility
Versioning and Migration
References

Appendix A. Field Index
Appendix B. Examples
Appendix C. Change Log
Appendix D. Open Issues

1. Introduction

1.1 Background and Motivation

iCalendar [RFC5545] is the de facto standard for exchanging calendar data, but it only describes "when something happens", not "what should be done automatically when it does". In AI-Agent scenarios, a large class of tasks is naturally driven by dates or events (sports fixtures, holidays, statutory deadlines, project milestones, major life events). Their common structure is:

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

This specification provides a declarative, standards-legal, client-compatible representation for that structure, making a calendar event a portable carrier for an automation task.

1.2 Scope

This specification defines:

the syntax, semantics, location, and cardinality of the extension properties;
how multi-stage triggers bind to VALARM;
the template declaration and expansion algorithm;
recommendations for handling recurring (including non-Gregorian) events;
encoding, security, and interoperability requirements.

This specification does not define: the Agent engine's internal implementation, task-scheduling algorithms, credential management, or the transport protocol of any particular push channel. These are implementation details left to the consumer.

1.3 Design Principles

P1. Standards-legal: use only the x-prop extension point permitted by RFC 5545; invent no top-level component. P2. Lossless presentation: when a general calendar client ignores all extension properties, event display MUST be unaffected. P3. Separation of concerns: presentation, automation metadata, and the source of truth are kept in three layers (Section 3). P4. DRY: repeated prompts are declared once as a template and reused by reference with parameters. P5. Security first: a .ics is an exportable snapshot and MUST NOT carry secrets, credentials, personally identifiable information, or runtime state (Section 11).

2. Terminology and Conventions

2.1 Requirements Notation

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. In the Chinese translation these keywords remain in English and are authoritative in that form.

2.2 Definitions

Producer: the party that generates a .ics conforming to this specification (typically the Floatboat server-side exporter).
Consumer / Engine: the party that parses the extension properties and actually executes the automation tasks.
Source of Truth: the server-side store that holds the authoritative task configuration, credentials, and runtime state.
Presentation layer / Automation layer / Source of truth: see the three-layer data model in Section 3.1.
Stage: a single unit of automatic execution, with a definite trigger offset (T−N / T+N) relative to an event anchor; in this specification a stage is bound to one VALARM (Section 6).
Template: a reusable prompt text, declared at the calendar-component level, that contains placeholders.
Reference: an instantiation of a template at the event level or stage level, carrying variable values.
Objective: the natural-language task description handed to the Agent for a stage (or the whole event); it may be produced by expanding a template or given inline.
Placeholder: a marker of the form {{name}} (template variable) or {{VAR_NAME}} (server-injected variable).

2.3 Namespace and Prefix

Every extension property defined by this specification MUST be prefixed with X-FLOATBOAT-.
Stage-level sub-properties MUST appear only inside a VALARM component within a VEVENT (Section 6).
A producer MUST NOT use this prefix to carry semantics not defined in this specification or a later version of it, unless it is marked as a vendor-private experimental field using the second-level prefix X-FLOATBOAT-X-.
A consumer that encounters an unrecognized X-FLOATBOAT-* property SHOULD ignore it and continue processing (forward compatibility).

2.4 Referenced Base Components

This specification reuses the following standard iCalendar elements, whose syntax and semantics are governed by the base standards: VCALENDAR, VEVENT, VALARM, UID, DTSTART, DTEND, SUMMARY, DESCRIPTION, LOCATION, RRULE, RDATE, EXDATE, TRIGGER, ACTION, RELATED-TO.

3. Architecture

3.1 Three-Layer Data Model

A deployment conforming to this specification MUST conceptually distinguish the following three layers:

Layer	Carrier	Reader	Persistence
Presentation	Standard iCal properties: `SUMMARY` / `DTSTART` / `DESCRIPTION` / `VALARM`	Humans and calendar clients	Authoritative; MUST remain intact
Automation	`X-FLOATBOAT-*` properties (event-level and alarm-level)	Consumer / engine	Non-authoritative; MAY be stripped by clients
Source of Truth	Server-side store: credentials, runtime state, history	Engine	Sole authority

Normative constraints:

A producer MUST ensure that, even if the automation layer is removed entirely, the presentation layer still constitutes a legal and semantically complete iCalendar object.
A consumer MUST NOT keep "must-not-lose" state (e.g., execution history, credentials, last-run time) only in the automation layer; such data MUST be authoritative in the source of truth.
When a .ics that has been edited/synced by a client flows back missing the automation layer, the consumer SHOULD re-bind the task configuration from the source of truth using the event UID (Section 13).

3.2 Unified Automation-Task Model

An automation event MAY be composed of the following elements; of these, "explicit trigger" and "push output" are necessary conditions for an executable task:

Structured input — X-FLOATBOAT-INPUT-SOURCE / -INPUT-URI (Section 5.2.5).
Explicit trigger — time triggers are expressed as multi-stage VALARMs (Section 6); non-time triggers via X-FLOATBOAT-TRIGGER-TYPE / -TRIGGER-CONDITION; recurrence via RRULE and X-FLOATBOAT-RECUR-TYPE (Section 7).
Push output — X-FLOATBOAT-OUTPUT-CHANNEL / -OUTPUT-TARGET, with failure alerts carried separately by -ALERT-CHANNEL (Section 5.2.5).

4. Conformance

4.1 Conforming Producer

A conforming producer MUST:

emit a valid RFC 5545 document satisfying P2 (lossless presentation);
declare X-FLOATBOAT-EXPORT-SCHEMA and X-FLOATBOAT-PROFILE-VERSION on the VCALENDAR;
obey the syntax, cardinality, and encoding requirements of this specification for every X-FLOATBOAT-* property (Sections 5, 10);
write none of the content prohibited by Section 11 into any X-FLOATBOAT-* property.

4.2 Conforming Consumer

A conforming consumer MUST:

correctly handle line unfolding and character un-escaping (Section 10) before interpreting any property value;
implement the template-expansion algorithm of Section 8.2;
obey the execution-mode semantics of Section 9, in particular the gating of AUTONOMOUS;
ignore X-FLOATBOAT-* properties it does not recognize without aborting processing (Section 4.3).

4.3 Extensibility and Unknown Fields

The property set of this specification MAY be extended in later versions. A consumer MUST ignore unknown X-FLOATBOAT-* properties; a producer MUST NOT assume that a consumer recognizes fields above its PROFILE-VERSION.

5. Property Definitions

This section is the normative core. Each property states: location and cardinality, value, rules, and an example. Unless stated otherwise, all text values obey the escaping and folding rules of Section 10.

5.1 Calendar-Component Properties

Placed inside VCALENDAR, outside any VEVENT.

X-FLOATBOAT-EXPORT-SCHEMA

Location / cardinality: VCALENDAR, 1 (required of a conforming producer).
Value: the fixed string calendar-event-extension.
Rule: identifies the calendar as using the profile defined by this specification.

X-FLOATBOAT-PROFILE-VERSION

Location / cardinality: VCALENDAR, 1.
Value: a positive integer. The value for this specification is 2.
Rule: a consumer MUST use it to determine the available field set; on encountering a higher version it SHOULD degrade per Section 4.3.

X-FLOATBOAT-PROMPT-TEMPLATE

Location / cardinality: VCALENDAR, 0..n (distinguished by ID).
Parameters: ID (REQUIRED, unique template identifier, kebab-case recommended); VERSION (RECOMMENDED, positive integer); LANG (OPTIONAL, BCP 47 [RFC5646] language tag).
Value: the prompt body, which MAY contain placeholders of the form {{name}}; variable names are recommended to be snake_case.
Rule: multiple versions of the same ID MAY coexist. Templates are consumed by the reference-and-expansion mechanism of Section 8.

5.2 Event-Component Properties

Placed inside VEVENT.

5.2.1 Identity Properties (pass-through)

The following are engine-internal identifiers, MAY be opaque to a consumer, and SHOULD be preserved verbatim by a producer. Each has cardinality VEVENT 0..1.

Property	Value
`X-FLOATBOAT-PROVIDER-KIND`	Provider category, e.g. `floatboat_calendar`
`X-FLOATBOAT-EVENT-ID`	Internal event ID
`X-FLOATBOAT-BINDING-ID`	Binding ID
`X-FLOATBOAT-TASK-ID`	Associated automation-task ID

5.2.2 Core Control Properties

X-FLOATBOAT-EXECUTION-MODE

Location / cardinality: VEVENT 0..1; MAY also appear in a VALARM to override a single stage.
Value: READONLY | ASSIST | AUTONOMOUS (semantics in Section 9.1).
Rule: if omitted, a consumer MUST assume READONLY. When the value is AUTONOMOUS, a producer MUST also provide a non-empty X-FLOATBOAT-RETRY-POLICY, and a consumer SHOULD run a DRY-RUN:TRUE rehearsal before first activation.
Example: X-FLOATBOAT-EXECUTION-MODE:ASSIST

X-FLOATBOAT-AUTOMATION-STATUS

Location / cardinality: VEVENT 0..1.
Value: active | paused | archived.
Rule: if omitted, a consumer MUST assume active. When the value is not active, a consumer MUST NOT fire any stage.

X-FLOATBOAT-URGENCY

Location / cardinality: VEVENT 0..1.
Value: hard | soft.
Rule: if omitted, assume soft. hard indicates that a miss has irreversible consequences (e.g. statutory penalties); a consumer SHOULD enforce RETRY-POLICY and ALERT-CHANNEL for hard events.

5.2.3 Objective Declaration

X-FLOATBOAT-OBJECTIVE-REF

Location / cardinality: VEVENT 0..1; MAY also appear in a VALARM (stage objective, see 5.3).
Parameters: TEMPLATE (REQUIRED, the ID of the referenced template); VERSION (OPTIONAL, the expected template version).
Value: variable assignments of the form key1=value1,key2=value2 (encoding in Section 10.3).
Rule: if VERSION is declared and does not match an existing template, a consumer MUST choose one of reject / degrade / warn and SHOULD log it. Expansion is defined in Section 8.2.

X-FLOATBOAT-AUTOMATION-OBJECTIVE (legacy)

Location / cardinality: VEVENT 0..1.
Value: the fully expanded objective text.
Rule: retained for v0.1 compatibility. When both OBJECTIVE-REF and this property exist in the same component, a consumer MUST treat OBJECTIVE-REF as authoritative and this property as a derived cache. New producers SHOULD use OBJECTIVE-REF.

5.2.4 Trigger Properties

Time triggers MUST be expressed with the multi-stage VALARM of Section 6. The following properties are for non-time triggers:

X-FLOATBOAT-TRIGGER-TYPE

Location / cardinality: VEVENT 0..1. Value: TIME (default) | THRESHOLD | WEBHOOK | EVENT.
Rule: if omitted, assume TIME.

X-FLOATBOAT-TRIGGER-CONDITION

Location / cardinality: VEVENT 0..1. Value: a condition expression, e.g. PM25>75, INVENTORY_SKU_007<50.
Rule: REQUIRED when TRIGGER-TYPE is not TIME; the data source referenced by the expression MUST be declared via INPUT-*. The expression grammar is not standardized in this version (see Appendix D).

Legacy single trigger: X-FLOATBOAT-AUTOMATION-TRIGGER-ANCHOR (start | end) and X-FLOATBOAT-AUTOMATION-TRIGGER-OFFSET-SECONDS (integer seconds, negative = before the anchor). These are the v0.1 single-stage representation; a consumer MUST interpret them equivalently as a single stage with a TRIGGER;RELATED=<anchor> offset (Section 6). New producers SHOULD use VALARM stages.

5.2.5 Input / Output / Observability Properties

All located in VEVENT, cardinality 0..1; OUTPUT-CHANNEL, EXECUTION-MODE, etc. MAY be overridden per stage inside a VALARM.

Property	Value / example	Rule
`X-FLOATBOAT-INPUT-SOURCE`	`RSS`/`API`/`WEBHOOK`/`EMAIL`/`FORM`/`SENSOR`/`FILE`/`NONE`	Input entry-point category
`X-FLOATBOAT-INPUT-URI`	`https://rsshub.app/.../{{USER_ID}}`	MUST be in placeholder form; MUST NOT contain secrets/signatures (Section 11)
`X-FLOATBOAT-OUTPUT-CHANNEL`	`FEISHU,BARK,NOTION`	Comma-separated channel enumeration, at least one
`X-FLOATBOAT-OUTPUT-TARGET`	`feishu://chat/{{CHAT_ID}}`	Channel target; MUST be in placeholder form
`X-FLOATBOAT-ALERT-CHANNEL`	`BARK`	Dedicated failure-alert channel; SHOULD be separate from the business output channel
`X-FLOATBOAT-RETRY-POLICY`	`MAX=3;INTERVAL=5m;BACKOFF=exponential`	Structured retry policy; `;` inside the value MUST be escaped as `\;` per 10.1
`X-FLOATBOAT-TIMEOUT`	`PT10M`	Single-execution timeout, ISO 8601 Duration
`X-FLOATBOAT-DRY-RUN`	`TRUE` / `FALSE`	Rehearsal mode; first launch of `AUTONOMOUS` SHOULD be `TRUE`
`X-FLOATBOAT-ROLLBACK-HINT`	`NOTIFY_HUMAN` / `NOOP` / free text	Recovery guidance after failure

5.2.6 Recurrence Properties

Property	Value	Rule
`X-FLOATBOAT-RECUR-TYPE`	`GREGORIAN`/`LUNAR`/`JIEQI`/`WORKDAY_ADJUSTED`/`ONCE`	Recurrence-semantics category; realization in Section 7
`X-FLOATBOAT-LUNAR-RULE`	`MONTH=7;DAY=15;LEAP=false`	Lunar rule; `;` MUST be escaped
`X-FLOATBOAT-JIEQI`	`QINGMING`/`DONGZHI`/…	Solar-term identifier
`X-FLOATBOAT-RESCHEDULE-RULE`	`NEXT_WORKDAY`/`PREV_WORKDAY`/`NONE`	Shift policy when the date falls on a non-working day

5.3 Alarm-Component Properties (Stages)

A VALARM that carries the following properties is called a Floatboat Stage. Besides the properties of this specification, such a VALARM MUST also satisfy RFC 5545's requirements for VALARM (at minimum ACTION and TRIGGER); its semantics are given in Section 6.

X-FLOATBOAT-STAGE-ID

Location / cardinality: VALARM 1 (mandatory for any Floatboat stage).
Value: a stable identifier unique within the enclosing VEVENT, e.g. t-14, t+1.
Rule: a consumer MUST use it to identify stage identity (for idempotency, retry, and de-duplication), and MUST NOT rely on a stage's relative position in the file as its identity.

X-FLOATBOAT-STAGE-ACTION

Location / cardinality: VALARM 0..1.
Value (recommended set, open in this version): checklist | comparison_table | draft_content | reminder | report | scrape | purchase_order.
Rule: lets the consumer choose a deliverable shape; an unknown value SHOULD be handled as a generic task.

Stage objective: each stage MUST provide exactly one of X-FLOATBOAT-OBJECTIVE-REF (syntax as in 5.2.3) or X-FLOATBOAT-OBJECTIVE (inline text).

Stage-level overrides: X-FLOATBOAT-OUTPUT-CHANNEL, X-FLOATBOAT-OUTPUT-TARGET, and X-FLOATBOAT-EXECUTION-MODE MAY appear inside a VALARM, overriding the same-named event-level property for that stage only.

6. Multi-Stage Triggering

6.1 Dual-Track Binding (normative)

Time-driven automation is organized into stages. A conforming implementation MUST follow dual-track binding:

Track A (visible to humans / clients): each stage MUST be represented as a VALARM containing ACTION:DISPLAY and TRIGGER, and SHOULD contain a human-readable DESCRIPTION. This lets general clients display a reminder.
Track B (authoritative for the engine): a stage's machine-readable metadata is carried by the X-FLOATBOAT-* sub-properties inside the VALARM, which a consumer MUST treat as authoritative.

A consumer MUST NOT rely on the survival of a VALARM or its sub-properties after a round trip through a third-party client; the source of truth MUST hold the complete stage list (Section 3.1), and the stages in a .ics are regarded as its exported projection.

6.2 Offset and Anchor

A stage's firing time MUST be expressed by the VALARM's TRIGGER. A relative trigger MUST use the RELATED=START or RELATED=END parameter together with an ISO 8601 Duration value.
A negative value means before the anchor (T−N); a positive value means after the anchor (T+N). Examples: TRIGGER;RELATED=START:-P14D (14 days before start), TRIGGER;RELATED=START:P1D (1 day after start), TRIGGER;RELATED=START:PT0S (at the anchor moment).
An absolute trigger MAY use a TRIGGER in VALUE=DATE-TIME form.

6.3 Stage Identity and Linking

Each stage VALARM SHOULD carry a UID (RFC 9074), to support stable references and acknowledgement (ACKNOWLEDGED) across synchronization.
Stage execution order is determined by the resolved instant of each TRIGGER; this specification defines no stage dependency beyond temporal order (see Appendix D).

7. Recurrence

7.1 Gregorian Recurrence

Gregorian cycles MUST be expressed with native RRULE / RDATE / EXDATE, and SHOULD set X-FLOATBOAT-RECUR-TYPE:GREGORIAN.

7.2 Lunar and Solar-Term Dates

iCalendar has no concept of lunar or solar-term dates. For lunar or solar-term recurrence:

a producer MUST pre-compute the concrete Gregorian dates within a bounded horizon and materialize them as RDATE;VALUE=DATE:…, so that all clients can display them;
a producer SHOULD retain X-FLOATBOAT-LUNAR-RULE or X-FLOATBOAT-JIEQI for later re-expansion;
a producer MAY attach RFC 7529 RSCALE as a semantic annotation, but MUST NOT rely on clients expanding it (support is extremely low).

7.3 Working-Day Adjustment

RRULE has no holiday awareness. For an event that "shifts when it falls on a non-working day", a producer MUST materialize the resolved dates with RDATE/EXDATE after pre-computation, or the consumer computes them at trigger time per X-FLOATBOAT-RESCHEDULE-RULE.

7.4 Re-computation Responsibility

For LUNAR / JIEQI / WORKDAY_ADJUSTED events, a producer SHOULD periodically re-expand and re-export the .ics to extend the pre-computation window. This re-computation is a server-side responsibility and is not borne by the calendar client.

8. Templating and Expansion

8.1 Declaration and Reference

A template is declared at the calendar-component level by X-FLOATBOAT-PROMPT-TEMPLATE (Section 5.1) and referenced at the event or stage level by X-FLOATBOAT-OBJECTIVE-REF (Section 5.2.3). The template mechanism is pure string substitution and MUST NOT contain conditionals, loops, or macros.

8.2 Expansion Algorithm (normative)

A consumer MUST obtain the final objective text, before firing a task, by the following steps:

Parse the VCALENDAR per RFC 5545: first unfold lines (Section 10.2), then un-escape TEXT values (Section 10.1).
Collect all X-FLOATBOAT-PROMPT-TEMPLATEs, index them by ID, recording the body and VERSION/LANG.
For each objective-bearing point (the event-level objective, and each stage VALARM): a. If X-FLOATBOAT-OBJECTIVE-REF is present: i. Take the template body for its TEMPLATE; if VERSION is declared and does not match the index, handle per the rule in 5.2.3. ii. Parse the reference value into an ordered list of key=value pairs (split on unescaped ,, then on the first =), and decode per Section 10.3. iii. For each {{key}} placeholder in the template body, perform a global literal substitution with the corresponding value. b. Else if an inline objective is present (stage X-FLOATBOAT-OBJECTIVE or event X-FLOATBOAT-AUTOMATION-OBJECTIVE): use it verbatim. c. Else: the bearing point has no objective, and a consumer MUST treat it as having no task (skip or error per policy).
If any unresolved {{…}} placeholder remains after expansion, a consumer MUST report it as an error and SHOULD NOT execute the task with unresolved placeholders.
Inject the final objective, together with the trigger offset, input, output channels, and execution mode, into the task context.

8.3 Version Matching

A reference MAY lock a template version via VERSION. When a producer changes a template's semantics it SHOULD increment VERSION; renaming a placeholder is a breaking change and SHOULD use a new template ID rather than an in-place rename (Section 13).

9. Execution Semantics

9.1 Execution Modes

Mode	Semantics	Side effects
`READONLY`	Reads data and produces reports/summaries only; executes directly	No write side effects
`ASSIST`	Produces a result but stores it as a draft/to-do, requiring human review before publishing	Writes only to a draft area
`AUTONOMOUS`	May perform side-effecting writes (write to DB, send messages, call external APIs)	Real side effects

Gating requirements:

When EXECUTION-MODE is omitted, a consumer MUST execute as READONLY.
A consumer MUST NOT execute side-effecting operations as AUTONOMOUS without a non-empty X-FLOATBOAT-RETRY-POLICY.
A stage-level EXECUTION-MODE overrides the event level and applies to that stage only.

9.2 Observability and Recoverability

A consumer SHOULD send failure alerts via X-FLOATBOAT-ALERT-CHANNEL, and this channel SHOULD be independent of the business output channel, to avoid silent failures caused by an outage of the primary channel.
A consumer SHOULD honor X-FLOATBOAT-RETRY-POLICY and X-FLOATBOAT-TIMEOUT; after exhausting retries it MUST raise an alert rather than fail silently.
When X-FLOATBOAT-DRY-RUN:TRUE, a consumer MUST NOT produce any externally visible side effect and produces only a rehearsal result.

10. Encoding

10.1 Character Escaping

Text values of X-FLOATBOAT-* are escaped per the TEXT rules of RFC 5545 §3.3.11:

Original character	Escaped as
`\` (backslash)	`\\`
`,` (ASCII comma)	`\,`
`;` (ASCII semicolon)	`\;`
newline	`\n` (the two literal characters)

Note: full-width punctuation (， ； 。) are ordinary characters and MUST NOT be escaped. A producer SHOULD use the same punctuation in the template body as in the original objective; otherwise the expanded result will not match the original. An exception is given in Section 10.3 (the structural delimiters of OBJECTIVE-REF).

10.2 Line Folding

A content line whose UTF-8 length exceeds 75 octets MUST be folded.
Folding MUST insert a CRLF at a suitable point in the content line and begin the continuation line with a single SPACE or TAB; unfolding removes that "CRLF + whitespace" sequence.
Folding MUST NOT split a multi-octet UTF-8 sequence; the fold point MUST fall on a Unicode code-point boundary.
Chinese characters are three octets each, so the limit is reached after about 25 characters.

10.3 Reference-Value Encoding (mini-format)

The value of X-FLOATBOAT-OBJECTIVE-REF uses the key=value(,key=value)* mini-format, in which , and = are structural delimiters written as literal characters (the comma-escaping of 10.1 is not applied to them). If a value itself needs to contain a literal ,, =, or ;, a producer MUST percent-encode it per RFC 3986 (%2C / %3D / %3B), and a consumer MUST decode it after parsing in step 8.2.

In other structured values that use ; as an internal delimiter (such as RETRY-POLICY, LUNAR-RULE), the ; is an ordinary TEXT character and MUST be escaped as \; per 10.1.

11. Security Considerations

A .ics file is frequently exported, shared via email/links, cached or indexed by third-party services, and backed up with the device. Therefore:

The following content MUST NOT appear in any X-FLOATBOAT-* property:

Category	Example	Correct approach
Keys / tokens / secrets	Bot Token, Device Key, PAT, Bearer	Store in a server-side credential vault; the `.ics` holds only a variable name
Webhook URLs containing signatures	`https://hooks.example.com/x/y/z`	`OUTPUT-TARGET:webhook://{{HOOK_ID}}`
Personally identifiable information (PII)	Phone number, ID number, plaintext email	Placeholder `{{USER_PHONE}}`, real value on the server
Runtime state	Last-run time, error stack, execution history	Store in the source of truth; do not write back to the `.ics`
Environment / intranet configuration	DB connection string, intranet address	Server-side configuration

Additional requirements:

INPUT-URI, OUTPUT-TARGET, etc. MUST use the {{VAR_NAME}} placeholder form; the real values are injected by the consumer on the server.
A consumer MUST NOT trust the automation layer in a .ics to be complete or untampered; critical configuration MUST be authoritative in the source of truth and SHOULD be re-bound by event UID (Sections 3.1, 13).
Because AUTONOMOUS mode can produce irreversible side effects, a consumer MUST apply the gating of Section 9.1 and SHOULD require out-of-band authorization for such events.

12. Interoperability and Client Compatibility

12.1 Survival of Extension Properties and Custom VALARMs (informative)

Client	Read-only import	After user edit & save	CalDAV round trip	Multiple VALARMs	X-prop inside VALARM
Apple Calendar	Mostly retained	Usually retained	Survives if server unchanged	Supported	Mostly retained
Google Calendar	Easily drops non-standard X-prop	High chance of loss	Does not retain non-standard X-prop	May truncate	Dropped
Outlook (Win/365)	Version-dependent	Dropped on export	No native CalDAV	Only the first is honored	Dropped
Thunderbird	Generally retained	Risk of loss	Known VALARM sync defects	Supported	Not guaranteed
Fastmail	Stored verbatim	Depends on client write-back	Passed through by server	Supported	Passed through

Conclusion: extension properties survive a read-only import reasonably well, but reliability is low after "edit & save" and after a CalDAV round trip via Google/Outlook. This is the direct rationale for Section 3.1 (source of truth on the server, re-bind by UID) and Section 6.1 (the engine does not depend on VALARM survival).

12.2 Relationship to JSCalendar (informative)

JSCalendar [RFC8984] is the JSON representation of iCalendar. Its alert model is more structured (OffsetTrigger with relativeTo/offset, a built-in acknowledged), and its extensions use domain-name prefixes rather than X-. It is recommended that an implementation use a JSCalendar-style JSON as the internal authoritative representation, while exporting the .ics of this specification for external interchange; until native client support for JSCalendar matures, it is not recommended as the primary export format.

13. Versioning and Migration

Scenario	Requirement
Reword a prompt (semantics unchanged)	Same `ID`, increment `VERSION`
Rename a placeholder	Breaking change; SHOULD use a new `ID`
Deprecate an old template	Retain the body; events no longer reference it
v0.1 → v0.2	A consumer MUST read legacy single triggers and `AUTOMATION-OBJECTIVE` compatibly; on export a producer SHOULD rewrite them as `VALARM` stages and `OBJECTIVE-REF`, and set `PROFILE-VERSION:2`
Client edit flow-back	Re-bind from the source of truth by `UID`; a missing automation layer MUST be reconstructed from the source of truth

14. References

14.1 Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, 1997.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, 2017.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, 2009.
[RFC9074] Daboo, C., et al., "VALARM Extensions for iCalendar", RFC 9074, 2021.
[RFC5646] Phillips, A., Davis, M., "Tags for Identifying Languages", BCP 47, RFC 5646, 2009.
[RFC3986] Berners-Lee, T., et al., "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, 2005.
[ISO8601] ISO 8601, "Date and time — Representations for information interchange".

14.2 Informative References

[RFC7529] Daboo, C., Lemonnier, G., "Non-Gregorian Recurrence Rules in iCalendar", RFC 7529, 2015.
[RFC8984] Jenkins, N., Stepanek, R., "JSCalendar: A JSON Representation of Calendar Data", RFC 8984, 2021.
[RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", RFC 5546, 2009.
[AOE-RESEARCH] Automation-task research (13 scenario and framework documents), 2026.

Appendix A. Field Index

All prefixed with X-FLOATBOAT-.

Calendar-level: EXPORT-SCHEMA, PROFILE-VERSION, PROMPT-TEMPLATE
Event-level — identity: PROVIDER-KIND, EVENT-ID, BINDING-ID, TASK-ID
Event-level — control: EXECUTION-MODE, AUTOMATION-STATUS, URGENCY
Event-level — objective: OBJECTIVE-REF, AUTOMATION-OBJECTIVE (legacy)
Event-level — trigger: TRIGGER-TYPE, TRIGGER-CONDITION, AUTOMATION-TRIGGER-ANCHOR (legacy), AUTOMATION-TRIGGER-OFFSET-SECONDS (legacy)
Event-level — I/O & observability: INPUT-SOURCE, INPUT-URI, OUTPUT-CHANNEL, OUTPUT-TARGET, ALERT-CHANNEL, RETRY-POLICY, TIMEOUT, DRY-RUN, ROLLBACK-HINT
Event-level — recurrence: RECUR-TYPE, LUNAR-RULE, JIEQI, RESCHEDULE-RULE
Stage-level (inside VALARM): STAGE-ID, STAGE-ACTION, OBJECTIVE-REF/OBJECTIVE, OUTPUT-CHANNEL/OUTPUT-TARGET (override), EXECUTION-MODE (override)

Appendix B. Examples

File	Description
`examples/before.ics`	Original expanded form (2 events, single trigger, inline objective)
`examples/after.ics`	Template-DRY rewrite, byte-for-byte equivalent to `before.ics`
`examples/multi-stage.ics`	Multi-stage `VALARM` + output channels + execution modes + recurrence (product launch, T−14 → T+1)
`tools/build_examples.py`	Generates the above examples and runs the equivalence regression (`after` expands == `before` objective)

Appendix C. Change Log

0.2 (2026-05-29): added multi-stage VALARM triggering, TRIGGER-TYPE, recurrence (RECUR-TYPE/lunar/solar-term/working-day adjustment), the input/output and observability property families, URGENCY, standardized execution modes, the Security Considerations section, and the relationship to JSCalendar; fixed the emoji/punctuation/folding equivalence of the examples; upgraded the document form to a specification standard.
0.1: first version, defining PROMPT-TEMPLATE and OBJECTIVE-REF, single trigger, and the compatibility matrix.

Appendix D. Open Issues

Whether STAGE-ACTION should be frozen into a closed enumeration.
Standardization of the TRIGGER-CONDITION expression grammar.
Whether stage dependencies beyond temporal order (task chains) should be in scope.
Whether to provide an official JSCalendar export.
Final alignment of names with Floatboat's internal schema.

FilesExpand file tree

SPEC.md

Latest commit

History