SuperAPI AI Directory

synthesis-onboarding

General & other

View repository

Updated 10-22 16:15

About this skill

Synthesis Onboarding

Everything a new person needs to go from a bare machine to a working synthesis setup — close to one command plus an auth step. Built for two audiences at once: engineers who want a scriptable, verifiable installer, and non-engineering colleagues who should never see a complicated question.

Three ideas carry the whole design:

  1. One engine, org manifests. The engine is generic. An organization ships configuration — a .agents/onboarding.yaml in its knowledge-base repo — never installer code. Any org gets a colleague installer by writing one YAML file and a three-line wrapper script.
  2. Convergence, not scripts. Every run states desired state and moves the machine toward it. Re-running is always safe: it updates, repairs half-finished installs, and reports instead of clobbering anything a person edited.
  3. Fail closed and loud. Stale caches, unknown manifest keys, and unverifiable state stop with plain-language instructions. A check that cannot run never looks like a check that passed.

The two front doors

Terminal (works with nothing pre-installed except macOS):

curl -fsSL https://raw.githubusercontent.com/synthesisengineering/synthesis-skills/main/onboard.sh | sh

Agent (when Claude Code or Codex already has this plugin): ask the assistant to "set up the synthesis ecosystem" — it runs the same engine:

python3 <this-skill>/scripts/onboard.py install

Organization members use their org's wrapper instead (one command from the org's knowledge-base repo), which calls the same engine with the org's manifest. See references/org-manifest.md.

Commands

onboard.py install [--manifest PATH] [--dry-run] [--json]
                   [--clients claude,codex] [--no-plugin-cli]
                   [--with-personal-workspace NAME]
onboard.py update          # explicit native-plugin refresh + install convergence
onboard.py doctor  [--manifest PATH] [--json]
onboard.py init-workspace --workspace NAME [--remote URL]
onboard.py uninstall [--dry-run]

Exit codes (guard contract): 0 fully converged / healthy; 1 errors or a step that needs the user (auth, git identity) — re-run after acting; 2 the engine could not establish ground truth (no git, invalid manifest).

What install does, in order

Phase Behavior
preflight Verify git (guides through xcode-select --install if missing); detect clients via SYNTHESIS_CLAUDE_BIN/SYNTHESIS_CODEX_BIN → PATH → well-known locations (incl. the ChatGPT app's bundled codex). Absent clients are skipped, not fatal.
ecosystem install adds a missing native plugin and checks an existing one without replacing its live cache. update explicitly refreshes existing native plugins, verifies the resulting version when running from a source checkout, and states whether a new Claude Code session or Codex task is required. A first installation may use the repo's direct-copy fallback when a client lacks the plugin CLI; an installed native plugin is never replaced by duplicate copies.
org-skills For each manifest skills_repos entry: SSH-first clone/refresh into the engine cache, then delegate to that repo's own installer with its source pinned to the fresh cache. A cache that cannot refresh stops the step (SYNTHESIS_ONBOARD_ALLOW_STALE=1 overrides, loudly).
knowledge-bases Clone to ~/workspaces/<org-workspace>/<name>, or adopt an existing clone found by matching remotes (never moved). Superseded remotes are repointed to the manifest primary (git remote set-url). Fast-forward pull when clean. When the repo ships .githooks and no global hooks engine is active, wire repo-local core.hooksPath so protective hooks run on fresh clones. Auth failures print the manifest's auth_help and mark the step "needs you" — the run continues and the re-run completes it.
workspace Generate ~/workspaces/<org-workspace>/AGENTS.md (+ CLAUDE.md = @AGENTS.md): the welcome, what-you-can-ask list, KB contract pointers.
migrations Apply the manifest's skill tombstones (remove / rename / superseded-by-public) to user-level skill copies — archive first, always.
doctor + welcome Verify everything, then greet: what to try asking, where the guides are, and that re-running is always safe.

Receipts and the no-clobber rule

State lives at ~/.synthesis/onboarding/receipts.json: every generated file's checksum, adopted repo locations, run history. A generated file whose current content matches its receipt is engine-owned and may be updated (previous copy archived under ~/.synthesis/onboarding/backups/). A file a person edited is never overwritten — the engine warns and moves on. uninstall removes only receipt-owned files (archived first) and never touches knowledge-base clones or plugins.

Safe plugin upgrades

Run onboard.py update only after closing other Claude Code sessions and Codex tasks that use this marketplace, and make it the invoking session's last action before starting a new session/task. Native clients resolve plugin hooks to versioned cache paths; replacing that cache can invalidate hook commands already loaded by another live session. Ordinary install and doctor runs never refresh an existing native plugin.

Scaffolding a personal knowledge workspace

onboard.py init-workspace --workspace alice [--remote git@github.com:alice/ai-knowledge-alice.git]

Creates ~/workspaces/<name>/ai-knowledge-<name>/ with projects/index.yaml, lessons/, AGENTS.md + CLAUDE.md adapter, README, git init and first commit — the synthesis-project-management container shape. Project content stays agent-authored (that skill's "examine an example and adapt" principle); this scaffolds the container so day one needs no hand-wiring.

Configuration

Env var Default Purpose
SYNTHESIS_ONBOARD_HOME $HOME Root for all install targets (tests use a sandbox home)
SYNTHESIS_ONBOARD_STATE_DIR ~/.synthesis/onboarding Receipts + backups
SYNTHESIS_WORKSPACES_ROOT ~/workspaces Where workspaces and KBs live
SYNTHESIS_ONBOARD_CACHE_DIR XDG cache Org repo caches
SYNTHESIS_ONBOARD_SOURCE_DIR this repo synthesis-skills checkout to install from
SYNTHESIS_CLAUDE_BIN / SYNTHESIS_CODEX_BIN auto Client binary override; set-but-empty means "treat as absent"
SYNTHESIS_ONBOARD_ALLOW_STALE unset Accept an unrefreshable cache (loud)
SYNTHESIS_ONBOARD_NO_PLUGIN_CLI unset Force file-copy fallback

Relationship to neighbors

  • install.sh (repo root) — the per-skill copy fallback this engine delegates to when a client lacks native plugin support.
  • onboard.sh (repo root) — the curl-able bootstrap: ensures git, clones or refreshes this repo, hands off to this engine.
  • synthesis-skills-manager — the agent-run protocol for skill authors (multi-repo source management, synthesis merges). This engine is the end-user installer; it never edits sources.
  • synthesis-agent-conformance — the deep parity audit for maintainers. onboard.py doctor is the end-user health check; conformance remains the authoritative source/runtime/handoff verification.
  • synthesis-project-management / context-lifecycle — define the workspace shape that init-workspace scaffolds.

Supported client surfaces

  • Claude Code, ChatGPT Codex desktop, and Codex CLI are first-class native plugin surfaces.
  • Codex IDE is reported as UNSUPPORTED: it does not load plugins, and its shared user-skill roots cannot hold a second public copy without creating duplicate definitions in desktop/CLI.
  • A plugin change is visible only in a newly started session/task. Preserve the synthesis checkpoint before switching; do not ask an existing task to pretend it reloaded its startup registry.

Safety rules

  • Never delete without archiving first; never force-push anything.
  • Never overwrite a file the user edited (receipts decide ownership).
  • Never enumerate or clone repos the manifest does not name.
  • Org manifests are validated fail-closed: unknown keys are errors.
  • The engine runs on python3 stdlib alone (PyYAML optional) so a fresh Mac with Command Line Tools needs nothing else.
  • v1 targets macOS; the engine avoids macOS-only code paths so Linux and Windows (WSL first) can follow without redesign.