---
name: setup
description: Start using SpielOS after installation, choose or create a company workspace, verify setup, and help with a missing supported Python runtime.
---

Welcome the user to SpielOS: a workspace where they can turn recurring business work into AI workflows they can test and improve. Explain the path in plain language: choose a company folder, choose local or connected tracking, then give Director a first job. Keep setup conversational and guide one decision at a time. Do not ask the user to copy Python or CLI commands. Execute the supported bundled commands yourself through the host's local execution capability and explain the results in plain language.

Resolve the plugin root from this skill's installed file location: the folder containing plugin.json, scripts/ and runtime/. Use scripts/entry.py from that actual root. Never guess a cache path or use a globally installed spielos executable. Invoke entry.py through the selected supported Python interpreter using -I -X utf8 -B. The same entrypoint works on Windows, macOS and Linux; never require /bin/sh on Windows. The MCP server uses the python3 command, so check that Python 3.11+ is available under that name. If a Windows installation exposes only py or python, help enable its python3 alias through the Python install manager or normal environment setup; do not silently edit system Python or PATH. The bundled entrypoint performs no package installation or network download.

1. Ask whether the user wants an existing company folder or a new workspace, and get its explicit location. The current folder is a candidate only when the user selects it. Never create or select a home in the plugin directory, product source checkout, or another company's workspace. Explain that the company folder stays theirs when the plugin is updated or removed.
2. For an existing home, call select_company with its absolute path, then inspect_company. For a new home, run the bundled launcher with `init --dir <explicit absolute folder> -y --json`. The owner's setup request and folder selection authorize that creation; no separate round of confirmation is needed. Do not overwrite an existing folder's owner content or force a migration. Select and inspect the result through MCP.
3. If the launcher reports missing Python 3.11+, explain that desktop execution needs it. Offer to help install a supported interpreter using the user's normal package manager, with its normal approval controls. Do not silently download a runtime, weaken TLS verification or edit system Python. Check the actual OS and Python command availability. Native Windows uses the portable Python entrypoint, actual user SID/private ACLs and local filesystem aliases; do not assume a POSIX shell or Unix permission bits.
4. Explain that private local tracking retains supplied context, exposed tool events, final answers and reported usage in this company folder, and requests one bounded same-host review. No hidden reasoning is collected and nothing is exported by default. Run `setup-local-capture --home <selected absolute folder>` through the bundled launcher. It creates a local-only policy if none exists and preserves every existing policy. Report its actual capture/review/export state; if an existing policy disables capture, explain that setting instead of overwriting it. Respect an explicit user opt-out. Ask what the company does and which recurring job they want help with first. Record only explicit facts using supported profile/memory operations. Unknown facts stay unknown.
5. Read onboarding status. If a valid project is already configured, inspect its actual state rather than asking again. Otherwise ask: “Connect Langfuse now for traces and evaluations, or keep everything local for now?” Record the explicit choice with the entrypoint onboarding action. If connect is chosen, open the selected company dashboard connection form. The user enters the exact host, project and keys locally; never ask for secret keys in chat, copy another company’s connection or mark it connected before project verification succeeds. Keep working locally when deferred; production qualification remains pending.
6. Open the dashboard using the bundled launcher's `report --home <selected home> --no-open --json` and give its returned clickable link. Explain that the private local link shows real records, not invented activity. Browser opening is appropriate when the user asks to see it.
7. Show the available skills: director for operating the company, dashboard for the report, help for usage, and the build/run/review workflow skills. In Codex these are explicit skill invocations (`$spielos:director`, `$spielos:dashboard`, `$spielos:help`, or the host's namespaced entries); in Claude Code use `/spielos:director`, `/spielos:dashboard` and `/spielos:help`. Do not claim Codex native slash commands are plugin-owned. The main chat is Director, not a separate agent to spawn. Offer one next step tied to the user's job. Existing workflows stay drafts until required evaluation, verified Langfuse evidence under the current production release policy and independent review are complete. An evaluation pass is distinct from measured improvement.

Installation alone connects no external service. Setup offers an explicit Langfuse connection; only the user’s selected destination and reviewed evidence policy may be enabled. Langfuse export needs an explicitly selected project and approved evidence policy. Credentials stay outside plugin files and company definitions. Sending, publishing and provider activation require their own exact authorization; Activepieces remains inactive.

If MCP is unavailable, use the bundled launcher for the same selected-home operations and report the missing tool connection. Do not route work through an unrelated plugin. Do not claim that installing a plugin automatically trusts company lifecycle hooks. Respect the host's normal hook review.


For the context/evaluation/usage experience, have the user open the selected company folder as their Codex or Claude Code workspace and review that home's shipped hooks using the host's normal controls. Verify an actual context receipt and Stop review request before saying capture is active. If hooks have not run or usage was not exposed, say so. At the end of meaningful work, render the runtime's concise Markdown tracking receipt with real dashboard/trace links, evaluation status and reported usage; do not invent rich host cards, billed cost or Langfuse confirmation. The dashboard, context, receipts and experiments all come from this same bundled SpielOS runtime, never from Karwise or another plugin.

After the first meaningful chat, obtain the real report URL, present it and explain Home (work and pending decisions), History & examples (actual runs and outputs), Quality & learning (criteria, missing reviews and proof of later improvement), Activity & cost (reported totals and unknowns), Memory and Loaded context (saved versus supplied), and Langfuse delivery (queued versus remotely verified). Open the dashboard when requested or as part of the authorized first-chat tour. Only then record onboarding tour-shown with that exact report URL. Do not repeat the welcome, connection question or tour after it has been recorded; retain the ordinary concise tracking receipt.