@rune-kit/rune 2.22.2 → 2.24.0

package/skills/adversary/references/oracle-mode.md

@@ -42,8 +42,9 @@ Emit `oracle.dispatched` carrying `{sessionId, triggerSignal, sourceSkill, targe
 
 | Target model | Protocol |
 |--------------|----------|
-| sonnet-class (gpt-5, gemini-3-flash, claude-sonnet) | Synchronous — block until reply or 60s timeout |
-| opus-class (gpt-5-pro, gemini-3-pro, claude-opus-4-7) | Async — primary agent continues; poll `.rune/oracle-pending/<sessionId>.json` between phases |
+| sonnet-class (gpt-5.6-terra, gemini-3-flash, claude-sonnet-5) | Synchronous — block until reply or 60s timeout |
+| opus-class (gpt-5.6-sol, gemini-3-pro, claude-opus-4-8) | Async — primary agent continues; poll `.rune/oracle-pending/<sessionId>.json` between phases |
+| frontier-class (claude-fable-5, API-only) | Async, heaviest second opinion for the hardest red-team / architecture calls. **API-only** — not available on a subscription runtime, so reach it via an API key or a non-Anthropic CLI, never via the primary Claude Code session's model. Thinking is always on (control depth with `effort`, do not send a `thinking` param) and it can return a `refusal` stop reason — treat a refusal as "no oracle reply", fall back to opus-class. |
 
 ### 5. Validate response
 

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ name: ba
 description: "Business Analyst agent. Use when starting a new feature requiring requirements elicitation BEFORE plan or cook. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume."
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.2.1"
   layer: L2
   model: opus
   group: creation
@@ -19,6 +19,11 @@ Business Analyst agent — the ROOT FIX for "Claude works a lot but produces not
 
 > Wrong requirements shipped correctly is the most expensive bug. BA's job is to prevent it — measure clarity (Step 2.5), measure completeness (Step 3.5), and measure cross-dimension consistency (Step 3.6) before handoff.
 
+> **Goal-first (advisory, 2026).** The Requirements Document is the goal spec current
+> models want up front. Where the platform has a native goal/outcome command — Claude
+> Code `/goal`, Managed Agents Outcomes (rubric) — seed it from this document's scope
+> boundaries + acceptance criteria so the whole run stays anchored to the agreed WHAT.
+
 <HARD-GATE>
 BA produces WHAT, not HOW. Never write code. Never plan implementation.
 Output is a Requirements Document → hand off to rune:plan for implementation planning.

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.6.1"
+  version: "2.7.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -379,6 +379,24 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 
 **REQUIRED SUB-SKILL**: Use `rune:fix`
 
+### Reuse Ladder (climb before you write)
+
+Before writing the code for each task, climb this ladder and stop at the first rung that holds. Advisory, not a gate — it shapes *what* you write, never blocks the phase. Runs AFTER you understand the change (scout done, plan approved), never as a substitute for tracing the real flow.
+
+1. **Needs to exist at all?** Speculative need → skip it, say so in one line (YAGNI).
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Re-implementing what sits a few files over is the most common slop — `Grep` before you write.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** DB constraint over app code, CSS over JS, `<input type="date">` over a picker lib.
+5. **Already-installed dependency solves it?** Use it. Never add a new dep for what a few lines cover.
+6. **One line?** Make it one line.
+7. **Only then** — the minimum code that makes the test pass.
+
+Two rungs work → take the higher one and move on. Mark a deliberate shortcut with a `// yagni:` comment naming its ceiling + upgrade path (`// yagni: global lock — per-account locks if throughput matters`) so the De-Sloppify Pass and later readers see intent, not ignorance.
+
+**Bug-fix corollary** — the lazy fix IS the root-cause fix: `Grep` every caller of the function you're about to touch, then fix the shared function once. One guard where all callers route through is a smaller diff than one guard per caller — and patching only the path the ticket names leaves every sibling caller still broken.
+
+**Never lazy about**: understanding the problem, input validation at trust boundaries, error handling that prevents data loss, security, accessibility, anything explicitly requested. The ladder shortens the solution, never the reading — a small diff you don't understand is a confident wrong fix, not laziness.
+
 1. Mark Phase 4 as `in_progress`
 2. **Phase-file execution** — if working from a master plan + phase file:
    - Execute tasks from `## Tasks` section wave-by-wave

package/skills/marketing/SKILL.md

@@ -3,7 +3,7 @@ name: marketing
 description: "Create marketing assets and execute launch strategy. Use when crafting landing copy, social banners, SEO meta, blog posts, or video scripts — coordinates with launch (deploy + announce) and the @rune-pro/growth pack (research / content / CRO)."
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: sonnet
   group: delivery
@@ -183,6 +183,28 @@ Produce ready-to-post content:
 
 **Product Hunt tagline** (under 60 characters)
 
+### Step 4.5 — Caption Doctrine (captions that start conversations)
+
+A social caption's job is NOT to summarize the post/video — it's to HOOK a scroller and
+start a conversation. A caption that re-tells the content is dead weight ("headline, not
+transcript"). Apply this to every caption attached to the Step 4 posts and to any video/
+image ship.
+
+**Format (4 short pieces, whole caption well under ~500 chars):**
+1. **Hook line** (~100 chars max — mobile feeds truncate around ~125 chars and most readers never tap "See more"): tension / curiosity / bold claim, in DIFFERENT words than the content's own hook.
+2. **Optional context line** (~90 chars): ONE extra stake / number / twist the content doesn't spell out. Not a plot summary.
+3. **One genuine open-ended question**: real opinion, many valid answers ("How much do you usually bump budget each time?"). This is the comment engine.
+4. **Soft CTA to the first comment**: "link in the first comment 👇".
+
+**Platform reality checklist (2025):**
+- **Link goes in the FIRST COMMENT, never the caption body.** Top-performing FB content is overwhelmingly linkless and platforms downrank in-body links (widely reported).
+- **No engagement bait.** Meta demotes explicit begging ("comment YES if…", "tag a friend", react/share requests). Genuine opinion questions are exempt and encouraged.
+- **0-1 hashtag, never a wall** — Meta flags an "inordinate amount of hashtags" as spam.
+- **Max 3 emoji** (emotional ones) or none. No em-dash. No superlatives ("best ever", "game-changer", "revolutionary").
+- **NEVER transcript the content.** If the caption reads like the voiceover or the post body, rewrite it.
+
+**Long-form intro posts** (a detailed FB/LinkedIn intro, distinct from a short caption): every paragraph ≤ 2 lines with a blank line between, keep technical terms in their usual form, include one honest caveat, humble tone — no oversell, no hashtag wall, link still in the first comment.
+
 ### Step 5 — SEO metadata
 
 Produce for the landing page:
@@ -318,6 +340,9 @@ Known failure modes for this skill. Check these before declaring done.
 | Counter-playbook without detection mechanism | HIGH | Every scenario needs a monitoring method — "watch for price drops" is useless without specifying WHERE to watch and HOW to automate |
 | Counter-playbook with unrealistic response windows | MEDIUM | If response window is 24h but pre-built assets don't exist, the playbook will fail — either extend window or create assets NOW |
 | Generating counter-playbook for blue ocean products | LOW | Skip Step 3.5 if no direct competitors — counter-strategies need someone to counter |
+| Caption that transcripts/summarizes the content | MEDIUM | Step 4.5: caption is a HOOK, not a recap — if it reads like the post body, rewrite. Add a genuine question to drive comments |
+| Link placed in caption body instead of first comment | MEDIUM | Step 4.5: platforms downrank in-body links — link goes in the first comment; caption body stays linkless |
+| Engagement-bait or hashtag wall in captions | MEDIUM | Step 4.5: Meta demotes "comment YES / tag a friend" and hashtag walls — use 0-1 hashtag and a real opinion question |
 
 ## Done When
 

package/skills/mcp-builder/SKILL.md

@@ -370,8 +370,8 @@ When building MCP servers that call AI providers, support **dual-model configura
 ```typescript
 // config.ts
 const config = {
-  primaryModel: process.env.PRIMARY_MODEL || 'claude-sonnet-4-20250514',
-  backgroundModel: process.env.BACKGROUND_MODEL || 'claude-haiku-4-5-20251001',
+  primaryModel: process.env.PRIMARY_MODEL || 'claude-sonnet-5',
+  backgroundModel: process.env.BACKGROUND_MODEL || 'claude-haiku-4-5',
 };
 ```
 

package/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<200 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "1.7.1"
   layer: L2
   model: opus
   group: creation
@@ -22,6 +22,17 @@ Strategic planning engine for the Rune ecosystem. Produces a **master plan + pha
 
 This is enterprise-grade project management: BA produces WHAT → Plan produces HOW (structured into phases) → ANY coder executes each phase with full context.
 
+> **Goal-first — leverage native goal/outcome commands (advisory, 2026).** Current
+> agent models (Opus 4.8, Sonnet 5, and the API-only Fable) perform best when handed
+> the full goal + constraints up front, then left to execute at high effort. Some
+> platforms now expose this natively: Claude Code `/goal` sets a run's north-star;
+> Managed Agents **Outcomes** (`user.define_outcome` + rubric) grade-and-iterate to a
+> target. The master plan IS that goal contract in durable form — when a native
+> goal/outcome command is present, seed it from the master plan's Overview +
+> acceptance criteria instead of re-stating the goal loosely. Advisory only: the
+> master plan + phase files stay the source of truth on every platform (goal/Outcome
+> are single-session; the plan survives across sessions and platforms).
+
 <HARD-GATE>
 NEVER produce a single monolithic plan file for non-trivial tasks.
 Non-trivial = 3+ phases OR 5+ files OR estimated > 100 LOC total change.
@@ -402,7 +413,7 @@ Append to plan output when invoked standalone. Suppress when called as sub-skill
 ```yaml
 chain_metadata:
   skill: "rune:plan"
-  version: "1.7.0"
+  version: "1.7.1"
   status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
   domain: "[area planned]"
   files_changed:

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code."
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.3.0"
   layer: L2
   model: sonnet
   group: development
@@ -296,6 +296,24 @@ Proceed to Step 6 only after Stage 1 passes. Code quality findings (bugs, patter
 
 The review report MUST show both stages: spec compliance verdict first, then code quality findings.
 
+### Step 5.7: Subtractive Pass (over-engineering lens)
+
+Stage 1 catches SPEC-CREEP (unrequested *features*). This pass goes further: it hunts complexity worth **deleting** even inside requested scope, and reports it as a one-line-per-finding cut list with a net-lines total. Run it on any diff that adds a class, wrapper, config option, or dependency. Skip for pure config/docs/style diffs.
+
+Tag each finding, one line: `<file>:L<line>: <tag> <what>. <replacement>.`
+
+| Tag | Cuts | Replacement |
+|-----|------|-------------|
+| `delete:` | Dead code, unused flexibility, speculative feature | Nothing |
+| `stdlib:` | Hand-rolled thing the standard library ships | Name the function |
+| `native:` | Dependency or code doing what the platform already does | Name the feature |
+| `yagni:` | Abstraction with one implementation, config nobody sets, layer with one caller | Inline it until a 2nd caller exists |
+| `shrink:` | Same logic, fewer lines | Show the shorter form |
+
+End with the only metric that matters: `net: -<N> lines, -<M> deps possible.` Nothing to cut → `Lean already.` and move on.
+
+**Ranking discipline**: these are LOW/MEDIUM findings (complexity, not correctness) — a subtractive suggestion NEVER outranks a real bug. A single smoke test or assert-based self-check is the ponytail minimum, not bloat — never flag it for deletion. This pass lists cuts; it does not apply them (route to `rune:fix`).
+
 ### Step 6: Report
 
 Produce a structured severity-ranked report.
@@ -621,7 +639,7 @@ Append to Code Review Report when invoked standalone. Suppress when called as su
 ```yaml
 chain_metadata:
   skill: "rune:review"
-  version: "1.2.0"
+  version: "1.3.0"
   status: "[DONE | DONE_WITH_CONCERNS]"
   domain: "[area reviewed]"
   files_changed: []  # review doesn't change files

package/skills/session-bridge/SKILL.md

@@ -553,7 +553,7 @@ When `oracle.dispatched` arrives, payload contains:
 - `sessionId` — caller-provided unique id
 - `triggerSignal` — `agent.stuck` or manual
 - `sourceSkill` — `debug` | `fix` | manual
-- `targetModel` — concrete model name (e.g. `gpt-5-pro`, `gemini-3-pro`, `claude-opus-4-7`)
+- `targetModel` — concrete model name (e.g. `gpt-5.6-sol`, `gemini-3-pro`, `claude-opus-4-8`; API-only frontier: `claude-fable-5`)
 - `bundleHash` — sha256 of the bundled context (idempotency key)
 
 ### Step D2 — Idempotency check
@@ -570,7 +570,7 @@ Create `.rune/oracle-pending/<sessionId>.json`:
   "dispatchedAt": "2026-04-27T12:34:56Z",
   "triggerSignal": "agent.stuck",
   "sourceSkill": "debug",
-  "targetModel": "claude-opus-4-7",
+  "targetModel": "claude-opus-4-8",
   "bundleHash": "sha256:9f3a...",
   "status": "pending",
   "timeoutAt": "2026-04-27T12:44:56Z",

package/skills/video-creator/SKILL.md

@@ -3,7 +3,7 @@ name: video-creator
 description: "Video content planning. Writes narration scripts, storyboards, shot lists, and asset checklists. Saves plan to marketing/video-plan.md."
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L3
   model: sonnet
   group: media
@@ -44,7 +44,9 @@ Derive constraints from platform:
 
 ### Step 2: Script
 
-Write a narration script with timing marks:
+Write a narration script with timing marks. **Before writing a single line, apply the
+Narration Craft principles below** — a script the viewer HEARS lives or dies on the
+opening and the flow, not the shot list.
 
 Structure:
 - **Hook** (0–5s): opening line that grabs attention — state the problem or the payoff
@@ -161,6 +163,71 @@ Then output a summary to the calling skill:
 3. Edit using the storyboard as reference
 ```
 
+## Narration Craft (decides whether a script hooks or bores)
+
+A demo script is HEARD by a person, not read off a slide. These principles separate an
+engaging script from generic voiceover — apply them in Step 2, before writing any line.
+
+**The 9 principles:**
+1. **Pain-first opening.** Open on the viewer's biggest pain or a stat already in flight ("Nếu bạn hay phải…", "This repo has 9k stars and…"). NEVER a flat catalogue opener ("Today we'll look at…", "This is a tool that…") — it names no problem and gives zero reason not to scroll.
+2. **Contrast structures.** "not just X but Y", "not X, it's Y", "like X but with Y". Contrast pulls attention.
+3. **2nd-person address.** "you'll see right away", "if you build on an M-series Mac…". Bring the viewer in.
+4. **Demonstrative immediacy.** "right here", "this", "on the timeline now". Concrete and present.
+5. **Specific real names, keep the jargon.** Name actual files, commands, competitors ("Final Cut", "Cursor", "ffmpeg"). Generic terms ("an AI tool", "the framework") are banned. Don't force-translate jargon into awkward words.
+6. **Quantified social proof — ONCE.** "over 9k stars". Never dump stars + forks + issues back-to-back as separate fragments.
+7. **Short clauses, comma-flowed.** "You can trim, replace, or regenerate it." One breath, not bullet fragments.
+8. **Caveat-as-feature.** State one honest limit or a "who should NOT use this". This is the most trust-building line in the video — a retention feature, not filler.
+9. **Use-case landing.** Close on a SPECIFIC viewer scenario, not "go check it out".
+
+**Named + numbered "weapons".** Give each differentiator a title and a number ("Weapon 01/02"). Mine the 2-3 NON-OBVIOUS specifics (a regex, a guard, an algorithm, a fallback) — one precise surprising mechanism beats a generic capability list.
+
+**Connectors between scenes.** Each scene after the first opens with a linguistic connector referring back ("The core of it is…", "Specifically…", "But note…") so the whole video plays as ONE monologue, not N telegraphic captions read in a row. Read the full script aloud in sequence — if it sounds like disconnected soundbites, rewrite.
+
+**Auto-fail patterns — reject the script if any appear:**
+- ❌ Hook/Problem/Solution/CTA fill-in-the-blank treated as isolated fragments
+- ❌ Sidebar stats (stars/forks/issues) as separate one-line scenes
+- ❌ Every sentence restarts as a stand-alone bullet ("X runs one pipeline. Y writes. Z narrates.")
+- ❌ Generic capability claims ("full-featured", "very powerful", "popular in the community")
+- ❌ Describing the README/repo instead of the product
+- ❌ Closing with "go check it out" / "thanks for watching"
+
+## Voiceover: TTS-Safe Narration (when narration is machine-spoken)
+
+When narration will be synthesized by a TTS engine (AI voiceover, not a human reading),
+the spoken `narration` and the on-screen text are SEPARATE channels — one is heard, one
+is read. Optimize each independently; never feed a raw slug, number, or symbol into TTS
+and hope the voice guesses right. (The Vietnamese examples below illustrate the pattern;
+apply the same phonetic + numbers-as-words substitution for whatever language the target
+TTS engine speaks.)
+
+**Numbers → spoken words** (many neural TTS engines can misread bare digits — VN examples):
+
+| Form | TTS misreads | Write as |
+|---|---|---|
+| Version decimal | `GPT 5.5` → "năm rưỡi" | `GPT năm chấm năm` |
+| Stat decimal | `82.7%` | `tám mươi hai phẩy bảy phần trăm` |
+| Spec | `200MP` | `hai trăm megapixel` |
+| Price | `$5` / `21 triệu` | `năm đô` / `hai mươi mốt triệu đồng` |
+| Multiplier / percent | `2x` / `30%` | `gấp đôi` / `ba mươi phần trăm` |
+
+**English/brand names → phonetic in narration, exact spelling on screen:**
+
+| Term | narration (heard) | display (read) |
+|---|---|---|
+| README | `ruýt my` | `README` |
+| ffmpeg | `ép ép em peg` | `ffmpeg` |
+| GitHub / repo | `git hâb` / `rề pô` | `GitHub` / `repo` |
+| API / GPT | `ây pi ai` / `gí pi tí` | `API` / `GPT` |
+
+**Strip from spoken narration:** emoji, URLs (say "github chấm com gạch…"), symbols (`→ & % $ # / @`), slash-commands (say "the plugin install command"), file extensions mid-sentence (say "the YAML file"), camelCase identifiers, ellipsis `…` and em-dash `—` (TTS misreads them — split into two short sentences). End every sentence with `.` or `?` for a natural pause.
+
+**Keep the jargon, natural spoken register.** Write the way a knowledgeable friend SAYS it — but keep the standard technical term ("commit", "endpoint", "prompt" stay in their usual form; a hard translation sounds wrong and loses meaning). Only translate when the local word is the one people actually use.
+
+**Production notes for a spoken video (if it will actually be produced, not just planned):**
+- **One voice, one provider across all scenes** — a voice/provider change mid-video is jarring.
+- **Measure TTS duration FIRST**, then size each scene's visuals to the real audio length — estimating duration then rendering causes A/V drift.
+- **Karaoke captions are the #1 pro-signal** for short-form (TikTok/Reels/Shorts): a bottom-center caption filling word-by-word in sync with the voice, keyword-accented. Muted-autoplay comprehension plus the single strongest "professional" cue — reserve a bottom caption band for it.
+
 ## Note
 
 This skill creates PLANS for video production. Actual recording and editing must be done by a human or a dedicated screen recording tool.
@@ -185,10 +252,15 @@ Known failure modes for this skill. Check these before declaring done.
 | Missing CTA section in script | MEDIUM | CTA (last 10s) is required in every script — no exceptions regardless of duration |
 | Not saving to file (only verbal output) | HIGH | Constraint 3 + Step 6: Write to output_path is mandatory — verbal only = no persistence |
 | Promising an actual deliverable video file | MEDIUM | Note explicitly: this skill creates a PLAN — actual recording is done by a human |
+| Flat catalogue opener ("Today we'll look at…") instead of a pain-first hook | HIGH | Narration Craft #1: open on the viewer's biggest pain — an opener that names no problem loses the scroll in 2 seconds |
+| Raw slugs/numbers/symbols left in narration for TTS ("README", "82.7%", "5.5") | HIGH | Voiceover section: rewrite spoken narration phonetically + numbers-as-words; keep exact spelling only on the display channel |
+| Script reads as N disconnected soundbites | MEDIUM | Narration Craft connectors: each scene after the first opens referring back — read the whole script aloud before declaring done |
 
 ## Done When
 
 - Platform constraints identified and applied to duration/format
+- Narration Craft applied — pain-first opening, cross-scene connectors, ≥1 caveat-as-feature, no auto-fail patterns
+- If narration is TTS-spoken: numbers-as-words + phonetic brand names in the spoken channel, exact spelling on display
 - Script written with timing marks (hook, setup, demo/body, CTA)
 - Storyboard created scene-by-scene with transitions
 - Shot list categorized by type (screen recording, terminal, code, diagram)