football-pilgrimage

Football Pilgrimage Guide

Generate an emotionally resonant football pilgrimage guide. Input: a team name (+ optional travel dates). Output: a narrative-driven travel guide where every spot tells a story, enhanced with "On This Day" historic events, automatic match detection during your trip, and the team's official crest.

Language rule: Match the user's language. If the user writes in Chinese, output the entire guide in Chinese. If in English, output in English. Always mirror the user's input language — including the pre-check prompts, phase titles, spot stories, On This Day narratives, and all other text.

Dependencies

ESPN API Reference

See references/espn-api.md for full API documentation including base URL, league slugs, endpoints, response formats, team lookup guide, and common team IDs.

Quick Start

User: "Generate an AC Milan football pilgrimage guide, departing April 15"

1. ESPN API: search teams in ita.1 → find AC Milan (team_id=103), get crest URL (see ESPN API Reference) 2. Web search "AC Milan wikipedia history stadium legends" → founding story, stadium (San Siro), legends, honors 3. ESPN API: fetch schedule for team 103 → check for matches between April 15-19, extract stadium name 4. Web search for stadium tour, football museum, fan pubs — and the story behind each spot 5. Web search "AC Milan history on this day April memorable moments" → find historic events for the trip 6. Generate the pilgrimage guide with emotional narrative, spot stories, On This Day section, and match alert if applicable

Commands

generate_pilgrimage

Main command — generates a complete pilgrimage guide for a team.

Pre-check — if no team specified:

If the user triggers a pilgrimage request without specifying a team (e.g., "I want a football pilgrimage guide", "plan a stadium trip for me"), do NOT guess. Instead: 1. Ask the user: "Which team is your heart's home? Tell me your club and I'll craft the perfect pilgrimage." 2. If the user is unsure or says "recommend one", suggest 3–5 iconic pilgrimage destinations based on popularity and experience richness: - 🏟️ Liverpool — Anfield, The Kop, Shankly Gates, "You'll Never Walk Alone" - 🏟️ Barcelona — Camp Nou (under renovation → Spotify Camp Nou), La Masia, Les Corts - 🏟️ AC Milan / Inter Milan — San Siro, shared cathedral of two rival faiths - 🏟️ Real Madrid — Santiago Bernabéu, the newly renovated galáctico temple - 🏟️ Bayern Munich — Allianz Arena, FC Bayern Museum, Säbener Straße 3. Wait for the user to choose before proceeding with the workflow.

Pre-check — if no departure date specified:

If the user provides a team but no departure date, recommend the best travel date within the next 30 days by combining match schedule and On This Day events: 1. Fetch the team's upcoming fixtures via ESPN API (see Get team schedule) 2. Filter for home matches within the next 30 days — a home match is the #1 factor for choosing a date 3. Search On This Day events for dates around those home matches: "{team_name} on this day {month} {day}" — find dates with rich historical significance 4. Recommend the best departure date with reasoning, e.g.: - 🔥 "I recommend departing April 15 — on April 17, {team} has a home match vs {opponent}, AND on April 16, back in {year}, {historic_event}. This gives you the perfect combination of live football and historical resonance!" - If no home match in the next 30 days: "No home matches in the next 30 days, but I recommend {date} — on this day in {year}, {historic_event}. You can still enjoy the stadium tour and city pilgrimage!" 5. Ask the user to confirm or adjust the recommended date before generating the full guide.

Workflow:

> ⚡ Concurrency strategy: Steps 1 is sequential (needed by later steps). Steps 2–5 should run in parallel to minimize latency. Within each step, all searches should also be parallel.

1. Discover team info via ESPN API + Wikipedia (sequential — needed by all later steps): - Determine the ESPN league slug (e.g., ita.1 for Serie A) — see League Slugs. If unsure, try the most likely league for the team name - Search the teams list to find team_id and crest URL — see Search team - ⚠️ The team profile endpoint does NOT return venue info. Stadium name comes from the schedule endpoint — see step 2 and ESPN API notes - Search Wikipedia for team background: Web search "{team_name} wikipedia history stadium legends honors" — extract founding year, stadium name, city, honors, legendary players, club motto, and key historical moments from search results. Do NOT use web_fetch on Wikipedia (it times out). This is the primary source for storytelling content in the guide - Extract: team_id, crest URL, city from ESPN; founding story, legends, stadium history from Wikipedia - If team name is ambiguous (e.g., "Inter" could be Inter Milan or Inter Miami), try multiple league slugs or confirm with the user

── After step 1 completes, launch steps 2–5 in parallel ──

2. Check schedule + get stadium info via ESPN API 🔀 (see ESPN API Reference for curl commands and response format): - Fetch past results and upcoming fixtures via the schedule endpoints - Extract stadium: From any home match, get venue.fullName and venue.address.city - Check for trip matches (if departure_date and duration provided): Filter events where date falls within trip dates - For each match found, extract: opponent name, home/away, kickoff time - If home match found: 🔥 This is the highlight of the pilgrimage! Adjust the itinerary to make this the "Stadium Day". Use flyai to search match tickets and recommend to user - If away match found: Still worth noting — user might want to watch at a fan pub - If no match found: Note it and suggest checking for schedule updates closer to the trip

3. Research pilgrimage spots with stories 🔀 — launch 3 web_search calls in one batch (merged queries for speed): - web_search: "{stadium_name} history legends stadium tour" — stadium origin, iconic moments, tour info - web_search: "{city} {team_name} fan pubs landmarks statues monuments" — pubs, landmarks, statues and their stories - web_search: "{city} {team_name} football museum shops merchandise" — museum exhibits, shops, memorabilia - ⚠️ Do NOT search for ticket prices, flight prices, or hotel prices via Web Search. Use flyai for all ticket/pricing queries - After spots are identified, use flyai to search attraction tickets (stadium tour, museum, etc.) and include ticket info in the guide

4. Research On This Day events 🔀 — only 1 web_search call for the entire trip: - web_search: "{team_name} history on this day {month} memorable moments" (use the departure month) - From the search results, pick events whose dates fall within the trip dates. Assign each matching event to the corresponding trip day - If no events match the trip dates, that's fine — simply omit On This Day sections from the guide - ⚠️ Anti-fabrication rules: - ONLY use events that appear in Web Search results — never generate events from memory or training data - If no events found for a specific day, skip that day entirely — do NOT output any On This Day section for that day. No placeholder text, no filler quotes. Simply omit - Prefer well-documented events (league matches, cup finals, official transfers) over vague anecdotes

5. Ticket search via flyai 🔀: - Match tickets (if home match found in step 2): flyai search-tickets --event "{team_name} vs {opponent}" --date "{match_date}" --city "{city}" - Attraction tickets: flyai search-tickets --attraction "{stadium_name} tour" --date "{date}" --city "{city}" (stadium tour, museum, etc.)

── After all parallel steps complete, generate the guide ──

6. Generate the guide with emotional narrative structure (see Guide Structure reference)

7. Ask about flights & hotels — after the guide is generated, ask the user: - "Need me to search for flights and hotels? Just tell me your departure city and I'll find the best options for you! ✈️🏨" - If user says yes and provides departure city, use flyai: - flyai search-flight --origin "{departure_city}" --destination "{city}" --dep-date "{date}" - flyai search-hotels --city "{city}" --check-in "{date}" --nights {duration} - If user already provided departure_city in the initial request, still ask to confirm before searching

get_stadium_info

Get detailed stadium information for pilgrimage planning.

Returns: stadium name, capacity, address, tour availability, ticket prices, visiting hours, plus the stadium's origin story and legendary moments.

get_pilgrimage_spots

Get a curated list of pilgrimage spots for a team's city. Each spot includes a backstory.

Returns: list of spots with name, description, address, significance, story (historical background, legendary events, famous anecdotes tied to this spot).

get_on_this_day

Get historic football events that match the user's trip dates.

Workflow: 1. Web search "{team_name} history on this day {month} memorable moments" (use the departure month) — only 1 search 2. From results, filter events whose calendar date (month + day) falls within the trip dates 3. Assign each matching event to the corresponding trip day 4. For days with no matching event, simply omit — do NOT invent an event

⚠️ Critical: Every event in the output MUST come from a Web Search result. If you cannot point to a specific search result that contains the event, do not include it.

get_trip_matches

Check if the team has any matches during the user's trip dates.

Workflow: 1. Determine ESPN league slug and team_id (see Finding a Team) 2. Fetch past results and upcoming fixtures via schedule endpoints (see ESPN API Reference) 3. Merge both results, filter events where date falls within [departure_date, departure_date + duration - 1] 4. For each match found, extract: home/away, opponent, kickoff time, status 5. Return matches sorted by date, with home matches highlighted

Output guidance:

get_travel_plan

Generate travel plan (flights + hotels) for the pilgrimage.

Team Crest (Logo)

The team's official crest is obtained from ESPN API responses:

1. Primary source — ESPN teams list or team profile → team.logos[0].href returns a URL like https://a.espncdn.com/i/teamlogos/soccer/500/{team_id}.png 2. Direct construction — If you know the team_id, the crest URL follows a predictable pattern: https://a.espncdn.com/i/teamlogos/soccer/500/{team_id}.png 3. Fallback — If crest URL is missing, search "{team_name} official logo png" via Web Search

Guide Structure (Emotional Arc)

See references/guide-structure.md for the full 5-phase narrative arc (Pre-departure → Arrival → Stadium Day → Deep Experience → Departure), spot storytelling format, match day itinerary, and optional travel & stay section.

Data Sources

| Source | What it provides | |--------|-----------------| | ESPN API | Team ID, name, crest URL, match schedule, stadium info (from schedule endpoint). See ESPN API Reference | | Wikipedia (via Web Search) | Team history, founding story, legends, honors, stadium background | | Web Search | Stadium tours, museums, fan pubs, landmarks, spot backstories, On This Day events | | flyai | Flights, hotels, and match tickets (when departure city provided or user asks for pricing) |

Examples

See references/examples.md for 3 complete examples: basic pilgrimage, pilgrimage with travel + On This Day + match detection, and standalone On This Day query.

Error Handling

Common Mistakes

See references/examples.md for 3 complete examples: basic pilgrimage, pilgrimage with travel + On This Day + match detection, and standalone On This Day query.