---
name: athos
description: AI fitness coaching via the Athos production backend. Use when a user wants to install Athos, onboard, check plans, log food/photos/activity, modify workouts, inspect dashboards, handle Athos webhooks, or manage adaptive coaching. Loads modular references for onboarding, food/activity, plan changes, program context, notifications, and ops.
---

# Athos — Production Coaching Skill

Athos is an AI-powered personal fitness coach. The backend owns fitness/nutrition intelligence, program state, meal analysis, activity math, notification jobs, and replans. The Claw owns the relationship: interview, translate, deliver, and call the backend with user context.

## Production URLs

- Production app/API: `https://app.athos.fitness`
- Signup: `https://app.athos.fitness/app/signup`
- Skill page: `https://app.athos.fitness/skill`
- Installer: `curl -fsSL https://app.athos.fitness/install | bash`
- Login: `athos login --api-key "<api-key>" --url "https://app.athos.fitness"`
- Test env for verification only: `https://app-test.athos.fitness`

Default `ATHOS_API_URL` to production unless DJ explicitly says test/staging.

## Non-Negotiable Rules

- Never invent training science or nutrition numbers. Fetch Athos state or call the right endpoint.
- Personal context boundary: the backend only knows context that has been submitted. If local memory/chat has allergies, injuries, schedule, equipment, disliked foods, reports, or preferences, pass them to Athos instead of blaming the backend.
- Product-feedback boundary: if DJ says “Athos:” in a meta/product context, treat reminder/coaching copy as product feedback unless he explicitly asks to log food or coach him.
- Use `GET /api/v1/program/week/current` as the Canonical source of truth for current workouts/meals. Do not use `/api/v1/plans/workout` for user-facing current-week delivery; it is DEPRECATED for user-facing workout delivery.
- Keep planned vs logged state distinct. A planned workout is not completed until logged.
- For food logs, preserve user portion facts exactly. If the user supplies explicit calories/protein/macros, those values are authoritative for the supplied item/meal.
- Do not create, delete, or rebuild local OpenClaw crons for Athos notifications. Athos owns `notification_jobs`; Railway Cron dispatches due jobs.
- Do not globally suppress a user's whole week because one reminder/meal/workout is wrong. Translate/fix the specific unsafe item and save missing context.
- Destructive account actions require explicit confirmation.

## Modular References

Read only the reference needed for the current task:

- `references/auth-install.md` — auth, prod install, session links, app nav, Cai/chat, PWA QA.
- `references/onboarding.md` — interview, submit answers, strategy checkpoint, confirmation, plan delivery.
- `references/program-plans.md` — current week, program context, schedule adjustment, today/broad/program modification, rest-of-week replan, workout logging, weekly plan delivery.
- `references/weekly-review.md` — the weekly three-focus review endpoint (fitness/nutrition/habit lanes), the reveal message, today/score focus fields, and the weekly loop.
- `references/food-activity.md` — text/photo food logging, corrections, failed-analysis retry, nutrition stats, personalized meal guidance, activity logging.
- `references/webhooks-notifications.md` — webhook registration, transform/event loop, dedupe, `notification.due`, backend-owned notification delivery.
- `references/friends-social.md` — friend score races: invite/redeem/approve/decline/share/unlink/summary, the scores-only privacy contract, one-way visibility, non-toxic coaching copy rules.
- `references/ops-context.md` — context enrichment, local notes, test/prod boundaries, legacy references.
- `references/api-endpoints.md` — endpoint cheat sheet.
- `references/plan-schemas.md` — response/schema notes.

## Quick Auth Pattern

Use either env vars or `memory/athos-config.json` created by `athos login`:

```bash
ATHOS_API_URL=https://app.athos.fitness
ATHOS_API_KEY=ak_...
curl -H "Authorization: Bearer $ATHOS_API_KEY" "$ATHOS_API_URL/api/v1/program/week/current"
```

Web access links:

```http
POST /api/v1/auth/session-link
Authorization: Bearer <api_key>
Body: {"redirect":"/app/dashboard"}
```

Before sending a session link, verify the target account has the state the user should see. Send one fresh complete URL; do not store full tokens in durable notes.

## How to Help Users Use Athos Well

Teach capabilities naturally during onboarding and early coaching:

- Ask for dashboards and summaries: “Show my Dashboard”, “How did this week go?”, “What are my food trends?”
- Ask for workout changes: “My shoulder hurts — modify pressing”, “Move Thursday to Saturday”, “Make this a 25-minute session.”
- Give extra context whenever something changes: soreness, sleep, stress, equipment, travel, missed workouts, disliked foods, allergies, schedule shifts, performance notes.
- Explain waits: plan generation and bigger modifications can take a few minutes because Athos builds a real personalized plan, not a generic template.
- If the user asks vaguely (“what should I do?”), check fresh Athos state first, then ask one quick question only if needed.

## Onboarding Flow

1. Fetch `GET /api/v1/onboarding/questions`.
2. Ask the first 1-2 required questions conversationally. Do not dump a form.
3. Submit `POST /api/v1/onboarding/submit-answers` with exact question IDs.
4. Do **not** poll as the primary flow. Wait for webhook. Only poll `/api/v1/onboarding/status` as fallback: poll /status only as fallback.
5. On `onboarding.strategy_ready`, fetch `GET /api/v1/onboarding/strategy-summary` and ask for direction-level confirmation.
6. Confirm with `POST /api/v1/onboarding/confirm-strategy`.
7. On `onboarding.complete`, Fetch /api/v1/program/week/current and Fetch /api/v1/program/strategy; deliver a concise plan summary.

If you just installed Athos or ran `athos login`, do not stop at "setup complete." Fetch `GET /api/v1/onboarding/questions` and Ask the first 1-2 required questions conversationally unless the user explicitly pauses.

## Current Plan and Modification Routing

- Current/today answer: `GET /api/v1/program/week/current`, select the `daily_schedule` item where `is_today` is true, and report planned vs logged state distinct.
- Fast activity/logging change: `POST /api/v1/program/activity-modify`.
- Today/current workout pain/equipment/time edit: `POST /api/v1/program/today/modify`.
- Travel/schedule window: `POST /api/v1/program/schedule-adjustment` with `travel_windows`, `quiet_hours`, and available windows.
- Broad one-off change to this week: `POST /api/v1/program/modify`.
- Reshape the *rest* of this week (shorten/redo the remaining days, "I'm slammed the rest of the week"): `POST /api/v1/program/replan-week` — regenerates only the remaining, non-completed days and leaves completed/past days unchanged. Prefer this when the intent is "redo what's left of the week."
- Durable constraint applied to the current week now: `POST /api/v1/program/update` — persists the constraint and updates the current week in place. It won't rewrite a completed day (returns 422 if the request implies one); scope to upcoming days or use `/replan-week`.
- Advance to next week / get the weekly three-focus review: `POST /api/v1/program/replan` (see `references/weekly-review.md`).

Durable context (new constraint, injury, uploaded report) is saved with `POST/PATCH /api/v1/program/context`. Saving context does not auto-replan; if Athos recommends one it appears at `GET /api/v1/program/replan-offer`, which the user can accept to run a rest-of-week replan (`/replan-week`).

`/program/modify`, `/program/today/modify`, and `/program/update` all run the same patch-ops engine: one LLM call authors a small list of typed patch operations, then deterministic code applies + lints them, so every day the request did not touch stays byte-identical. Handle three outcomes:

1. **Applied (200):** the plan changed. Relay the `explanation`, then re-fetch current week to confirm.
2. **No change (200):** the plan already satisfied the request — `decision="no_change"` / `modification_type="no_change"`, nothing was saved. Relay the explanation as-is; do not retry and do not claim you changed anything.
3. **Honest failure (422):** the backend could not safely apply the request, so **nothing was saved** and the plan is unchanged. The `detail` message is user-facing — tell the user it did not go through and retry once with a more specific rephrase. There are no template fallbacks: a 422 is a real failure, never a canned workout.

Never present `explanation`/`adjustments_made`/`coach_message` as if a change happened on a no-change (2) or a failure (3). Completed prior days are immutable — an op targeting an already-completed day returns 422; offer to adjust an upcoming day instead. (`/program/today/activity/modify` is the separate in-workout session editor and is NOT on this patch-ops path.)

Plan Integrity Verification: after modifications, re-fetch current week and verify user-facing output changed. Use `GET /api/v1/program/week/current`. Do not treat `POST /api/v1/program/modify` with `scope="ongoing"` as a clean full replan substitute; it is a best-effort current-plan patch and can report that the full program update failed.

## Food, Activity, and Meal Guidance

- Text food: prefer save-first async `POST /api/v1/food/entries/analyze-text`; then poll entry only if needed.
- Photo food: `POST /api/v1/food/analyze-image` or async entry path where available.
- Correct meal: `POST /api/v1/food/entries/{entry_id}/correct-text`; preserve user portion facts exactly.
- Failed analysis: failed rows are preserved and excluded from stats; surface retry/repair instead of letting zero-calorie failed meals disappear.
- Nutrition stats: `GET /api/v1/food/stats`.
- Pre-meal planning loop: when Athos sends `delivery_action=ask_pre_meal_plan`, ask what they were planning to eat, then call `POST /api/v1/nutrition/pre-meal-guidance` with `planned_meal`, `meal_type`, `notification_job_id`, and `idempotency_key`. Use the backend response as the nutrition decision. Do not invent a meal plan in Claw.
- Activity logging: `POST /api/v1/activity/log`; use MET-backed activity estimates from Athos, not invented burn.
- Never give generic meal recommendations if user context exists. Check fresh Athos state, allergies/avoids, actual training day, current remaining macros, and `GET /api/v1/program/overview`. Fetch durable context when relevant with `GET /api/v1/program/context`.
- If a planned food conflicts with user preferences, personalize it instead of parroting it. Keep the nutrition intent and macros. Example: If the plan says salmon but the user dislikes fish, swap to a comparable protein. If the user is traveling or slammed, offer the minimum viable option. Use elevated insulin/metabolic-health context and allergies/avoids/religion/diet. If context is missing, ask one quick question.

## Program Context Ingestion

Save durable context that should affect future plans:

```http
POST /api/v1/program/context
GET /api/v1/program/context
```

Use context types: `lab_result`, `fitness_assessment`, `medical_note`, `body_comp`, `performance_test`, `nutrition_constraint`, `injury`, `schedule_change`, `other`.

Include `apply_to`: `future_replans`, `current_week`, or `full_program`. Saving context does **not** automatically trigger a replan. If response says `plan_update_recommended=true`, ask/route to the right modification or update flow. Examples: Elevated fasting insulin, aerobic_capacity assessment, injury limitations, travel schedule.

## Webhook Event Handling

Register callbacks with `POST /api/v1/webhooks` using the installed `athos-webhook` transform. Include `X-Athos-Signature`, `custom_headers`, and `Authorization` where configured.

## Setup Verification Path

Before onboarding a new user, prove the skill package and hook loop are wired:

1. Fetch `GET /api/v1/skill/setup-requirements` for the required events and hook contract.
2. Register or update the user's callback with `POST /api/v1/webhooks` so it subscribes to every `required_webhook_events` item.
3. Run `POST /api/v1/skill/setup-test` with the user's API key. This emits `athos.installation_test` and `skill.updated` through the registered hook.
4. If `ok=false`, repair missing subscriptions or hook delivery before onboarding.
5. Direct per-hook test path remains `POST /api/v1/webhooks/{webhook_id}/test` with `event_type` such as `athos.installation_test`, `skill.updated`, or `notification.due`.


Important event types handled by this skill/package:

- `onboarding.insufficient_context`
- `onboarding.strategy_ready`
- `onboarding.complete`
- `plan.generated`
- `plan.modified`
- `replan.complete`
- `workout.scheduled`
- `reminder.scheduled`
- `notification.plan_scheduled`
- `notification.due`
- `feedback.processed`
- `food.analyzed`
- `activity.logged`
- `activity.feedback_ready`
- `program.context.added`

Dedupe by concrete identifiers. Examples: `food.analyzed:user:<id>:entry:<entry_id>`, `activity.logged:user:<id>:activity:<activity_id>`, `activity.feedback_ready:user:<id>:activity:<activity_id>`, notification `idempotency_key`, plan/week IDs, event IDs. Deliver post-workout feedback once for the matching completed activity. Do not double-deliver.

For `notification.due`: Fetch /api/v1/program/week/current, check fresh Athos state, obey `quiet_hours`, use `safe_summary`, respect `action_required`, then deliver once. Do not rebuild local crons.

If `notification.due` has `delivery_action=ask_pre_meal_plan` or `action_required=ask_pre_meal_plan`, run the Pre-Meal Planning Loop: deliver the backend `draft_message` as a question, collect the user's `planned_meal`, POST it to the `pre_meal_reply_hook`, then send the returned guidance. Do not invent a meal plan in Claw.

## Backend-Owned Notifications → Claw Delivery

Athos stores `notification_jobs`. Railway Cron claims due jobs and emits `notification.due`. The Claw is the delivery adapter and relationship layer.

Delivery Requirements:
- Use the event `idempotency_key`.
- Check fresh Athos state before sending.
- Use `safe_summary` as grounding, not as blind copy.
- Respect `quiet_hours` and user safety context.
- Do not double-deliver.

## When to Load References

- Installing or auth/session links → `references/auth-install.md`.
- Starting or debugging onboarding → `references/onboarding.md`.
- Workouts, schedule, program changes → `references/program-plans.md`.
- Food/photo/activity/macro questions → `references/food-activity.md`.
- Webhook event or reminder delivery → `references/webhooks-notifications.md`.
- Friend races, invites, score sharing, social coaching copy → `references/friends-social.md`.
- API details/schemas → `references/api-endpoints.md` and `references/plan-schemas.md`.