Skip to content

puntorigen/avatar-skills / onboarding-script

onboarding-script

Verified

scripts/scaffold_episode.py

View on GitHub
#!/usr/bin/env python3
"""Scaffold per-episode beat sheets (episode.json) from a curriculum.json.

Each episode gets a beat skeleton (hook -> content/demo/broll -> outro) with a
`kind` per beat (talking_head | demo | broll) and TODO placeholders for the agent
to fill with copy grounded in company_context.json. `demo` beats are pre-seeded
from the episode's `demo_targets`.

Pure stdlib.

    python3 scaffold_episode.py --curriculum onboarding/acme/curriculum.json \
        --out-dir onboarding/acme/episodes/
    python3 scaffold_episode.py --curriculum .../curriculum.json --episode create-project
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

HOOK_SECS = 3
OUTRO_SECS = 5
SECS_PER_BEAT = 6  # rough pacing target


def build_beats(ep: dict) -> list[dict]:
    seconds = int(ep.get("target_seconds", 45))
    lang = ep.get("language", "en")
    topics = ep.get("topics") or [ep.get("title", "the topic")]
    demo_targets = ep.get("demo_targets") or []
    needs_demo = bool(ep.get("needs_demo")) or bool(demo_targets)

    n_total = max(4, round(seconds / SECS_PER_BEAT))
    n_mid = max(2, n_total - 2)  # excluding hook + outro
    mid_secs = max(2, round((seconds - HOOK_SECS - OUTRO_SECS) / n_mid))

    beats: list[dict] = []

    beats.append({
        "id": "b1", "kind": "talking_head", "seconds": HOOK_SECS,
        "narration": f"TODO: warm one-line hook for '{ep.get('title')}' — the promise, no jargon.",
        "on_screen": "TODO: presenter to camera; title card optional.",
        "caption": "TODO: short caption (<= 6 words).",
        "note": "Hook: say who this is for and what they'll get. Keep it to ~1 short sentence.",
    })

    # Plan the middle: place demo beats first, then one B-roll, rest talking_head.
    demo_slots = len(demo_targets) if demo_targets else (1 if needs_demo else 0)
    demo_slots = min(demo_slots, n_mid)
    broll_slot = 1 if n_mid - demo_slots >= 1 else 0
    kinds = (["demo"] * demo_slots) + (["broll"] * broll_slot)
    kinds += ["talking_head"] * (n_mid - len(kinds))

    di = 0
    for i, kind in enumerate(kinds):
        topic = topics[i % len(topics)]
        bid = f"b{i + 2}"
        beat = {
            "id": bid, "kind": kind, "seconds": mid_secs,
            "narration": f"TODO: explain '{topic}' for the new hire. Ground it in company_context.json; mark unknowns [TO CONFIRM].",
            "on_screen": "TODO: what appears on screen.",
            "caption": "TODO: short caption.",
        }
        if kind == "demo":
            tgt = demo_targets[di] if di < len(demo_targets) else {}
            di += 1
            beat["demo"] = {
                "url": tgt.get("url", ""),
                "intent": tgt.get("intent", f"TODO: describe the screen recording for '{topic}' (natural language)."),
                "language": lang,
            }
            beat["note"] = "Screen recording: the narration is the voice-over spoken while the demo plays. Needs url + intent."
        elif kind == "broll":
            beat["broll"] = f"TODO: describe a silent B-roll visual reinforcing '{topic}' (people/objects/UI, NO presenter)."
            beat["note"] = "B-roll: the narration is voice-over; describe the visual, no presenter on camera."
        else:
            beat["note"] = f"Talking-head on '{topic}'. Short spoken sentences (captions show one phrase at a time)."
        beats.append(beat)

    beats.append({
        "id": f"b{len(beats) + 1}", "kind": "talking_head", "seconds": OUTRO_SECS,
        "narration": "TODO: recap in one line + the single next action for the new hire.",
        "on_screen": "TODO: presenter to camera; end card with the next step.",
        "caption": "TODO: the next step, short.",
        "note": "Outro: one clear call to action / where to go next.",
    })
    return beats


def build_episode(ep: dict, curriculum: dict) -> dict:
    return {
        "id": ep.get("id"),
        "order": ep.get("order"),
        "slug": ep.get("slug"),
        "title": ep.get("title"),
        "company": curriculum.get("company"),
        "company_name": curriculum.get("company_name"),
        "language": ep.get("language", curriculum.get("language", "en")),
        "audience": ep.get("audience", curriculum.get("audience")),
        "target_seconds": int(ep.get("target_seconds", 45)),
        "objective": ep.get("objective", ""),
        "topics": ep.get("topics", []),
        "sources": list(ep.get("sources", [])),
        "voice": {"emotion": "warm"},
        "beats": build_beats(ep),
    }


def main() -> int:
    ap = argparse.ArgumentParser(description="Scaffold per-episode beat sheets from a curriculum.")
    ap.add_argument("--curriculum", type=Path, required=True, help="curriculum.json from scaffold_curriculum.py")
    ap.add_argument("--episode", help="Only scaffold this episode id (default: all)")
    ap.add_argument("--out-dir", type=Path, help="Output dir (default: onboarding/<company>/episodes/)")
    ap.add_argument("--force", action="store_true", help="Overwrite existing episode files")
    args = ap.parse_args()

    try:
        curriculum = json.loads(args.curriculum.read_text(encoding="utf-8"))
    except Exception as exc:  # noqa: BLE001
        print(f"ERROR: could not read curriculum: {exc}", file=sys.stderr)
        return 1

    episodes = curriculum.get("episodes", []) or []
    if args.episode:
        episodes = [e for e in episodes if e.get("id") == args.episode]
        if not episodes:
            print(f"ERROR: no episode with id '{args.episode}' in curriculum", file=sys.stderr)
            return 1

    out_dir = args.out_dir or (args.curriculum.parent / "episodes")
    out_dir.mkdir(parents=True, exist_ok=True)

    written = 0
    for ep in episodes:
        dest = out_dir / f"{ep.get('slug')}.episode.json"
        if dest.exists() and not args.force:
            print(f"  skip (exists): {dest}  (use --force to overwrite)")
            continue
        data = build_episode(ep, curriculum)
        dest.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
        print(f"  -> {dest}  ({len(data['beats'])} beats)")
        written += 1

    print(f"  {written} episode file(s) written to {out_dir}")
    print("  Next: fill each episode.json (ground in company_context.json), then check_episode.py.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall