Calendar.md Specification

An open standard for human-readable, agent-modifiable calendars using Markdown and Event Sourcing.

About

Calendar.md is a lightweight calendar/schedule specification for agents, combining an append-only log with generated monthly views for clear human reading and reliable automation.

Overview

This project defines a file format and interaction protocol for maintaining calendars in a Git repository. It is designed to be:

1. Human-Friendly: Visualized using markdown-it-calendar syntax in monthly files.
2. Agent-Friendly: Structured as an append-only log of events, ensuring every change is traceable and reproducible.
3. Conflict-Resilient: Modifications are log-based, minimizing merge conflicts.

Documentation

• Specification (SPEC.md): The core technical specification.
• Agent Tooling (AGENT_TOOLING.md): Optional reference interface (Protocol) for agent interactions.
• Schemas: JSON Schemas for validation.

Ecosystem Fit

Calendar.md is recommended to work alongside AGENTS.md/SOUL.md and Agent Skills as a complementary trio for building complete personal assistant workflows.

License

This project is licensed under the MIT License.

Example Structure

Check the examples/ directory for a reference implementation:

examples/
├── .calendar/
│   └── logs/
│       └── 2024/
│           └── 01.log   <-- Source of Truth (Append-only)
└── calendar/
    └── 2024/
        ├── 01.md        <-- Generated View (Do not edit)
        └── 02.md        <-- Generated View (Do not edit)

Usage

1. Modifying the Calendar (Agents & Humans)

To add or update an event, append a new line to .calendar/logs/YYYY/MM.log following the Log Format.

TIMESTAMP | ACTOR | ACTION | PAYLOAD

2. Generating the View

To update the view, you need a script that parses the log and generates the markdown files. A reference implementation is available in the separate calendar-skills project.

Acknowledgements

Special thanks to markdown-it-calendar for the inspiring calendar syntax and initial implementation concept.