running-coach-index

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