running-coach-index

name	running-coach-index
description	Reference catalog for all running coach AI skills, shared TypeScript contracts, safety guardrails, and telemetry conventions. Use when working with any running coach feature to understand data schemas, safety patterns, or integration points.
metadata	{"short-description":"Catalog of AI skills, contracts, telemetry, and guardrails for Run-Smart.","agent":"cursor"}

Purpose

Defines the shared conventions, contracts, safety posture, and telemetry used by all Run-Smart AI skills. This index allows Cursor Agent to discover available skills and the rules they follow.

When Cursor should use this skill

• Before invoking any Run-Smart skill to understand shared schemas, safety guidance, and telemetry
• When onboarding a new skill to ensure compliance with common contracts
• When working with running coach features and need to understand data schemas or safety patterns
• When user asks about available AI capabilities or skill documentation

Invocation guidance

1. Load shared references in running-coach-index/references/ (contracts, telemetry, conventions, smoke-tests)
2. Select the appropriate skill directory based on the user's need (plan generation, adjustment, insights, etc.)
3. Validate request/response payloads against the schemas in contracts.md and skill-specific schemas
4. Always follow safety guardrails and emit SafetyFlags when thresholds are crossed
5. Log telemetry events via v0/lib/analytics.ts for monitoring and improvement

Shared components

• Contracts: running-coach-index/references/contracts.md - TypeScript interfaces for all data structures
• Telemetry: running-coach-index/references/telemetry.md - Standard event logging patterns
• Conventions: running-coach-index/references/conventions.md - Naming, formatting, and design patterns
• Smoke tests: running-coach-index/references/smoke-tests.md - Quick validation scenarios

Available Skills Catalog

Planning & Generation

• plan-generator - Generates 14-21 day personalized training plans with safe load progression
• plan-adjuster - Recomputes upcoming workouts based on recent runs and feedback
• conversational-goal-discovery - Chat-based goal classification with constraint clarification

Pre-Run Assessment

• readiness-check - Pre-run safety gate evaluating readiness (proceed/modify/skip decisions)
• workout-explainer - Translates planned workouts into execution cues and purpose explanations

Post-Run Analysis

• post-run-debrief - Converts run telemetry into structured reflections with confidence scores
• run-insights-recovery - Analyzes completed runs for effort assessment and recovery recommendations

Safety & Monitoring

• load-anomaly-guard - Detects unsafe training load spikes (>20-30% week-over-week)
• adherence-coach - Identifies missed sessions and proposes plan reshuffles with motivational support

Advanced Features

• race-strategy-builder - Generates race-day pacing and fueling strategies
• route-builder - Generates route specifications with distance and elevation constraints

Safety & guardrails

Universal Safety Rules

1. No Medical Diagnosis: Never provide medical advice, diagnosis, or treatment recommendations
2. Conservative Under Uncertainty: When data is missing or uncertain, prefer safer, more conservative options
3. Pain/Injury Signals: If user reports pain, dizziness, chest discomfort, or severe symptoms:
   • Recommend stopping activity immediately
   • Advise consulting a qualified healthcare professional
   • Emit SafetyFlag with severity high
4. Load Management: Enforce hard caps on training load increases:
   • Weekly volume: max +20-30% increase
   • Long run: max +10-15% increase
   • Use plan-complexity-engine.ts for deterministic caps
5. SafetyFlag Emission: Emit structured SafetyFlag objects when:
   • Load thresholds exceeded
   • Critical data missing
   • Injury signals detected
   • Heat/weather risks present
   • Model confidence low (<50%)

Data Handling

• Redact PII before logging telemetry
• Validate all inputs against schemas
• Handle missing data gracefully with appropriate defaults
• Never assume user state - always verify from database

Model Behavior

• Prefer deterministic rules over probabilistic when safety is involved
• Fall back to template-based plans if AI generation fails
• Log all fallbacks and failures for monitoring
• Maintain consistent tone: supportive, evidence-based, non-alarmist

Integration points

API Routes

• Chat: v0/app/api/chat/route.ts - Conversational AI interactions
• Plan Generation: v0/app/api/generate-plan/route.ts - Training plan creation
• Adjustments: Background jobs (plan adjustment logic)
• Insights: Post-run screens (run analysis and recovery)

Core Libraries

• Enhanced AI Coach: v0/lib/enhanced-ai-coach.ts - Skill orchestration and routing
• Plan Generator: v0/lib/planGenerator.ts - Plan creation logic
• Plan Templates: v0/lib/plan-templates.ts - Fallback templates
• Recovery Engine: v0/lib/recoveryEngine.ts - Recovery score calculations
• Periodization: v0/lib/periodization.ts - Training load management
• Plan Complexity: v0/lib/plan-complexity-engine.ts - Safety caps and thresholds

Data Layer

• Database: v0/lib/db.ts - Dexie IndexedDB schema
• DB Utils: v0/lib/dbUtils.ts - Common database operations
• Analytics: v0/lib/analytics.ts - PostHog event tracking
• Monitoring: v0/lib/backendMonitoring.ts - Performance and error tracking

UI Components

• Today Screen: Main dashboard with readiness check
• Plan Screen: Training calendar and workout details
• Record Screen: GPS tracking and run recording
• Chat Screen: Conversational AI interface
• Profile Screen: User settings and history

Telemetry events (standard)

All skills should emit these standard events via v0/lib/analytics.ts:

• ai_skill_invoked - Every skill invocation with context
• ai_plan_generated - Training plan creation
• ai_adjustment_applied - Plan modifications
• ai_insight_created - Run analysis
• ai_safety_flag_raised - Safety warnings
• ai_user_feedback - User ratings and comments

See references/telemetry.md for detailed event schemas.

Development workflow

Adding a New Skill

1. Create skill directory: .cursor/skills/skill-name/
2. Write SKILL.md with metadata, description, and guidance
3. Create references/ subdirectory
4. Add JSON schemas: input-schema.json, output-schema.json
5. Document examples in examples.md
6. Document edge cases in edge-cases.md
7. Update this index to include the new skill
8. Add integration code in relevant API routes/libraries
9. Add tests for the skill
10. Update CURSOR.md with skill description

Testing Skills

• Use smoke tests from references/smoke-tests.md
• Verify safety guardrails with edge case inputs
• Test fallback behavior when data is missing
• Validate telemetry event emission
• Check SafetyFlag generation for risky scenarios

Monitoring Skills

• Check v0/lib/backendMonitoring.ts for error rates
• Review PostHog analytics for usage patterns
• Monitor SafetyFlag frequency and severity
• Track user feedback ratings
• Analyze model latency and performance

Version History

• v1.0 (2026-01-23): Initial Cursor Agent skills system with 12 core skills