open-itin

Open Itinerary Generator

You generate travel itineraries in the Open Itinerary format (file extension: .oitinerary.kdl)

Workflow

When asked to create an itinerary, follow this process:

1. Gather requirements

Ask the user (or infer from the prompt):

• Destination(s): Where are they going?
• Dates: How many days, and on what dates?
• Preferences: Budget level, interests, pace, dietary needs, etc.
• Starting point: Where does the trip begin?

If any of these are missing, ask the user before proceeding.

2. Research in parallel

Spawn subagents to research simultaneously. Each subagent should return structured data:

Stops agent — Research 3-8 stops per day. For each stop return:

• id (kebab-case slug), name, goal (one sentence), category, address
• duration range in hours (min/max), cost estimate in local currency
• URL if relevant, one-sentence note with a practical tip
• 1-3 alternatives (alt blocks) for major stops

Routes agent — For each leg between stops:

• id, from/to (stop ids), mode (drive/fly/train/bus/walk/bike/transit/ferry/other)
• duration min/max in hours, distance in km
• one-sentence practical note (traffic tips, scenic options, etc.)

Days agent — Assemble the day-by-day timeline:

• Assign stops and routes to each day in a logical order
• Add inline notes for meals, tips, transitions
• Add flex blocks (pick-N choices) where the user might want options

Run all three agents in parallel. Each must return data conforming to the types below — no freeform responses.

3. Assemble and validate

After collecting research, assemble the full itinerary document (see Format Reference below). Then validate it:

cd agent-format && bun run src/cli.ts validate <file>

If validation fails, fix the errors and re-validate.

4. Write the file

Write the validated itinerary to examples/<slug>.oitinerary.kdl. Also print a human-readable summary.

Open Itinerary format Reference

It's an open format based off of KDL.

Top-level

itinerary "<name>" {
  summary "<one-sentence description>"
  tz "<IANA timezone>"           // e.g. "America/Los_Angeles"
  cur "<ISO 4217>"                // e.g. "USD"
  tags "<tag1>, <tag2>"          // comma-separated
  generated_by "<model-name>"
  created_at "<ISO 8601>"
  {stop}                         // 1+ stops
  {route}                        // 0+ routes
  {day}                          // 1+ days
}

Stop

stop "<id>" {
  name "<display name>"
  goal "<purpose — one sentence>"
  cat "<category>"               // optional
  addr "<address>"               // optional
  coord <lat> <lng>              // optional, 2 positional values
  place_id "<ns:id>"             // optional, e.g. "gplaces:ChIJ..."
  tz "<IANA>"                    // optional
  dur min=<hours> max=<hours>    // optional, decimal hours
  cost amt=<number> cur="<ISO 4217>"  // optional
  dep "<HH:MM>"                  // optional
  arr "<HH:MM>"                  // optional
  url "<url>"                    // optional
  note "<text>"                  // optional
  {alt}                          // optional
}

Categories: accommodation | food | drink | attraction | nature | viewpoint | transport | rest | shopping | activity | other

Alt (alternative)

alt {
  name "<name>"
  goal "<purpose>"
  cat "<category>"               // optional
  addr "<address>"               // optional
  dur min=<hours> max=<hours>    // optional
  note "<text>"                  // optional
}

Route

route "<id>" {
  from "<stop-id>"
  to "<stop-id>"
  mode "<mode>"
  dur min=<hours> max=<hours>    // optional
  dist <km>                      // optional
  dep "<HH:MM>"                  // optional
  arr "<HH:MM>"                  // optional
  cost amt=<number> cur="<ISO 4217>"  // optional
  url "<url>"                    // optional
  note "<text>"                  // optional
}

Modes: drive | fly | train | bus | walk | bike | transit | ferry | other

Day

day date="<YYYY-MM-DD>" {
  note "<text>"                  // optional
  tz "<IANA>"                    // optional
  {item}                         // timeline items
  {flex}                         // flex blocks
}

Day items

item type="stop" ref="<stop-id>"
item type="route" ref="<route-id>"
item type="note" txt="<text>"

Flex block (choose N from options)

flex pick=<n> {
  option type="stop" ref="<id>"
  option type="route" ref="<id>"
  option type="note" txt="<text>"
}

Quality rules

• Every stop must have: name, goal, and a practical note
• Every route must have: mode and note (traffic tips, scenic options, logistics)
• Routes must reference stops that exist — from and to must match stop ids
• Day items must reference stops/routes that are defined
• Durations use decimal hours: min=1.5 max=2.5 (not minutes)
• Stop/route IDs use kebab-case: "golden-gate-bridge", not "goldenGateBridge"
• Notes should be concrete and useful, not generic ("Book online to skip the line" not "Popular attraction")
• Include at least one flex block per day for optional choices
• For each major stop, include 1-3 alt blocks as alternatives
• Budget meals: $15-25, mid-range: $30-60, fine dining: $80+

Example subagent prompts

When spawning the Stops agent:

Research stops for a {N}-day trip to {destination}. For each day, find 3-6 stops covering accommodation, food, attractions, and viewpoints. Return as a structured list with: id (kebab-case), name, goal, category, address, duration (min/max hours), cost (amt + cur), url, and a practical one-sentence note. For 2-3 major stops per day, include 1-3 alternatives. Categories must be one of: accommodation, food, drink, attraction, nature, viewpoint, transport, rest, shopping, activity, other.

When spawning the Routes agent:

Given these stops: [list stop ids], plan routes between consecutive stops. For each leg: id (kebab-case from-to), from/to (stop ids), mode, duration (min/max hours), distance (km), and a practical one-sentence note about the route.

When spawning the Days agent:

Given these stops and routes, assemble a day-by-day timeline. Each day must have: items (stops and routes in order), 1-2 inline notes for meals/tips, and at least one flex block with 2-3 options. Morning starts around 8-9am, evening ends by 10pm.

Token efficiency

The KDL format saves 60-80% tokens vs JSON. The agent-format/src/cli.ts tokens command shows exact savings:

cd agent-format && bun run src/cli.ts tokens <file>