@olegkoval/agent-skills 1.35.3 → 1.37.0

package/plugins/olko-creative/skills/music-to-plex/references/youtube-full-album-fallback.md

@@ -0,0 +1,34 @@
+# YouTube full-album fallback salvage
+
+Use this when RuTracker / Download Station fails and the only practical source is a YouTube full-album upload.
+
+## Pattern observed
+
+- `yt-dlp` can pull a clean album source, but uploader metadata is often garbage.
+- Treat the first download as a source artifact, not Plex-ready media.
+- Validate tags with `ffprobe` or `mutagen` before any organize step.
+
+## Repair flow
+
+1. Download the upload at highest audio quality.
+2. Inspect embedded metadata immediately.
+3. If the output is one long FLAC, split it into tracks using album track timings.
+4. Retag each track with canonical artist, album, year, tracknumber, and tracktotal.
+5. Embed official cover art, not the YouTube thumbnail.
+6. Move the repaired album into the final NAS music path.
+7. Refresh Plex only after the final path exists.
+8. Verify the album appears in Plex search.
+
+## NAS transfer workaround
+
+When `rsync` or `scp` fights remote path quoting, use a tar pipe instead:
+
+```bash
+cd /local/staging && tar -cf - *.flac | ssh user@nas 'cd "/volume1/music/.../Release" && tar -xf -'
+```
+
+If macOS leaves AppleDouble sidecar files on the NAS, remove `._*` before refresh.
+
+## Session note
+
+For `Ozzy Osbourne - Diary Of A Madman (1981)`, the fallback source was a YouTube full-album upload. The tracks were downloaded to FLAC, retagged, cover art embedded, copied into `/volume1/music/metal/Ozzy Osbourne/Diary Of A Madman (1981)`, AppleDouble files removed, and Plex refreshed with `mtp refresh --path`.

package/plugins/olko-creative/skills/music-to-plex/references/youtube-lineage-playlist-fallback.md

@@ -0,0 +1,33 @@
+# YouTube-only lineage playlist fallback
+
+Use when the user wants a new DJ crate or playlist based on mood/lineage rather than a formal release request, and the intended path is YouTube track finding/downloading only.
+
+## Trigger
+
+- The user says things like "check this message and create new playlist" and provides lane/feeling language instead of a single album.
+- The brief is built from references, influences, or lineage tags such as "classic deep house DNA", "modern disco/deep house revival", "jazzy/warm cuts", or a left-field closer.
+- The task is explicitly on the YouTube branch, not a tracker or store purchase flow.
+
+## Pattern
+
+1. Convert the message into a small set of lanes first.
+2. Pick 1-3 anchor artists or canonical tracks per lane.
+3. Search exact titles with `yt-dlp`/YouTube query strings before broadening the search.
+4. Prefer official or Topic uploads, then the cleanest stable upload with the closest duration and metadata match.
+5. Assemble a local crate manifest, tracklist, and playlist file.
+6. Verify the files exist and the playlist content matches the intended lane order.
+
+## Curation notes
+
+- Keep the middle of the set mix-friendly.
+- Use the final lane for the emotional curveball or taste-flex closer.
+- If the user explicitly says the branch is YouTube-only, do not route through tracker/search paths for acquisition.
+- If Spotify or another catalog route is unavailable, skip it and continue with the YouTube branch instead of stalling.
+
+## File outputs
+
+- `00_MANIFEST.json`
+- `00_TRACKLIST.md`
+- `00_PLAYLIST.m3u8`
+
+This reference is session-derived but the pattern is reusable for future YouTube-only crate builds.

package/plugins/olko-creative/skills/music-to-plex/references/youtube-playlist-import.md

@@ -0,0 +1,50 @@
+# YouTube-first playlist import for MTP
+
+Use this flow when the user gives a YouTube playlist URL or a plain track list and wants it landed in Plex.
+
+## Input shapes
+- Playlist URL
+- Plain list of `Artist - Title` lines
+
+If only a track list is provided, resolve each track on YouTube first, then download in album/sequence order.
+
+## Download + staging
+Use max-quality audio extraction and preserve ordering with explicit numbering:
+
+```bash
+yt-dlp -x --audio-format flac --audio-quality 0 \
+  --write-thumbnail --convert-thumbnails jpg --embed-thumbnail \
+  --add-metadata \
+  -o "/tmp/mtp_youtube_crates/<crate>/work/raw/%(playlist_index)02d - %(title)s.%(ext)s" \
+  "<youtube-url>"
+```
+
+Notes:
+- Keep a manifest with index, source URL, resolved artist/title, and final filename.
+- For VA / DJ-style sets, keep track order stable even if metadata is messy.
+- If a title needs cleanup, fix it in tags, not by renaming out of sequence.
+
+## Import into Plex
+- Copy the finalized files into the NAS import path that Plex scans for the music section.
+- Trigger a library scan after the copy.
+- Create a normal Plex playlist from the imported track rating keys in the exact source order.
+
+## Verification
+Prefer proof over assumptions:
+- Check Plex scanner logs for `Added new metadata item` / `Loaded metadata for ...` on each track.
+- Confirm the imported track by querying Plex search directly and inspecting the returned `ratingKey`, `title`, `originalTitle`, and `parentTitle`.
+- For playlist verification, read the playlist back and enumerate items in order.
+
+## Plex metadata quirks
+- For compilation-style sets, Plex often shows `grandparentTitle=Various Artists`.
+- The displayed `title` may be the track title, while `originalTitle` carries the artist.
+- Search by both artist and title when matching imported tracks.
+- If a search query misses a track, try the cleaned title and artist separately.
+
+## Session-proven pattern
+The Deep Lineage Set import worked by:
+1. staging 8 FLAC tracks from YouTube,
+2. copying the final files into a Plex-scanned NAS import directory,
+3. refreshing Plex,
+4. creating a playlist in the source order,
+5. verifying all 8 items and their order.

package/plugins/olko-creative/skills/music-to-plex/references/youtube-track-resolution-heuristics.md

@@ -0,0 +1,23 @@
+# YouTube track resolution heuristics
+
+Use this when a user gives a plain `Artist - Title` list and wants it turned into a Plex playlist.
+
+## Search pattern
+- Run `yt-dlp --flat-playlist --dump-json "ytsearch5:<artist> <title>"` for each line.
+- Keep the source order from the user list. Never reorder by search result rank.
+
+## Scoring
+Prefer results with:
+1. exact title match,
+2. artist match in the channel/uploader name,
+3. `Topic` channel or official upload,
+4. clean metadata over remix/edit clutter.
+
+## Pitfalls
+- The first search hit is often wrong for house/disco catalog cuts.
+- If the user only gives a vibe list and not a playlist name, derive a short title from the theme, then ask once before creating the Plex playlist.
+- For compilation-style uploads, check both title and channel before deciding.
+
+## Verification
+- After download, confirm each track title still maps to the intended line.
+- When building the Plex playlist, read it back and verify item order matches the source list.

package/plugins/olko-creative/skills/music-to-plex/references/zero-track-playlist-recovery.md

@@ -0,0 +1,21 @@
+# Zero-track playlist recovery
+
+Use this when Plex shows a playlist shell but the track list is empty or `0 tracks`.
+
+## What it means
+
+- The playlist object exists.
+- The import likely failed to attach playable items, or the items have not been indexed yet.
+- Do not treat the playlist as done until Plex returns leaf items.
+
+## Recovery order
+
+1. Read back the playlist with `GET /playlists/<id>/items`.
+2. Confirm the returned leaf count matches the source track count.
+3. Compare the returned order with the intended playlist order.
+4. If the playlist is still empty, re-check the source track `ratingKey` list before trying another create.
+5. If the UI says `0 tracks` but the API returns items, trust the API and let PlexAmp refresh.
+
+## Rule
+
+A playlist is only imported when the API read-back shows the expected number of items and order. The UI tile alone is not proof.

package/plugins/olko-garmin-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-garmin-kit",
   "description": "Build, test and publish Garmin Connect IQ watch faces.",
-  "version": "1.35.3",
+  "version": "1.37.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-git-tools/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-git-tools",
   "description": "Everyday git and GitHub CLI operations: conventional commits, branch hygiene.",
-  "version": "1.35.3",
+  "version": "1.37.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-github-pr/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "olko-github-pr",
   "description": "Drive GitHub pull requests to merge-ready: review-bot loops, CI fixes, descriptions, dependency triage.",
-  "version": "1.35.3",
+  "version": "1.37.0",
   "author": {
     "name": "Oleg Koval"
   },

package/plugins/olko-github-pr/skills/lekker-review/README.md

@@ -0,0 +1,60 @@
+# lekker-review
+
+FAANG-quality PR code review for GitHub. It gathers the context a human reviewer
+would gather and checks the branch out into an isolated worktree when the depth
+requires one. `scan` runs two triage agents without a verifier. `medium` and
+`deep` run five specialists and attempt proofs for at most five non-rule
+Critical findings.
+
+![lekker-review at a glance](assets/poster-overview.png)
+
+## Why it is not a checklist reviewer
+
+Most review tooling reports whatever the model believed on its first pass.
+This skill spends most of its budget trying to disprove itself.
+
+![How findings are proved](assets/poster-proof.png)
+
+- **Adversarial verification.** `medium` sends non-rule Criticals through an
+  independent verifier's five-challenge refutation; `deep` also sends
+  Importants. `scan` does not run verifiers.
+- **Proof of bug.** In `medium` and `deep`, up to five non-rule Criticals are
+  sent to prover agents that attempt to write and run a failing test. A proof
+  that comes back green is counter-evidence: the finding is downgraded or
+  explicitly justified, never quietly kept.
+- **Hard-rule exemption.** A finding tagged with a `rule` keeps Critical
+  severity and skips verification, because the verifier asks runtime-failure
+  questions that a standards violation can never answer.
+- **Fix mode.** `--fix` has one agent edit each file, a read-only verifier read
+  the real `git diff`, and the captured proof re-run. If the proof stays red the
+  group is reverted. Nothing is pushed without explicit confirmation.
+
+## Requirements
+
+Claude Code only. The review pipeline needs the Workflow tool for multi-agent
+orchestration and the Artifact tool for the living review page. `git` and an
+authenticated `gh` are required.
+
+## Setup
+
+`references/house-rules.md` ships as a template. Replace its example rules with
+your team's own non-negotiables, the ones that should always be Critical
+regardless of review depth. The skill has no hard rules of its own: everything
+blocking comes from that file.
+
+## Usage
+
+```text
+lekker-review https://github.com/owner/repo/pull/123
+lekker-review owner/repo 123 deep --post
+lekker-review owner/repo 123 --fix
+```
+
+Depth is auto-selected from the diff size when you do not name one: `scan` under
+150 changed lines and 5 files, `deep` over 800 changed lines or 25 files or when
+the diff touches migrations or `*.sql`, `medium` otherwise.
+
+## Regenerating the posters
+
+The posters are self-contained HTML in `assets/`. Open either file in a browser
+at a 1280x720 viewport and screenshot it to regenerate the PNG.

package/plugins/olko-github-pr/skills/lekker-review/SKILL.md

@@ -329,6 +329,50 @@ anchors. Apply your own judgment to every finding.
 - Pre-existing code not touched by this diff
 - Anything you are not confident about - omit rather than hedge
 
+**Approval standard.** The verdict answers "does this definitely improve the
+codebase's health", not "is this how I would have written it". Perfect code does
+not exist. `✅ LGTM - ship it` is the right call for a change that improves
+health and violates no hard rule, even with open Observations or Idiomatic
+findings. Reserve `🚫 Needs work` for an unfixed Critical, a hard-rule
+violation, or an Important finding that changes external behaviour or data
+shape. Never manufacture a Critical to justify a verdict, and never block on
+taste.
+
+**PR sizing.** Judge how much a reviewer must hold at once, not the raw diff
+count:
+- Under ~300 changed lines, or larger but one logical change: no finding.
+- Over ~800 changed lines spanning more than one logical change: `important`,
+  and name the split. Pick the strategy that fits - stack (sequential
+  dependencies), by file group (different reviewers), horizontal (shared code
+  and stubs first, then consumers), vertical (smaller full-stack slices).
+- A diff that both refactors existing code and adds new behaviour: `important`
+  at any size. Those are two PRs, and bundling them hides the real change.
+- A change that pushes a single file past ~1000 total lines with no
+  decomposition: `observation`. Ask for the extraction first, then the feature.
+Exempt: whole-file deletions and mechanical or automated refactors, where the
+reviewer verifies intent rather than every line.
+
+**Verify the verification.** Read the PR body for the author's verification
+story: which tests were run, whether the build passed, whether it was exercised
+manually, screenshots for a UI change, a before/after for a behaviour or
+performance change. A non-trivial PR whose body claims nothing about
+verification is an `observation` naming the evidence that is missing. `CI: ✅
+All passing` is not a verification story - it only says the suite that already
+existed still runs.
+
+**Rationalizations to reject.** If one of these is the reason a finding is about
+to be dropped or softened, keep the finding:
+
+| Rationalization | Reality |
+|---|---|
+| "The tests pass, so it's fine" | Tests do not catch architecture, security, or data-shape problems. |
+| "It works, that's good enough" | Working code that is unreadable or insecure is debt that compounds. |
+| "The refactor makes it cleaner" | Relocating complexity is not reducing it. Count the concepts a reader holds. |
+| "It's only a small addition to this file" | Judge the resulting structure, not the diff size. |
+| "It's just a version bump" | A bump is a behaviour change nobody in the PR wrote. |
+| "They'll clean it up later" | Later does not come. Require it now, or require a ticket. |
+| "An agent wrote it, so it's probably fine" | Generated code needs more scrutiny, not less: it is confident and plausible when wrong. |
+
 **Idiomatic & Consistency exception:** the conventions agent raises non-blocking
 suggestions ONLY when a concrete better pattern provably already exists in the
 codebase. Never on taste alone. These land in their own section, not in

package/plugins/olko-github-pr/skills/lekker-review/assets/poster-overview.html

@@ -0,0 +1,204 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=1280, initial-scale=1">
+  <title>Lekker Review Overview</title>
+  <style>
+    * { box-sizing: border-box; }
+    html, body { width: 1280px; height: 720px; margin: 0; overflow: hidden; }
+    body {
+      color: #e8e8e8;
+      background: radial-gradient(circle at 0 0, rgba(255, 200, 60, 0.05), transparent 38%), #0d0d0d;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    .poster {
+      width: 1280px;
+      height: 720px;
+      padding: 40px;
+      display: grid;
+      grid-template-rows: 62px 38px 220px 128px 60px 22px;
+      gap: 16px;
+      align-content: space-between;
+      overflow: hidden;
+    }
+    h1 {
+      margin: 0 0 8px;
+      color: #f5c542;
+      font: 700 30px/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      letter-spacing: 0.06em;
+    }
+    .subtitle { margin: 0; color: #9a9a9a; font-size: 15px; line-height: 1.35; white-space: nowrap; }
+    .pipeline { display: flex; align-items: center; gap: 8px; min-width: 0; }
+    .step {
+      height: 38px;
+      padding: 0 13px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: #9a9a9a;
+      background: #161616;
+      border: 1px solid #2c2c2c;
+      border-radius: 8px;
+      font: 13px/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      white-space: nowrap;
+    }
+    .step.hot { color: #f5c542; border-color: #f5c542; }
+    .arrow { flex: 0 0 auto; color: #555; font: 15px/1 ui-monospace, "SFMono-Regular", Menlo, monospace; }
+    .cards { display: flex; gap: 16px; min-width: 0; }
+    .card {
+      flex: 1 1 0;
+      min-width: 0;
+      height: 220px;
+      padding: 16px;
+      background: #161616;
+      border: 1px solid #262626;
+      border-radius: 10px;
+      overflow: hidden;
+    }
+    .kicker {
+      margin: 0 0 8px;
+      color: #f5c542;
+      font: 700 11px/1.2 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      letter-spacing: 0.11em;
+      text-transform: uppercase;
+    }
+    h2 { margin: 0 0 14px; font-size: 19px; line-height: 1.1; font-weight: 600; }
+    .claims { display: grid; gap: 9px; }
+    .claim { margin: 0; color: #9a9a9a; font-size: 12.5px; line-height: 1.38; }
+    .panel {
+      padding: 14px 16px;
+      background: #161616;
+      border: 1px solid #262626;
+      border-radius: 10px;
+      overflow: hidden;
+    }
+    .panel-title {
+      margin: 0 0 10px;
+      color: #f5c542;
+      font: 700 11px/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      letter-spacing: 0.11em;
+    }
+    .severity-row { display: flex; flex-wrap: wrap; gap: 10px; min-width: 0; margin-bottom: 10px; }
+    .chip {
+      flex: 1 1 0;
+      min-width: 0;
+      padding: 7px 10px;
+      color: #8a8a8a;
+      background: #1e1e1e;
+      border: 1px solid #2c2c2c;
+      border-radius: 6px;
+      font: 11.5px/1.15 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      white-space: normal;
+    }
+    .chip strong { color: #e8e8e8; font-weight: 700; }
+    .chip.critical { color: #f0dcdc; background: #a35c60; border-color: #a35c60; }
+    .chip.critical strong { color: #f0dcdc; }
+    .rule { margin: 0; color: #e8e8e8; font-size: 12.5px; line-height: 1.25; font-weight: 600; }
+    .statement {
+      display: flex;
+      align-items: center;
+      color: #e8e8e8;
+      font-size: 18px;
+      line-height: 1.2;
+      font-weight: 600;
+    }
+    footer {
+      display: flex;
+      align-items: end;
+      justify-content: space-between;
+      color: #6a6a6a;
+      font: 11.5px/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
+      white-space: nowrap;
+    }
+  </style>
+</head>
+<body>
+  <main class="poster">
+    <header>
+      <h1>LEKKER REVIEW</h1>
+      <p class="subtitle">Depth selects two triage agents or five specialists; verification follows depth. Nothing is pushed without confirmation.</p>
+    </header>
+
+    <section class="pipeline" aria-label="Review pipeline">
+      <div class="step">parse input</div><span class="arrow">→</span>
+      <div class="step">context + worktree</div><span class="arrow">→</span>
+      <div class="step">review agents</div><span class="arrow">→</span>
+      <div class="step hot">verify + prove</div><span class="arrow">→</span>
+      <div class="step">synthesize</div><span class="arrow">→</span>
+      <div class="step">fix / post</div>
+    </section>
+
+    <section class="cards" aria-label="Review agents">
+      <article class="card">
+        <p class="kicker">AGENT 01</p>
+        <h2>Quality</h2>
+        <div class="claims">
+          <p class="claim">Business logic</p>
+          <p class="claim">Data integrity and security</p>
+          <p class="claim">Error handling and scalability</p>
+          <p class="claim">Pre-existing code stays out of scope</p>
+        </div>
+      </article>
+      <article class="card">
+        <p class="kicker">AGENT 02</p>
+        <h2>Implementation</h2>
+        <div class="claims">
+          <p class="claim">Integration contracts</p>
+          <p class="claim">Migration safety</p>
+          <p class="claim">CI failures feed Critical findings</p>
+          <p class="claim">External behavior and data shape</p>
+        </div>
+      </article>
+      <article class="card">
+        <p class="kicker">AGENT 03</p>
+        <h2>Simplification</h2>
+        <div class="claims">
+          <p class="claim">Count reader-held concepts</p>
+          <p class="claim">Relocating is not reducing</p>
+          <p class="claim">Split refactor from behavior</p>
+          <p class="claim">Ignore 2-3 duplicated lines</p>
+        </div>
+      </article>
+      <article class="card">
+        <p class="kicker">AGENT 04</p>
+        <h2>Conventions</h2>
+        <div class="claims">
+          <p class="claim">Existing precedent required</p>
+          <p class="claim">Cite the precedent</p>
+          <p class="claim">Taste alone is dropped</p>
+          <p class="claim">Idiomatic findings never block</p>
+        </div>
+      </article>
+      <article class="card">
+        <p class="kicker">AGENT 05</p>
+        <h2>Test Quality</h2>
+        <div class="claims">
+          <p class="claim">Coverage verdict</p>
+          <p class="claim">Mutation-slip risk</p>
+          <p class="claim">Mock smells and gaps</p>
+          <p class="claim">Would tests catch a regression?</p>
+        </div>
+      </article>
+    </section>
+
+    <section class="panel" aria-label="Severity tiers">
+      <p class="panel-title">SEVERITY</p>
+      <div class="severity-row">
+        <div class="chip critical"><strong>Critical</strong> / blocks the merge</div>
+        <div class="chip"><strong>Important</strong> / should fix</div>
+        <div class="chip"><strong>Observation</strong> / worth raising</div>
+        <div class="chip"><strong>Idiomatic</strong> / cited precedent</div>
+      </div>
+      <p class="rule">Critical and Important cover real failure risk; adopter-defined hard-rule violations also remain Critical. No nitpicking.</p>
+    </section>
+
+    <div class="statement">Approve when the change definitely improves codebase health, violates no hard rule, and leaves only non-blocking findings.</div>
+
+    <footer>
+      <span>AUTO: SCAN additions+deletions &lt;150 AND ≤5 files · DEEP &gt;800 OR &gt;25 files OR migrations/ OR *.sql · MEDIUM otherwise</span>
+      <span>lekker-review</span>
+    </footer>
+  </main>
+</body>
+</html>