Time

time

Use temporal to anchor work at NOW and place events as spatial distances (ahead/behind) for reliable temporal reasoning.

Ego-Moving Metaphor (Required)

Use one frame only: you move forward through time. Future is ahead of you. Past is behind you. Correct: "We are approaching the deadline." Incorrect: "The deadline is approaching."

Prerequisites

temporal must be on your $PATH. If temporal is not on $PATH, run scripts/install.sh from the skill directory. scripts/install.sh auto-detects OS/arch, verifies SHA-256 checksums from values bundled in the installer (not from the release checksums file), and installs to /usr/local/bin/temporal when writable or ~/.local/bin/temporal otherwise. Installer defaults to v0.1.0. You can override version/install dir with TEMPORAL_VERSION and TEMPORAL_INSTALL_DIR. For versions without a bundled checksum, set TEMPORAL_SHA256 to an independently obtained digest. Ensure ~/.local/bin is on your $PATH (for example, export PATH="$HOME/.local/bin:$PATH" in your shell profile). Note: The OS-specific curl examples below install binaries without checksum verification; prefer scripts/install.sh when possible. Install (macOS Apple Silicon): mkdir -p ~/.local/bin && curl -L https://github.com/Ikana/temporal/releases/latest/download/temporal-darwin-arm64 -o ~/.local/bin/temporal && chmod +x ~/.local/bin/temporal Install (macOS Intel): mkdir -p ~/.local/bin && curl -L https://github.com/Ikana/temporal/releases/latest/download/temporal-darwin-x64 -o ~/.local/bin/temporal && chmod +x ~/.local/bin/temporal Install (Linux x64): mkdir -p ~/.local/bin && curl -L https://github.com/Ikana/temporal/releases/latest/download/temporal-linux-x64 -o ~/.local/bin/temporal && chmod +x ~/.local/bin/temporal Install (Linux ARM64): mkdir -p ~/.local/bin && curl -L https://github.com/Ikana/temporal/releases/latest/download/temporal-linux-arm64 -o ~/.local/bin/temporal && chmod +x ~/.local/bin/temporal Install a custom version with explicit checksum: TEMPORAL_VERSION=v0.1.1 TEMPORAL_SHA256=<sha256> ./scripts/install.sh Install/build instructions: github.com/Ikana/temporal

Quick Start

temporal init temporal add "Sprint review" --on "2026-02-21" --type ceremony temporal add "v0.3.0 deadline" --in "13 days" --type milestone --notes "new auth flow" temporal show

init [--timezone <iana_tz>] [--force]

Create time.md with NOW as the anchor. Use --force to overwrite an existing file.

now [--timezone <iana_tz>]

Update only the NOW section timestamp metadata. Does not recalculate event distances.

add <event> (--in <duration> | --on <date> | --at <datetime>) [--type <type>] [--notes <text>]

Add one event with exactly one time selector: --in: relative duration ("3 days", "in 4 hours", "2 days ago") --on: date input ("2026-03-01", "tomorrow", "next Monday") --at: ISO datetime ("2026-02-20T14:00:00Z")

show

Print full time.md to stdout.

past

Print NOW + the Behind (Past) timeline section.

ahead

Print NOW + the Ahead (Future) timeline section.

refresh

Move NOW to current time and recalculate all event distances/order.

remove <event>

Remove an event from timeline and sequences.

seq <name> <event1> <event2> [event3...]

Create/update a named sequence chain.

span <name> --from <when> --to <when>

Create/update a named duration span. --from must be before --to.

Annotated time.md Format

• # Time Context
• ## Now
• **timestamp**: 2026-02-19T09:00:00.000Z <!-- anchor -->
• **weekday**: Thursday
• **week**: 8 of 52
• **quarter**: Q1 2026
• **timezone**: Europe/Amsterdam
• ## Timeline
• ### Behind (Past)
• | distance | event | type | notes | iso |
• |----------|-------|------|-------|-----|
• | 1 day behind | bug #42 reported | issue | auth timeout | 2026-02-18T10:00:00.000Z |
• ### Ahead (Future)
• | distance | event | type | notes | iso |
• |----------|-------|------|-------|-----|
• | 2 days ahead | sprint review | ceremony | demo v0.2.1 | 2026-02-21T14:00:00.000Z |
• ## Sequences
• ### release-cycle
• v0.2.0 released → bug #42 reported → [NOW] → sprint review → v0.3.0 deadline
• ## Durations
• | span | from | to | length |
• |------|------|----|--------|
• | current sprint | 5 days behind | 2 days ahead | 7 days |

Scratch Pad Pattern (/tmp)

Use this for one-shot reasoning so project files stay clean: cd /tmp temporal init --force temporal add "Draft due" --on "2026-02-25" temporal add "Client review" --in "3 days" temporal show # draft your output using the timeline rm -f time.md

Sequences

Use sequences to express ordered chains for planning: temporal seq "release-cycle" "RFC drafted" "Implementation starts" "Testing" "Launch" show places [NOW] at the correct position relative to sequence events.

Spans

Use spans for time windows: temporal span "Sprint 12" --from "2026-02-17" --to "2026-02-28" The Durations table shows from/to distances and total length.

Key Rules

Run temporal refresh before reading time.md when it may be stale. Event names must be unique; remove before re-adding the same name. Markdown timeline output is written to stdout. Errors/warnings are written to stderr. temporal is fully non-interactive (no prompts).