@damiangilgonzalez/harness 1.3.7

package/skills/planetscale/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: planetscale
+
+should_trigger:
+  - prompt: "How do I make a schema change on PlanetScale without taking the table offline?"
+    why: "Core Online DDL / deploy-request workflow — branch, deploy request, shadow-copy cutover — is the heart of this skill."
+  - prompt: "My deploy request on PlanetScale has been stuck in the queue for ages and won't cut over. What's going on?"
+    why: "Non-obvious stuck-deploy symptom; the skill distinguishes 'still copying via VReplication' from 'gated waiting on apply' and routes to the deploy-requests reference."
+  - prompt: "PlanetScale won't let me add a foreign key. What's the right way to model this relationship?"
+    why: "No-FK design is a named scope; the answer is emulated relations / relationMode, not a generic schema lecture."
+  - prompt: "I'm on Vercel Edge and my MySQL connection to PlanetScale keeps timing out. How do I connect?"
+    why: "Non-obvious: raw TCP MySQL is blocked on edge runtimes; the fix is the @planetscale/database HTTP driver, which is PlanetScale-specific."
+  - prompt: "Necesito cambiar el esquema sin downtime en PlanetScale, ¿cómo lo hago?"
+    why: "Spanish phrasing of the core branch + deploy-request zero-downtime workflow."
+  - prompt: "I deployed a PlanetScale deploy request about 40 minutes ago and need to undo it — can I still revert?"
+    why: "Non-obvious: the ~30-minute revert window has likely closed, and reverts exclude dropped tables/cols and FK changes — a load-bearing nuance of this skill."
+  - prompt: "Set relationMode = prisma for my PlanetScale database and explain why."
+    why: "PlanetScale-specific ORM knob for emulating relations without DB foreign keys; the skill owns this even though Prisma is an ORM."
+
+should_not_trigger:
+  - prompt: "This MySQL query does a full table scan even with an index. How do I make it use the index?"
+    route_to: mysql
+    why: "Engine-level query tuning / index usage — identical answer on RDS MySQL — is the mysql sibling, not the PlanetScale platform workflow."
+  - prompt: "Design my PostgreSQL schema with proper constraints and pick the right column types."
+    route_to: postgresdb
+    why: "Postgres engine design and SQL semantics route to postgresdb, even when PlanetScale also sells managed Postgres."
+  - prompt: "I want Postgres branches for spinning up preview environments per pull request."
+    route_to: neon
+    why: "Postgres copy-on-write branching is Neon's model; PlanetScale branches are Vitess MySQL gated by deploy requests, a different engine and flow."
+  - prompt: "Can you explain how expand-contract migrations work in general, regardless of database?"
+    route_to: db-migrations
+    why: "Engine-agnostic migration theory belongs to db-migrations; this skill is the concrete PlanetScale deploy-request realization."
+  - prompt: "My Prisma Client updateMany returns the wrong count — what is the ORM actually doing?"
+    route_to: prisma-orm
+    why: "ORM client API ergonomics are the prisma-orm sibling; this skill owns only the PlanetScale connector knobs like relationMode."
+
+capability:
+  - scenario: "Walk me through shipping an ADD COLUMN on users plus a new orders table to a production PlanetScale MySQL database with zero downtime and a rollback plan."
+    must_include:
+      - "Creates a dev branch (pscale branch create), not editing main/production directly"
+      - "Applies the DDL on the branch (pscale shell), never against the production branch"
+      - "Opens a deploy request with pscale deploy-request create"
+      - "Runs pscale deploy-request diff and reads it before deploying"
+      - "Explains Online DDL: shadow table + VReplication copy + non-blocking cutover"
+      - "Addresses auto-apply ON by default vs --disable-auto-apply + deploy-request apply for the gated cutover"
+      - "Notes the ~30-minute revert window and that it excludes dropped tables/columns and FK-constraint changes"
+      - "Designs the new orders table without a DB-level foreign key (indexed relation column + app/ORM integrity), or justifies the unsharded FK opt-in"

package/skills/planetscale/references/deploy-requests.md

@@ -0,0 +1,75 @@
+# Deploy requests — lifecycle, gating, lint, reverts
+
+Offloaded depth from SKILL.md §"The deploy-request workflow". The body has the happy path; this file
+covers the states a deploy request moves through, why it stalls, and the revert carve-outs.
+
+## Lifecycle states
+
+A deploy request moves through roughly:
+
+1. **Open** — created from a dev branch against production; PlanetScale has computed a schema diff.
+2. **Approved** — a reviewer ran `pscale deploy-request review … --approve` (or approved in the UI).
+3. **Queued / deploying** — the deploy is submitted; Vitess starts Online DDL (shadow table build +
+   VReplication copy). Large tables spend most of their time here.
+4. **Pending cutover / gated** — if auto-apply was disabled (`--disable-auto-apply`), the copy is done
+   and the change waits for a manual `pscale deploy-request apply` before cutting over.
+5. **Deployed** — cutover complete. The **~30-minute revert window** opens here.
+6. **Reverted** or **permanent** — either reverted within the window, or finalized after it closes.
+
+## Online DDL mechanics
+
+A deploy does not run a blocking `ALTER`. Vitess:
+
+- builds a **shadow table** with the target schema,
+- uses **VReplication** to copy existing rows and continuously apply in-flight writes from old→new,
+- waits for the shadow to catch up (lag → ~0),
+- performs an atomic **cutover**, swapping the shadow in as the live table.
+
+That is why a deploy against a big table can sit in "deploying" for a long time: it is copying rows,
+not stuck. Watch the deploy's progress before assuming it hung.
+
+## Why a deploy is queued / won't cut over
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| "Queued" for a long time on a large table | VReplication is still copying rows | Wait; check copy progress. It is working, not stuck. |
+| Deployed-but-not-cut-over | Auto-apply disabled; it is gated | Run `pscale deploy-request apply <db> <number>`. |
+| Another deploy already in flight | Deploys serialize per branch | Let the in-flight one finish or revert it first. |
+| Blocked at open with lint errors | The diff violates a schema lint rule | Fix the DDL on the branch, re-diff, re-open. |
+
+## Lint errors
+
+PlanetScale lints the schema diff before it will deploy. Common blockers: a table without a primary
+key (Vitess wants one for VReplication), or unsupported/foot-gun DDL. Resolve by editing the DDL on the
+**branch** (open a `pscale shell`, fix the schema), regenerate the diff, and re-open the deploy request.
+Never try to force a lint failure through.
+
+## Revert carve-outs
+
+The ~30-minute window lets you undo a deploy **while preserving writes that happened after the deploy**
+— for most additive changes. It does **not** cleanly cover:
+
+- **Dropped tables or columns** — the data is gone; a revert cannot resurrect it.
+- **Foreign-key constraint changes** — excluded from clean revert.
+
+After the window closes the deploy is permanent. Treat the window as a safety net for *additive*
+changes, and plan destructive rollbacks (re-adding a dropped column, restoring data) as **new forward
+deploys**, not as reverts.
+
+## Declarative vs imperative schema
+
+Two ways to express the change on a branch:
+
+- **Imperative** — you run the `ALTER`/`CREATE` statements yourself in `pscale shell`; the deploy
+  request diffs branch-vs-production and deploys that diff.
+- **Declarative** — you keep the desired schema in version control and let PlanetScale compute the DDL
+  needed to converge the branch to that target.
+
+Either way the deploy request is the gate and the diff is the contract. Read the diff before deploying.
+
+## Branch protection / safe migrations
+
+Production branches are protected by default. **Safe migrations** on a branch is the setting that
+*requires* the deploy-request flow — it stops raw schema edits from landing directly on the protected
+branch. Keep it on for any branch that fronts production. Dev branches are disposable; protect the one
+that matters.

package/skills/planetscale/references/no-foreign-keys.md

@@ -0,0 +1,88 @@
+# Designing without foreign keys on PlanetScale
+
+Offloaded depth from SKILL.md §"Design without foreign keys". The body has the rule and one Bad→Good
+fence; this file covers emulated cascades, the ORM specifics, and the unsharded opt-in caveats.
+
+## Why FKs fight Vitess
+
+Two of Vitess's first-class features make native FKs a poor default:
+
+- **Horizontal sharding** — a foreign key between rows on different shards has no meaning; the
+  constraint cannot be enforced across the shard boundary.
+- **Online DDL** — FK constraints complicate the shadow-table copy + cutover dance.
+
+On top of that, FK constraint checks add per-write overhead that **degrades high-concurrency
+workloads**. PlanetScale historically disallowed FKs entirely; they are now an **opt-in but
+unsharded-only** feature. So the scale-safe default is app-level referential integrity.
+
+## Emulated relations
+
+You keep the relationship — you just stop asking the database to enforce it.
+
+- **Index the relation column.** A non-FK relation still needs its index for join/lookup performance.
+  `KEY idx_orders_user_id (user_id)`.
+- **Enforce existence in the app/ORM.** Validate that `user_id` points at a real user before insert.
+- **Cascade explicitly.** There is no `ON DELETE CASCADE`. Delete dependents yourself, in a
+  transaction or a background job:
+
+```sql
+-- App-side cascade, in one transaction (or a queued job for large fan-out):
+START TRANSACTION;
+DELETE FROM order_items WHERE order_id IN (SELECT id FROM orders WHERE user_id = ?);
+DELETE FROM orders      WHERE user_id = ?;
+DELETE FROM users       WHERE id = ?;
+COMMIT;
+```
+
+For large fan-out, prefer a batched background job over one giant transaction so you do not hold writes.
+
+## Prisma: relationMode = "prisma"
+
+Setting `relationMode = "prisma"` tells Prisma to emulate relations in the client instead of emitting
+DB-level foreign keys. Prisma then also creates the **implicit indexes** on relation scalar fields that
+a real FK would have given you for free.
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+
+model Order {
+  id     BigInt @id @default(autoincrement())
+  userId BigInt
+  user   User   @relation(fields: [userId], references: [id])
+
+  @@index([userId]) // required under relationMode="prisma" — no implicit FK index from the DB
+}
+```
+
+ORM-client ergonomics beyond this knob belong to `../../prisma-orm/SKILL.md`, not here.
+
+## Drizzle: app-level relations
+
+Drizzle models relations in app code via `relations()` and queries them with the relational API. On
+PlanetScale you index the join column and skip the `references()`-backed DB constraint; the relation
+lives in code, not in the database. The query-builder side is `../../drizzle-orm/SKILL.md`.
+
+## The unsharded FK opt-in
+
+Native FKs are available again, but **only on unsharded keyspaces**. It is acceptable to use one when:
+
+- you are certain the table will **never** shard (small, bounded, low-write reference data), and
+- you accept the extra Online DDL friction the FK introduces, and
+- you remember that FK constraint changes are **excluded from clean schema reverts** (see
+  deploy-requests.md).
+
+If any of those is shaky, default back to emulated relations. Document *why* a given table is allowed
+an FK so the next person does not "fix" it.
+
+## Bad → Good patterns
+
+| Pattern | Bad on PlanetScale at scale | Good |
+| --- | --- | --- |
+| Relation | DB `FOREIGN KEY … REFERENCES` | Indexed column + app/ORM-emulated relation |
+| Delete dependents | `ON DELETE CASCADE` | Explicit transactional or batched delete in app code |
+| Index on relation column | Relying on the FK's implicit index | Declare the index yourself (`@@index`, `KEY`) |
+| Integrity guarantee | "the database will reject orphans" | Validate before write; reconcile orphans in a job |

package/skills/planetscale/scripts/verify.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — planetscale skill content gate. Read-only, idempotent, never writes.
+#
+# Checks the SKILL's own SKILL.md + references/*.md for accuracy and consistency:
+#   1. The deploy-request CLI verbs (create / diff / review / deploy) are all present and
+#      correctly named — the workflow is the spine of this skill.
+#   2. No claim that PlanetScale "enforces foreign keys by default" (the opposite is true:
+#      FKs are an opt-in, unsharded-only feature).
+#   3. The serverless driver is spelled EXACTLY @planetscale/database — no invented names
+#      (@planetscale/serverless, planetscale-js, @planetscale/mysql, ...).
+#   4. Every fenced code block is language-tagged.
+#
+# Exit code: non-zero ONLY on a real content failure. An empty / clean target exits 0 with no
+# false failure: if no SKILL.md is found we [skip] and pass (so this is safe to run anywhere).
+#
+# Portability: stock macOS bash 3.2 (no mapfile / associative arrays). Arrays are initialised
+# so they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# Resolve the skill root: directory containing this script's parent (scripts/ -> skill dir).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+
+if [ ! -f "$SKILL_MD" ]; then
+  skip "no SKILL.md found at $SKILL_MD — nothing to check"
+  exit 0
+fi
+
+# Gather the content files: SKILL.md + every references/*.md. Initialised array (set -u safe).
+FILES=("$SKILL_MD")
+if [ -d "$SKILL_DIR/references" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$SKILL_DIR/references" -type f -name '*.md' -print0 2>/dev/null)
+fi
+
+# Concatenate once for whole-skill greps.
+ALL="$(cat "${FILES[@]}" 2>/dev/null || true)"
+
+# ---- 1. deploy-request CLI verbs present ----
+MISSING=""
+for verb in create diff review deploy; do
+  if ! printf '%s' "$ALL" | grep -Eq "deploy-request[[:space:]]+$verb"; then
+    MISSING="$MISSING $verb"
+  fi
+done
+if [ -n "$MISSING" ]; then
+  err "missing deploy-request verb(s):$MISSING"
+else
+  ok "deploy-request workflow verbs present (create / diff / review / deploy)"
+fi
+
+# ---- 2. no 'enforces foreign keys by default' style claim ----
+if printf '%s' "$ALL" | grep -Eiq 'enforce[sd]?[^.]*foreign[[:space:]]+key[^.]*by[[:space:]]+default'; then
+  err "found a claim that PlanetScale enforces foreign keys by default — it does not (opt-in, unsharded-only)"
+else
+  ok "no false 'enforces foreign keys by default' claim"
+fi
+
+# ---- 3. serverless driver spelled exactly @planetscale/database ----
+# Only inspect lines that actually USE the driver (import / require / from / a pkg-manager add) so
+# that an anti-patterns row deliberately LISTING wrong names as a banlist is not a false failure.
+USAGE="$(printf '%s' "$ALL" | grep -E '(^|[^A-Za-z])(import|require|from)([^A-Za-z]|$)|(npm|pnpm|yarn|bun)[[:space:]]+(add|install|i)[[:space:]]' || true)"
+if printf '%s' "$ALL" | grep -Eq '@planetscale/'; then
+  if printf '%s' "$USAGE" | grep -Eoq '@planetscale/[a-z-]+'; then
+    BADPKG="$(printf '%s' "$USAGE" | grep -Eo '@planetscale/[a-z-]+' | grep -v '^@planetscale/database$' || true)"
+    if [ -n "$BADPKG" ]; then
+      err "imported a non-canonical @planetscale package: $(printf '%s' "$BADPKG" | sort -u | tr '\n' ' ')"
+    else
+      ok "serverless driver imported exactly as @planetscale/database"
+    fi
+  else
+    ok "@planetscale/database referenced; no non-canonical import found"
+  fi
+else
+  skip "@planetscale/* package not referenced — nothing to check"
+fi
+if printf '%s' "$USAGE" | grep -Eq '\bplanetscale-js\b'; then
+  err "imported an invented driver name 'planetscale-js'"
+fi
+
+# ---- 4. every code fence is language-tagged ----
+# Count opening fences (those followed by a language token) vs total fences. A bare ``` that opens
+# a block has no trailing word; closing fences are bare too. We pair them: every other ``` is a
+# closer, so opening fences are the odd-indexed ones. Simplest robust check: no opening fence may be
+# bare. We walk fences in order and require odd (1st,3rd,...) fences to carry a language tag.
+for f in "${FILES[@]}"; do
+  bad="$(awk '
+    /^```/ {
+      n++
+      if (n % 2 == 1) {            # opening fence
+        tag = substr($0, 4)
+        gsub(/[[:space:]]/, "", tag)
+        if (tag == "") { print FILENAME ":" NR }
+      }
+    }
+  ' "$f")"
+  if [ -n "$bad" ]; then
+    err "untagged opening code fence(s) in:"
+    printf '%s\n' "$bad"
+  fi
+done
+if [ "$EXIT" -eq 0 ]; then ok "all code fences language-tagged"; fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/podcast/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: podcast
+description: "Use when planning, recording, editing or publishing one podcast episode end to end — the run-of-show and guest brief, recording settings, the loudness master, the Podcasting 2.0 sidecars for chapters and transcripts, the RSS item, and timestamped SEO show notes. Covers audio that is quiet on one platform and loud on another, feeds rejected for bad artwork, and chapters that will not appear in the app. NOT clipping the episode into social posts (that is `social-publisher`), NOT cutting the vertical short (that is `video-shorts`)."
+tags: [podcast, audio, rss, show-notes, podcasting-2.0]
+recommends: [social-publisher, video-shorts, newsletter, brand-voice, content-engine]
+origin: risco
+---
+
+# Podcast — One Episode, Plan to Published
+
+*You own the production craft and the distribution surface of a single audio episode: the run-of-show, the recording settings, the loudness target, the chapters and transcript sidecars, the RSS `<item>`, and the show-notes page that ranks. You do not invent the show's voice, plan the content calendar, or cut the clips — you take one episode from idea to a feed entry an app can ingest.*
+
+An episode moves through four phases: **plan → record → edit & master → publish** (plus the show-notes page that ships with publish). Every load-bearing number below is sourced and dated (accessed 2026-06-02). Use the current numbers; do not guess from memory.
+
+## The flow — find the phase, do that phase
+
+Read the ask, drop it into one phase, execute that phase, and stop at its hand-off. Do not redo earlier phases the user already has.
+
+| The ask sounds like | Phase | You produce |
+| --- | --- | --- |
+| format, run-of-show, guest brief, questions, cold-open | 1 Plan | an episode outline + question list |
+| double-ender, sample rate, multitrack, "how do I record remotely" | 2 Record | a recording-settings checklist |
+| "how loud", LUFS, true peak, mono vs stereo, export format | 3 Edit & master | a mastering target sheet + export plan |
+| RSS item, enclosure, chapters, transcript, artwork, submit to Apple | 4 Publish | a valid `<item>` + `chapters.json` + `transcript.vtt` |
+| show notes, episode page, timestamps, SEO | Show notes | a blog-shaped, timestamped page |
+
+## Phase 1 — Plan
+
+Pick the format first; it sets everything downstream.
+
+| Format | Use when | Why |
+| --- | --- | --- |
+| Solo | you own the expertise and want tight control | no scheduling, fastest to ship, easiest to master (mono) |
+| Interview | the value is a guest's knowledge | borrowed audience + authority; needs a guest brief |
+| Co-host | a recurring two-voice dynamic | chemistry carries it; needs two locals |
+| Narrative | story-driven, scripted, sound-designed | highest production cost; script before you record |
+
+**Run-of-show.** Write a timed segment table before recording so the edit has a spine. Target minutes for a ~40-min interview:
+
+| Segment | Target | Purpose |
+| --- | --- | --- |
+| Cold-open | 0:30 | best 30s of tape, pulled forward to hook |
+| Intro | 1:00 | show ID + episode promise + guest one-liner |
+| Segment(s) | 30:00 | the body — 2-4 themed blocks, not one shapeless chat |
+| CTA | 0:30 | one ask (subscribe / a specific link), never three |
+| Outro | 1:00 | recap + where to go next + sign-off |
+
+**Guest brief** (send before the record): episode topic + angle, 4-6 question themes (not the verbatim list — keep some spontaneity), tech check (headphones + a quiet room + the recording link), the time/timezone, and how their name and links should appear. A guest who knows the themes gives sharper tape.
+
+**Question design.** Open-ended, single-barrel, no yes/no. One idea per question.
+
+```text
+Bad   "Did you find fundraising hard, and what would you change?"  (double-barreled yes/no)
+Good  "Walk me through the moment fundraising got hardest."         (open, single, invites a story)
+```
+
+## Phase 2 — Record
+
+**Record locals, never the call.** A remote double-ender records each participant *locally* — Riverside/Descript capture every speaker on their own machine at 48 kHz uncompressed WAV, one track per speaker, cloud-backed in real time, so quality is independent of the connection. The Zoom/Meet mixdown is compressed, single-track, and drops out with the bandwidth. (Riverside double-ender; Buzzsprout remote-recording guide 2026 — accessed 2026-06-02.)
+
+```text
+Bad   Hit "record" in Zoom and edit the resulting compressed stereo mixdown.
+Good  Double-ender: each speaker's local 48 kHz WAV on its own track, cloud-backed,
+      assembled into a multitrack you edit downstream.
+```
+
+Recording checklist:
+
+- [ ] **Remote** → double-ender (Riverside/Descript). **In-person** → multitrack recorder/interface, one mic per speaker.
+- [ ] **48 kHz, uncompressed WAV**, separate track per speaker — never a pre-mixed single track.
+- [ ] **Local + cloud backup** running before you start talking.
+- [ ] **Track to ~-18 dBFS peaks**, leaving headroom — do not record hot toward 0 dBFS; clipped tracks are unrecoverable and you fix loudness at the master, not the mic.
+- [ ] Headphones on every speaker (kills echo/bleed); record 10s of room tone for noise cleanup.
+
+## Phase 3 — Edit & master
+
+**Edit order.** Assemble → content edit (cut tangents, fix flow) → cleanup (noise reduction, level the tracks against each other) → master last. Master on the finished mix, never mid-edit.
+
+**Master once to -16 LUFS integrated, stereo, true peak -1 dBTP.** This is the single safe target. Apple Podcasts recommends -16 LUFS integrated; Spotify normalizes podcasts to -14 LUFS and turns *down* anything louder on playback — so you do not master a separate file per platform. The -1 dBTP ceiling prevents inter-sample clipping after MP3 encoding. (SONE "Podcast Loudness Standards 2026"; Descript "Podcast Loudness Standard"; Podnews LUFS FAQ — accessed 2026-06-02.)
+
+| Destination | Integrated LUFS | True peak | Channels | Note |
+| --- | --- | --- | --- | --- |
+| Apple Podcasts | -16 | -1 dBTP | stereo | the reference target |
+| Spotify | normalizes to -14 | -1 dBTP | stereo | louder uploads are turned down; do not over-master for it |
+| Mono voice (solo) | -19 (≈ -16 stereo) | -1 dBTP | mono | mono is ~half the file size for a single voice |
+| YouTube (if you also post audio video) | ~-14 | -1 dBTP | stereo | normalized like Spotify |
+
+The mono equivalent of -16 LUFS stereo is **-19 LUFS** — relevant only when you publish a single-voice episode as mono. (SONE / Podnews — accessed 2026-06-02.)
+
+**Export.** Keep the **WAV master** as your archive. Encode the distribution file to **MP3** (commonly 128 kbps stereo / 96 kbps mono for voice) — that MP3 is what the RSS `<enclosure>` points at. Note its byte length and MIME type; you need both for the `<item>`.
+
+## Phase 4 — Publish
+
+The deliverable is a valid RSS episode `<item>` plus its sidecars. A complete annotated `<item>`, the full iTunes/RSS channel tag list, and the Podcasting 2.0 tag set with every attribute live in `references/rss-and-namespace.md` — load it before hand-writing a feed.
+
+**The `<item>` must carry** (Apple's required set + the enclosure):
+
+- `<title>` and `<itunes:title>`, `<description>` (the show notes), `<pubDate>` (RFC-822).
+- `<enclosure url="…" length="…BYTES" type="audio/mpeg"/>` — the MP3 URL, its size in **bytes**, and the MIME type. A wrong `length` breaks the player's scrubber.
+- `<guid isPermaLink="false">` — a stable unique ID that never changes after publish; changing it duplicates the episode in every app.
+- `<itunes:duration>` (seconds or HH:MM:SS) and `<itunes:image href="…"/>`.
+
+**Artwork constraints (feeds are rejected otherwise):** cover art must be a **square JPG or PNG, RGB color space, minimum 1400×1400 px and maximum 3000×3000 px**. (RSS.com hosting guide 2026 — accessed 2026-06-02.)
+
+**Podcasting 2.0 sidecars** (wire them in the `<item>`; full shapes in the reference):
+
+- `chapters.json` → `<podcast:chapters url="…" type="application/json+chapters"/>`. The JSON has `version` + a `chapters[]` array; each chapter has a numeric `startTime` (seconds) and `title`, and startTimes are **monotonically non-decreasing**. The hosted file can be edited after publish.
+- `transcript.vtt` / `.srt` → `<podcast:transcript url="…" type="text/vtt"/>`. The **`type` attribute is required** (`text/vtt`, `application/srt`, or `application/json`); you may add multiple `podcast:transcript` tags for multiple formats. Creator-supplied transcripts beat Apple's auto-generated ones. (Podcasting 2.0 namespace docs — accessed 2026-06-02.)
+- `<podcast:person>` for host and guest (role + image href).
+
+**Apple auto-generates transcripts (since 2024-03) and chapters (iOS 26.2), but auto-chapters only fire when the creator supplied none** — your manual `podcast:chapters` always wins, so supply them when timestamps matter. (Apple Newsroom 2024-03; Castopod/TechBuzz iOS 26.2 coverage — accessed 2026-06-02.)
+
+**Submission reality.** A feed needs **at least one published episode** before you can submit it — Apple requires it and Spotify for Creators hides RSS distribution until the first episode ships. Apple review can take **up to 72 hours**; most hosts publish new episodes within hours. (VNYL RSS guide; RSS.com; Spotify for Creators — accessed 2026-06-02.)
+
+## Show notes
+
+Top-ranking show notes are **blog-shaped, ~1,500+ words**, not a one-paragraph blurb. Timestamps are both a UX and an SEO signal. (Sweetfish "Show Notes Template"; Increv "SEO show notes 2025" — accessed 2026-06-02.)
+
+Template:
+
+```text
+H1            target keyword as the episode title
+Summary       2-3 sentences, keyword-bearing, what the listener gets
+Chapters      timestamped list (00:00 Intro / 04:12 …) mirroring chapters.json
+Takeaways     3-5 bullets — the episode's claims, skimmable
+Guest         short bio + links (site, social)
+Resources     every tool/book/link mentioned
+CTA           one ask (subscribe / a specific URL)
+```
+
+**Title craft** — specific and outcome-bearing beats sequential:
+
+```text
+Bad   "Episode 12"
+Good  "Episode 12: How Marta scaled a solo SaaS to $40k MRR without ads"
+```
+
+Embed `PodcastEpisode` JSON-LD on the page (name, datePublished, duration as ISO-8601 `PT35M`, `associatedMedia` → the MP3, `partOfSeries` → the show) so the episode is eligible for rich results — see `references/rss-and-namespace.md` for the block.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| Mastering a separate file per platform | Spotify turns down anything over -14 anyway; you just add work and risk inconsistency | Master once to -16 LUFS stereo / -1 dBTP |
+| Editing the recorded Zoom/Meet mixdown | Compressed, single-track, drops out with bandwidth; unrecoverable | Double-ender local 48 kHz WAV, one track per speaker |
+| Tracking hot toward 0 dBFS | Clipped peaks are permanent; loudness is a master-stage fix, not a mic-gain fix | Track to ~-18 dBFS peaks, set loudness at the master |
+| `<podcast:transcript>` without a `type` | Apps cannot parse it; the tag is ignored | Always include `type=` (`text/vtt`, `application/srt`, `application/json`) |
+| Wrong/blank `<enclosure length>` | Breaks the player scrubber and progress | Use the MP3's exact size in bytes |
+| Changing `<guid>` after publish | Apps treat it as a brand-new episode — duplicates the feed | Set a stable guid once; never change it |
+| 1024×1024 or non-square cover art | Below the 1400 px floor / non-square → feed rejected | Square JPG/PNG, RGB, 1400-3000 px |
+| Show notes as a one-paragraph summary | No keywords, no timestamps → no ranking, no UX value | Blog-shaped ~1,500 words with timestamped chapters + takeaways |
+| Relying on Apple auto-chapters when timing matters | Auto-chapters only fire when you supplied none, and you lose control of titles | Ship a manual `chapters.json` via `podcast:chapters` |
+
+## Hand-offs
+
+- Clip the episode into posts for X/LinkedIn/IG and schedule them → `../social-publisher/SKILL.md`.
+- Cut the vertical/short video of a moment → `../video-shorts/SKILL.md`.
+- Write the email that announces the episode to the list → `../newsletter/SKILL.md`.
+- Define the show's tone/persona the episode should sound like → `../brand-voice/SKILL.md`.
+- Decide *which* episodes exist and the cadence across the catalog → `../content-engine/SKILL.md`.
+
+## References
+
+- `references/rss-and-namespace.md` — required + recommended iTunes/RSS channel and item tags, a full annotated `<item>` example, the Podcasting 2.0 tag set with attributes (`transcript`, `chapters`, `person`, `funding`, `season`, `episode`), a sample `chapters.json`, a `transcript.vtt` snippet, and the `PodcastEpisode` JSON-LD block.
+
+After you emit a `chapters.json`, a feed/`<item>`, or a `transcript.vtt`, run `scripts/verify.sh <dir-or-file>` to lint the shape (parse, monotonic startTimes, required enclosure attributes, transcript `type`, artwork size).

package/skills/podcast/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — podcast
+
+These cases are routing + capability checks for a human or an LLM judge; there is no
+automated test runner beyond `scripts/verify.sh` (which lints emitted artifacts — a
+`chapters.json`, an RSS feed/`<item>`, or a `transcript.vtt` — not these prompts). To
+run them: read `cases.yaml` and confirm the skill's `description` would fire on every
+`should_trigger` prompt (including the jargon-only "chapters.json + double-ender + -16
+master" case that never says "podcast" and the Catalan "masteritzar l'àudio" phrasing),
+that each `should_not_trigger` prompt routes to the named sibling instead
+(`video-shorts`, `social-publisher`, `brand-voice`, `newsletter`, `content-engine`), and
+that an end-to-end answer to the `capability` scenario satisfies every line of its
+`must_include` rubric — the -16 LUFS / -1 dBTP master-once rule with Spotify's -14
+normalization, 48 kHz WAV master + MP3 enclosure, a monotonic `chapters.json` wired via
+`podcast:chapters`, a `podcast:transcript` carrying a `type`, an `<item>` with the
+required enclosure/guid/duration/artwork fields, blog-shaped timestamped show notes, and
+the one-episode-first + 72h-Apple submission note. To check an actual emitted artifact,
+point `scripts/verify.sh` at the file or directory it produced.

package/skills/podcast/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: podcast
+
+# Prompts that MUST load `podcast`. The skill owns ONE episode end to end: the
+# run-of-show, recording settings, the loudness master, the Podcasting 2.0
+# sidecars, the RSS <item>, and the timestamped show-notes page. It does NOT
+# clip the episode for social (social-publisher), cut the vertical short
+# (video-shorts), define the show voice (brand-voice), pick which episodes
+# exist (content-engine), or write the announcement email (newsletter).
+should_trigger:
+  - prompt: "Plan the run-of-show for a 40-minute interview episode with a founder guest."
+    why: "Core Phase 1 — format choice, timed segments, guest brief and question design are exactly this skill's plan deliverable."
+
+  - prompt: "What LUFS and true-peak should I master this episode to for Apple and Spotify?"
+    why: "Core Phase 3 — the central loudness number (-16 LUFS stereo / -1 dBTP, Spotify normalizes to -14) lives here."
+
+  - prompt: "Write a valid RSS item with the transcript and chapters tags for episode 14."
+    why: "Core Phase 4 — a compliant <item> with Podcasting 2.0 enclosure/guid/transcript/chapters is the publish deliverable."
+
+  - prompt: "Write timestamped, SEO show notes for this episode."
+    why: "The show-notes phase — blog-shaped, timestamped, ~1,500-word page is owned here."
+
+  - prompt: "Generate a chapters.json and wire the double-ender locals into a -16 master."
+    why: "Non-obvious — jargon only, never says the word 'podcast'; chapters.json + double-ender + -16 master are unambiguously this skill."
+
+  - prompt: "Masteritzar l'àudio del podcast i escriure les show notes amb timestamps."
+    why: "Catalan for 'master the podcast audio and write the show notes with timestamps' — covers Phase 3 + show notes in another language."
+
+should_not_trigger:
+  - prompt: "Cut three vertical clips from this episode for Reels and TikTok."
+    route_to: video-shorts
+    why: "Editing the vertical/short video cut is video-shorts; podcast delivers the full-length audio master and its sidecars, not the clip."
+
+  - prompt: "Schedule this episode's promo posts across X, LinkedIn, and Instagram."
+    route_to: social-publisher
+    why: "Distribution and repurposing scheduling is social-publisher; podcast stops at the RSS item and the show-notes page."
+
+  - prompt: "Define the tone and personality our show should sound like."
+    route_to: brand-voice
+    why: "The verbal identity/persona spec is brand-voice; podcast shapes one episode but does not invent the voice."
+
+  - prompt: "Write the email announcing the new episode to our subscriber list."
+    route_to: newsletter
+    why: "The list email is newsletter; podcast produces the episode page, not the broadcast email."
+
+  - prompt: "Which episode topics should we line up for next quarter?"
+    route_to: content-engine
+    why: "Deciding WHICH episodes exist and the catalog cadence is content-engine; podcast produces ONE chosen episode."
+
+capability:
+  - scenario: >
+      Take a recorded 35-minute remote founder interview to publish-ready: give the
+      mastering target, produce a chapters.json and wire the transcript, write a valid
+      RSS <item>, and draft the show-notes page.
+    must_include:
+      - "States master ONCE to -16 LUFS integrated, stereo, -1 dBTP true peak, and notes Spotify normalizes to -14 (no per-platform master)."
+      - "Specifies 48 kHz WAV as the archive master and an MP3 for the enclosure (and that the interview should have been a double-ender, locals not the call)."
+      - "Produces a chapters.json with version + chapters[], numeric startTimes that are monotonically non-decreasing, wired via <podcast:chapters>."
+      - "Wires the transcript via <podcast:transcript> WITH a required type attribute (e.g. text/vtt)."
+      - "Writes an RSS <item> with <enclosure url length type>, a stable <guid>, an <itunes:duration>, and square 1400-3000 px artwork."
+      - "Drafts blog-shaped show notes: H1 target keyword, 2-3 sentence summary, timestamped chapter list, key takeaways, guest bio + links, one CTA, ~1,500 words."
+      - "Notes a feed needs one published episode before submission and that Apple review can take up to 72 hours."