Skip to content

puntorigen/avatar-skills / onboarding-script

onboarding-script

Verified

REFERENCE.md

View on GitHub
# Onboarding Script — reference

The discovery playbook (how the agent augments the machine-detected context),
the JSON schemas, the tool-to-topic map, and the degrade-gracefully rules.

## Discovery playbook

`detect_context.py` covers the **CLI-visible** sources. You (the agent) then
augment `company_context.json` with the sources a script can't reach (MCPs, repo
docs) and fill the `facts{}` block. Ground every claim; never invent internal
process — mark unknowns `[TO CONFIRM]` and confirm with the user.

### GitHub (`gh`) — identity, create-project, deploy

Already probed by the script (login, orgs, repos, notable repos, CI deploy
hints). Deepen the two action topics by reading the flagged repos:

```bash
OWNER=<org>; REPO=<skills-or-template-repo>
gh api repos/$OWNER/$REPO/readme --jq '.content' | base64 -d | head -c 4000
gh api repos/$OWNER/$REPO/contents/CONTRIBUTING.md --jq '.content' 2>/dev/null | base64 -d | head -c 4000
gh api repos/$OWNER/$REPO/contents/.github/workflows --jq '.[].name'
# read a specific workflow to ground "how we deploy"
gh api repos/$OWNER/$REPO/contents/.github/workflows/deploy.yml --jq '.content' | base64 -d
```

Put the concrete steps into `facts.create_project.steps[]` and
`facts.deploy.steps[]`, each with the repo/workflow it came from in `sources[]`.

### Notion MCP (if connected)

Detect it first (inspect the MCP servers). If present, search for the handbook
and process docs and pull the relevant pages. Typical queries:
- "onboarding" / "new hire" / "getting started" / "handbook"
- "engineering guidelines" / "code review" / "branching" / "definition of done"
- "deploy" / "release" / "runbook" / "infrastructure"
- "tools" / "accounts" / "access" / "provisioning"

Record `mcp.notion = "connected"` and cite each page title/URL used in the
episode's `sources[]`. If no Notion MCP is connected, set `mcp.notion = "absent"`
and rely on the other sources.

### Linear MCP (if connected)

If present, read the real "how we work":
- teams + members (who owns what)
- workflow states (the actual pipeline: Backlog -> ... -> Done)
- labels, cycles/sprints, and any Linear "Documents"
- a couple of representative projects/issues to show the flow

Feed this into the **best-practices** and **get-help** episodes. Record
`mcp.linear = "connected"` (or `"absent"`), cite what you used.

### Chat transcripts

`detect_context.py` greps this project's `agent-transcripts/*.jsonl` for the
company/stack keywords and records matches. Read the matched files for
company-specific decisions (stack choices, deploy quirks, naming conventions).
Treat them as **hints**, not authority — confirm anything you'll state as fact.

### Public info (optional, intro only)

A `perplexity_ask` MCP (if present) can enrich the **welcome** episode with
*public* positioning only. Never use it to fabricate internal process.

## Degrade-gracefully rules

- Every source is optional. A missing source is recorded in `sources[]` with
  `status` ∈ `ok | missing | unauthenticated | unknown` and added to `gaps[]`.
- For any fact you can't ground, write the copy with a `[TO CONFIRM]` marker and
  surface it in the confirmation step (workflow step 2). `check_episode.py` warns
  on residual `[TO CONFIRM]`.
- Prefer asking one targeted question over guessing. In particular, when
  `company_selection.needs_user_choice` is true (more than one probable company
  across gh/gcloud/vercel/az), ask the user to pick from `company_candidates[]`
  and re-run with `--company`/`--org`. Likewise ask "What's our deploy target?"
  when no cloud CLI is authed and CI has no hints.

## Tool -> topic map

Which discovered source primarily feeds which episode:

- **Welcome & company intro** <- gh owner profile, Notion handbook, public info.
- **Tools & accounts** <- gh org, clouds (`az`/`gcloud`/`vercel`), other CLIs, Notion "accounts/access".
- **Best practices** <- gh CONTRIBUTING + branch protection, Linear workflow states, Notion "engineering guidelines".
- **Create a new project** <- gh `skills`/`templates`/`.github` repo READMEs, `npx skills add`, template repos.
- **How we deploy** <- gh `.github/workflows/*.yml` deploy hints + the authed cloud CLI (Azure/GCP/Vercel), Notion runbook.
- **Get help & next** <- Linear teams/owners, Notion index, gh CODEOWNERS.

## Cloud CLI probes (first-class, read-only)

- **Azure** `az`: `az account show -o json` -> subscription/tenant/user.
- **GCP** `gcloud`: `gcloud config list --format=json` + `gcloud projects list --format=json --limit=25`.
- **Vercel** `vercel`: `vercel whoami` + `vercel projects ls`.
- **Name-detected** (presence only): `aws`, `flyctl`/`fly`, `wrangler`, `kubectl`, `docker`, `heroku`, `netlify`, `supabase`, `terraform`, `pulumi`, `railway`, `render`.

Each records `{tool, present, authed, identity?, projects[]}`.

## Schemas

### company_context.json

```
generated_at        ISO timestamp
company             { name, login?, slug, kind, description?, url?, sources[] }   # the resolved/selected one
company_candidates[] { name, slug, kind: github_org|github_account|gcloud|vercel|az,
                       sources[], signals[] }   # every probable company, merged across sources
company_selection   { selected: <slug|null>, needs_user_choice: bool, reason }   # ask the user when true
github              { present, authed, login, orgs[], selected_owner, ambiguous_owner?,
                      owner_profile{}, repos[]{name,description,language,topics,default_branch,is_template,visibility,url,updated_at},
                      notable{ skills_repo, templates[], dotgithub, template_flagged[] },
                      workflows[]{ repo, deploy_hints[] } }
clouds[]            { tool: az|gcloud|vercel, present, authed, identity?{}, projects[] }
other_clis[]        { tool, present }
transcripts         { dirs[], files_scanned, matches[]{file, hits[]} }
mcp                 { notion: unknown|connected|absent, linear: ... }   # agent fills
stack_inferred[]    strings
sources[]           { source, status: ok|missing|unauthenticated|unknown, detail }
facts               { mission, values[], team,
                      tools_accounts[]{tool,detail,source},
                      best_practices{summary,items[],sources[]},
                      create_project{summary,steps[],sources[],skills_repo,templates[]},
                      deploy{summary,steps[],sources[],hints[]} }               # agent fills
gaps[]              strings (assumptions to confirm)
```

### curriculum.json

```
company, company_name, language, audience, generated_at, guideline, context_path
episodes[] { id, order, slug, title, objective, audience, language,
             target_seconds, topics[], needs_demo, demo_targets[]{url,intent}, sources[] }
```

### episode.json (source of truth — edit these)

```
id, order, slug, title, company, company_name, language, audience,
target_seconds, objective, topics[], sources[], voice{emotion,...}
beats[] {
  id, kind: talking_head|demo|broll, seconds,
  narration,            # the spoken VO (the avatar says this)
  on_screen, caption, note,
  demo?  { url, intent, language }     # when kind == demo
  broll? "visual description"          # when kind == broll
}
```

### Rendered outputs

- `<slug>.script.md` — human shooting script table.
- `<slug>.narration.txt` — VO paragraphs (blank-line separated).
- `<slug>.reel.txt` — `avatar-video-reel` plain text; `demo` beats become
  `[DEMO: url | intent]\n<VO>\n[/DEMO]`; others are plain talking-head lines.
- `<slug>.storyboard.json` — `avatar-reel-composer` scaffold. `talking_head`
  beats -> `talking_head` scenes; `demo`/`broll` beats -> `broll` scenes. Every
  `scene.text` is the beat's verbatim narration and `script` is those joined by
  single spaces (reel-composer's hard tiling rule). `avatar_dir` is a placeholder.

## Handoff

```bash
# avatar-video-reel — the [DEMO]-marked script (records the demos interactively)
python3 .cursor/skills/avatar-video-reel/scripts/generate_reel.py \
  --script-file onboarding/<company>/scripts/04_create-project.reel.txt \
  --language <lang> --format reel --preview

# avatar-reel-composer — set avatar_dir in the storyboard first, then:
python3 .cursor/skills/avatar-reel-composer/scripts/compose_reel.py \
  onboarding/<company>/scripts/01_welcome.storyboard.json --dry-run
```
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