opensite-ai/opensite-skills / book-recorded-sessions
book-recorded-sessions
VerifiedPlan, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| assets/segment_types.yaml | config | 5.1 KB |
| references/contributor-release.md | markdown | 2.8 KB |
| references/merge-rules.md | markdown | 2.4 KB |
| references/session-formats.md | markdown | 3.8 KB |
| scripts/chapter_trace.pyexecutable | script | 8.1 KB |
| scripts/session_ingest.pyexecutable | script | 9.4 KB |
| scripts/session_plan.pyexecutable | script | 8.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |