Trip File Format

Each trip is stored as a YAML file in Trip Files. This defines the canonical structure.

Root Structure

trip:
  name: "Display name for the trip"
  destination: "City, Country or Region"
  dates:
    start: 2025-03-15  # ISO date
    end: 2025-03-22
  status: upcoming  # upcoming | in-progress | completed

itinerary: []    # Daily schedule
bookings: {}     # Reservations and confirmations
budget: {}       # Expense tracking
documents: {}    # Notes and important info

Itinerary

Organized by date, each day contains timed entries:

itinerary:
  - date: 2025-03-15
    entries:
      - time: "09:00"
        activity: "What's happening"
        location: "Where"
        type: travel        # travel | accommodation | food | activity | meeting | other
        status: planned     # planned | completed | skipped
        notes: "Optional details"
        duration: "2h"      # Optional expected/actual duration

Entry types help organize the itinerary: travel for flights/trains/transfers, accommodation for check-in/out, food for meals and reservations, activity for tours/sights/experiences, meeting for business or social appointments.

Status meanings: planned is the default for future items, completed when done (agent logs actual time/notes), skipped if cancelled or didn't happen.

Bookings

Track all reservations with confirmation details:

bookings:
  flights:
    - flight: "AA123"
      route: "JFK → CDG"
      datetime: 2025-03-15T09:00
      confirmation: "ABC123"
      notes: "Window seat 12A"
  hotels:
    - name: "Hotel Le Marais"
      address: "15 Rue de Rivoli, Paris"
      checkin: 2025-03-15
      checkout: 2025-03-22
      confirmation: "HLM789"
      notes: "Late checkout requested"
  reservations:
    - name: "Dinner at Le Comptoir"
      datetime: 2025-03-16T19:30
      party_size: 2
      confirmation: "LC456"
  other:
    - type: "Car rental"
      provider: "Hertz"
      pickup: 2025-03-18T10:00
      dropoff: 2025-03-20T10:00
      confirmation: "HZ789"

Budget

Track planned budget and actual expenses:

budget:
  currency: EUR
  planned: 2500
  expenses:
    - date: 2025-03-15
      item: "Airport taxi"
      amount: 45
      category: transport  # transport | food | accommodation | activity | shopping | other
    - date: 2025-03-15
      item: "Dinner at bistro"
      amount: 85
      category: food

Categories help summarize spending: transport (flights, trains, taxis, rentals), food (meals, drinks, groceries), accommodation (hotels, not in booking cost), activity (tickets, tours, experiences), shopping (souvenirs, purchases), other (tips, misc).

Documents

Store important information and notes:

documents:
  emergency_contacts:
    - name: "US Embassy Paris"
      phone: "+33 1 43 12 22 22"
    - name: "Hotel"
      phone: "+33 1 42 78 47 39"
  notes: |
    Passport in hotel safe
    Metro pass in wallet
    Restaurant reservations confirmed via email
  packing_notes: "Pack adapter, umbrella"

File Naming

Trip files are named with a slug: lowercase, hyphenated, descriptive.

Good examples: paris-march-2025.yaml, japan-honeymoon.yaml, nyc-conference-q2.yaml, italy-family-trip.yaml

The slug should make the trip identifiable at a glance. Include destination and a distinguishing element (date, purpose, or occasion).

Status Transitions

• upcoming: Trip is planned but hasn't started. Default for new trips.
• in-progress: User is currently on this trip. Only one trip should be in-progress at a time.
• completed: Trip is finished. Archive state for reference.

Transition to in-progress when user says they're starting or when the start date arrives and user interacts. Transition to completed when user says they're done or asks to wrap up the trip.