Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
bump: patch
---

### Changed

- Skill instructions for course-digest, distill, docpage-digest, map-corpus and video-digest use
plain emphasis instead of capital letters, and drop notes about how a rule came about.
- Corrected facts the instructions had wrong: the screenshot file names and folders the
extractor writes, the referer header it sends, where key-frame images live, and the claim-inventory
phase number. Version-dependent tool facts (Chrome remote debugging, ffmpeg `-ss` and its
`whisper` filter, the plugin variables) now point at their upstream pages.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
bump: patch
---

### Changed

- The audit skill says the orchestrator writes the report, `latest.json` and the history line,
and the session writes none of them.
- The severity rubric and remediation policy now match the checks: tamper protection off is WARN,
a detection is CRIT only with no recorded remediation, Clear-TempFiles triggers on the
`disk-space` check, and a first run is a dry run. Capital-letter emphasis is lower-cased.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- The setup skill uses plain emphasis instead of capital letters.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
bump: patch
---

### Changed

- The audit and audit-posture skills use plain emphasis instead of capital letters.
- Three eval grader criteria drop a trailing note that repeated the criterion; what each grader
checks is unchanged.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
bump: patch
---

### Changed

- `miro_bulk_create_sticky_notes` says a mid-batch failure returns an error without the IDs of
notes already placed, so check the board before retrying. `miro_attach_tag` states what it
returns and that it errors on an item type that takes no tags.
- The setup skill names its one API gate: a request runs only when `verify-api` was passed, and
only the read-only call.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
bump: patch
---

### Changed

- The config reference points at the upstream pages for subagent `model` values and the effort
cap's scopes instead of restating them. Skill headings and the drift-audit skeptic prompt use
plain emphasis instead of capital letters.
- The `su-apply-guard-off-confirms` eval no longer expects a local-layer offer, which its own
description says cannot arise at a home root.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
bump: patch
---

### Changed

- The audit skill and its context files use plain emphasis instead of capital letters and drop
design-history asides. The principles references name the marketplace repository as the home
of the `lib/hook-utils.test.sh` worked example.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
bump: patch
---

### Changed

- The name-it-better skill and its sources file, description included, use plain emphasis
instead of capital letters.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
bump: patch
---

### Changed

- The audit and delta skills and their context files use plain emphasis instead of capital
letters, and the scrutiny method drops a history aside.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
bump: patch
---

### Changed

- The `discriminate.py` and `spawn-census.sh` refusal messages and the harness README state the
rule and its reason without the story of an earlier run.
- The verify skill requires one verifier and says when a second is worth dispatching. Skill and
catalog facts about pyperf, Criterion, benchstat, JMH, `gh run view` and plugin auto-update
point at their upstream pages.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
bump: patch
---

### Changed

- The animate, scene and vfx skills say to judge motion from the preview sheet, not the GIF, and
drop a restated claim about one browser tool's `file:` URL handling.
6 changes: 3 additions & 3 deletions plugins/knowledge/reference/citation-shape.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Tracked citation shape

This document owns the citation shape that `knowledge` skills use whenever a TRACKED output
This document owns the citation shape that `knowledge` skills use whenever a tracked output
refers to fetched external content. The rule it serves: **tracked outputs cite, never copy**.
The verbatim snapshot stays in the untracked work slice; only the citation crosses into anything
committed.
Expand Down Expand Up @@ -44,7 +44,7 @@ checkable against its slice without re-fetching.

## Sub-resource anchors (optional extension)

A citation MAY narrow to a region of the resource with the emitting skill's deterministic node
A citation may narrow to a region of the resource with the emitting skill's deterministic node
id (e.g. map-corpus `n0007-05b0396b`, whose trailing 8 hex are the first 8 of the node's span
hash). Serialization is fixed so independent emitters converge:

Expand All @@ -66,7 +66,7 @@ skill's manifest format doc.

## Drift

A citation asserts what WAS fetched, not what the URL serves now. On re-fetch, a differing hash
A citation asserts what was fetched, not what the URL serves now. On re-fetch, a differing hash
means upstream drift: record the new fetch as a new citation (new date, new hash) and note the
drift; never edit the old citation's hash in place and never silently re-snapshot over the slice
the old citation points into.
Expand Down
2 changes: 1 addition & 1 deletion plugins/knowledge/reference/providers/github/repo-tree.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ gh api "repos/<owner>/<repo>/git/trees/<sha>?recursive=1" > discovery/repo-tree.
```

The snapshot is immutable like every other discovery snapshot. Per
[Get a tree](https://docs.github.com/en/rest/git/trees#get-a-tree) (read 2026-11-02): any value of
[Get a tree](https://docs.github.com/en/rest/git/trees#get-a-tree) (read 2026-11-02; recheck when that page changes its truncation limits): any value of
`recursive` returns the whole subtree, each `tree` entry carries `path`, `mode`, `type` and `sha`,
and a recursive listing is capped at 100,000 entries and 7 MB. Past the cap the response sets
`truncated` to `true`, and the parser refuses it: a truncated listing is not a complete
Expand Down
10 changes: 5 additions & 5 deletions plugins/knowledge/skills/course-digest/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ Slug conformance is form-only (kebab-case `[a-z0-9-]`, ≤ 40 chars, Windows-res
## Prerequisites (verify before starting)

1. **course-extraction deps**. `node "${CLAUDE_PLUGIN_ROOT}/skills/course-digest/extraction/setup-deps.mjs" --data-dir "${CLAUDE_PLUGIN_DATA}"`. Installs the pipeline's node dependencies into `${CLAUDE_PLUGIN_DATA}` (persists across plugin updates) and provisions Playwright's Chromium into `${CLAUDE_PLUGIN_DATA}/ms-playwright`. Idempotent. Safe to re-run, and re-run after a plugin update.
2. **Platform auth**. Set `COURSE_EMAIL`/`COURSE_PASSWORD` (Dometrain → Clerk) or `TEACHABLE_EMAIL`/`TEACHABLE_PASSWORD` (Teachable) in your shell before invoking; they inherit into the pipeline's node subprocess. The env-var prefix is course-config-driven via `platformConfig.authEnvPrefix`. Session cookies persist under `${CLAUDE_PLUGIN_DATA}/auth/<platform>.auth-state.json` and are reused across runs. **Interactive manual login is the fallback** when no credentials are set. It opens a browser window for you to log in. NOTE: the manual-login prompt (`node:readline` + headed browser) may not function under headless plugin execution; env-var + cookie-reuse carry the skill regardless, and manual login is a known limitation there, not a blocker. These credentials live in shell environment variables, not in plugin `userConfig`: this plugin's `userConfig` options are non-secret scalars. Where option values are kept: <https://code.claude.com/docs/en/plugins/manifest-reference#where-values-are-stored>.
2. **Platform auth**. Set `COURSE_EMAIL`/`COURSE_PASSWORD` (Dometrain → Clerk) or `TEACHABLE_EMAIL`/`TEACHABLE_PASSWORD` (Teachable) in your shell before invoking; they inherit into the pipeline's node subprocess. The env-var prefix is course-config-driven via `platformConfig.authEnvPrefix`. Session cookies persist under `${CLAUDE_PLUGIN_DATA}/auth/<platform>.auth-state.json` and are reused across runs. **Interactive manual login is the fallback** when no credentials are set. It opens a browser window for you to log in. The manual-login prompt (`node:readline` + headed browser) may not function under headless plugin execution; env-var + cookie-reuse carry the skill regardless, and manual login is a known limitation there, not a blocker. These credentials live in shell environment variables, not in plugin `userConfig`: this plugin's `userConfig` options are non-secret scalars. Where option values are kept: <https://code.claude.com/docs/en/plugins/manifest-reference#where-values-are-stored>.
3. **ffmpeg**, required for video frame extraction (scene detection, interval capture). Check: `ffmpeg -version`. Install: `winget install Gyan.FFmpeg` (Windows), `brew install ffmpeg` (macOS), `sudo apt install ffmpeg` (Linux). Floor 7.1+ (newer codecs, AV1, Opus, degrade or fail below this).
4. **ImageMagick 7**, required by `classify-frames.js` for contact sheet generation (`magick montage`). Check: `magick -version`. Install: `winget install ImageMagick.ImageMagick` (Windows), `brew install imagemagick` (macOS), `sudo apt install imagemagick` (Linux). Ubuntu <26.04 ships v6. V7 may require building from source.
4. **ImageMagick 7**, required by `classify-frames.js` for contact sheet generation (`magick montage`). Check: `magick -version`. Install: `winget install ImageMagick.ImageMagick` (Windows), `brew install imagemagick` (macOS), `sudo apt install imagemagick` (Linux). Where the distribution's package is v6 (`magick` is missing or reports 6.x), v7 may require building from source.
5. **A browser tool for Phase 1 (course discovery)**, picked by the browser-tool rubric `/testing:run-e2e` owns. A missing tool is a prerequisite gap to report, not a reason to switch tools. Frame extraction needs no browser tool: the scripts read HLS URLs themselves.

If any prerequisite fails, stop and inform the user. Re-run `setup-deps.mjs` for the node dependencies + Chromium; the media binaries (ffmpeg, ImageMagick) are OS-level installs via your platform's package manager per the commands above.
Expand Down Expand Up @@ -102,12 +102,12 @@ node "${CLAUDE_PLUGIN_ROOT}/skills/course-digest/extraction/run.mjs" --data-dir
node "${CLAUDE_PLUGIN_ROOT}/skills/course-digest/extraction/run.mjs" --data-dir "${CLAUDE_PLUGIN_DATA}" extract-course.js --course-dir <path-to-course-data> --metadata-only
```

Script uses Playwright's bundled Chromium with a fresh temp context (not Chrome itself. Chrome 136+ blocks CDP on default profiles). Auth handled via `addCookies()` after context launch: with credentials set it logs in and saves state; subsequent runs inject cached cookies automatically. Skips already-extracted lessons (crash-safe, resumable). Runs headless by default (`--show-browser` to show the browser).
Script uses Playwright's bundled Chromium with a fresh temp context (not Chrome itself, which ignores the remote-debugging switches on its default data directory; the version and switches: <https://developer.chrome.com/blog/remote-debugging-port>). Auth handled via `addCookies()` after context launch: with credentials set it logs in and saves state; subsequent runs inject cached cookies automatically. Skips already-extracted lessons (crash-safe, resumable). Runs headless by default (`--show-browser` to show the browser).

**Key technical details:**

- Uses `--disable-blink-features=AutomationControlled` to bypass automation detection on course platform logins
- Chrome profiles are NOT used. Playwright's own Chromium with a dedicated temp context dir in the OS temp directory
- Chrome profiles are not used. Playwright's own Chromium with a dedicated temp context dir in the OS temp directory
- Auth state saved to `${CLAUDE_PLUGIN_DATA}/auth/<platform>.auth-state.json` (session expiry depends on the platform's auth provider, configured in `platformConfig.authWarnDays`)
- HLS video URLs captured via DOM read from the video player element (selector from `platformConfig.videoPlayerSelector`). No claude-in-chrome needed
- Frame extraction via ffmpeg scene detection (threshold 0.1), with interval fallback for sparse results
Expand Down Expand Up @@ -200,7 +200,7 @@ Multi-modal extraction gaps beyond these three (code OCR from frames, slide-text

### Dedup semantics

Dedup phase (`classify-frames.js --phase dedup`) **reports** near-duplicates but does NOT
Dedup phase (`classify-frames.js --phase dedup`) **reports** near-duplicates but does not
delete frame files. Actual frame curation happens in `generate-manifests.js` which sets
`keep: true/false` per frame. Frame PNG files remain on disk. Manifests define which frames to use
during synthesis.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,9 @@ at higher cost.
For higher accuracy on specific frames, Claude's vision can read PNG files directly during
summarization phase.

**Recommended approach**: Hybrid two-pass. Tesseract on all frames (free, fast), then
selectively send high-value frames (code-heavy keyframes) to Claude vision during summarization.
**Recommended approach**: start with Claude vision on the curated keyframes (Option B below). Once
Option A is built, run Tesseract on all frames (free, fast), then send high-value frames
(code-heavy keyframes) to Claude vision during summarization.

**Output**: `code-snippets.md` per lesson, containing extracted code blocks.

Expand Down
15 changes: 8 additions & 7 deletions plugins/knowledge/skills/course-digest/context/storage-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,10 @@ courses/<platform>/<slug>/
notes.md # Lesson notes (if platform provides them)
code-snippets.md # Code extracted from lesson (inline code blocks)
resources.json # Download URLs, article links, PDF links (Teachable adapter)
screenshots/ # Key frames as PNG files
001-slide-intro.png # Zero-padded, descriptive suffix
002-code-example.png
screenshots/ # Extracted frames as PNG files
scene-01/
scene_0001.png # Scene-detection frame
interval_0001.png # Interval-capture fallback frame
02-what-will-you-learn/
transcript.md
...
Expand Down Expand Up @@ -205,26 +206,26 @@ Per-lesson resource metadata: download URLs, article links, PDF links extracted
- Understanding progression (how codebase evolves lesson by lesson)
- Catching discrepancies (what code does vs what instructor says)

Phase 3 synthesis agents read BOTH: repo for architectural context, downloads for lesson-specific teaching. Repo alone misses journey; ZIPs alone miss big picture.
Phase 3 synthesis agents read both: repo for architectural context, downloads for lesson-specific teaching. Repo alone misses journey; ZIPs alone miss big picture.

For courses with GitHub repos instead of ZIPs, `code/repo/` is a shallow clone and per-section analysis comes from `git log` or directory-based sections.

### Screenshots

- Format: PNG
- Max width: 1280px
- Naming: `{NNN}-{descriptive-suffix}.png` (e.g., `001-test-list-creation.png`)
- Naming: the extractor writes `screenshots/scene-01/scene_NNNN.png` (scene detection) and `screenshots/scene-01/interval_NNNN.png` (interval fallback)
- Only capture when visual content adds information beyond transcript:
- Code on screen (IDE, terminal)
- Architecture diagrams
- Slides with visual content
- UI demonstrations
- Do NOT screenshot talking-head segments; the transcript covers those
- Do not screenshot talking-head segments; the transcript covers those

## Size management

- **No video/audio files**, ever
- **Screenshots**: resize to 1280px wide, compress with reasonable quality
- **Transcripts**: typically 1-3 KB per minute of video (~30 KB for a 30-min lesson)
- **course.json**: grows with lessons but stays under 50 KB for large courses
- **Expected total per course**: 1-5 MB for transcripts + metadata, 10-50 MB with screenshots
- **Expected total per course**: 1-5 MB for transcripts + metadata; with screenshots, size it from the measured per-lesson figures in [screenshot-strategy.md](../reference/screenshot-strategy.md#file-size-management)
18 changes: 9 additions & 9 deletions plugins/knowledge/skills/course-digest/context/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@

Eight phases executed in order. Each phase produces artifacts consumed by subsequent phases.

**Critical ordering rule:** ALL context must be gathered before summarization begins. Module
**Ordering rule:** all context must be gathered before summarization begins. Module
summaries generated from transcripts alone are incomplete. They miss code syntax, visual
diagrams, repo patterns. Full sequence: Extract → Process Frames → Analyze Code
Repo → Validate → THEN Synthesize.
Repo → Validate → then Synthesize.

**Completeness markers:** Module summaries should note their context sources:

Expand Down Expand Up @@ -183,7 +183,7 @@ only, then discard.
## Phase 3: Synthesize

**Goal:** Produce per-module summaries combining all three knowledge modalities into a unified
analysis. A `[full-context]` summary is NOT just transcripts with metadata. It synthesizes what
analysis. A `[full-context]` summary is not just transcripts with metadata. It synthesizes what
the instructor says, what's shown on screen, what the actual code does.

**Three modalities (all required for `[full-context]`):**
Expand All @@ -192,7 +192,7 @@ the instructor says, what's shown on screen, what the actual code does.
|----------|--------|-----------------|
| Audio/transcript | `transcript.md` per lesson | Instructor explanations, arguments, verbal emphasis, things said but not shown |
| Visual/frames | Frame PNG files + `manifest.json` | Code on screen, architecture diagrams, slides, terminal output, UI demos |
| Code/repo | `code/repo/<section>/` source files | Actual implementation patterns, DI setup, project structure, what the code DOES vs what the instructor SAYS it does |
| Code/repo | `code/repo/<section>/` source files | Actual implementation patterns, DI setup, project structure, what the code does vs what the instructor says it does |

**Multi-agent approach per module:**

Expand Down Expand Up @@ -238,7 +238,7 @@ Build this table during Phase 2c. Example from per-section repo:
**Per module, identify:**

- Core concepts taught (with lesson references)
- Code patterns demonstrated (from transcripts AND actual code AND visual frames)
- Code patterns demonstrated (from transcripts and actual code and visual frames)
- Discrepancies between what's said, shown, and coded (these are high-value findings)
- Best practices advocated
- Anti-patterns warned against
Expand All @@ -261,7 +261,7 @@ Build this table during Phase 2c. Example from per-section repo:

## Phase 5: Recommend

**Goal:** Map course learnings to THIS repository. Primary deliverable.
**Goal:** Map course learnings to this repository. Primary deliverable.

1. Read `course-summary.md` + all module summaries
2. Read repository's CLAUDE.md, `.claude/rules/`, key architecture files
Expand Down Expand Up @@ -303,9 +303,9 @@ When invoked with `/knowledge:course-digest resume <slug>`:

## Execution model: sequential vs parallel

**Bot detection constraint:** All browser-based extraction (Phase 2) MUST be sequential. Dometrain and
**Bot detection constraint:** All browser-based extraction (Phase 2) must be sequential. Dometrain and
similar platforms rate-limit and detect automated access. Navigate no faster than ~2 seconds between
lessons. Do NOT parallelize DOM interactions, browser contexts, lesson navigation.
lessons. Do not parallelize DOM interactions, browser contexts, lesson navigation.

**What can run in parallel:**

Expand Down Expand Up @@ -351,4 +351,4 @@ at recording time. Before using recommended patterns, verify current stable vers
`/discovery:research` or `mcp__nuget__get_latest_package_version`.

**Rule:** Course content is a starting point for research, not a final answer. Every action item
gets `/discovery:explore` + `/discovery:research` verification AT TIME OF INTEGRATION, not at digest time.
gets `/discovery:explore` + `/discovery:research` verification at time of integration, not at digest time.
Loading
Loading