de-workshop-setup

Workshop setup: from laptop to READY

You are setting up a participant's laptop for a hands-on workshop. Many participants have never used a coding agent, so this is their first one. Make it calm and visible: before each step, say in one line what you are about to do and why, then do it. At the end they should have seen what an agent is: something that reads, runs, checks and fixes, not just something that chats.

Mode = the argument you were given: setup (default), check (change nothing, only report), or update (the morning of the workshop).

Ground rules

• Ask before installing anything system-wide, and show the exact command. Use the official installers in

references/install.md. Never use sudo unless the person says yes to that specific command.

• Never ask for, print or store secrets, including the workshop key. If a command prints a key, don't repeat it.
• Signing in can't be done by you. Ask the person to run orq auth login themselves in a normal terminal, choose

API key and paste the workshop key the facilitator sent (or OAuth (browser) if the facilitator invited them personally). Then continue.

• The evidence that the laptop is ready is uv run mart doctor ending in READY. Your opinion is not.

Don't print the READY card until doctor says so.

• If something fails twice the same way, stop and tell the person exactly what to send to the facilitator

(the failing command and its last lines of output).

Steps (mode setup)

1. Where am I? Detect the OS and shell (uname -s or $PSVersionTable). Check whether the current directory

is the workshop repo: workshop.toml and src/mart/ exist. (There's no AGENTS.md yet on purpose: participants write it in Activity 2. Don't create it.) Also note the place: a dev container or Codespace ($REMOTE_CONTAINERS or $CODESPACES is set) already has every tool installed, so skip to step 3; WSL (/proc/version mentions microsoft) counts as Linux. See WSL, dev containers and Codespaces in references/install.md.

1. Tools. Check git --version, uv --version, orq --version, claude --version, codex --version.

Show a short table: found / missing / too old (minimums are in workshop.toml once the repo is there: orq 11.6, Claude Code 2.1, Codex 0.160). Keep what's installed and recent enough, whatever installed it (npm, brew, winget, native). Offer to install what's missing, or update what's too old, one tool at a time, from references/install.md. Node.js is not needed. After installing, re-check the version: if it's still old, an older copy comes first on PATH (see references/install.md). A tool that is installed but "not recognized" is almost always a stale PATH in this terminal (VS Code and Windows Terminal freeze it when they start): follow A tool is installed but "not recognized" in references/install.md before reinstalling anything.

1. orq sign-in. Run orq status. If it isn't authenticated, ask the person to sign in (see ground rules).

• Signed in with an API key: that's the workshop key. Nothing else to do: it doesn't expire during the workshop.
• Signed in with the browser: if workshop.toml names a workspace and project and they differ from the active

ones, ask the person to run orq switch <workspace> <project> (switching workspace needs a human). Then run orq setup --capability gateway so the agents get a durable key (browser logins expire after an hour, and the workshop is two hours).

Explain the one idea: every model call from both agents goes through orq, so the whole room's token use is in one place, and each person's key has its own budget.

1. The repo. If we're not inside it, say plainly what you are about to download and where: *the workshop files,

the GitHub repo <repo from workshop.toml, or the URL the facilitator sent>, into <folder>. The default folder is the one the person is in (the folder open in VS Code): that folder itself if it's empty, otherwise a new `agentic-de-workshop` folder inside it. Let them pick another, then `git clone` there. The repo is private: if the clone asks for a password or says not found*, the person signs in to GitHub (gh auth login, or the browser window git opens) with the account the facilitator gave access to. From now on, run every command with the repo as the working directory.

1. Build. In the repo: uv sync, then uv run mart build, then uv run mart sync-skills.

uv sync downloads packages. In Codex that can't run inside the sandbox: ask the person to approve running it outside the sandbox, or to run uv sync in a normal terminal (the bootstrap script already did it once). Explain: mart is the one tool both agents use; build recreates the mart from scratch, so nothing you do today can break it permanently.

1. Doctor. Run uv run mart doctor. For every FAIL, apply its fix: line (asking first if it installs

something), then run doctor again. Stop after three rounds.

1. Prove it live (once). Run uv run mart doctor --live. It sends one tiny prompt through orq to Claude and one

to Codex (a few cents). Tell the person that before running it. In Codex, this launches other agents, which can't start inside Codex's own sandbox: ask to run it outside the sandbox, or have the person run it in a normal terminal.

1. READY card. Only when doctor printed READY, show:

╭───────────────────────────────────────────────────────────────╮
│  ✅  READY for Agentic Data Engineering (Claude Code × Codex)   │
├───────────────────────────────────────────────────────────────┤
│  repo      <path>                                              │
│  orq       <workspace> / <project>  · signed in as <email>      │
│  agents    Claude Code <v> · Codex <v>  · both answered via orq │
│  mart      built · <n>/<n> core tests green · 1 contract open   │
╰───────────────────────────────────────────────────────────────╯
Your workshop files are in <path>. If VS Code has another folder open: File → Open Folder → <path>.
On the day, open two terminals in the repo:
  left :  orq launch claude --no-mcp --no-skills
  right:  orq launch codex  --no-mcp --no-skills

Then a two-minute primer, in plain words, of what they'll do: meet two "interns" (Claude Code and Codex) and ask them about the data, give them an onboarding note, teach them a routine (a skill), and finally let their main agent hand a ticket to a helper (a subagent). They never write code: uv run mart is a small Python tool they only run. Don't do any of the activities for them, and don't create AGENTS.md, skills or subagents: that's the workshop. Offer one warm-up they can try right now: "In this session, ask: which region sold the most in March, and how do you know?" Point out that the answer should come with the query the agent ran: that's the habit for the day.

Mode check

Steps 1, 2 and 6 only, with no installs. The only file it touches is doctor's readiness stamp (.mart/ready.json). Report what would be needed. Print the READY card only if doctor says READY.

Mode update (the morning of the workshop)

In the repo: if git status --porcelain --untracked-files=no is clean, git pull --ff-only (if not, say which files changed and don't pull; new files of the person's own, like a saved transcript, don't block the pull). Then uv sync (in Codex: outside the sandbox, as in step 5), uv run mart build, uv run mart sync-skills. Refresh this skill with npx skills update -g -y if npx exists. Offer orq update, claude update and the Codex upgrade only if doctor says a version is too old. Finish with uv run mart doctor and the READY card.

If you are not in the repo and the clone fails

Most often it's the corporate proxy or VPN. Show git config --global --get http.proxy and suggest the person try again off VPN, or download the ZIP from the facilitator. Don't change proxy settings yourself.