name	course-architect
description	Reconcile, validate, and snap course milestones and points of interest (POIs) extracted by Gemini against trackpoints from GPX/KML routes.
risk	low
source	project

Course Architect Skill

This skill provides instructions, guidelines, and command-line utilities to reconcile unstructured or semi-structured course metadata with spatial route trackpoints (supporting loop and out-and-back pass snapping).

When to Use

Use this skill when:

Reconciling a route's GPX track file with a text metadata file (e.g. PP-meta-data.txt detailing milestones/amenities).
Generating structured JSON layouts of courses with correct coordinate snapping and elevation lookups.
Automatically identifying multiple passes on out-and-back or looping trails (e.g., Barr Camp on Pikes Peak).
Running verification tests on route milestone snapping distances in the terminal.

Key Abstractions

Route trackpoints: Arrays of coordinate objects { lat, lon, ele, dist_m } representing the physical trail path.
Coordinate Snapping: Projects the waypoint coordinate to the nearest trackpoint segment.
Snapping Search Window: To handle loop and out-and-back routes, the snap logic searches within a ±3000 meter window around the nominal pass distance first to keep the waypoint pinned to the correct pass (outbound vs. inbound).
Automatic Multi-Pass Detection: Walks the trackpoints to find all distance local minima (under 200m) and merges close duplicates (within 2000m) to generate correct outbound/inbound passes automatically.

CLI Usage

Run the Javascript CLI utility from the root of the workspace to reconcile any course track and metadata text file:

node ./.gemini/skills/course-architect/scripts/reconcile_course.js \
  <gpx_path> \
  <metadata_path> \
  <output_json_path> \
  [--model <model_name>] \
  [--units imperial|metric]

Example

node ./.gemini/skills/course-architect/scripts/reconcile_course.js \
  ./samples/Pikes_Peak.gpx \
  ./samples/PP-meta-data.txt \
  ./samples/reconciled_pikes_peak.json

Validation & Assertions

Always verify that:

Waypoint coordinates are snapped to the nearest trackpoint within a tight distance tolerance.
For out-and-back sections, the waypoint has two passes (e.g. Pass 1 Outbound, Pass 2 Inbound) at correct distances.
Detour trackpoints are inserted into the route's trackpoints array when waypoints don't sit directly on the track, using the correct snapped index to preserve layout sequence.

Course Architect Skill

When to Use

Use this skill when:

Reconciling a route's GPX track file with a text metadata file (e.g. PP-meta-data.txt detailing milestones/amenities).

Generating structured JSON layouts of courses with correct coordinate snapping and elevation lookups.

Automatically identifying multiple passes on out-and-back or looping trails (e.g., Barr Camp on Pikes Peak).

Running verification tests on route milestone snapping distances in the terminal.

Key Abstractions

Route trackpoints: Arrays of coordinate objects { lat, lon, ele, dist_m } representing the physical trail path.

Coordinate Snapping: Projects the waypoint coordinate to the nearest trackpoint segment.

Snapping Search Window: To handle loop and out-and-back routes, the snap logic searches within a ±3000 meter window around the nominal pass distance first to keep the waypoint pinned to the correct pass (outbound vs. inbound).

Automatic Multi-Pass Detection: Walks the trackpoints to find all distance local minima (under 200m) and merges close duplicates (within 2000m) to generate correct outbound/inbound passes automatically.

CLI Usage

Run the Javascript CLI utility from the root of the workspace to reconcile any course track and metadata text file:

node ./.gemini/skills/course-architect/scripts/reconcile_course.js \ <gpx_path> \ <metadata_path> \ <output_json_path> \ [--model <model_name>] \ [--units imperial|metric]

Example

node ./.gemini/skills/course-architect/scripts/reconcile_course.js \ ./samples/Pikes_Peak.gpx \ ./samples/PP-meta-data.txt \ ./samples/reconciled_pikes_peak.json

Validation & Assertions

Always verify that:

Waypoint coordinates are snapped to the nearest trackpoint within a tight distance tolerance.

For out-and-back sections, the waypoint has two passes (e.g. Pass 1 Outbound, Pass 2 Inbound) at correct distances.

Detour trackpoints are inserted into the route's trackpoints array when waypoints don't sit directly on the track, using the correct snapped index to preserve layout sequence.