Health

Health — Personal Health Knowledge Graph

The Health skill turns your wearables into a queryable, local-first knowledge graph with validated longevity-proxy synthesis on top. It is a substrate, not a coach. The agent reads from it; the user reads the projections; humans interpret. v1 ships the Garmin adapter and the hex architecture that lets Apple Health, Whoop, Oura, and CGM drop in as single-file adapters with zero application-core changes.

This is the substrate-shaped answer to the questions "how did I sleep last night?", "am I overreached?", "what's my VO2max arc this year?" — answered against a trace store you own, not a vendor cloud.

Setup (first run — installs all dependencies)

This skill is a Python package with a health CLI. npx skills add copies this manifest but does NOT install the CLI — so, before the first health command, ensure it's installed. This is the single step that pulls all dependencies:

command -v health >/dev/null 2>&1 || bash "<this skill's dir>/install.sh"

install.sh (bundled alongside this SKILL.md) detects uv / python3 ≥ 3.12, creates an isolated venv, installs broomva-health with every dependency (pydantic, typer, rich, garth, …) plus the [garmin] extra, and symlinks health onto your PATH. It is idempotent — safe to re-run; upgrades in place; never touches global Python.

Agent: if command -v health fails, run bash <skill-dir>/install.sh (resolve <skill-dir> to the directory containing this SKILL.md) before the first health command, then proceed. Re-run it after updating the skill.

Agents (the reasoning layer)

This skill ships authored agents in agents/ — prompts as versioned data, released with the skill. install.sh links them into ~/.claude/agents/, so one install yields CLI + skill + agent.

Invocation paths: auto-delegation (the host agent routes on the spec's description) · explicit (Agent(subagent_type: "health-analyst", …) or "use the health-analyst agent") · parallel fan-out (one per metric domain) · scheduled (cron / /loop) for digests.

The split that makes this work: the skill is the retrieval substrate (raw → structured → series → synthesis); the agent is the reasoning layer. An agent reaches data only through the health CLI — never Garmin, never the SQLite store — so ingest is never duplicated and every answer traces to a command. It also keeps large reads (a raw dump over months) inside the subagent's own context instead of the main thread.

New agents are a one-file PR: add agents/<name>.md, and tests/unit/test_agent_specs.py pins the contract.

When to invoke

Invoke this skill on any trigger in the frontmatter trigger_keywords list. The router is:

Default discipline: any health-domain conversation opens with health status (a P15 Snapshot reflex). The agent never answers a health question from training-data priors when the live trace store could answer it.

Architecture

Five-layer hex, dependency arrow points inward:

cli/         ─→  application/  ─→  ports/  ←─  adapters/
                                                 ├─ sources/      (Garmin v1; Apple, Whoop, Oura, CGM ≥ v2)
                                                 ├─ repositories/ (SQLite default; SQLCipher v1.1)
                                                 ├─ projections/  (Obsidian daily-note; healthOS feed)
                                                 ├─ token_stores/ (filesystem default; Keychain optional)
                                                 ├─ rate_limiters/ (token-bucket)
                                                 └─ mfa/          (prompt / env / Keychain)
domain/      pure Pydantic v2 — sample shapes, metric registry, results, errors
synthesis/   derived views — HRV-CV, CTL/ATL/TSB, VO2max arc (stdlib-only)
migrations/  numbered SQL files + idempotent runner
config/      paths + settings (TOML + env, env wins)

• domain has zero I/O. It defines QuantitySample, CategorySample, CorrelationSample, Workout, Device, the MetricCode registry with canonical units, the Source enum, all Result types, and the HealthError hierarchy.
• ports are Protocol-typed seams: TraceSource, TraceRepository, ProjectionTarget, RateLimiter, TokenStore, MFAProvider, Clock.
• application holds the four v1 use cases: SyncSourceUseCase, BackfillSourceUseCase, HealthStatusUseCase, RenderDailyNoteUseCase. Each is a frozen dataclass with constructor-injected ports.
• adapters are the only place concrete dependencies live.
• cli wires concrete adapters into use cases at startup. The CLI is the only impure entry point.

This separation is what lets a new source (e.g. Whoop) drop in as a single file in adapters/sources/ without touching anything else. The application layer never imports an adapter.

Deep-dive: References/architecture.md.

Workflows

Each workflow doc starts with a one-line When invoked rule and ends with example output. See Workflows/*.md.

CLI surface

# Authentication
health auth login [--source garmin] [--profile NAME]   # one-time MFA login
health auth status [--source garmin]                    # token validity per source
health auth logout [--source garmin]                    # delete token bundle

# Sync & backfill
health sync [--source garmin] [--since ISO_DATETIME]   # incremental pull (today's snapshot)
health backfill --source garmin --months N             # last N calendar months
health backfill --source garmin --days N                # last N days
health backfill --source garmin --from YYYY-MM-DD [--to YYYY-MM-DD]  # explicit range
#   Activities fetched once for the window; daily wellness day-by-day, ~1s/day
#   pacing (a 10-month pull ≈ 20 min). Idempotent → safe to re-run / resume.
#   For a complete multi-year cold start, prefer Garmin's GDPR export tarball.

# Reflexive
health status                                           # snapshot across all sources
health doctor                                           # verify install + paths + perms

# Projection & query
health daily-note [--date YYYY-MM-DD]                  # emit Obsidian daily-note frontmatter
health context [--focus s1,s2,...] [--window-days N] [--activities N] [--no-health] [--no-weight]
#   sections: profile, stats, health, training, weight, activities, synthesis (latest-in-window snapshot)
health series --metric M [--from D] [--to D] [--bucket day|week|month|quarter|year] [--agg mean|sum|min|max|first|last|count]
#   STRUCTURED time-series for any metric (the layer between context's snapshot and raw's JSON).
#   No --bucket → every sample, uncapped. With --bucket → query-time aggregation (processed/enriched),
#   e.g. `series --metric steps --bucket month --agg sum`, `series --metric resting_heart_rate --bucket week`.
health synthesis [--on YYYY-MM-DD]                     # derived metrics traversing full history
#   → hrv_cv_30d, ctl, atl, tsb, vo2max_arc, recovery_score
#   ctl/atl/tsb = 42d/7d EWMA of Garmin per-activity training load (activityTrainingLoad); TSB=CTL−ATL.
#   Per-metric `health <sleep|hrv|rhr|...>` and `training <status|vo2max|...>` queries are v1 stubs.
health raw [--from D] [--to D] [--endpoint NAME] [--source garmin]   # verbatim upstream responses
#   The LOSSLESS layer: every field the source returned, nothing curated. Garmin's daily summary
#   is ~94 fields (we type ~5); sleep carries sleepLevels (stages) + hrvData; stress carries the
#   intraday array. Completeness over truncation — uncapped within range. Captured on every
#   sync + backfill. endpoints: daily_summary, sleep, hrv, stress, spo2, respiration,
#   body_battery, vo2max, training_readiness, weight, hydration.

# Output formatters (applies to every subcommand)
health <cmd> --format {json,jsonl,csv,tsv,human}       # default: json

Exit codes: 0 success · 1 error · 2 auth-required (re-run health auth login) — matches eddmann/garmin-connect-cli convention so wrapping scripts can branch on $?.

Output formatters: every CLI subcommand routes user-visible output through cli/formatters.py::format_value. Direct print(json.dumps(...)) calls inside subcommands are an explicit anti-pattern.

Garmin backends (config: [garmin] backend)

Garmin has four interchangeable backends behind the one TraceSource port — the payoff of the hex architecture. Select via ~/.config/broomva-health/config.toml:

[garmin]
backend = "native"        # default — in-house garth client, rides your token

The skill never handles your Garmin password on the default (native) backend. health auth login detects the delegated backend and skips the password prompt; auth is the token import.

First-time setup (default native backend):

# Mint a token once (interactive — credentials go straight to Garmin):
uv tool install garmin-connect-cli && garmin-connect auth login
# Bring it in-house + pull data:
health auth import                   # copies that token into our store
health sync                          # in-house garth pull → trace DB

Already have an oauth1_token.json + oauth2_token.json elsewhere? health auth import --from <dir>.

Composition with bstack primitives

The skill is designed to compound with the existing bstack primitives, not replace any of them.

The skill is not a primitive — it is a substrate that several primitives compose against.

Privacy invariants

The Health skill is the most privacy-sensitive workspace component. The invariants are hard:

1. SQLite by default; SQLCipher upgrade path documented — v1 ships unencrypted SQLite at ~/broomva-health/traces/<source>.db. v1.1 will add the [encrypted] extra (pysqlcipher3) and a one-shot migration to SQLCipher with the encryption key stored in macOS Keychain. See References/privacy-architecture.md.
2. Tokens at 0o600; directory at 0o700 — ~/.config/broomva-health/tokens/ directory is mode 0o700 (only owner can read), token files are mode 0o600. The filesystem token store enforces this at write time.
3. Never log PII — no log statement may contain email, password, MFA code, raw token bytes, sample values, or device serials. The agent never echoes these to the conversation log either. PII redaction is enforced at the formatter layer.
4. Local-first; no telemetry; no third-party calls beyond the source's own API — the Health skill makes network calls only to the source vendors (Garmin Connect, in v1). No analytics, no crash reporters, no "phone home".
5. Reconciliation is a projection, not a column — samples carry source + device; which-source-wins for a given metric/window is computed at projection time, not stored as a flag in the trace. This preserves provenance permanently.
6. Apple HealthKit's local-only model is the reference — Apple keeps every HKSample on-device unless the user explicitly shares with an app. We aspire to the same posture for everything we ingest.

Failure to uphold these invariants is a P20 blocker — Cross-Review must reject any PR that touches adapters/repositories/ or adapters/token_stores/ without re-verifying them.

What this skill explicitly is NOT

• Not a coaching surface in v1. It does not tell you to take a rest day, hit zone 2, or sleep more. Coaching is the v2 vision (see Workflows/Coaching.md) and requires Telos + calendar + context integration that is intentionally out-of-scope here.
• Not Apple Health in v1. The Apple Health adapter is designed-for (the APPLE_HEALTH Source enum member exists; the port shape is HealthKit-compatible) but unimplemented. Adding it is a P5 fan-out task per References/extension-guide.md.
• Not a Garmin Health API client. Garmin Health is enterprise-only and not viable for a single-user knowledge graph. The default native backend is in-house — it calls Garmin's connectapi through garth, riding an existing token (no fresh login, no external binary); cli delegates to eddmann/garmin-connect-cli, library uses garminconnect directly — see References/garmin-api-landscape-2026.md and the Garmin backends section above.
• Not a replacement for apps/healthOS/. healthOS is the platform; this skill produces the substrate that healthOS can read from. The [ProjectionTarget] port exists precisely so healthOS can subscribe without coupling.
• Not a Strava / Wahoo / Polar middle-tier. Strava has no sleep/HRV/body-battery; Wahoo has no API; Polar's API is gated. These are not viable substrates for a health KG.
• Not a vendor "recovery score" passthrough. Body Battery, Training Readiness, Whoop Recovery are stored as opaque metric codes (BODY_BATTERY, TRAINING_READINESS) for completeness but synthesis recomputes its own composites. Reasoning: Altini and others have documented that vendor recovery scores are unvalidated "made up scores" — see References/validation-evidence.md.

Self-evolution hooks

The Health skill is a P22 primitive candidate — not promoted. Per the L3 stability budget in CLAUDE.md, promotion requires the rule-of-three: three concrete failures the skill prevents, with citations, logged in research/entities/pattern/bstack-engine.md. Current count: 0. Track here:

• Failure 1: unrecorded — the daily "did I sync Garmin?" ritual that produced no persistent answer.
• Failure 2: unrecorded — repeated re-asking of "what's my VO2max trend?" because no skill owned the question.
• Failure 3: unrecorded — agent answering health questions from training-data priors when the live trace store could answer.

When each failure is logged with citation (session ID + date + concrete artifact), the skill graduates from primitive_candidate to a numbered primitive. Until then it remains a skill — useful, composable, but not in the table at CLAUDE.md §Bstack Core Automation Primitives.

The L3 cadence is deliberate: skills compose; primitives stabilize. Don't promote until the substrate has earned its row.

Related skills / references

Workspace skills:

• /bookkeeping (P6) — promote high-signal health observations into the entity graph
• /persist (P12) — persist iterate health-sync.md for daily sync loop
• /cross-review (P20) — mandatory gate before merging health substrate changes
• /telos — health metrics feed Telos GOALS/MISSION/MODELS

Per-workflow docs:

• Workflows/Sync.md
• Workflows/Backfill.md
• Workflows/Status.md
• Workflows/DailyNote.md
• Workflows/TrainingLoad.md
• Workflows/RecoveryReview.md
• Workflows/VO2maxArc.md
• Workflows/Coaching.md (NOT IMPLEMENTED in v1)

References:

• References/architecture.md — hex architecture deep-dive
• References/garmin-api-landscape-2026.md — why we built from scratch
• References/healthkit-data-model.md — sample-type rationale
• References/extension-guide.md — how to add a source
• References/rate-limit-discipline.md — what's safe; what bans accounts
• References/privacy-architecture.md — local-first model + SQLCipher path
• References/validation-evidence.md — what synthesis metrics are HIGH-confidence

External:

• Linear BRO-1235
• Design plan (HTML, human-readable): docs/plans/2026-05-22-health-skill.html
• Trace schema spec (HTML, human-readable): docs/specs/2026-05-22-health-trace-schema.html