Kids Sports Schedule Coordinator

What you’re building

This one is for Nick the dad, not the property manager. Two daughters, four activities: one plays U10 futsal and U10 soccer, the other plays U8 soccer and takes dance. Each has its own practice nights, Saturday games, coach, location, and team app — TeamSnap, SportsEngine, a dance-studio Google Sheet — and none of them talk to each other. Every Sunday night Nick mentally overlays all three, texts the carpool chat, and hopes he did not miss an overlap. Sometimes he does, and Saturday morning becomes a scramble.

This tool ingests each kid’s schedule from a CSV or JSON file, merges everything into one family calendar, flags time and travel-time conflicts, suggests carpool groupings, and exports ICS files for phone sync plus a printable weekly summary. One command, one calendar, no more mental gymnastics on Sunday night.

ℹSoftware pattern: Multi-source calendar aggregation with conflict detection

Ingest events from multiple independent sources, normalize them into a common schema, detect overlapping time windows, and flag resource conflicts (here, the resource is a parent who cannot be in two places at once). This is the same pattern behind meeting schedulers (Calendly, Clara), resource booking systems, ops dashboards (shift scheduling, fleet dispatch), and project management tools (Gantt conflict detection). The domain changes; the algorithm does not.

🔍Youth sports logistics primer for non-parents

If you do not have kids in organized sports, here is why scheduling gets complicated fast:

Futsal is indoor soccer on a hard court, five-a-side, smaller heavier ball. Seasons run fall through winter; practices twice a week, games Saturdays at indoor complexes.
Youth soccer (outdoor) runs spring and fall. At U8 and U10 (under 8, under 10), games are short halves scheduled back-to-back at field complexes, so your slot might be 8, 9:30, or 11 AM with no choice in the matter.
Dance classes run year-round on a fixed weekly schedule. Recital season adds Friday rehearsals about six weeks out — schedules come late and change often.
Why conflicts happen: Two kids means double the commitments. Overlapping Saturday games at different fields need two parents (or a carpool ride). A 5:00 PM pickup and a 5:30 PM dropoff 15 minutes apart leaves no margin. Add dance and you are solving a constraint problem every week.
Carpool culture: In youth sports, carpooling is survival — coordinated ad hoc in group texts. A parent who can see which families are going to the same place at the same time can organize it far better.

The showcase

The finished tool produces:

Unified calendar view (HTML): every event for every kid on one color-coded weekly calendar. Each child gets a distinct color. Events show activity, time, location, and type.
Conflict detection with color-coded warnings: overlapping events highlighted in red with a clear description — which two events overlap, by how many minutes, at which locations. Travel-time conflicts flagged when back-to-back events at different locations leave too little buffer for the drive.
Carpool suggestion engine: groups families by proximity (same zip or within 5 miles) and identifies shared rides for same-time, same-location events, with a suggested driver rotation.
ICS export: .ics files (one per child, plus a combined family file) for Apple Calendar, Google Calendar, Outlook, or any calendar app. Conflict events are tagged “[CONFLICT]” in the title.
Printable “This Week” family summary: a clean day-by-day breakdown with conflict alerts, carpool notes, and a packing checklist (which kid needs cleats vs. dance shoes vs. indoor shoes, which day).

The prompt

Start your AI CLI tool in an empty directory and paste this prompt:

Build a Node.js CLI tool called kids-schedule-coordinator that ingests
multiple children's activity schedules from CSV or JSON files, merges them
into a unified family calendar, detects time conflicts, suggests carpool
groupings, and exports ICS calendar files plus a printable weekly summary.

PROJECT STRUCTURE:
kids-schedule-coordinator/
  package.json
  src/
    cli.js                (entry point, argument parsing with Commander)
    schedule-parser.js    (CSV and JSON ingestion, normalization)
    conflict-detector.js  (time overlap and travel-time conflict detection)
    carpool-engine.js     (proximity grouping and ride-share suggestions)
    calendar-builder.js   (HTML weekly calendar view generator)
    ics-exporter.js       (ICS file generation for calendar app import)
    weekly-view.js        (printable "This Week" family summary)
    sample-data.js        (generates realistic sample schedules)
  templates/
    calendar.hbs          (Handlebars HTML calendar template)
    weekly-summary.hbs    (Handlebars printable weekly summary template)
  static/
    style.css             (calendar and summary styling)

REQUIREMENTS:

1. CLI INTERFACE (src/cli.js)
   - Usage: node src/cli.js [options] <schedule-files...>
   - Accepts one or more schedule files (CSV or JSON), auto-detects format
     by file extension
   - --output or -o: output directory for generated files (default: ./family-calendar)
   - --week or -w: target week start date in YYYY-MM-DD format (default: next Monday)
   - --family-name or -f: family name for calendar titles (default: "Englehart")
   - --buffer or -b: minimum buffer minutes between back-to-back events at
     different locations (default: 30)
   - --carpool-radius or -r: max miles for carpool grouping (default: 5)
   - --carpool-file or -c: optional JSON file with carpool family data
     (names, addresses, zip codes)
   - --generate-sample: generate sample schedule files and carpool data, then exit
   - --ics: generate ICS calendar files (default: true)
   - --no-ics: skip ICS generation
   - --print: also generate the printable weekly summary HTML
   - After parsing arguments, orchestrate the pipeline: parse schedules,
     detect conflicts, run carpool engine, build calendar HTML, export ICS
     files, optionally build weekly summary. Print a text summary of
     conflicts found and carpool opportunities to the terminal with chalk
     color coding.

2. SCHEDULE PARSER (src/schedule-parser.js)
   Parse activity schedules from CSV or JSON files. Each file represents
   one source (a team app export, a dance studio schedule, a manual entry).

   CSV expected columns (case-insensitive, flexible matching):
   - Child Name (or Child, Kid, Player, Student)
   - Activity (or Sport, Class, Program)
   - Team Name (or Team, Group, Level) -- optional
   - Day of Week (or Day, DayOfWeek) -- e.g., "Monday", "Tue", "Saturday"
   - Start Time (or StartTime, Start, Time) -- e.g., "5:30 PM", "17:30", "5:30pm"
   - End Time (or EndTime, End) -- e.g., "6:30 PM", "18:30"
   - Location (or Venue, Field, Facility)
   - Address (or Addr, FullAddress) -- street address for distance calculation
   - Type (or EventType, Category) -- "practice", "game", "rehearsal",
     "tournament", "scrimmage", "recital"
   - Coach (or Instructor, Coach/Instructor) -- optional
   - Season Start (or SeasonStart, StartDate) -- optional, YYYY-MM-DD
   - Season End (or SeasonEnd, EndDate) -- optional, YYYY-MM-DD
   - Notes (or Comments) -- optional, free text

   JSON expected format:
   {
     "source": "TeamSnap" or "SportsEngine" or "manual",
     "child": "Daughter Name",
     "activity": "U10 Futsal",
     "events": [
       {
         "dayOfWeek": "Tuesday",
         "startTime": "17:30",
         "endTime": "18:30",
         "location": "SportsPlex Indoor",
         "address": "123 Sports Dr, Arlington, VA 22201",
         "type": "practice",
         "coach": "Coach Martinez",
         "team": "Arlington Fire U10",
         "seasonStart": "2026-01-05",
         "seasonEnd": "2026-03-28",
         "notes": ""
       }
     ]
   }

   Normalization rules:
   - Parse time strings flexibly: "5:30 PM", "5:30pm", "17:30", "530pm"
   - Normalize day-of-week: accept full names, 3-letter abbreviations,
     2-letter abbreviations. Store as full lowercase ("monday", "tuesday").
   - Normalize event types to canonical set: "practice", "game", "rehearsal",
     "tournament", "scrimmage", "recital". Map common variants ("match" ->
     "game", "lesson" -> "practice", "class" -> "practice", "performance"
     -> "recital", "showcase" -> "recital").
   - Assign a color to each child (configurable but defaults):
     First child: #3b82f6 (blue), Second child: #ec4899 (pink),
     Third child: #f59e0b (amber), Fourth child: #10b981 (green).
   - Expand recurring events: for a given target week, generate concrete
     date-time instances from the day-of-week + time pattern. If season
     start/end are provided, only generate events within the season window.
   - Return a unified array of normalized event objects:
     { id, childName, childColor, activity, team, date (YYYY-MM-DD),
       dayOfWeek, startTime (HH:MM 24hr), endTime (HH:MM 24hr),
       durationMinutes, location, address, type, coach, notes, source }

3. CONFLICT DETECTOR (src/conflict-detector.js)
   Detect scheduling conflicts across all events for the target week:

   a. TIME OVERLAP CONFLICTS:
      Two events for different children that overlap in time. For each
      overlap, calculate:
      - overlapMinutes: how many minutes the events overlap
      - conflictType: "full" (one event entirely within the other),
        "partial" (partial overlap), "adjacent" (back-to-back with
        no gap)
      - parentCoverage: can two parents cover both events? (flag as
        "needs-two-parents" if overlap exists, "one-parent-ok" if
        events are sequential with buffer)

   b. TRAVEL TIME CONFLICTS:
      Back-to-back events for the SAME child (or requiring the same
      parent) at different locations. Estimate travel time between
      locations using a simple approach:
      - If both addresses are provided, use zip code distance as a
        rough proxy: same zip = 5 min, adjacent zip = 15 min,
        different area = 25 min
      - If addresses are not available, use location name matching:
        same location = 0 min, different location = 20 min (default)
      - Compare travel time + buffer against the gap between events.
        If gap < travel time + buffer, flag as a travel conflict.
      - Report: gap available (minutes), estimated travel time,
        buffer needed, deficit (minutes short)

   c. SAME-CHILD CONFLICTS:
      Two events for the same child at the same time. This is a hard
      conflict -- the child cannot be in two places. Flag with highest
      severity.

   Return a sorted array of conflicts:
   { id, severity ("critical", "warning", "info"), conflictType,
     event1, event2, overlapMinutes, travelMinutes, gapMinutes,
     bufferDeficit, resolution (suggested fix), parentCoverage }

   Suggested resolutions:
   - Same-child overlap: "Schedule conflict -- [child] cannot attend both.
     Choose one or contact coaches about alternate times."
   - Time overlap (different kids): "Both parents needed. [Parent A] to
     [event1], [Parent B] to [event2]."
   - Travel conflict: "Only [N] minutes between events at different
     locations. Leave [event1] [M] minutes early or arrange carpool
     for [event2]."

4. CARPOOL ENGINE (src/carpool-engine.js)
   Generate carpool suggestions for events where ride-sharing is possible.

   Input: the carpool families file (JSON) with this structure:
   [
     {
       "familyName": "Englehart",
       "zipCode": "22202",
       "children": ["Daughter1", "Daughter2"],
       "canDrive": true,
       "vehicleSeats": 6,
       "notes": "Available weekdays after 4 PM"
     },
     {
       "familyName": "Thompson",
       "zipCode": "22202",
       "children": ["Jayden"],
       "canDrive": true,
       "vehicleSeats": 5,
       "notes": ""
     }
   ]

   Grouping logic:
   - For each event (by activity + day + time + location), find all
     carpool families whose children participate in the same activity.
   - Filter to families within the carpool radius (compare zip codes
     using a simple lookup: same zip = 0 miles, adjacent zip codes in
     the 222xx Arlington range = 2-4 miles, different prefix = 8+ miles).
   - Group families into carpool clusters.
   - For each cluster, suggest a driver rotation: cycle through families
     that canDrive, distributing driving duties evenly across the season.
   - Calculate seats needed vs seats available per carpool.

   Return:
   [
     {
       event: { activity, dayOfWeek, startTime, location },
       families: ["Englehart", "Thompson", "Rivera"],
       suggestedDriver: "Thompson (this week)",
       rotation: ["Thompson", "Englehart", "Rivera"],
       seatsNeeded: 4,
       seatsAvailable: 5,
       notes: "All within 22202 -- 2 min between pickups"
     }
   ]

   If no carpool file is provided, skip carpool suggestions and print
   a message: "No carpool data provided. Use --carpool-file to enable
   carpool suggestions."

5. CALENDAR BUILDER (src/calendar-builder.js)
   Generate an HTML weekly calendar view using Handlebars:

   Layout:
   - Header: "[Family Name] Family Calendar" title, week date range
     (e.g., "March 9 - March 15, 2026"), generated timestamp
   - Weekly grid: 7 columns (Monday-Sunday), rows representing 30-minute
     time slots from 7:00 AM to 9:00 PM
   - Event blocks: positioned by day and time, height proportional to
     duration, colored by child (using the assigned child color)
   - Each event block shows: time, activity name, location (abbreviated),
     type badge (practice/game/rehearsal in small pill)
   - Conflict markers: events involved in conflicts get a red border
     and a warning icon. Hovering (or tapping on mobile) shows the
     conflict description.
   - Conflict summary panel: below the calendar grid, a list of all
     detected conflicts with severity icons, descriptions, and
     suggested resolutions
   - Carpool panel: below conflicts, a list of carpool opportunities
     for the week with family names and suggested drivers
   - Legend: child name + color swatch, event type badges, conflict
     severity icons

   Styling (static/style.css):
   - Light, print-friendly theme (this goes on the fridge):
     Background: #ffffff, grid lines: #e5e7eb, time labels: #6b7280
   - Child colors as left borders and light background fills on events
   - Conflict events: red (#ef4444) dashed border, light red background
   - Game events: bold text. Tournament events: bold + star icon.
   - Responsive: on mobile, switch to a vertical day-by-day list
     instead of the 7-column grid
   - Print CSS: fits on standard Letter paper in landscape orientation,
     hides interactive elements, uses solid borders

6. ICS EXPORTER (src/ics-exporter.js)
   Generate ICS (iCalendar) files for importing into calendar apps:

   - One ICS file per child: "daughter1-calendar.ics",
     "daughter2-calendar.ics" -- contains only that child's events
   - One combined family ICS file: "englehart-family-calendar.ics" --
     all events for all children
   - Each ICS event includes:
     SUMMARY: "[Child] - [Activity] ([Type])" e.g.,
       "Daughter1 - U10 Futsal (Practice)"
     DTSTART / DTEND: correct date and time in local timezone
     LOCATION: venue name and address
     DESCRIPTION: team name, coach, any notes. If the event has a
       conflict, append "CONFLICT: [conflict description]"
     CATEGORIES: activity name
     COLOR: child's assigned color (use X-APPLE-CALENDAR-COLOR for
       Apple Calendar compatibility)
   - Conflict events get "[CONFLICT] " prepended to the SUMMARY
   - Use the ical-generator library for proper ICS formatting
   - Handle timezone correctly (default: America/New_York)

7. WEEKLY VIEW (src/weekly-view.js)
   Generate a printable "This Week at a Glance" HTML summary:

   Layout:
   - Title: "[Family Name] Family -- This Week" with date range
   - Day-by-day breakdown (Monday through Sunday):
     Each day shows:
     - Date and day name
     - All events sorted by start time, each showing:
       time, child name (with color dot), activity, location, type
     - Conflict alerts inline (red banner with description)
     - Carpool notes inline (blue banner with driver info)
   - Daily packing checklist:
     Based on event types, list what each child needs:
     "Monday: [Daughter2] -- dance shoes, leotard, water bottle"
     "Tuesday: [Daughter1] -- indoor shoes, shin guards, water bottle"
     "Saturday: [Daughter1] -- cleats, shin guards, uniform, water bottle;
               [Daughter2] -- cleats, shin guards, uniform, water bottle"
     Packing rules:
     - Futsal: indoor shoes, shin guards, water bottle
     - Soccer (practice): cleats, shin guards, water bottle
     - Soccer (game): cleats, shin guards, uniform, water bottle, snack
     - Dance (class): dance shoes, leotard, hair pins, water bottle
     - Dance (rehearsal): dance shoes, costume, hair pins, water bottle
     - Tournament: cleats, shin guards, uniform, water bottle, snack,
       camp chair, sunscreen
   - Weekly conflict summary: total conflicts, critical vs warning,
     unresolved items
   - Carpool summary: total carpool opportunities, miles saved estimate
     (rough: assume 5 miles per one-way trip avoided)

   Styling:
   - Clean, minimal, black-and-white friendly (designed to be printed)
   - Child color dots for quick visual identification
   - Conflict alerts in bold with a simple border
   - Fits on 1-2 pages of Letter paper in portrait orientation

8. SAMPLE DATA GENERATOR (src/sample-data.js)
   When --generate-sample is passed, create realistic schedule files
   for Nick's family:

   a. futsal-schedule.csv -- Daughter1, U10 Futsal (Arlington Fire):
      - Practice: Tuesday 5:30-6:30 PM, Thursday 5:30-6:30 PM
      - Location: SportsPlex Indoor (620 S Frederick St, Arlington VA 22204)
      - Games: Saturday 10:00-11:00 AM (location varies by week, default:
        Thomas Jefferson Community Center, 3501 S 2nd St, Arlington VA 22204)
      - Coach: Martinez
      - Season: January 5, 2026 -- March 28, 2026

   b. soccer-daughter1.json -- Daughter1, U10 Soccer (Arlington Storm):
      - Practice: Monday 4:30-5:30 PM, Wednesday 4:30-5:30 PM
      - Location: Barcroft Park Field 2 (4200 S Four Mile Run Dr, Arlington VA 22206)
      - Games: Saturday 9:00-10:15 AM (location varies, default:
        Gunston Park, 2700 S Lang St, Arlington VA 22206)
      - Coach: Williams
      - Season: March 2, 2026 -- May 30, 2026

   c. soccer-daughter2.csv -- Daughter2, U8 Soccer (Arlington Blaze):
      - Practice: Tuesday 4:00-5:00 PM, Thursday 4:00-5:00 PM
      - Location: Long Bridge Park Field 1 (475 Long Bridge Dr, Arlington VA 22202)
      - Games: Saturday 9:00-10:00 AM (default:
        Long Bridge Park Field 3, 475 Long Bridge Dr, Arlington VA 22202)
      - Coach: Patel
      - Season: March 2, 2026 -- May 30, 2026

   d. dance-schedule.json -- Daughter2, Jazz/Ballet (Arlington Dance Studio):
      - Class: Monday 5:00-6:00 PM, Wednesday 5:00-6:00 PM
      - Location: Arlington Dance Studio (3028 Wilson Blvd, Arlington VA 22201)
      - Friday Rehearsal: 4:30-6:00 PM (recital season only, starting
        April 10, 2026)
      - Location for rehearsal: Kenmore Middle School Auditorium
        (200 S Carlin Springs Rd, Arlington VA 22204)
      - Instructor: Ms. Chen
      - Season: year-round (class), April 10 -- May 22, 2026 (rehearsals)

   e. carpool-families.json -- 5 families:
      - Englehart (22202, 2 kids, can drive, 6 seats)
      - Thompson (22202, 1 kid on U10 Futsal + U8 Soccer, can drive, 5 seats)
      - Rivera (22204, 1 kid on U10 Futsal, can drive, 7 seats -- minivan)
      - Kim (22206, 1 kid on U10 Soccer, can drive, 5 seats)
      - Okafor (22201, 1 kid in dance + U8 Soccer, can drive, 5 seats)

   BUILT-IN CONFLICTS in the sample data for the week of March 9-15, 2026:
   - Saturday morning: Daughter1 U10 soccer game (9:00-10:15 AM at Gunston
     Park) overlaps with Daughter2 U8 soccer game (9:00-10:00 AM at Long
     Bridge Park) -- both parents needed, different locations
   - Tuesday evening: Daughter2 U8 soccer practice ends at 5:00 PM at
     Long Bridge Park, Daughter1 futsal starts at 5:30 PM at SportsPlex
     Indoor -- 30-minute gap but 15-minute drive, tight with buffer
   - Saturday: Daughter1 futsal game (10:00-11:00 AM at TJ Community
     Center) starts right after her soccer game ends (10:15 AM at Gunston
     Park) -- same child, 15-minute gap, different locations, 10-minute drive

DEPENDENCIES: csv-parser, ical-generator, handlebars, chalk, commander

💡Start with sample data

The --generate-sample flag creates all five files with realistic schedules and built-in conflicts. Run the tool against sample data first to see how conflict detection and carpool suggestions work. Then replace the sample files with your actual schedules exported from TeamSnap, SportsEngine, or wherever your team data lives.

What you get

After your AI CLI tool finishes, set up the project:

cd kids-schedule-coordinator
npm install

Generate sample data and run the tool

# Generate sample schedule files and carpool data
node src/cli.js --generate-sample -o ./family-calendar

# Run the coordinator for the week of March 9
node src/cli.js \
  ./family-calendar/futsal-schedule.csv \
  ./family-calendar/soccer-daughter1.json \
  ./family-calendar/soccer-daughter2.csv \
  ./family-calendar/dance-schedule.json \
  --week 2026-03-09 \
  --family-name Englehart \
  --buffer 30 \
  --carpool-file ./family-calendar/carpool-families.json \
  --print \
  -o ./family-calendar

Open ./family-calendar/calendar.html in your browser. You should see:

Weekly calendar grid color-coded by child: blue blocks for Daughter1 (futsal and soccer), pink for Daughter2 (soccer and dance), positioned by day and time slot.
Saturday morning conflict in red: both daughters have 9:00 AM soccer games at different fields. The summary says “Both parents needed” and names the locations.
Saturday mid-morning conflict: Daughter1’s soccer game ends 10:15 AM at Gunston Park while her futsal game starts 10:00 AM at TJ Community Center — flagged as a same-child conflict with a travel deficit.
Tuesday evening travel warning: Daughter2’s soccer ends 5:00 PM at Long Bridge Park, Daughter1’s futsal starts 5:30 PM at SportsPlex — the 30-minute gap minus travel leaves little buffer.
Carpool suggestions below the calendar: Thompson and Rivera grouped with Englehart for futsal, Kim for U10 soccer, Okafor for dance and U8 soccer.

Open an ICS file in your calendar app to verify events import correctly, and open ./family-calendar/weekly-summary.html for the printable version — it should fit on one to two pages with the daily packing checklist.

Common issues and fixes

Problem	Follow-up prompt
Events do not appear on the calendar grid	`The calendar HTML is rendering but no event blocks are visible. Check that calendar-builder.js correctly maps each event's startTime and dayOfWeek to the grid position. The time slot calculation should convert "17:30" to a row offset: (17 - 7) * 2 + 1 = row 21 (for 30-minute slots starting at 7 AM). The day column should map "tuesday" to column 2 (Monday = 1). Make sure the CSS uses position: absolute within a position: relative day column, with top calculated from the row offset.`
ICS files show wrong timezone or times are off by hours	`The ICS events show times shifted by 4 or 5 hours. The ical-generator library needs the timezone set explicitly. Set the calendar timezone to "America/New_York" and make sure each event's start and end are created as timezone-aware Date objects, not UTC. Use: event.start = moment.tz("2026-03-10 17:30", "America/New_York").toDate() or equivalent.`
Conflict detector misses the Saturday overlap	`The Saturday morning conflict between the two soccer games is not being detected. Make sure the conflict detector compares events across different children, not just within the same child. For each pair of events on the same date, check if event1.startTime < event2.endTime AND event2.startTime < event1.endTime. If both conditions are true, the events overlap.`
Carpool engine returns empty results	`The carpool engine finds no carpool opportunities even though the carpool-families.json file is loaded. The matching logic needs to join carpool families to events by activity name. Check that the activity names in the carpool family children's data match the activity names in the schedule files. Use case-insensitive, partial matching: if a child is listed on the "U10 Futsal" activity and the carpool file lists them as participating, they should match.`
Printable weekly view does not fit on one page	`The weekly summary overflows to 3+ pages when printed. Reduce the font size for the daily schedule to 11px, use compact spacing (line-height: 1.3), and set the packing checklist to a two-column layout. Add CSS @media print { body { font-size: 11px; } .day-section { page-break-inside: avoid; } } to keep each day together and prevent awkward splits.`

🔧

When Things Go Wrong

Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.

Symptom

Travel time conflicts not being detected

Evidence

Back-to-back events at different locations show no travel warnings. Tuesday evening has only 30 minutes between venues that are 15 minutes apart, but no conflict appears.

What to ask the AI

"The conflict detector is checking for time overlaps but not for travel-time gaps. Add a second pass after overlap detection: for each pair of sequential events on the same day that involve the same parent (either the same child or two children requiring one parent each), calculate the gap between event1.endTime and event2.startTime. Estimate travel time by comparing addresses or locations. If gap < travelTime + bufferMinutes, create a travel conflict with severity 'warning' and include the gap, estimated travel, and buffer deficit in the conflict object."

Symptom

Packing checklist shows wrong gear for event types

Evidence

The weekly summary says to bring cleats for futsal, but futsal is indoor and requires indoor shoes. Dance rehearsal says to bring a leotard but it should say costume.

What to ask the AI

"The packing rules are not differentiating between activity types correctly. Update the packing logic in weekly-view.js to use both the activity name and the event type: if activity contains 'futsal', use the futsal gear list (indoor shoes, shin guards, water bottle) regardless of type. If activity contains 'dance' and type is 'rehearsal', use rehearsal gear (dance shoes, costume, hair pins, water bottle). If type is 'practice' or 'class', use class gear (dance shoes, leotard, hair pins, water bottle). The mapping should check activity first, then event type."

Symptom

Same-child conflict not flagged as critical

Evidence

Daughter1 has a soccer game ending at 10:15 AM and a futsal game starting at 10:00 AM on Saturday. The tool flags it as a warning instead of critical, but the child literally cannot be in two places at once.

What to ask the AI

"The conflict severity logic is treating all overlaps the same. Update conflict-detector.js to assign severity 'critical' when both events belong to the same child and their times overlap (one starts before the other ends). This is a hard conflict -- the child cannot attend both. Different-child overlaps at the same time should be 'warning' (both parents needed) and travel-time gaps should be 'info' or 'warning' depending on the deficit."

Symptom

ICS file imports but events repeat every week forever

Evidence

Importing the ICS file into Google Calendar shows the events repeating every week with no end date, even though the season ends in March.

What to ask the AI

"The ICS exporter is creating recurring events (RRULE) instead of individual date instances. For a weekly family view tool, generate individual one-time events for each occurrence in the target week, not recurring events. Each event should have a specific DTSTART and DTEND with the concrete date (e.g., 2026-03-10T17:30:00). Do not add RRULE properties. If the user wants a full season of events, generate one event per occurrence per week within the season window."

How it works

The pipeline is a straight line through the seven source files:

CLI (cli.js) parses arguments with Commander, validates the schedule files, and orchestrates the run: parse, detect conflicts, run the carpool engine, build the calendar HTML, export ICS, optionally build the printable summary. It prints a color-coded conflict summary to the terminal so Nick sees problems without opening a browser.
Schedule Parser (schedule-parser.js) auto-detects CSV vs JSON, normalizes column names and time formats, assigns each child a color, and expands recurring events into concrete instances for the target week. Every event ends up with the same structure regardless of which app it came from.
Conflict Detector (conflict-detector.js) runs three passes: same-child double-bookings, cross-child time overlaps (both parents needed), and travel-time gaps too short for the drive plus buffer. Conflicts are scored by severity with suggested resolutions.
Carpool Engine (carpool-engine.js) matches families to events by activity, filters by zip-code proximity, clusters them, and suggests a driver rotation. It surfaces opportunities; it does not enforce anything.
Calendar Builder (calendar-builder.js) compiles the Handlebars template onto a 7-column weekly grid, applies child colors, marks conflicts with red borders, and renders the conflict and carpool panels.
ICS Exporter (ics-exporter.js) generates one iCalendar file per child plus a combined family file via ical-generator, tagging conflict events in the summary.
Weekly View (weekly-view.js) builds the printable day-by-day summary with inline conflict alerts, carpool notes, and the packing checklist.

Customize it

Add weather integration

Add a --weather flag that checks the weather forecast for each outdoor event
in the target week. Use the Open-Meteo API (free, no key required) with the
event location's coordinates (geocode from address using a simple zip-to-
coordinates lookup). For each outdoor event (soccer games, soccer practices),
add a weather badge to the calendar view: sun icon if clear, cloud icon if
overcast, rain icon if precipitation > 50%. Flag rainy-day events with a
yellow warning: "Rain likely -- check with coach for cancellation." Indoor
events (futsal, dance) are not affected and should not show weather data.

Add team roster management

Add a --roster flag that accepts a JSON file with team rosters (player names,
parent names, parent phone numbers, parent email). For each carpool group,
show the contact info for the suggested driver so Nick can text them directly.
Add a "Snack Schedule" feature: for game days, rotate snack duty among
families on the roster and include "Snack duty: [Family Name]" on the
calendar and weekly summary. Track which families have already brought
snacks this season so the rotation is fair.

Add budget tracker

Add a --budget flag that loads a JSON file with activity costs: registration
fees, equipment costs, uniform costs, tournament entry fees, and travel
estimates. Add a "Season Budget" section to the weekly summary showing:
total spent to date, upcoming costs this month, per-child breakdown, and
per-activity breakdown. Flag when total season cost exceeds a configurable
budget threshold. Export a simple CSV budget report for tracking expenses
across seasons.

Add morning digest notification

Add a --digest flag that generates a plain-text "Today's Schedule" summary
for the current day (or a specified date). The digest shows: what is
happening today, who needs to be where and when, what to pack, any
conflicts, and the carpool driver. Format it for easy copy-paste into a
text message or email. Add an optional --email flag with an email address
to send the digest automatically using nodemailer. Nick could set this up
as a cron job to get a text every morning at 6 AM with today's family schedule.

Try it yourself

Generate the coordinator with the prompt above, then npm install and --generate-sample.
Run the tool for the week of March 9, 2026 with all four schedule files and the carpool file.
Open the HTML calendar — are all events positioned correctly on the grid?
Check the conflict summary. You should see at least three: the Saturday morning double-game, the Saturday same-child overlap, and the Tuesday evening travel warning.
Open an ICS file in your calendar app. Do events import with correct times and locations?
Read the packing checklist in the printable summary — does each day list the right gear for the right kid?
Move Daughter2’s Saturday game to 10:30 AM and re-run. Does the Saturday morning conflict disappear?

Key takeaways

Calendar aggregation eliminates the mental overhead. Three team apps and a Google Sheet become one calendar. The parser normalizes everything so the rest of the tool does not care where the data came from.
Conflict detection catches what your brain misses at 10 PM on Sunday. Overlaps are obvious on a grid, not when you are mentally overlaying three schedules while packing lunches. The detector does the math once and flags every problem.
Travel-time awareness turns a calendar into a logistics plan. Knowing two events overlap is useful. Knowing you have 30 minutes between venues 15 minutes apart — and need the rest for parking and check-in — is actionable.
The patterns you use at work apply to your personal life. Calendar aggregation, conflict detection, resource scheduling, and notification digests sit behind property dashboards and ops centers too. The domain differs; the engineering is identical.
Tools you build for yourself get used. A tool that solves a problem you have every week is one you will actually run — and because you know the domain, you instantly know whether the output is right.

KNOWLEDGE CHECK

Daughter1 has a soccer game from 9:00-10:15 AM at Gunston Park. She also has a futsal game from 10:00-11:00 AM at TJ Community Center, which is a 10-minute drive from Gunston Park. The family uses a 30-minute buffer for travel between locations. How should the conflict detector classify this situation?

What’s next

In Lesson 8, you will build the Coaching Playbook Builder. Nick played football at JMU and has a kinesiology degree, so he thinks in plays and movement patterns. The playbook builder is a visual tool for diagramming youth formations, drawing player routes, organizing drill sequences, and exporting printable practice plans. Same AI CLI workflow, same one-command philosophy — applied to the field instead of the fridge calendar.

Kids Sports Schedule Coordinator

What you'll learn

What you’re building

The showcase

The prompt

What you get

Generate sample data and run the tool

Common issues and fixes

When Things Go Wrong

How it works

Customize it

Add weather integration

Add team roster management

Add budget tracker

Add morning digest notification

Try it yourself

Key takeaways

What’s next