cos

Set up and operate the encrypted off-site backup for the chief-of-staff live data (board, guard, config, vault). Daily AES-256-GCM snapshots are pushed to a PRIVATE GitHub repo (immutable git history); the recovery key lives in the macOS Keychain. Use when bootstrapping the app on a new machine, when you need to RESTORE after data loss/corruption, to take an on-demand backup before a risky/bulk operation on live data, to verify backups are healthy, or when rotating the recovery key. This is a first-class setup skill alongside mcp-bridge-setup and guard-setup.

Sweep Gmail — BOTH received AND sent mail — and reconcile every thread onto the Cos board: link the message onto the matching case, advance or close tasks, move the lane, set catalog labels, dedup against existing cases so one matter is one card, and — the headline guardrail — NEVER undo the user's manual board edits. Use when the user says "go through my email and update the board", "sync my inbox / sent mail to the board", "reconcile email with my cases", "update the board from my mail", or when the scheduled mail sweep hands a batch of threads to be reconciled.

The reminder janitor — a periodic sweep that reviews every OPEN reminder on the board and CLOSES the ones whose job is already done or whose moment has passed, so the reminders list stays a live to-do surface instead of a graveyard of stale nudges. For each open reminder it reads the full context via the `board` MCP (the nudge, its due date, HOW LONG it has been sitting, its checklist, its linked emails, and — when it links a case — that case's current state), then takes a CRITICAL look and sorts each into CLOSE (the thing happened / got done → complete), DISMISS (no longer relevant / the decision window lapsed / superseded → dismiss), KEEP-OPEN (still live, or pinned by a star / priority), or NEEDS-YOU (a passed deadline it can't prove is settled). It AUTO-closes ONLY what is PROVEN done (a finished checklist, a linked case now closed, a delivery whose date clearly passed); every judgment call — a lapsed job-alert, an old "decide whether to" nudge, a cold FYI, anything tied to a starred node — it PROPOSES fo

Sweep WhatsApp — BOTH inbound AND the user's own sent messages, across DMs AND group chats with recent activity — and reconcile every chat onto the Cos board: link the message onto the matching case, advance or close tasks, move the lane, set catalog labels, dedup against existing cases so one matter is one card, and — the headline guardrail — NEVER undo the user's manual board edits. Use when the user says "go through my WhatsApp and update the board", "sync my chats to the board", "reconcile WhatsApp with my cases", "update the board from my messages", or when the scheduled WhatsApp sweep hands a batch of chats to be reconciled.

Manage the BODY add-on — the single owner of your body identity, your weight + body-composition history, and your GOAL. It drives the `body` MCP: set/read your FREE-TEXT objective (describe what you're after in your own words — fat loss, muscle gain, recomposition, maintenance — plus an optional target weight) via set_body_objective / get_body_objective; set/read your identity (sex, date of birth, height, training status, whether you lift) via set_body_profile / get_body_profile; log weigh-ins + body composition (weight, body-fat %, lean mass, waist) via log_weight / list_weights; and read the deterministic physiology facts (age, BMR, maintenance TDEE, BMI, fat-free mass, trend) via get_body_status. The goal is PROSE, not a pick-list. Use when the user says "set my goal", "I want to build muscle / lose fat / recomp / maintain", "I'm 178 cm", "I was born in 1991", "log my weight", "I'm 18% body fat", "my waist is 84 cm", "what's my BMR / maintenance / body status", or otherwise asks to define their body goal,

Manage the ATHLETE PROFILE — the Fitness add-on's TRAINING-FOCUS singleton that the AI coaching skills (training plan, weekly review, pre-workout brief) read to personalise their output. It SETS / UPDATES / READS the one profile per board via the `fitness` MCP's `get_athlete_profile` / `set_athlete_profile` tools: the training-focus goal + goal date, weekly availability (days/week, max session minutes), the sports trained, and the equipment on hand. It maps free-text ("I have a bike and a pool", "5 days a week, 90 min max") onto the English `VALID_ATHLETE_*` vocabularies and validates before writing. Training STATUS, your WEIGHT, and your BODY goal (fat loss / muscle / recomp) are NOT here — those live in the body add-on (the `body-profile` skill / the `body` MCP). Use when the user says "set my athlete profile", "I'm training for a triathlon", "I can train 4 days a week", "I have a kettlebell / a treadmill / pool access", "what's my training profile", or otherwise asks to define what they're TRAINING for and

The Fitness add-on OVERVIEW / router — the index that fires on GENERIC or ambiguous fitness requests and points you at the right FOCUSED skill. Use it when the user gestures at fitness without a specific ask — "help me with my fitness", "what can the fitness add-on do", "I want to get fit / train better / level up my training", "set me up for fitness", "where do I start with the fitness coach" — i.e. when the intent is clear (fitness) but the JOB is not. Do NOT use it when the request already names a job — those belong to the focused skills and own their own triggers: a weekly plan → fitness-training-plan; today's readiness / "should I train today" → fitness-pre-workout-brief; "how was my week" → fitness-weekly-review; sleep-vs-performance → fitness-correlations; pushing / logging / reading Apple Watch data → fitness-health-data; setting the training focus / availability / equipment → fitness-athlete-profile; setting the body goal / training status / weight / identity → body-profile. This skill routes; it doe

Surface and INTERPRET the sleep ↔ performance CORRELATIONS the board computes from the logged Apple-Watch + workout data — the deterministic stats twin of the Fitness add-on. The board computes (and persists) the Pearson r and the linear regression deterministically; YOU (the agent) trigger that compute via the `fitness` MCP and then read the numbers back to the user in plain language — strength + direction of the correlation, what the regression slope implies, and ACTIONABLE training guidance (e.g. "your deep-sleep correlation is strong → protect deep sleep before key sessions"), honest about small samples / weak links. You do NOT recompute Pearson yourself; the board owns the math. Use when the user says "how does my sleep affect my performance", "sleep vs performance", "correlate my sleep and training", "what affects my training", "does deep sleep help my workouts", "is my sleep linked to my training", "show me my sleep-performance correlation", or otherwise asks to relate their sleep to how they train. NO

The Fitness DATA-PLANE operator — ingests, queries, and maintains Apple Watch health data on the Cos board via the `fitness` MCP, and pushes a health report to the vault. It INGESTS canonical health entries (push workout / sleep / HRV / resting-HR / steps / VO2max, dedup by id, 90-day auto-purge), READS the data back (raw entries, a per-type summary, multi-day trends, a full daily health + nutrition summary), FIXES bad rows (hard-delete by id or date range), and composes + persists a HEALTH REPORT to the vault. It does NOT design plans / reviews / briefs and does NOT edit the athlete profile — those are the coaching + profile skills. Always with not-medical-advice framing on any interpretation. Use when the user says "push my watch data", "log my workout", "log my sleep", "log my HRV", "I ran 5k", "how did I sleep", "what's my HRV trend", "summarize my health today", "how was my day", "show my resting HR over two weeks", "delete that bad entry", "remove the duplicate sleep entry", "save my health summary to t

Prepare and persist TODAY'S pre-workout / training-readiness brief — the daily "should I train today?" call. It reads the board's deterministic FORM SCORE (0–100, with its hrv / sleep / resting-HR / load breakdown), folds in last night's sleep + this morning's metrics + recent training load + the athlete profile + today's PLANNED session, then YOU author a short brief — readiness (ready / caution / rest), the recommended session (the plan, adjusted to recovery), the warnings, the green lights, and a one-liner — and `save_pre_workout_brief` it (upserted by today's date). Always with not-medical-advice framing. Use when the user says "should I train today", "am I ready to train", "am I recovered", "pre-workout brief", "training brief", "what should I do today", "what's on for today", "how's my readiness", or otherwise asks whether to train, go easier, or rest. It does NOT make the weekly plan (fitness-training-plan owns that) — it reads today's recovery and the planned session and gives the go / hold-back call.

The Fitness coach's HEADLINE skill — generate a personalised WEEKLY TRAINING PLAN for the athlete with deliberate VARIETY / ROTATION (rotate sports, focus, and intensity week to week; alternate hard/easy; progressive overload toward the goal date), then PERSIST it via `save_training_plan` so it lands on the /fitness/training-plan history feed. It reads the athlete profile (training focus, goal date, days/week, max session, sports, equipment) AND the body add-on (training status, current weight, the free-text body goal), the last ~4 weeks of actual workouts, the recovery state (HRV / sleep / resting HR / form score), and the LAST few plans — and deliberately varies the new week against them so no two weeks look the same. Use when the user says "make me a training plan", "plan my week of workouts", "generate this week's training plan", "build my weekly training plan", "plan my training", "what should I train this week", "I'm training for <an event>, plan my week", or otherwise asks for a forward week of structu

Generate and persist the WEEKLY REVIEW — the look-BACK over a training week on the Cos board via the `fitness` MCP. A focused sub-skill of fitness-coach: it FETCHES the week's health (summary + trends: sleep, HRV, resting HR, steps, workouts), the workouts actually done, the week's training plan (to compare planned vs done), and the daily form scores across the week, then YOU (the agent) author the review — an overall 0–100 score, a prose summary, and structured training / sleep / recovery / nutrition blocks with 3–5 recommendations and a next-week focus — and PERSIST it via `save_weekly_review` (upserted by ISO week). It lands on the `/fitness/weekly-review` history feed. Always with not-medical-advice framing. Use when the user says "how was my training this week", "weekly review", "review my week", "how did my week go", "recap my training week", or otherwise asks to look back on the week's training.

The Nutrition & Chef operator — turns a plain-language food/kitchen request into structured writes on the Cos board via the `nutrition` MCP. It LOGS what you ate (estimating calories + optional macros + a green/amber/red health flag), maintains the PANTRY (add / read / update / remove on-hand items, flag low stock + expiring soon), and PLANS meals from what's on hand — reading the pantry first, preferring expiring ingredients, honoring the user's ALLERGIES + diet, and optionally putting a meal on the calendar. It owns the DIETARY PROFILE (allergies, diet type/regime, the "views on diet" methodology) and AUTHORS the daily nutrition targets — reading the user's free-text goal + the physiology facts (from the `body` MCP) + the dietary profile, computing the calorie/macro targets itself, and saving them — always with not-medical-advice framing. Use when the user says "log what I ate", "I had X for lunch", "what's in my fridge", "add Y to the pantry", "we're low on Z", "plan meals", "what can I cook", "meal plan f

Build a NEW optional vertical (an "add-on") in the Cos repo the framework-native way — one four-layer slice (nav + API + data + MCP) gated by ONE Settings.addons.<id> flag, with all data folded onto cases.json. Use when adding a whole new feature area (a "health" dashboard, a "finance" tracker, a "reading list", etc.), when reviewing/refactoring a feature that was built OUTSIDE the framework (its own *-store.ts, its own data/*.json, hardcoded nav, an unregistered route prefix), or whenever you're about to mint a new persistence store / new top-level nav and need to know whether it should instead be an add-on. The worked example is Nutrition & Chef (board/lib/addons.ts, mcp/nutrition-server, board/app/api/nutrition, tests/api-nutrition-gate.mjs); the cautionary example is the Health & Athlete PR this skill was written from.

Stand up the `body` MCP for the foundational "Body" add-on on a new machine and wire it into both Claude clients — an in-repo thin fetch-wrapper over the board's /api/body/* routes (like the nutrition/fitness servers). Body is the single owner of body identity, the weight + body-composition series, and the free-text objective that Nutrition + Fitness read. Its writes are add-on-gated (attributed to the agent via `x-actor`) and its reads are open. It is exposed to Claude Code via a supergateway + launchd BRIDGE on $BODY_BRIDGE_PORT/:8012 and to Claude Cowork Desktop as a direct stdio command. The add-on HARD AUTO-ENABLES whenever Nutrition or Fitness is enabled (so it is usually already on). Use when setting up the body add-on on a new machine, when Cowork or Code can't see the `body` server, when the body bridge (:8012) is down, when a body write 404s, or when wiring the /body surface.

The single first-run entry point that stands up the WHOLE Cos system, sequencing the four component setup skills in dependency order — setup-vault → guard-setup → mcp-bridge-setup → backup-recovery. Use when setting up the chief of staff system, doing a first-run setup, onboarding a new machine, or asking for the full setup; also when you're unsure which component skill to run first and want the guided end-to-end runbook.

Stand up the `fitness` MCP for the "Fitness" add-on on a new machine and wire it into both Claude clients — an in-repo thin fetch-wrapper over the board's /api/fitness/* routes (like the nutrition/calendar servers). Its writes are add-on-gated (attributed to the agent via `x-actor`) and its reads are open. It is exposed to Claude Code via a supergateway + launchd BRIDGE on $FITNESS_BRIDGE_PORT/:8011 and to Claude Cowork Desktop as a direct stdio command, and the add-on must be ENABLED (Settings.addons.fitness.enabled) for its writes to land + its /fitness + /fitness/health nav to appear. Use when setting up the fitness add-on on a new machine, when Cowork or Code can't see the `fitness` server, when the fitness bridge (:8011) is down, when any write 404s (add-on disabled), or when enabling/disabling the Fitness add-on.

The board's housekeeper — a periodic maintenance sweep that REORGANIZES the case tree into a clean Initiative ▸ Workstream ▸ Case hierarchy. It clusters the flat standalone cases the reconcilers leave behind, groups same-entity matters under Initiatives, splits a grown Initiative into Workstreams, renames sloppy agent-made containers to the canonical entity name and writes their one-line descriptions, merges and retires duplicates, and surfaces what matters — ALWAYS grounded in the user's stated priorities (starred nodes, P0/P1, priority notes) and NEVER renaming, re-homing, or archiving anything a human placed or named by hand. It does not triage messages, send anything, or touch lanes / tasks / labels. Use when the user says "organize my board", "tidy / clean up the board", "group my cases into initiatives", "rename / merge my initiatives", "re-balance the hierarchy", "file my orphan cases", or when the scheduled board-organize sweep runs.

Scan WhatsApp + Gmail for messages still awaiting MY reply — the ones that need nothing more than an answer, so they spin off no case, reminder, or event and get forgotten — record each on the board as an unanswered message, and mark it answered the moment I reply (so it leaves the view). Use when the user says "what haven't I answered", "show my unanswered messages", "go through my messages for unreplied ones", "what do I still owe a reply to", or when the scheduled unanswered-messages sweep hands a batch of recently-active chats/threads to be checked.

Wire this repo's CORE stdio MCP servers (board, calendar, guard, vault) into Claude Cowork Desktop and Claude Code. (The optional openwhispr voice add-on and the whatsapp add-on each have their OWN setup skill — /openwhispr-mcp-setup, /whatsapp-mcp-setup — so they're out of scope here.) Cowork uses direct stdio `command` entries in claude_desktop_config.json (validated — it does NOT accept HTTP `url` entries); Claude Code uses .mcp.json over the supergateway + launchd HTTP bridge. Use when setting up on a new machine, when Cowork or Code can't see board/calendar/guard/vault, when a bridge is down, or when wiring a new MCP server. Covers the stdio config, supergateway + launchd, the search + guard sidecar LaunchAgents, verification, and the node/simdjson + pm2 gotchas.

Stand up the `openwhispr` voice-notes MCP on a new machine and wire it into both Claude clients — the OpenWhispr add-on alongside mcp-bridge-setup (like whatsapp-mcp-setup). It exposes the external OpenWhispr desktop app's local transcript store (a SQLite DB + `.webm` recordings under `~/Library/Application Support/open-whispr/`) as a stdio MCP, fronted by a supergateway + launchd bridge on $OPENWHISPR_BRIDGE_PORT/:8002 for Claude Code and a direct stdio command for Cowork, and owns the watermark that makes voice ingestion idempotent. Use when setting up OpenWhispr/voice on a new machine, when Cowork or Code can't see the `openwhispr` server, when the openwhispr bridge (:8002) is down, when the voice ingest loop can't find notes, or when list_transcripts is stuck on fixtures instead of the real store.

Drive the `openwhispr` MCP — read OpenWhispr voice transcripts (text + `.webm` audio) and own the idempotency watermark. `list_transcripts` returns only UNPROCESSED notes; `mark_processed` (LAST, after a note is fully handled) advances the watermark so it is never re-emitted. Use for any voice-note read, audio fetch, or processing loop.

Set up the prompt-injection Guard classifier model end-to-end — pick a named model preset (default the gated Meta Llama-Prompt-Guard-2-86M), accept the Llama license + authenticate with the current `hf` CLI, prefetch the gated model, configure COS_GUARD_MODEL/THRESHOLD/CLASSIFIER in config/cos.env, install/reload the guardsvc launchd plist via gen-launchd.mjs, and verify the sidecar (:8009) + guard MCP (:8004) report the real model and not the heuristic fallback. Use when setting up Guard on a new machine, switching the guard model/preset, the guard is silently stuck on the heuristic fallback, after gaining HuggingFace access to a gated model, or when GatedRepoError / a cold sidecar appears in the guard logs.

Stand up the `nutrition` MCP for the "Nutrition & Chef" add-on on a new machine and wire it into both Claude clients — the simplest of the optional add-ons (a pure thin fetch-wrapper over the board's /api/nutrition/* routes, like the calendar server; NO sidecar, NO external repo, all in-repo at mcp/nutrition-server). It is exposed to Claude Code via a supergateway + launchd BRIDGE on $NUTRITION_BRIDGE_PORT/:8007 and to Claude Cowork Desktop as a direct stdio command, and the add-on must be ENABLED (Settings.addons.nutrition.enabled) for its 14 tools' WRITES to land + its /nutrition nav to appear. Use when setting up the nutrition/chef add-on on a new machine, when Cowork or Code can't see the `nutrition` server, when the nutrition bridge (:8007) is down, when log_food / plan_meal / add_pantry_item write but the board 404s them, or when enabling/disabling the Nutrition & Chef add-on.

Bootstrap a NEW private vault instance from the committed example-vault template — copy the template to vault/<name>, point the vault MCP bridge (:8005) at it via COS_VAULT_DIR, register it with Obsidian + capture its unique vault ID into settings.json (so the board's obsidian:// deep-links open the in-repo vault unambiguously), register it with backup, and confirm it is gitignored. Use when the user says "set up a new vault", "create my vault", "spin up a new knowledge base", wants a fresh private knowledge base, or when Obsidian vault deep-links from the board open the wrong vault — and as the vault step of the cos-setup orchestrator (which sequences the MCP bridge after this).

Stand up WhatsApp on a new machine and wire the `whatsapp` MCP into both Claude clients — the WhatsApp add-on alongside mcp-bridge-setup. It builds the external whatsapp-mcp repo's TWO processes (the Go whatsmeow bridge, run as a launchd SIDECAR like search/guard on $WHATSAPP_GO_PORT/:8010; the Python stdio MCP, exposed to Claude Code via a supergateway bridge on $WHATSAPP_MCP_BRIDGE_PORT/:8006 and to Cowork as a direct stdio command), does the one-time QR pairing against your phone's Linked Devices, and registers `whatsapp` in `.mcp.json` + the Cowork config. Use when setting up WhatsApp on a new machine, when Cowork or Code can't see the `whatsapp` server, when the Go bridge is down, when /whatsapp-triage can't reach WhatsApp, or when the linked device was removed / the session expired and you must re-pair the QR.

Drive the `vault` MCP — `ingest` is async (submit, then poll `ingest_status` to a terminal state; never re-submit an in-flight job); `query` is synchronous. Use for any vault ingest or query.

Diagnose and fix a Cos MCP server that is failing in Claude Cowork Desktop (or in Claude Code) — "board not responding", a server missing from the tool list, a tool call erroring, vault 401, openwhispr can't open its DB, whatsapp dead, or a server that dies after a while. Walks the escalation ladder (relaunch → read Cowork's per-server logs → reproduce the spawn outside Cowork → apply the known fix → regenerate config) and knows the two distinct wiring paths (Cowork = direct stdio from claude_desktop_config.json; Claude Code = launchd supergateway bridges on :8001–:8006). Use when Cowork or Code "can't see" board/calendar/guard/vault/openwhispr/whatsapp, when an MCP tool call fails or times out, when a server shows as failed/disconnected, after editing claude_desktop_config.json or .mcp.json, or whenever an MCP server is misbehaving and you need to find the real cause.

Ingests an item (inline text and/or attached on-device files) into the domain-split knowledge wiki. Classifies the item's domain (work | life), writes a factual source page, copies attached artifacts into raw/assets, re-synthesizes the affected entity and concept pages, resolves entities to canonical [[wikilinks]] via aliases.md, and maintains the strong per-domain index and log. Knowledge-only — no tasks, no board, no channel polling. Invoked headlessly by the vault Agent SDK client via the MCP ingest route.

Scheduled integrity pass over the domain-split knowledge wiki. Runs over work/wiki, life/wiki, and shared/wiki independently and flags: filename != H1, broken [[wikilinks]], orphan pages, strong-index integrity gaps, cross-domain leaks, stray task checkboxes (knowledge-only violations), and legacy priorities.md / reminders/ that should not exist. Read-only health check — it FLAGS, it does not write the board. Use when the user says "audit", "health check", "lint", "find problems", or on a schedule.

Answer questions against the domain-split knowledge wiki. Read-only. Determine the domain (work | life | both), enter through the strong per-domain index, follow [[wikilinks]], and answer with [[wikilink]] citations. Also surface any associated artifacts (files under raw/assets linked from the cited pages). Use when the user asks what they know about something, wants to explore connections between topics, or says "what do I know about X". The vault has no board access: decline pure open-work / to-do questions.