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:
- One engine, org manifests. The engine is generic. An organization
ships configuration — a
.agents/onboarding.yamlin its knowledge-base repo — never installer code. Any org gets a colleague installer by writing one YAML file and a three-line wrapper script. - 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.
- 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 doctoris the end-user health check; conformance remains the authoritative source/runtime/handoff verification. - synthesis-project-management / context-lifecycle — define the
workspace shape that
init-workspacescaffolds.
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.