Onboarding script

Onboarding Script

Write the words + screens for an ordered series of onboarding reels that introduce a new team member to a company. This skill only produces the scripts (text/JSON); the videos are generated later by the avatar pipeline (avatar-video-reel / avatar-reel-composer), which the outputs drop straight into.

It is company-agnostic: it learns the company from whatever tooling is connected — the logged-in GitHub org/account (gh), the cloud CLIs (az/gcloud/vercel), a Notion MCP, a Linear MCP, and past chat transcripts — and degrades gracefully when a source is missing (records the gap and asks you to confirm an assumption instead of inventing facts).

What it produces

An ordered curriculum (curriculum.json) and, per episode, a format-agnostic package so either downstream skill can consume it:

• NN_<slug>.script.md — human shooting script (beats: VO + on-screen + [DEMO] intent + B-roll + captions + timing).
• NN_<slug>.narration.txt — clean spoken VO only (feed to voice-clone / avatar-reel-composer's narrate.py).
• NN_<slug>.reel.txt — plain-text script with [DEMO: url | intent]...[/DEMO] markers (drop-in for avatar-video-reel).
• NN_<slug>.storyboard.json — a storyboard scaffold (talking_head + broll scenes whose text tiles the narration verbatim) for avatar-reel-composer; fill avatar_dir when you pick an avatar.
• README.md — the series index, in order.

All outputs land under onboarding/<company>/ (git-ignored).

Workflow

Copy this checklist and track progress:

- [ ] 1. Discover context   (detect_context.py + augment with MCP/CI/transcripts)
- [ ] 2. Confirm the company (fill facts{}, resolve gaps, get sign-off on assumptions)
- [ ] 3. Plan the curriculum (scaffold_curriculum.py — user guideline OR default minimum)
- [ ] 4. Scaffold episodes   (scaffold_episode.py — one beat sheet per episode)
- [ ] 5. Write the copy       (fill each episode.json, grounded in company_context.json)
- [ ] 6. Validate             (check_episode.py — fix every FAIL, weigh WARNs)
- [ ] 7. Render               (render_episode.py — the 4 files/episode + README)
- [ ] 8. Hand off             (feed .reel.txt / .storyboard.json to the avatar skills)

1. Discover context

Probe every connected source and write company_context.json:

python3 .cursor/skills/onboarding-script/scripts/detect_context.py \
  --out onboarding/<company>/context/company_context.json
# optional: --org <github-org>  --keywords "acme,widget,platform"  --no-workflows

The script covers the CLI-visible sources (read-only, short timeouts, never fails a run if a tool is absent):

• GitHub (gh): login, orgs, repos (name/description/language/topics/default branch/template flag), flags a skills/templates/starter/.github repo, and scans a few repos' .github/workflows/*.yml for deploy hints.
• Clouds (first-class, each optional): az account show; gcloud config list + gcloud projects list; vercel whoami + vercel projects ls. Plus name-detection of aws/flyctl/wrangler/kubectl/docker/…
• Transcripts: finds this project's agent-transcripts/ and greps for company/stack keywords.

Then you (the agent) augment the JSON with the MCP-only and doc-only sources (the script can't call MCPs) — see REFERENCE.md "Discovery playbook" for the exact queries:

• If a Notion MCP is connected: search for handbook / onboarding / engineering-guidelines / deploy pages; pull the relevant ones.
• If a Linear MCP is connected: read the team, workflow states, labels and projects (the real "how we work" process).
• Read the flagged repos' README/CONTRIBUTING and CI workflows via gh api to ground the create-project and deploy steps.
• Mine the transcript matches for company-specific facts.

Fill the facts{} block and set each sources[].status. Never fabricate internal process: if a fact is unknown, leave it and mark it [TO CONFIRM].

2. Confirm the company

If company_selection.needs_user_choice is true (the probe found more than one probable company across the connected sources — e.g. a gh login/org plus a different gcloud/vercel/az account), STOP and ask the user which one is correct before doing anything else. Use AskQuestion and list company_candidates[] (show each name + the sources that suggested it). Then lock it in by re-running:

python3 .cursor/skills/onboarding-script/scripts/detect_context.py \
  --company <chosen>   # or --org <chosen> if it's the GitHub org \
  --out onboarding/<company>/context/company_context.json

Then show the user the resolved company, stack, and the gaps[] list, and get sign-off on any assumption before scripting.

3. Plan the curriculum

Ask the user for a guideline (which topics, order, target role, language, length). If they don't give one, propose the minimum default curriculum:

1. Welcome & company intro — mission, values, team, what we build.
2. Tools & accounts we use — the detected stack (gh org, cloud, Notion, Linear, comms) + how to get access.
3. Engineering best practices — branching, PRs, reviews, coding standards.
4. Create a new project with the company skills — the concrete bootstrap (template repo / npx skills add <org>/… / scaffold).
5. How we deploy — the real CI/CD + cloud flow (from the CI workflows and the detected cloud: Azure/GCP/Vercel).
6. Where to get help & what's next — people, docs, rituals.

# default minimum curriculum (grounded in the context)
python3 .cursor/skills/onboarding-script/scripts/scaffold_curriculum.py \
  --context onboarding/<company>/context/company_context.json \
  --language en --audience "new engineer" --seconds 45 \
  --out onboarding/<company>/curriculum.json

# custom set: write an episodes JSON (id/title/objective/topics/demo_targets) and pass it
python3 .cursor/skills/onboarding-script/scripts/scaffold_curriculum.py \
  --context .../company_context.json --episodes-file my_topics.json \
  --out onboarding/<company>/curriculum.json

4. Scaffold episodes

Turn the curriculum into one beat-sheet episode.json per episode:

python3 .cursor/skills/onboarding-script/scripts/scaffold_episode.py \
  --curriculum onboarding/<company>/curriculum.json \
  --out-dir onboarding/<company>/episodes/
# or a single one: --episode create-project

5. Write the copy

Edit each episodes/<slug>.episode.json. Every beat has a kind (talking_head | demo | broll), narration (the spoken VO), on_screen, caption, and — for demo beats — a demo.url + demo.intent (natural-language description of the screen recording). Ground every claim in company_context.json; cite the source in the episode's sources[]; mark anything unverified [TO CONFIRM]. Keep sentences short and spoken (this is read aloud / lip-synced and captioned).

6. Validate (feedback loop)

python3 .cursor/skills/onboarding-script/scripts/check_episode.py \
  onboarding/<company>/episodes/*.episode.json

Fix every FAIL; weigh each WARN. Re-run until it passes.

7. Render

python3 .cursor/skills/onboarding-script/scripts/render_episode.py \
  onboarding/<company>/episodes/*.episode.json \
  --out onboarding/<company>/scripts/

Writes the four files per episode + the series README.md index.

8. Hand off

The rendered files are drop-in for the avatar pipeline the user installs later:

# avatar-video-reel: the [DEMO]-marked plain-text script
python3 .cursor/skills/avatar-video-reel/scripts/generate_reel.py \
  --script-file onboarding/<company>/scripts/04_create-project.reel.txt --language en --format reel ...

# avatar-reel-composer: the storyboard scaffold (set avatar_dir first)
python3 .cursor/skills/avatar-reel-composer/scripts/compose_reel.py \
  onboarding/<company>/scripts/01_welcome.storyboard.json --finish

Output layout

onboarding/<company>/
  context/company_context.json   # what we discovered (+ your MCP/doc augmentation)
  curriculum.json                # ordered episodes
  episodes/<slug>.episode.json   # per-episode beat sheet (source of truth; edit these)
  scripts/                       # rendered: .script.md .narration.txt .reel.txt .storyboard.json
  README.md                      # the series index, in order

Anti-patterns

1. Inventing internal process (deploy steps, tools) not backed by a source — mark [TO CONFIRM] and ask instead.
2. Hard-coding one company — always resolve identity/stack from the connected tools; nothing is specific to any org.
3. One long block of VO — short sentences per beat so captions show one phrase at a time.
4. A demo beat without a url + intent — the recorder needs both (it drives the browser from the intent).
5. Skipping the confirmation step — never ship assumptions as facts.

Additional resources

• The full discovery playbook (exact gh + az/gcloud/vercel probes, Notion/Linear prompts, transcript mining, degrade-gracefully rules), the JSON schemas, and the tool-to-topic map: REFERENCE.md
• Worked examples: examples/curriculum.example.json, examples/episode.example.json, examples/01_welcome.script.example.md