Trip Planner

Trip Planner

Turn a fuzzy trip idea into a plan the user can book link-by-link. The deliverable is verified and bookable, not inspirational: every price and opening time carries a source + as-of date, or an explicit "verify at link" flag. AI travel tools fail on stale data, not on prose — fixing exactly that is this skill's job, so verification IS the work.

Hard rules

1. Never book, pay, hold, or enter personal data anywhere. Produce deep links and a checklist; the human books. This is what keeps the skill safe to run autonomously.
2. Prices and hours come from tools, never from memory. Model memory is fine for geography and "what's worth seeing"; anything bookable or closable gets checked. A missing price is written "—, check link", never guessed.
3. Cheap before expensive: bundled script + keyless APIs first (see references/data-sources.md), browser automation second and only for what scripts can't get (OTA hotel prices, LCC fares, odd venues). Never curl OTA/airline sites — they bot-block instantly; browser pane only. Pace requests like one polite human.
4. Search budgets are real: ~25 web searches for your own orchestration work (visa, flights, holidays, hotels, assembly) — separate from, not inclusive of, the ≤8 written into each parallel city subagent's prompt. Unbounded research agents hang and burn money, so the cap goes in the prompt every time. Budget exhausted → ship with the least-verified items flagged rather than digging further.
5. Reply in the language the user asked in. Report money in the user's home currency (infer from origin), stating the FX rate + date used once. FX source: frankfurter.dev first — but it only carries ~30 major currencies, and closed or minor ones (MAD / VND / EGP …) are not "unsupported", they are silently dropped from a 200 response (symbols=VND,USD comes back with USD alone). For those use https://open.er-api.com/v6/latest/<BASE> and check the returned object has the key you asked for; the plan states which source it used (data-sources.md §FX).
6. Track the phases as todos (whatever task/todo tool the harness has; none → a short checklist at the top of your working notes) so a long plan survives interruptions and stays visible.

Interaction contract

Three moments at most, usually two: (0) one intake message, only if a core fact is missing and can't be inferred (Phase 0 — most requests need none); (a) after Phase 2 — present 2-3 route skeletons, get a pick; (b) final delivery. Everything else runs without questions. If the user says "一次到位 / don't ask, just plan" or the session is clearly headless, skip (0) and (a): assume, pick the best skeleton yourself and state every assumption prominently at the top of the output.

Quick modes (no full pipeline)

• Gap filler — "I'm near X with 2 free hours": offer 2-3 options within a 15-min radius, one per energy level (a sight / food / a sit-down), each with walk time, a map link, a turn-back deadline, and — the one thing worth a search — confirmation that it is open right now. ≤3 searches; answer in minutes, not a report.
• Single day — "we have one day in Rome, what do we do?": run Phase 1's holiday + festival check, Phase 4 for that one day, and the Phase 6 self-check. Skip route skeletons, flights and hotels entirely; read scheduling.md and navigation.md and leave the rest closed. This is the most common request that is not a whole trip.
• Live replan — "missed the train / it's pouring": rebuild only the affected day from its degradation tags ([skippable]/[swap→…]/late_cut line) instead of re-planning the trip. [pinned] blocks hold; [opener] may move but costs a queue; re-verify only the hops that changed.

Phase 0 — Intake (one message, or none)

Read references/phase-0-intake.md now, before you decide whether to ask the user anything — it is the whole procedure for this phase (what counts as a core fact, how origin is inferred, the intake message format and its rules, what goes into prefs, the picture-capability check, the style line and the plan language, the exit criteria). This section is only the contract; do not compose an intake message from memory of the format.

Inputs: the user's request and anything said earlier. Outputs: the plan's top-level prefs block and lang, prefs.pictures (native | key | stock), the assumptions block for checkpoint (a) — and at most one intake message.

Gates — these decide pass/fail and do not move into the reference file:

• One message, or none. Ask only when a core fact (origin · destination · when / how long · page style) is missing and cannot be inferred; ask for everything in ONE message in the intake format (core first, optional after, each optional line with its default, one "all defaults" line); anything the user already stated is settled and never re-asked; never a follow-up "just one more thing".
• Origin is inferred and stated, not asked — from the conversation language, the locale / timezone or earlier messages, as that city's own international airport — or, when only a language / locale is known, that country's largest international gateway (phase-0-intake.md lists the common hubs; São Paulo is GRU, not GIG) — unless it is genuinely unguessable, which makes it the one core question.
• The picture-capability check runs silently before styles are mentioned; never ask for a key in chat, never read, print or copy themes/.auth_header; with no generator the page still ships in a theme on the stock kit (illustrated or clay only; the other six need generated pictures — offer illustrated) — a plain text page is never the deliverable.
• lang follows the language the user asked in — it drives the page chrome only (--lang overrides); every content string in the plan is written in the user's language too.

Phase 1 — Country brief (once per destination)

Read references/phase-1-brief.md now, before any fact about the destination is written — it is the whole procedure for this phase (where each fact comes from; the visa / holiday / event / weather / money / insurance / safety lines; the advisory line, the emergency card, the health line with the yellow-fever audit, the hazard line; the exit criteria). This section is only the contract; never answer a Phase 1 fact from memory of the procedure or of the country. In chat, Phase 1 is ≤ 10 lines — the brief cards themselves follow output-template.md §Brief templates.

Inputs: destination(s), dates, the traveller's passport and origin, the skeleton candidates. Outputs: the brief cards in canonical order, the Phase 1 checklist rows (visa lead time · travel-clinic consult · yellow-fever vaccine + ICVP · insurance · hazard gate · copies + registration), and the facts later phases inherit.

Gates — these decide pass/fail and do not move into the reference file:

• Every Phase 1 fact is the assembler's alone — visa / entry, advisory, health, hazard, insurance: city agents never decide them, and anything they say is overwritten.
• Official sources only, never memory — government, embassy and foreign-ministry pages, CDC / TravelHealthPro / WHO, the insurer's schedule — each line stamped source + as-of; nothing found → "n/a — see advisory", not a guess. The plan never doses or prescribes: it writes the travel-clinic consult date and the agenda.
• The advisory level drives the plan: a base, leg or day trip in a "do not travel" / Level 4 / 暂勿前往 area stops the pipeline and asks the user; Level 3 / "avoid all but essential" / 谨慎前往 goes to the user with the line in front of them; regional "avoid" areas are checked base by base, leg by leg.
• Transit counts: the visa audit and the yellow-fever certificate audit both run over every transit airport before "no visa needed" is written anywhere — and the yellow-fever audit starts from the departure country, not the passport.
• A hazard-season hit means a gate: season card, hazard gate on the checklist and in the .ics, insurance deadline NOW, exposed bookings kept refundable.
• User-named events are verified before anything else is planned.

Phase 2 — Route skeleton → checkpoint (a)

1. Longlist cities/areas scored against the user's ranked interests and prefs.scenery (nature / city / beach / forest / lake / mountain); shortlist by geography — order as a line or loop, never a star with backtracking. prefs.travel_style shapes the legs: self-drive → a rental leg and park/countryside bases (Phase 3 §Driving legs); group tour → the tour's own schedule is the spine (Phase 4).
2. Nights allocation: ≥2 nights per base (each 1-night stay burns a half day on packing and transit); prefer "base + day-trips" over hotel-hopping when the day-trip is <90 min each way. 10-15 days ≈ 8-13 usable days ≈ 2-4 bases, and 2-3 beats 4.
3. Day-count honesty: landing before 15:00 = half a sightseeing day, later = zero sightseeing days for the count — the evening still gets one free, walkable, unticketed block near the hotel (scheduling.md §Arrival day); departure day = zero unless the flight leaves after 18:00.
4. Decide open-jaw now (fly into the first base, out of the last) — on multi-city routes it usually beats round-trip because it refunds a backtracking day. Check both jaw directions in Phase 3; prices are asymmetric.
5. Present 2-3 skeletons (e.g. classic / nature-lean / relaxed): city order, nights per base, intercity legs with rough mode + duration, one-line pace verdict. Recommend one.

Phase 3 — Flights & intercity legs

Read references/phase-3-legs.md now, before the first flight scan — it is the whole procedure for this phase (the plan shape, the international price-source ladder, multi-airport and LCC arithmetic, the separate-tickets audit, intercity rail vs fly, driving legs, what every leg row records, the exit criteria). This section is only the contract; do not price a leg from memory of the procedure.

Inputs: the chosen skeleton (Phase 2), prefs.travel_style, the Phase 1 visa / entry facts (transit countries included). Outputs: legs[] — one pick + one backup per leg — the checklist rows for flights, date-locked rail and rentals, their budget rows, and the baggage walkthrough for multi-leg trips.

Gates — these decide pass/fail and do not move into the reference file:

• assets/plan.example.json is the single source of truth for the plan's shape — open it before writing a field; a wrong shape does not fail loudly — the renderers WARN and print an empty section.
• Every international pick and backup is priced in ≥ 2 sources (flight_scan / Google + Skyscanner / Kayak / Trip.com / the carrier's site); legs.note names them with the as-of date; a > 10 % disagreement prints as a band; no browser pane → Google alone and the note says so. "Price unverified" only when every source fails.
• Separate tickets across a foreign hub are a visa trap: the audit runs before "no visa needed" is written anywhere — including tickets the user already holds.
• Rail wins under ~5 h station-to-station; price on the operator's site. A park without a car is decided with the user, never by default.
• Every leg row carries price + currency + as-of, the checked-bag fee, the refund / change class and a deep link; one pick + one backup per leg.

Phase 4 — City day-plans

Read references/phase-4-days.md now, before any city is planned or any city agent is launched — it is the whole procedure for this phase (the city-agent contract, the six per-city steps, the route_tools order, the sun / check rules, and the exit criteria). This section is only the contract; do not plan a city from memory of the procedure, and build every city-agent prompt from that file's §City-agent contract (paste its lines, or pass the file's absolute path — the agent never sees SKILL.md).

Inputs: the chosen skeleton (Phase 2), the legs table (Phase 3), the Phase 1 brief facts and prefs. Outputs: per city, plan-JSON day objects insertable verbatim into days[] (output-template.md §city-block) — stops, hour-level timeline, hop_links, sun, rain_alt, ribbon — plus the city's checklist_items.

Gates — these decide pass/fail and do not move into the reference file:

• City agents never make visa / entry / health / advisory / hazard / insurance calls. Those facts are the assembler's Phase 1 job and override anything a city block says; a city agent's prompt carries search budget ≤ 8, an explicit "do not run geocoding" line, the plan language, the §city-block return format, and the visa / entry hard rule as its last line.
• Hour-level timelines are the default deliverable; day-level only when the user asks for a rough cut.
• route_tools.py check exits 0 before rendering — a BROKEN or SUSPICIOUS hop is fixed in the plan, never explained away in prose. A SUSPICIOUS hop has exactly two fixes: a vehicle really runs it (fly / drive / boat / train / bus) → declare that mode on the arriving stop and give it its legs[] row (add the row if the leg has none); nothing runs it (a 250 km hop inside one city is a mis-geocoded stop) → fix the stop, never the mode.
• sun --write runs before any sunrise / golden-hour / dark-start prose, after the stops carry coordinates; a plan that crosses timezones stamps every day's tz first.
• Every day has its rain alternative, its food area and its ribbon; anchors are chosen per interest-fit, ≤ pace + 1 optional per day.

Phase 5 — Hotels

Per base: pick 1-2 neighborhoods with reasons (near the rail hub actually used, safe after dark, luggage-friendly), in the lodging type and band from prefs.lodging (default mid-range hotel; a ryokan/onsen or B&B habit changes which properties you list). Browser spot-check Google Hotels/Booking with the real dates for a price band, then list 2-3 concrete properties: name, area, band per night, deep link with dates baked in (recipes in data-sources.md). Advise: book refundable now, re-shop 2-3 weeks out.

Phase 6 — Assemble, self-check, deliver

Read references/phase-6-assemble.md now, before the final plan.geo.json is written — it is the whole procedure for this phase (assembly order, cover title, the adversarial self-check list, delivery, the themed-render flow incl. stock mode, and the exit criteria). This section is only the contract; do not assemble or render from memory of the procedure.

Inputs: plan.geo.json assembled per references/output-template.md — the single editable source — plus Phase 0's prefs.theme / prefs.pictures / plan.lang. Outputs — three things every time, handed over through the harness's artifact / file tool: (1) the chat summary — route one-liner, total budget, the 3 biggest decisions made for the user, and in stock mode the picture notice; (2) trip-<theme>.html; (3) trip.kml — plus the gates .ics, always: the pre-departure ladder rows are date-locked gates (output-template.md §Pre-departure re-check ladder).

Gates — these decide pass/fail and do not move into the reference file:

• The deliverable is a themed page, never a plain text one. The plain render_plan.py page is an extra: on request for a printable version, or as the last resort after one honest fix attempt of the theme renderer — and then the summary says so.
• The adversarial self-check runs in full before delivery, fixes what it catches, and is recorded as "self-checked: N issues found and fixed" in meta.self_check and the last decisions[] row. The list lives in the reference file; a skipped item is a defect, not a shortcut.
• Acceptance bars are exit codes and eyes, not prose: route_tools check and scripts/plan_lint.py --strict exit 0 before rendering (the only tolerated FAIL: a polar day's sun, PLN-11), themes/qc.py exits 0 after, and the export-probe PNG or the page in a browser was actually looked at — none available → say so in the summary.
• plan.geo.json stays the single editable source: a later "move day 3 to Nara" is a JSON edit plus geocode → check → links → kml → render, never a rewrite.
• Cover title comes from references/cover-titles.md — never a literal placeholder, never a blacklisted cliché.

When things fail

• flight_scan.py errors twice (or cannot be installed — data-sources.md §Flights has the PEP 668 variants) → browser Google Flights; that blocked too → the second price source (Skyscanner / Kayak, data-sources.md §Flights → Second price source); only when every source fails do deep links go out marked "price unverified", keep moving. A harness with no browser pane is the one case a single source is acceptable — then legs.note says "single source — no browser"; a web search is never the rung after a failed scan while a browser exists.
• A venue's hours survive 2 searches unverified → schedule it flagged "confirm on arrival"; don't burn more budget.
• Anything still unverified at delivery gets a ⚠️ in the plan — visible honesty beats quiet confidence.

Bundled resources

Paths below are relative to the skill root (the directory holding this SKILL.md) — resolve it once and call the scripts by absolute path, because a subagent's working directory is not the skill directory and shell cwd does not persist between calls.

• references/data-sources.md — read before Phase 1: every API/URL recipe + fallback chain (flights, hotels, rail, venues, weather, FX, holidays, geocoding) — plus the booking-judgment rules that decide plans: §Group tours (weekday grids, min-party, calendar-vs-marketing, zero-cost holds and booking order) and §Hotels (checkout all-in pricing). Not just a curl cookbook.
• references/country-quick-notes.md — read the destination's section before Phase 2: passes, sell-outs, closure patterns, transit apps per country; destination absent → its "Destination not listed? — the checklist" section.
• references/output-template.md — read before Phase 4 fan-out (city-block format) and Phase 6 (deliverable structure).
• references/scheduling.md — read before building any hour-level timeline: dwell times, buffers, meals, energy curve, degradation tags, timeline verification.
• references/navigation.md — read with it: hop-link recipes, transit-row format, exit numbers, verify-vs-estimate policy, offline-maps (KML) workflow.
• references/cover-titles.md — bilingual poetic cover-title case library (poetry / prose / classic-literature sources + trip-archetype fit + cliché blacklist); read at Phase 6 when rendering.
• references/phase-0-intake.md — read at the start of Phase 0, before deciding whether to ask anything: core vs optional facts and their defaults, origin inference, the intake message format and rules (zh sample inline, en in output-template.md), the prefs block, the picture-capability check (native | key | stock), the style line and plan language, and the exit criteria. SKILL.md Phase 0 is only the contract; this file is the procedure.
• references/phase-1-brief.md — read at the start of Phase 1, before any destination fact is written: where each fact comes from, the visa / holiday / event / weather / money / insurance / safety lines, the advisory line (level → plan behaviour), the emergency card, the health line with the yellow-fever audit, the hazard line (season card + hazard gate), and the exit criteria. SKILL.md Phase 1 is only the contract; this file is the procedure.
• references/phase-3-legs.md — read at the start of Phase 3, before the first flight scan: the plan shape and its two traps, the international price-source ladder and the ≥ 2-sources rule, multi-airport and LCC arithmetic, the separate-tickets visa audit, intercity rail vs fly, driving legs, the fields every leg row records, the baggage walkthrough, and the exit criteria. SKILL.md Phase 3 is only the contract; this file is the procedure.
• references/phase-4-days.md — read at the start of Phase 4, before any city is planned: the city-agent contract (what every fan-out prompt must carry), the six per-city steps, the route_tools order (geocode → tz → sun → links → check → kml), the sun / check acceptance rules, and the exit criteria. SKILL.md Phase 4 is only the contract; this file is the procedure.
• references/phase-6-assemble.md — read at the start of Phase 6, before the final plan is written: assembly order, cover title, the full adversarial self-check list, delivery (themed page + KML + gates .ics), the themed-render flow incl. stock mode, the qc / export-probe acceptance bars, and the exit criteria. SKILL.md Phase 6 is only the contract; this file is the procedure.
• scripts/flight_scan.py — Google Flights grid scanner; run with --help first.
• scripts/route_tools.py — geocode stops, distance-check clustering, emit per-hop + whole-day map links and the trip KML; subcommands geocode / check / links / kml / ics (the gates .ics from the checklist's dated rows — -o gates.ics, bump --sequence on every plan change) / sun (civil dawn + sunrise/sunset per day from sunrise-sunset.org, sanity-checked, written into days[].sun in the canonical format; point = first stop, last stop on a moving day, or the day's sun_stop when set; non-zero exit = a day was skipped/rejected).
• scripts/render_plan.py — turn the plan JSON into the final self-contained HTML. It reads the same file route_tools does, so write the plan once and render often.
• scripts/plan_lint.py — the plan's content gate, run with --strict before any renderer (exit = FAIL count, like qc.py): brief present, non-empty and in canonical order; no placeholder / "awaiting" text; no markdown headings in cells; the self-check line in meta.self_check; art placeholders filled and prefs.pictures matching how the art was made; the gates .ics and trip.kml beside the plan; under --strict every day has at least one stop and a sun written by sun --write. check proves the geography and qc.py the HTML — this proves the words.
• assets/plan.example.json — runnable schema example and the single source of truth for the plan's top-level keys (prefs/budget/legs/checklist/hotels/ brief/days[]… shapes; output-template.md §Top-level plan skeleton mirrors it): copy it, replace the placeholders, and both scripts work on it immediately.
• references/themes.md — the themed-render manual: what each of the eight themes is, its art fields and known limits, how to add a theme, the recurring-defect checklist and the verification discipline. Read before rendering any theme.
• themes/ — the themed renderers (render_journal.py, render_noir2.py, render_theme2.py = illustrated, render_clay2.py, render_glass2.py, render_zine.py, render_splash.py, render_portal.py, render_picker.py) plus theme_common.py, qc.py (static QC, exit code = FAIL count), xprobe.sh / xt.sh (headless export probes), towebp.py / gen.py / split_sheet.py / cutout.py (asset pipeline), ART-SCHEMA.md (the one authoritative art.json contract) and themes/README.md.
• themes/assets/ — the shared picture library: all embeddable webp, the Caveat webfont, manifest.json (prompt/cost per generated asset), IMAGE-LIBRARY.md (index by subject — check its Generic pieces section before generating anything), portal/ (the portal theme's footage sidecar dir — empty in the tree; the US reference chain is a release asset, see portal/README.md) and stock/ — the stock kit (region cover paintings + landmark / generic-scene cut-outs in the illustrated style, stock/index.json + stock/README.md) that themes/stock_art.py uses to build an art file when the session has no image generator and no key.
• themes/stock_art.py — plan.geo.json --theme illustrated|clay [--lang zh|en] [--country ISO2] [--index PATH] [--force] -o plan.art.json: fills the picture slots from the stock kit + shared library (country match, day keyword match, generic props); you write the words; render with --assets themes/assets/stock. Stock mode only (Phase 0).