devcoach 0.8.3 → 0.9.0

package/assets/SKILL.md

@@ -1,13 +1,19 @@
 ---
 name: devcoach
 description: >
-  Personal coaching engine: deliver, log, and manage progressive technical lessons.
-  Use when a devcoach hook cue asks for a lesson; when the user asks about their
-  learning — "what did I learn today/this week", "show my profile", "how good am I
-  at X", "coaching log", "lessons to revisit" — or asks to set up or reconfigure
-  devcoach ("setup devcoach", "redo onboarding", "reset my topics"); and after
-  completing a substantial technical task (code, review, commit, debugging, config,
-  queries, infra) to evaluate whether ONE lesson is due.
+  Use for the user's personal learning record and coaching data managed by
+  devcoach. Trigger when: (1) the user mentions devcoach in any form — setting it
+  up, redoing onboarding, resetting topics, or reviewing/rebuilding their profile
+  or notebook; (2) the user asks about their own learning or skill level — what
+  they learned recently, their coaching log or lesson history (by period, starred,
+  or marked don't-know), how good they are at a technology, lessons to revisit,
+  or whether new tech from their recent work should be tracked; (3) a devcoach
+  hook cue requests a lesson; (4) you just completed substantial technical work
+  (code, review, commit, debugging, config, queries, infra) — then evaluate
+  silently whether ONE lesson is due, even when coaching is never mentioned.
+  Do NOT use for ordinary development tasks on code, apps, or documents that
+  merely contain words like profile, lessons, or notebook — only when the subject
+  is the user's own coaching data.
 ---
 
 # devcoach — Progressive Coaching
@@ -17,10 +23,11 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 The three hard rules, before anything else:
 
-1. **The lesson card is printed as visible reply text BEFORE calling `log_lesson` —
-   and only once, ever.** If you suspect the card was never printed, do NOT self-correct
-   by re-printing: a devcoach hook verifies visibility after the turn and recovers a
-   missing card itself. A card printed twice is an error.
+1. **The lesson card is printed as plain reply text BEFORE calling `log_lesson` —
+   and only once, ever.** The user sees only text you write directly in the reply:
+   the body passed to `log_lesson` is INVISIBLE to them, and composing it does not
+   count as showing the card. If, after `log_lesson` returns, your reply does not
+   contain the card as written text, write it then — once. Never write it twice.
 2. **The card ends the reply.** After `log_lesson` returns, output nothing else — no
    "lesson logged", no summary. The card is the last visible text of the turn.
 3. **A cue you decline is a `skip_lesson` call.** If a devcoach hook asked for a lesson
@@ -37,6 +44,14 @@ user explicitly asks to (re-)initialise their profile — read `references/onboa
 in this skill's directory and follow it. Do not deliver a lesson in the same turn as
 `complete_onboarding`; end the response after confirming setup.
 
+## Review & rebuild
+
+When the user asks to review or rebuild their profile or notebook — "review my
+profile/notebook", "rebuild/refresh my notebook", "refresh my profile from my
+projects", "any new tech I should track?" — read `references/review.md` in this
+skill's directory and follow it. Those flows are incremental and non-destructive;
+only an explicit "redo onboarding" goes through `references/onboarding.md`.
+
 ## Before delivering a lesson
 
 Read the **`devcoach://briefing`** MCP resource — ONE silent read returns everything
@@ -83,6 +98,11 @@ Priority order:
 Tiebreaker: always prefer the profile topic. Never teach off-context lessons, and
 never pitch **below** the user's confidence band on that topic.
 
+When the task's real stack is **not tracked** in the profile, prefer offering to
+track it (Profile expansion below) over teaching it by analogy to a tracked
+topic — analogy filing records the lesson under the wrong stack and can hide an
+entire technology from the coaching record for months.
+
 **Depth per confidence** (per-topic, never an average): `0–3` junior — explain from
 scratch, analogies, no jargon · `4–6` mid — the why, alternatives, trade-offs ·
 `7–9` senior — edge cases, production trade-offs, historical context · `10` —
@@ -129,10 +149,13 @@ know / dont_know / skip) — never render a feedback question yourself. Read the
 
 - `"know"` / `"dont_know"` → confidence already adjusted server-side. Done.
 - `null` → elicitation unsupported/declined. Append the text prompt "Did that land?
-  ✅ know · ❌ don't know · ⏭ skip", collect the reply next turn, then call
-  `submit_feedback(id, value)` — but only when confidence is below the lesson's band
-  for "know" (within/above band → already calibrated, skip the call). Never call
-  `update_knowledge` on top of feedback.
+  ✅ know · ❌ don't know · ⏭ skip" — and this line may only ever appear DIRECTLY
+  BENEATH the card's closing band in your reply text. If the card is not right
+  above it (the body you passed to log_lesson is invisible to the user — composing
+  it is not printing it), write the full card first, then this line. Collect the
+  reply next turn, then call `submit_feedback(id, value)` — but only when
+  confidence is below the lesson's band for "know" (within/above band → already
+  calibrated, skip the call). Never call `update_knowledge` on top of feedback.
 
 **Starring:** after feedback, if it was `dont_know` on a mid/senior lesson, or
 `get_lessons({search: topic_id})` shows 2+ lessons on the topic, offer *"Want to save

package/assets/references/onboarding.md

@@ -21,20 +21,30 @@ This means a user who restores from backup has their knowledge automatically, so
 only Step 4 runs. On-demand re-setup ("redo onboarding", "reset my topics") always
 re-runs Steps 1–3 regardless of `knowledge_ready`.
 
-## Step 1 — Ask how to set up (always ask; never pick for the user)
+## Step 1 — Ask how to set up (strongly recommend Automatic; never pick for the user)
 
-Present a single choice using the client's question UI (e.g. AskUserQuestion in
-Claude Code). Offer exactly three options and mark **Automatic** as recommended:
+Read `devcoach://onboarding` FIRST — its `detected_stack`, `detected_projects`, and
+`scanned_projects` come from a scan of the user's **full Claude Code history** (every
+project Claude has worked in, ranked by recent activity), not just the current folder.
 
-- **Automatic (Recommended)** — detect the tech stack from this project and build a
-  profile from it.
+Then present a single choice using the client's question UI (e.g. AskUserQuestion in
+Claude Code). Offer exactly three options, and make **Automatic** the first option,
+**strongly recommended**, with its description citing the real evidence — name the
+project count and 2–3 detected topics with where they were seen, e.g. *"I scanned 9
+of your Claude Code projects and found TypeScript (dev-coach), Java (discordbot,
+over-night-runner), Swift (blueprince) — I can build your profile from that."*:
+
+- **Automatic (Strongly recommended)** — build the profile from the detected
+  history-wide stack; the user only confirms and adjusts confidences.
 - **Guided** — a step-by-step conversation to map knowledge, confidence levels, and
   topic groups (thorough, interactive).
 - **Import backup** — restore knowledge, lessons, and settings from an existing
   backup file.
 
-Do **not** default to Automatic silently — surface the choice and wait for the user's
-answer before proceeding.
+When the scan found nothing (`scanned_projects` 0 or an empty `detected_stack`),
+present Automatic without the evidence sentence — it falls back to the current
+project's files. Do **not** default to Automatic silently — surface the choice and
+wait for the user's answer before proceeding.
 
 **If Import backup:** ask for the file path and call `restore` (CLI) with it. Restore
 brings back knowledge entries automatically — no further DB steps needed. Re-read
@@ -44,11 +54,14 @@ Step 4. If `notebook_ready` is also true, proceed normally.
 ## Step 2 — Collect topics for the chosen mode
 
 **Automatic mode:**
-- Read `devcoach://onboarding` and present a merged topic list: `detected_stack`
-  (auto-detected from project files) enriched with relevant entries from
-  `default_topics` (the project's default knowledge map).
-- Show each topic with its suggested confidence. Ask the user to confirm, adjust,
-  or remove each: *"Looks right? Or enter 1–10 to change it."*
+- Present a merged topic list: `detected_stack` (history-wide, already merged with
+  the current project) enriched with relevant entries from `default_topics` (the
+  project's default knowledge map).
+- Show each topic with its suggested confidence **and its provenance** from
+  `detected_projects` — e.g. *"java 6 — seen in discordbot, over-night-runner"*.
+  Weight what you emphasise by `prompt_count` and `last_activity`: a stack the user
+  works in daily deserves more topics than a one-off experiment. Ask the user to
+  confirm, adjust, or remove each: *"Looks right? Or enter 1–10 to change it."*
 - After the list, ask: *"Anything else I missed? List any tools, languages,
   frameworks, or practices you work with regularly."* — add each with a confidence.
 
@@ -105,9 +118,11 @@ as the `notebook` field of the `complete_onboarding` call in Step 3. The tool sa
 to `~/.devcoach/learning-state.md` atomically with the profile (so it is never empty
 and never created before the user finishes).
 
-Make it **personalized**: draw on everything you know about *this* user — not only this
-onboarding conversation, but how they work across **all their projects** (languages and
-tools they reach for, recurring habits, strengths, and gaps you have observed elsewhere).
+Make it **personalized**: draw on everything you know about *this* user — this
+onboarding conversation, plus the real cross-project data in `detected_projects`
+(per-project stacks, activity volume and recency, and each project's auto-`memory`
+excerpt — distilled facts about how the user actually works). Cite project names and
+observed habits; never quote prompt text (it is not in the data, by design).
 Generic boilerplate is a failure; write specific, real notes. Use this structure:
 
 ```markdown

package/assets/references/review.md

@@ -0,0 +1,67 @@
+# devcoach — Review & rebuild flows
+
+Read this file when the user asks to review or rebuild their coaching setup:
+"review my notebook", "review my profile", "rebuild my notebook", "refresh my
+profile from my projects", "any new tech I should track?". These flows are
+**incremental and non-destructive** — the only destructive path is a full redo,
+which lives in `references/onboarding.md`.
+
+Route by intent:
+
+```
+review my profile / notebook      →  Review (below)
+rebuild / refresh my notebook     →  Rebuild notebook (below)
+new tech to track?                →  New tech check (below)
+redo onboarding / reset topics    →  references/onboarding.md, Steps 1–3 (confirm first — it wipes)
+```
+
+## Review
+
+1. Read `devcoach://briefing` — one silent read returns the profile, the taught
+   topics, and the notebook.
+2. Walk the user through the profile **grouped, not topic-by-topic**: show each
+   group with its topics and confidences, and ask what looks wrong. Apply
+   changes as they come: `update_knowledge` (confidence), `add_topic` /
+   `remove_topic` (membership).
+3. Then show the notebook section by section (Observations, Recurring patterns,
+   Recommended focus, Open hypotheses). Ask what is stale or wrong. Fold the
+   edits into a revised full markdown and save it with ONE `update_notebook`
+   call at the end — never one call per edit.
+4. Close with the New tech check below.
+
+## Rebuild notebook
+
+Re-derive the notebook from real data; the knowledge map is untouched.
+
+1. Read `devcoach://onboarding` — `detected_projects` carries the history-wide
+   evidence: per-project stacks, activity volume and recency, and auto-memory
+   excerpts. Read `devcoach://briefing` for the current notebook and profile,
+   and `get_lessons({period: "all"})` for feedback history (`dont_know` lessons
+   are open gaps).
+2. Compose a fresh notebook (structure in `references/onboarding.md`, Step 4):
+   cite real cross-project observations — project names, stacks, what recurs,
+   what the memories reveal about how the user works. Preserve prior notes that
+   are still true; drop the stale ones. Never quote prompt text — it is not in
+   the data, by design.
+3. Show the draft, adjust to taste, save with `update_notebook`.
+
+## New tech check (keep the profile curated)
+
+Compare `detected_stack` + `detected_projects` (from `devcoach://onboarding`)
+against the current profile:
+
+- Candidate = a detected topic **absent from the profile** that appears in **2+
+  scanned projects** or in the current project.
+- Propose **at most 5** candidates, each with its evidence ("seen in discordbot
+  and over-night-runner") and a suggested starting confidence (the detected
+  value). Use the client's question UI; `add_topic` ONLY for the ones the user
+  confirms — never add silently.
+- Also surface retirement candidates: profile topics at confidence ≤ 3 that
+  appear in **no** scanned project. Offer `remove_topic`; keeping them is fine.
+- Nothing qualifies → say so in one line and stop. An overcrowded topic list
+  dilutes lesson choice — fewer, real topics beat completeness.
+- `devcoach://onboarding` unreachable, or `detected_projects` empty → derive
+  candidates from lesson history instead (`get_lessons`: recurring stacks in
+  `task_context` that lack a matching topic), tell the user the evidence is
+  history-only, and defer the retirement pass — never guess retirements
+  without profile access.

package/assets/static/relative-time.js

@@ -18,7 +18,15 @@
     return rtf.format(-Math.floor(diffDays / 365), 'year');
   }
 
-  document.querySelectorAll('[data-ts]').forEach(function (el) {
-    el.textContent = relativeTime(el.dataset.ts);
+  function applyRelativeTimes(root) {
+    root.querySelectorAll('[data-ts]').forEach(function (el) {
+      el.textContent = relativeTime(el.dataset.ts);
+    });
+  }
+
+  applyRelativeTimes(document);
+  /* HTMX-swapped fragments (lesson rows, lesson meta) arrive with raw dates. */
+  document.body.addEventListener('htmx:afterSettle', function () {
+    applyRelativeTimes(document);
   });
 })();