From agent-almanac
Plans optimized multi-stop tour routes using OSM data, with waypoint ordering via nearest-neighbor/TSP, time/distance estimates, and POI discovery. For road trips, walking tours, or itineraries minimizing travel time.
npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Composes Mapbox MCP tools to generate grounded, cited location responses from live data for queries on nearby POIs, neighborhoods, travel times, and distances.
Automates Google Maps tasks via Rube MCP (Composio): geocode addresses, search places, get directions, compute route matrices, reverse geocode, autocomplete, get place details. Useful for location services in apps.
Share bugs, ideas, or general feedback.
Plan and optimize a multi-stop tour route with time estimates, distance calculations, and points of interest along the way.
Collect and structure all stops the tour must include.
Waypoint Schema:
┌──────────┬────────────────────────────────────────────┐
│ Field │ Description │
├──────────┼────────────────────────────────────────────┤
│ name │ Human-readable label for the stop │
│ address │ Street address or place name │
│ lat/lon │ Coordinates (if known; otherwise geocode) │
│ duration │ Time to spend at this stop (minutes) │
│ priority │ Must-visit vs. nice-to-have │
│ hours │ Opening/closing times (if applicable) │
│ notes │ Parking, accessibility, booking required │
└──────────┴────────────────────────────────────────────┘
Separate fixed-order waypoints (e.g., hotel at start and end) from reorderable waypoints.
Expected: A structured list of all waypoints with at minimum a name and either an address or coordinates for each.
On failure: If a waypoint is ambiguous (e.g., "the castle"), use WebSearch to resolve it to a specific location. If coordinates are needed but only a name is available, defer to Step 2 for geocoding.
Convert all waypoints to latitude/longitude coordinates and verify they are reachable.
Geocoding Sources (in preference order):
1. Nominatim (OpenStreetMap) - free, no key required
https://nominatim.openstreetmap.org/search?q=QUERY&format=json
2. Overpass API - for POI-type queries
https://overpass-api.de/api/interpreter
3. Manual coordinates from mapping services
For each waypoint:
Expected: Every waypoint has valid latitude/longitude coordinates, and all points fall within a plausible geographic region (no outliers on wrong continents).
On failure: If geocoding returns no results, try alternative spellings, add region/country qualifiers, or search for nearby landmarks. If a waypoint is in a remote area with poor OSM coverage, use WebSearch to find coordinates from travel blogs or tourism sites.
Determine the visit sequence that minimizes total travel time or distance.
Optimization Strategies:
┌─────────────────────┬────────────────────────────────────────┐
│ Strategy │ When to use │
├─────────────────────┼────────────────────────────────────────┤
│ Fixed order │ Stops must be visited in given sequence│
│ Nearest neighbor │ Quick approximation for 5-15 stops │
│ TSP solver │ Optimal ordering for any number │
│ Time-window aware │ Stops have opening hours constraints │
│ Cluster-then-route │ Stops span multiple days/regions │
└─────────────────────┴────────────────────────────────────────┘
For the nearest-neighbor heuristic:
For multi-day tours, cluster waypoints by geographic proximity first, then optimize within each day.
Expected: An ordered sequence of waypoints that produces a route without excessive backtracking. Total distance should be within 20% of the theoretical optimum for fewer than 10 stops.
On failure: If the nearest-neighbor result has obvious backtracking (later stops are closer to earlier ones), try reversing the route or use a 2-opt improvement: swap pairs of edges and keep the swap if it shortens the route. For time-window constraints, verify that arrival times at each stop fall within opening hours.
Compute travel time and distance for each leg of the route.
Time Estimation Methods:
┌──────────────┬────────────┬────────────────────────────────┐
│ Mode │ Avg Speed │ Notes │
├──────────────┼────────────┼────────────────────────────────┤
│ Highway │ 100 km/h │ Varies by country/road type │
│ Rural road │ 60 km/h │ Add 20% for winding roads │
│ City driving │ 30 km/h │ Add time for parking │
│ Walking │ 4.5 km/h │ Flat terrain; reduce for hills │
│ Cycling │ 15 km/h │ Touring pace with luggage │
│ Hiking │ 3-4 km/h │ Use Munter formula for accuracy│
└──────────────┴────────────┴────────────────────────────────┘
For each consecutive pair of waypoints:
Expected: A time/distance matrix for all legs, with a running cumulative time that accounts for both travel and dwell time at each stop. Total tour duration should be realistic (not exceeding available daylight for walking tours).
On failure: If estimated times seem unrealistic (e.g., 2 hours for a 10 km city drive), check whether the detour factor is appropriate. For mountain roads, increase the detour factor to 1.6-2.0. For public transport, use WebSearch to check actual timetables rather than estimating.
Compile the optimized route into a complete itinerary with discovered points of interest.
POI Discovery (Overpass API query pattern):
[out:json];
(
node["tourism"="viewpoint"](around:RADIUS,LAT,LON);
node["amenity"="restaurant"](around:RADIUS,LAT,LON);
node["amenity"="cafe"](around:RADIUS,LAT,LON);
);
out body;
Recommended search radius:
- Along route corridor: 500 m for walking, 2 km for driving
- At waypoints: 1 km radius
Build the itinerary document:
Expected: A complete, time-budgeted itinerary document with realistic schedules, POI suggestions at each stop, and practical logistics information.
On failure: If POI queries return too many results, filter by rating or relevance. If the itinerary exceeds available time, mark lower-priority stops as optional or split into additional days. If no POIs are found in remote areas, note this and suggest the traveler research locally on arrival.
create-spatial-visualization — render the planned route on an interactive mapgenerate-tour-report — compile the itinerary into a formatted Quarto reportplan-hiking-tour — specialized planning for hiking segments within a tourassess-trail-conditions — check conditions for any walking/hiking legs