@isparling/engram-coach 0.1.0 → 0.2.0

package/skills/consult/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: consult
+description: Use when seeking advice; whether a key workout has been completed, life circumstances are changed, where advice about the plan is needed. Requires Intervals.icu MCP tools and config.json with coaching_docs_dir and prescriptions_dir configured.
+---
+
+# Consult
+
+## Overview
+
+Workflow for analysis of objective historical execution data, subjective athlete experience, existing workout prescriptions, and occurances in life outside of athletic endeavors. Provides evidence-based adjustments to the plan, and advice on balancing with life requirements. All reasoning is recorded as persistent knowledge in the coaching docs directory.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+## Workflow
+
+```dot
+digraph adapt_plan {
+    "Phase 1: Orient" [shape=box];
+    "Phase 2: Gather" [shape=box];
+    "Phase 3: Synthesize" [shape=box];
+    "Phase 4: Propose" [shape=box];
+    "Athlete approves?" [shape=diamond];
+    "Phase 5: Write" [shape=box];
+
+    "Phase 1: Orient" -> "Phase 2: Gather";
+    "Phase 2: Gather" -> "Phase 3: Synthesize";
+    "Phase 3: Synthesize" -> "Phase 4: Propose";
+    "Phase 4: Propose" -> "Athlete approves?";
+    "Athlete approves?" -> "Phase 5: Write" [label="yes"];
+    "Athlete approves?" -> "Phase 4: Propose" [label="revise"];
+}
+```
+
+---
+
+### Pre-Phase Setup _(no user input — run silently)_
+
+Follow **`${CLAUDE_PLUGIN_ROOT}/shared/setup.md`** — the shared configuration
+preamble (paths, config, profile, persona, athlete profile).
+
+**Optional steps this skill declares:** PRESCRIPTIONS, SEASON, MCP, MONITORING
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Orient _(no user input)_
+
+Read and search silently before asking anything:
+
+1. **Weekly consultation** - Read `{coaching_docs_dir}/{season}/{training-phase}/consultations.md` to gain context on recent concerns athlete has raised with coach over this training phase.
+2. **Historical adaptations** - Read `{coaching_docs_dir}/{season}/{training-phase}/{week}/.*-adaptation.md` records to understand historical adaptations and patterns tied to specific workouts.
+3. **Active prescription/plan** — List all YAML files in `prescriptions_dir`. For each file, find the maximum session_date. The active block is the file whose most recent session_date is on or before today. If ambiguous (multiple files with recent sessions), ask: "I found multiple prescription files with recent sessions: [list]. Which block are you currently in?" Read the full prescription file for the active block and the surrounding block context (week number, phase, upcoming sessions).
+4. **Training block context** — determine current phase (base/build/peak/recovery), position within the week, and upcoming workouts that may be affected by today's adaptation. After identifying the active block from step 1, resolve the block name to a template file name by stripping any date prefix and normalizing to lowercase with hyphens (e.g., "Build 1" → "build-1", "Base" → "base", "Race Specificity" → "race-specificity"). Then read `${CLAUDE_PLUGIN_ROOT}/templates/{block-name}.md` as additional context. This file describes the block's intent, session patterns, weekly structure, and success signals. If the file is missing: continue without it and annotate in the Orient summary: "[Block template {block-name}.md not found — proceeding without block template context.]"
+
+5. **Retrieval — find precedent.** Follow `${CLAUDE_PLUGIN_ROOT}/shared/retrieval.md`.
+   Build 2-3 queries from *this session's specifics* — the session type, the numbers
+   actually observed, and any anomaly worth explaining — never from this skill's name
+   or topic. Cover both levels the policy describes: durable pattern, and session
+   precedent. Report honestly when nothing relevant is found.
+
+Announce what you found before asking anything. If past decisions are relevant (e.g., "Last time RPE was high on week 2 sub-LT2, we reduced interval count by one"), surface them explicitly.
+
+### Phase 2 Gather _(one question at a time)_
+
+Ask only what execution data cannot answer. Adapt to what the data shows — if a specific pattern is visible (e.g., power fade >10% on final interval), ask specifically about that observation rather than generically.
+
+1. Do you have concerns about the plan? Has something come up that I should know about?
+
+If the answer to the first question doesn't provide enough context to work with, ask a few more questions to prompt athlete, for example:
+1. Are you sick?
+2. Are you more or less tired than expected?
+3. Is work overly stressful?
+
+**Ask one question at a time. Wait for each answer before asking the next.**
+
+### Phase 3 — Synthesize _(shown to athlete)_
+
+Reason aloud before proposing anything. Cover:
+
+- Sickness
+- Expected tireness, how that tracks to where athlete is in the phase/plan, threshold classification (green/amber/red per persona thresholds), and how it interacts with the existing signal picture (TSB/HRV/CTL). 
+- Consult the persona's monitoring.md `## Analysis Interpretation` section for the interpretation framework and coaching voice for each analysis. Higher-weight analyses (as configured in the persona's `analyses` config) receive more reasoning space; lower-weight analyses are mentioned briefly. Analyses that **reinforce** the existing signal picture (e.g., decoupling green while TSB is in push zone) are noted concisely. Analyses that **contradict** the existing signal picture (e.g., decoupling red while TSB is in push zone) are called out explicitly with the specific signal interaction from the monitoring.md — these contradictions are the high-value findings that may change the recommendation.
+- Subjective data weighted against objective data (e.g., low RPE despite power fade → pacing issue, not fitness gap)
+- Training block position — implications differ between early build (accumulate) and peak week (preserve)
+- Upcoming workout demands — does the next session's intensity change the calculus?
+- Emphasis relevant patterns from QMD history. Call out if this matches prior lessons/patterns/successes/mistakes.
+- Reference ATHLETE_PROFILE.md when patterns from prior blocks are relevant to the consultation question. Cite the source tag in your reasoning so the athlete can trace the basis (e.g., "based on the recovery pattern from `[block-review:build-1-2026]`").
+
+Alongside the reasoning above, assemble the typed domain input for this consultation as a `StructuredChangeSet`. If Phase 3 reasoning concludes the prescription should change, emit **one state change** containing:
+
+- `entity_type: "prescription"` with `key_components` carrying `arc_id` and the durable `session_id`
+- the effective date of the change
+- a concise statement of what changes and why
+- the COMPLETE updated prescription session value — never a prose patch. The value must carry every field of the session: `sessionId`, `sessionDate`, `sessionName`, block metadata (`blockName`, `week`, `day`), `order`, `effortZone`, and the full `intervals` array (each with `durationMin`, `powerLowPct`, `powerHighPct`, `count`, `recoveryMin`)
+- the artifact relative path (e.g. `prescriptions/{arc_id}.yaml`)
+
+Also emit **one consultation event** containing:
+
+- the athlete's question or concern
+- the subjective inputs gathered (sickness, fatigue, life stress)
+- the decision rationale linking Phase 3 evidence to the action
+- `action_targets`: the session IDs the decision acts on
+- the compatibility path of the consultation log (e.g. `coaching/consultations.md`)
+
+If no prescription change is warranted, the change set carries only the consultation event.
+
+**Monitoring contributions (merged BEFORE Phase 4)**
+
+Before Phase 4 begins, collect due monitoring contributions so ONE preview
+covers everything:
+
+1. Invoke the `monitoring-rollup` skill in **CONTRIBUTION MODE** with
+   `source = consult:{YYYY-MM-DD}` and the context already gathered this
+   session. It reads `{coaching_docs_dir}/tracking/concerns.yaml`, gathers
+   any DUE active concern, and RETURNS typed `state_changes` (keyed
+   `monitoring:<concern-id>:<signal>` current state) and append-only
+   `events` — it never previews, never applies, and never writes.
+2. Merge both arrays into THIS change set. The merged change set is what
+   Phase 4 previews: one plan hash and one approval cover the prescription
+   change, the consultation event, and all due monitoring changes together.
+3. If no concern is active or due, monitoring-rollup returns EMPTY arrays.
+   Merge them and continue — the parent's single preview stands; never
+   produce a second preview for monitoring.
+
+
+This phase is **explanatory only**. No changes proposed yet. The athlete can push back on any part of the reasoning before you proceed.
+
+### Phase 4 — Propose/Answer _(requires explicit approval)_
+
+Answer athlete's questions. Do not coddle the athlete. Propose specific changes to the plan, and **be realistic** about what matches the training goals. If there are multiple approaches, seek athlete's input for what fits their needs and be explicit about what the tradeoffs are, both within the training plan and inside the broader needs of their life.
+
+For each change, explicitly state:
+- **What** changes — interval count, duration, intensity target, rest period, structure
+- **Why** — the specific reasoning from Phase 3 that drives this change
+- **Tradeoffs** - what will have to change (whether other parts of plan, or outside scope of athletic endoavors, or anything else) to support this change.
+
+**Before presenting anything**, call `engram_capture_preview` with the Phase 3 merged `StructuredChangeSet` — the single preview covers the prescription change, the consultation event, and any due monitoring contributions as one plan.
+
+If the preview returns blocked, STOP: Phase 4 cannot proceed until the input is corrected and a preview succeeds.
+
+Present TOGETHER, in one message:
+
+1. The human coaching proposal. Answer athlete's questions; do not coddle the athlete. Propose specific changes to the plan, and **be realistic** about what matches the training goals. For each change state:
+   - **What** changes — interval count, duration, intensity target, rest period, structure
+   - **Why** — the specific reasoning from Phase 3 that drives this change
+   - **Tradeoffs** - what will have to change (whether other parts of plan, or outside scope of athletic endoavors, or anything else) to support this change.
+2. The record plan from the preview: which records will be created, refined, superseded, or retired.
+3. The generated compatibility artifact paths that will regenerate (e.g. `prescriptions/{arc_id}.yaml`, `coaching/consultations.md`).
+4. The exact `plan_hash` from the preview result.
+
+Ask for approval. Approval must explicitly cover BOTH the coaching action AND the record/artifact plan identified by that exact `plan_hash` — approving the advice approves the durable mutation of the same content.
+
+Wait for **explicit approval, rejection, or modification**. On modification, rebuild the change set, re-run `engram_capture_preview`, and present the new hash.
+
+### Phase 5 — Apply _(with approved hash)_
+
+Call `engram_capture_apply` with ONLY the exact `plan_hash` the athlete approved. Never edit any file directly — every prescription YAML, the consultation log, and the qmd index are updated by the apply pipeline (records → guarded index refresh → regenerated compatibility views).
+
+Outcome handling:
+
+- **stale**: the records changed since preview. Return to Phase 4: re-run `engram_capture_preview`, present the fresh record plan and new `plan_hash`, and obtain fresh athlete approval before applying again.
+- **apply failure**: stop Phase 5. No compatibility view is written and none may be edited by hand; diagnose and retry through the tools.
+- **committed with a stale index or stale views**: the records ARE authoritative — report the authoritative record IDs to the athlete and the exact retry state: re-calling `engram_capture_apply` with the SAME committed `plan_hash` in the same session reruns only materialization and never re-approves or re-applies the record mutations.
+- **committed clean**: report the applied record IDs.
+
+---
+
+## Key Constraints
+
+| Rule                       | Detail                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Rigid phases               | Execute in order — no skipping, reordering, or combining                                            |
+| Approval gate              | Nothing written until Phase 4 explicitly approved                                                   |
+| One question at a time     | Phase 2 never batches questions                                                                     |
+| Reasoning before proposing | Phase 3 must complete before Phase 4 begins                                                         |
+| Knowledge compounds        | Every adaptation recorded in `{coaching_docs_dir}/{season}/`; future Orient phases benefit from past decisions |

package/skills/intake/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: intake
+description: One-time coaching setup. Discovers athlete goals, maps to a coaching persona (or creates one from an existing coach's philosophy), migrates historical adaptation records, and writes config.json. Run this before invoking any other skill for the first time, or when onboarding a new season or athlete.
+---
+
+# Coaching Intake
+
+## Overview
+
+Rigid five-phase intake workflow. Establishes everything engram-coach needs to start coaching: goals, persona, prescriptions, and coaching docs path. Phases execute in exact order.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+---
+
+### Pre-Phase Setup _(no user input — run silently)_
+
+Follow **`${CLAUDE_PLUGIN_ROOT}/shared/setup.md`** — the shared configuration
+preamble (paths, config, profile, persona, athlete profile).
+
+**Optional steps this skill declares:** SEASON
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Goals
+
+Ask these three questions in a single message:
+
+1. **What is your primary goal?**
+   (e.g., race, target event, performance goal, health and fitness maintenance)
+2. **What is the target date?**
+   (e.g., "May 2, 2026" — or "no specific date / ongoing")
+3. **What is your primary sport or modality?**
+   (e.g., cycling, running, triathlon, swimming, multi-sport)
+
+After the athlete answers, summarize what was heard in 2-3 sentences. Confirm before continuing.
+
+> If the athlete asks to skip a question, accept a placeholder and continue — do not block on any single field.
+
+---
+
+### Phase 2 — Plan History
+
+Ask: **"Have you been following a formal training plan or working with a coach?"**
+
+---
+
+#### Path A: Existing plan or coach
+
+Ask two questions together:
+
+1. **What is the plan or coach's name?**
+   (e.g., "a volume-focused plan", "a sweet-spot base plan", "a polarized coach", "just following a generic program")
+2. **Describe their philosophy in a sentence or two.**
+   (e.g., "lots of volume, mostly easy Z1/Z2 riding", "hard threshold intervals with minimal easy work", "very conservative — always backed off when tired", "polarized: long easy plus hard VO2max efforts")
+
+Based on the description, recommend one of the four built-in personas. Present all four so the athlete can compare:
+
+```
+conservative  — Health-first. HRV veto: if HRV drops, the day is easy regardless of other signals.
+                Errs toward rest when signals conflict. Requires high freshness for hard sessions.
+
+aggressive    — Load-maximizing. Tolerates deep fatigue. Weighted scoring — no HRV veto.
+                Pushes hard sessions when there is any reasonable basis to train hard.
+
+polarized     — 80/20 intensity split. Long easy sessions in Z1 plus hard VO2max efforts in Z4.
+                Eliminates moderate-intensity (sweet spot / tempo) work.
+
+volume        — High-volume aerobic accumulation. 14-day CTL trend window as a primary signal.
+                Permissive fatigue tolerance within the full recovery and session-quality picture.
+```
+
+State the recommendation and explain why (one sentence connecting the athlete's description to the persona's philosophy).
+
+Ask: **"Does this match the philosophy you've been training under? Or would you like to create a custom persona based on your coach's actual thresholds and approach?"**
+
+- If the athlete accepts a built-in: note the chosen slug for Phase 4.
+- If they want a custom persona: say "To create a custom persona, I'll need your coach's specific thresholds and logic. Open `PERSONA_SCHEMA.md` in the engram-coach repo for the required field list — we can fill it in together now, or you can do it separately and set `active_persona` to your new slug in `config.json`." Proceed with intake using a placeholder slug and note in the intake record that the custom persona is pending.
+
+---
+
+Ask: **"Do you have historical coaching records or adaptation notes from this training block?"**
+
+(e.g., notes from the coach, adaptation records you've been keeping, a coaching journal)
+
+- **If yes:** Ask for the directory path where these files live. Then run:
+  ```
+  cd {path}
+  qmd update
+  ```
+  Note how many files were indexed. Say: "I've indexed {N} documents from {path}. These will be available as reasoning context in future skill invocations."
+- **If no:** Say: "No problem — coaching history will be built from this session onward."
+
+---
+
+#### Path B: No formal plan
+
+Ask four questions in a single message to identify the right persona:
+
+1. **When your training signals conflict** (e.g., low HRV but you feel physically ready), do you prefer to back off and protect recovery, or trust how you feel and train hard?
+2. **During build periods**, are you comfortable accumulating significant fatigue for weeks at a time, or do you prefer more frequent lighter recovery days?
+3. **For hard sessions**, do you prefer polarized training (long easy plus hard VO2max intervals, nothing in between), or mixed-zone work (sweet spot, tempo, threshold)?
+4. **Is your primary training concern** injury prevention and long-term health, or maximizing performance at a target event?
+
+Based on answers, apply this mapping:
+- Q1 "back off" + Q4 "health" → **conservative**
+- Q1 "trust feeling" + Q2 "comfortable with fatigue" + Q4 "performance" → **aggressive**
+- Q3 "polarized" → **polarized** (regardless of other answers)
+- Q2 "comfortable with significant fatigue" + Q4 "performance" + Q1 "moderate" → **volume**
+
+State the recommendation with a one-sentence explanation connecting the athlete's answers to the persona's philosophy. Ask for confirmation.
+
+---
+
+Ask: **"Do you have a prescription file (training plan YAML) already, or would you like help creating one?"**
+
+- If existing prescription: go to Phase 3A
+- If creating new: go to Phase 3B
+
+---
+
+### Phase 3A — Existing Prescription
+
+Ask: **"What is the path to your prescriptions directory?"**
+(The directory that contains your training plan YAML files — e.g., `~/code/training/prescriptions/`)
+
+Check that the path exists and contains at least one `.yaml` or `.yml` file.
+
+- If it exists and has YAML files: confirm the directory and list the file(s) found. Note the path for Phase 4.
+- If it does not exist or has no YAML files: stop and output:
+  > "No prescription files found at `{path}`. Prescription YAMLs define your session-by-session training plan and are required before `adapt-plan` can run. See `PRESCRIPTION_FORMAT.md` in this repo for the schema and an example. Create at least one file there and re-run intake."
+
+---
+
+### Phase 3B — New Prescription (guided creation)
+
+Ask four questions together:
+
+1. **What training block are you starting?**
+   (base / build-1 / build-2 / race-specificity)
+2. **How many weeks is this block?**
+3. **How many training days per week do you plan?**
+4. **Which days are key sessions** (high-intensity or long endurance), and which are easy/recovery?
+
+Based on the answers, generate a skeleton YAML. Use this structure (adapt session count and names to match their answers):
+
+```yaml
+# {BlockType} — {N}-week block
+# Generated by engram-coach intake. Fill in session_date values for each session
+# and set power targets. See PRESCRIPTION_FORMAT.md for full field reference.
+
+block_name: {block_slug}  # e.g., build_1, base, race_specificity
+
+sessions:
+
+  # Week 1
+  - week: 1
+    day: {KeyDay1}
+    session_date: YYYY-MM-DD  # replace with actual date
+    session_name: W1_KeySession
+    total_duration_min: 90     # adjust to your target
+    warmup_power_low_pct: 40
+    warmup_power_high_pct: 65
+    cooldown_power_low_pct: 35
+    cooldown_power_high_pct: 45
+    intervals:
+      - duration_min: 10        # adjust interval length
+        power_low_pct: 85       # adjust to block type
+        power_high_pct: 92
+        count: 3
+        recovery_min: 5
+        recovery_power_low_pct: 45
+        recovery_power_high_pct: 55
+
+  - week: 1
+    day: {EasyDay1}
+    session_date: YYYY-MM-DD
+    session_name: W1_Endurance
+    total_duration_min: 120
+    effort_zone: Z1-Z2          # simple sessions use effort_zone instead of intervals
+
+  # (repeat pattern for remaining weeks)
+  # See PRESCRIPTION_FORMAT.md for all available fields
+```
+
+Ask: **"Where should I save this file?"** (e.g., `~/code/training/prescriptions/build_1.yaml`)
+
+Write the skeleton YAML to the specified path. Note the prescriptions directory (parent folder) for Phase 4.
+
+---
+
+### Phase 3C — Capture Model
+
+Ask: **"Which provider/model should ambient conversation capture use?"**
+(e.g., `anthropic/claude-sonnet-4-5`, `openai/gpt-5-mini` — an explicit
+`provider/model` string.)
+
+This model runs the separate headless extraction pass after each settled turn.
+It is independent of the interactive session model and is never inherited from
+it. If the athlete has no preference, recommend a small, inexpensive model:
+extraction emits concise atomic candidate records, not coaching reasoning.
+
+Record the exact `provider/model` string for Phase 4. Ambient capture cannot
+run without it: if neither this value nor the `ENGRAM_COACH_CAPTURE_MODEL`
+environment variable is configured, capture fails as a configuration error.
+
+---
+
+### Phase 4 — Configure
+
+Assemble the `config.json` content using values collected during intake:
+
+```json
+{
+  "_comment": "Generated by engram-coach intake. config.json is gitignored — machine-specific paths are never tracked.",
+  "active_profile": "default",
+  "profiles": {
+    "default": {
+      "active_persona": "{chosen-slug}",
+      "coaching_docs_dir": "{coaching-docs-path}",
+      "prescriptions_dir": "{prescriptions-path}",
+      "season": "{season-label}"
+    }
+  },
+  "capture": {
+    "model": "{provider/model from Phase 3C}",
+    "timeout_seconds": 60,
+    "max_candidates_per_turn": 3
+  }
+}
+```
+
+For `capture`: write the exact `provider/model` string collected in Phase 3C
+and exactly `timeout_seconds: 60` and `max_candidates_per_turn: 3`. The
+`ENGRAM_COACH_CAPTURE_MODEL` environment variable, when set nonblank, overrides
+**only** `capture.model`; the timeout and candidate limit always come from this
+block.
+
+For `season`: derive from the goal date (e.g., "May 2, 2026" → `"2026"`). If no date was given, ask: **"What season label should I use for coaching records?"** (e.g., `"2026"`, `"2026-spring"`)
+
+For `coaching_docs_dir`: if not yet established (no Path A history migration and not previously configured), ask: **"Where should coaching records be written?"** (e.g., `~/code/training/docs/coaching`) Note: create the directory if it does not exist.
+
+Show the assembled config.json content. Ask: **"Does this look correct? I'll write it to `{config_path}`."**
+
+On confirmation:
+- Write `{config_path}`
+- If `coaching_docs_dir` does not exist on disk, create it: `mkdir -p {coaching_docs_dir}`
+
+---
+
+### Phase 5 — Intake Record
+
+Write `{coaching_docs_dir}/{season}/intake.md`:
+
+```markdown
+---
+date: {today ISO date}
+type: intake
+persona: {slug}
+goal_event: {goal from Phase 1}
+goal_date: {date from Phase 1}
+sport: {modality from Phase 1}
+prescription: {prescriptions_dir}
+---
+
+# Coaching Intake
+
+## Goals
+
+**Event:** {goal}
+**Target date:** {date}
+**Sport:** {modality}
+
+## Coaching Persona
+
+**Active persona:** {slug} — {one-sentence persona description}
+
+**Selection rationale:** {why this persona was chosen — from Path A recommendation or Path B reasoning}
+
+## Plan History
+
+{If Path A: "Previously on: {plan/coach name}. {Philosophy description}. Mapped to {slug} because {reason}."}
+{If Path A + history migration: "Historical coaching records indexed from {path} — {N} documents available via qmd query."}
+{If Path B: "No prior formal plan. Persona selected based on intake questionnaire responses."}
+
+## Prescription
+
+**Prescriptions directory:** {path}
+**Active block:** {block_name of first/only YAML found, or "pending — skeleton created at {path}"}
+
+## Next Steps
+
+1. Fill in `session_date` values in your prescription YAML if you used the skeleton generator
+2. Run `qmd update` in the engram-coach repo after adding coaching docs
+3. Invoke `adapt-plan` after completing a key session:
+   `Read and follow ./skills/adapt-plan.md`
+```
+
+Run `qmd update` in the engram-coach repo to index the intake record.
+
+Output the completion summary:
+
+```
+✓ Intake complete
+
+Persona:         {slug}
+Goal:            {goal event} — {date}
+Prescription:    {prescriptions_dir}
+Capture model:  {provider/model}
+Coaching docs:   {coaching_docs_dir}
+Intake record:   {coaching_docs_dir}/{season}/intake.md
+
+Next: Read and follow ./skills/adapt-plan.md after completing a key session.
+```