Skip to content

opensite-ai/opensite-skills / book-recorded-sessions

book-recorded-sessions

Verified

Plan, record, and merge recorded sessions into book chapters: solo lessons, interviews with a proxy reader, multi-guest panels, or hybrid lesson-plus-conversation episodes that also serve video and short-form clips. Covers contract-driven run-of-show, contributor releases and employer clearance, per-speaker capture and transcripts, speaker-attributed atoms, merging many sessions into a traceable chapter, and clip hand-off flags. Use when chapters are built from spoken recordings or podcasts. Not for narrating the finished audiobook or editing clips.

FileKindSize
SKILL.mdskill md4.9 KB
assets/segment_types.yamlconfig5.1 KB
references/contributor-release.mdmarkdown2.8 KB
references/merge-rules.mdmarkdown2.4 KB
references/session-formats.mdmarkdown3.8 KB
scripts/chapter_trace.pyexecutablescript8.1 KB
scripts/session_ingest.pyexecutablescript9.4 KB
scripts/session_plan.pyexecutablescript8.1 KB

scripts/session_plan.py

View on GitHub
#!/usr/bin/env python3
"""Turn a chapter contract into a run-of-show for a recorded session.

Formats: solo, interview (author + proxy reader), panel (author + practitioners), hybrid
(part A lesson with a proxy reader, part B conversation with practitioners). Every segment
maps to a chapter-contract field or atom type, so the recording produces what the chapter
needs. Segments marked as clips are designed to stand alone for short-form video.

Reads 03-manuscript/CHAPTER_CONTRACTS.yaml, 01-evidence/CONTRIBUTORS.csv (roles), and
assets/segment_types.yaml. Fails when the contract lacks a field the session must cover,
when the format needs a role nobody holds, or when an atoms_min type has no segment.

Usage:
  python scripts/session_plan.py <project_root> --chapter ch01 --format hybrid
         [--minutes 90] [--session-id S01] [--out RUN_OF_SHOW.md] [--json plan.json]
         [--allow-incomplete]
"""
import argparse
import csv
import json
import pathlib
import sys

try:
    import yaml  # type: ignore
except ImportError:  # pragma: no cover
    print("PyYAML is required: pip install pyyaml", file=sys.stderr)
    sys.exit(2)

HERE = pathlib.Path(__file__).resolve().parent
REQUIRED = ["title", "reader_problem", "promise", "key_model", "outcome_exercise"]


def load_contributors(root):
    p = root / "01-evidence" / "CONTRIBUTORS.csv"
    if not p.exists():
        return []
    with open(p, newline="", encoding="utf-8") as fh:
        return [r for r in csv.DictReader(fh) if (r.get("contributor_id") or "").strip()]


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("root")
    ap.add_argument("--chapter", required=True)
    ap.add_argument("--format", required=True, choices=["solo", "interview", "panel", "hybrid"])
    ap.add_argument("--minutes", type=int, help="total session minutes (default from the format)")
    ap.add_argument("--session-id", default="S??")
    ap.add_argument("--segments", default=str(HERE.parent / "assets" / "segment_types.yaml"))
    ap.add_argument("--out", help="write the run-of-show markdown here")
    ap.add_argument("--json")
    ap.add_argument("--allow-incomplete", action="store_true", help="plan even if contract fields are empty")
    args = ap.parse_args()
    root = pathlib.Path(args.root).resolve()

    lib = yaml.safe_load(pathlib.Path(args.segments).read_text(encoding="utf-8"))
    contracts = yaml.safe_load((root / "03-manuscript" / "CHAPTER_CONTRACTS.yaml").read_text(encoding="utf-8")) or {}
    ch = next((c for c in contracts.get("chapters", []) if c.get("id") == args.chapter), None)
    problems, warnings = [], []
    if ch is None:
        print(f"chapter {args.chapter} not found in CHAPTER_CONTRACTS.yaml", file=sys.stderr)
        return 1
    fmt = lib["formats"][args.format]
    total = args.minutes or int(fmt["minutes"])

    missing = [f for f in REQUIRED if not str(ch.get(f) or "").strip()]
    if missing:
        (warnings if args.allow_incomplete else problems).append(
            f"contract fields empty: {missing}; complete the chapter contract before recording")
    if not str(ch.get("verification_step") or "").strip():
        warnings.append("contract has no verification_step; the verification segment will ask for one")

    people = load_contributors(root)
    by_role = {}
    for r in people:
        by_role.setdefault((r.get("role") or "").strip(), []).append(r)
    for need in fmt.get("needs", []):
        if need not in by_role:
            problems.append(f"format '{args.format}' needs a contributor with role '{need}' in CONTRIBUTORS.csv")
    for r in people:
        if (r.get("role") or "").strip() not in ("author", "producer") and not (r.get("rights_id") or "").strip():
            problems.append(f"{r['contributor_id']}: no rights_id; get a signed contributor release before recording")

    weights = [(seg, float(wt), part) for seg, wt, part in fmt["segments"]]
    scale = total / sum(wt for _, wt, _ in weights)
    mins = [max(1, round(wt * scale)) for _, wt, _ in weights]
    mins[-1] += total - sum(mins)
    segs, t = [], 0
    for (seg, _, part), m in zip(weights, mins):
        d = lib["segments"][seg]
        lead = d["lead"] if d["lead"] in by_role else "author"
        names = [p["name"] for p in by_role.get(lead, [])] or [lead]
        covers = {f: str(ch.get(f) or "").strip() for f in d.get("covers", [])}
        segs.append({"id": seg, "title": d["title"], "part": part, "start_min": t, "end_min": t + m, "minutes": m,
                     "lead_role": lead, "lead": ", ".join(names), "covers": covers,
                     "atom_types": d.get("atom_types", []), "clip": bool(d.get("clip")),
                     "purpose": d.get("purpose", ""), "prompts": d.get("prompts", [])})
        t += m

    produced = {a for s in segs for a in s["atom_types"]}
    for typ in (ch.get("atoms_min") or {}):
        if typ not in produced:
            problems.append(f"atoms_min type '{typ}' has no segment in format '{args.format}'")
    coverage = {f: [s["id"] for s in segs if f in s["covers"]] for f in REQUIRED + ["verification_step"]}
    for f in ("promise", "reader_problem", "key_model", "outcome_exercise"):
        if not coverage[f]:
            problems.append(f"contract field {f} is not covered by any segment")

    report = {"pass": not problems, "session_id": args.session_id, "chapter": args.chapter, "format": args.format,
              "minutes": total, "segments": segs, "coverage": coverage, "clip_segments": [s["id"] for s in segs if s["clip"]],
              "problems": problems, "warnings": warnings}

    lines = [f"# Run of show: {args.session_id} — {ch.get('id')} {ch.get('title') or ''}".rstrip(), "",
             f"Format: {args.format} · {total} minutes · atoms needed: {ch.get('atoms_min') or {}}", "",
             "## Before recording", "",
             "- Signed contributor releases on file for every guest (RIGHTS_LEDGER status: cleared).",
             "- Confidentiality brief: no client names, deal terms, or internal numbers without written clearance.",
             "- One microphone per speaker on its own track; 48 kHz/24-bit WAV; camera angles set.",
             "- Slate: session id, date, chapter. Record 30 seconds of room tone with everyone silent.",
             "- On the record: everyone confirms they know the recording feeds the book, channel, and clips.",
             "", "## Segments", ""]
    for s in segs:
        lines += [f"### {s['start_min']:02d}-{s['end_min']:02d} min · part {s['part']} · {s['title']}"
                  + (" · clip" if s["clip"] else ""), "",
                  f"Lead: {s['lead']} ({s['lead_role']}). Purpose: {s['purpose']}"]
        for f, v in s["covers"].items():
            lines.append(f"- Must cover `{f}`: {v or 'MISSING in contract'}")
        lines.append(f"- Produces atoms: {', '.join(s['atom_types']) or 'none'}")
        for q in s["prompts"]:
            lines.append(f"- Prompt: {q}")
        lines.append("")
    lines += ["## After recording", "",
              "- Producer exports per-speaker transcripts and markers.csv (segment_id,start) to the session folder.",
              "- Run session_ingest.py, extract atoms with speaker and session_id, run atom_coverage.py.",
              "- Record pickups for any gap the coverage check reports before drafting the chapter.", ""]
    if problems or warnings:
        lines += ["## Problems and warnings", ""] + [f"- PROBLEM: {p}" for p in problems] + [f"- warning: {w}" for w in warnings]
    md = "\n".join(lines) + "\n"
    if args.out:
        out = pathlib.Path(args.out)
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text(md, encoding="utf-8")
    print(f"{'PASS' if report['pass'] else 'FAIL'} {args.chapter} {args.format}: {len(segs)} segments, {total} min, "
          f"{len(report['clip_segments'])} clip segments")
    for p in problems:
        print(f"  - {p}")
    for w_ in warnings:
        print(f"  ~ {w_}")
    if args.json:
        pathlib.Path(args.json).write_text(json.dumps(report, indent=2), encoding="utf-8")
    return 0 if report["pass"] else 1


if __name__ == "__main__":
    sys.exit(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