09.03.09 — Setup skills#

Two skills: setup-environment (onboarding a new contributor, human or AI) and profile-environment (governing how much latitude the engagement grants the LLM). Both feed the suite’s assembled CLAUDE.md.

The skill#

input  : a fresh repo
output : onboarding steps:
            1. venv
            2. pip install (dev deps + ocarina)
            3. ruff / mypy / pre-commit installed
            4. CLAUDE.local.md created (paths requested from user)
            5. runner smoke-check (minimal test that validates everything works)
            6. pre-commit loop tested

Step 1: venv#

python -m venv .venv
source .venv/bin/activate

Step 2: pip install#

pip install . ruff mypy mypy-extensions typing-extensions pre-commit

Step 3: dev tooling#

pre-commit install --config .pre-commit-config.yaml

Step 4: `CLAUDE.local.md`#

CLAUDE.local.md is gitignored and contains machine-specific paths.

The setup-environment skill:

Checks whether the file exists.
If not: creates it from the CLAUDE.md template.
Asks the user for the paths (chromedriver, Ocarina ecosystem repo clones).
Doesn’t guess paths (except find ~/ -name chromedriver -type f 2>/dev/null which is documented as a hint).

CLAUDE.md:

CLAUDE.local.md is gitignored and stores per-machine paths. If it’s missing, create it with the template below — and ask for the paths, don’t guess.

Step 5: runner smoke-check#

python -u src/main.py --browser firefox --driver-path ./geckodriver --workers 3 --only "valid_login"

Runs just a smoke test. If it passes: the environment is OK.

--only valid_login filters everything else. Allows a fast check rather than a full cycle.

Step 6: pre-commit loop#

# make a minor edit in src/
git add src/edited_file.py
git commit -m "test: setup smoke"

pre-commit should run. If it fails, surface it and debug together. In “vibe testing” mode, the more aggressive the pre-commit the better: the AI ends up in a context close to reinforcement learning.

If the pre-commit has a “big” battery — say, systematically cross-checking formatting, lint, and typing — the AI will be far more effective at self-correcting quickly and can never commit something totally inappropriate (= that doesn’t even “compile”).

Added value#

Without the skill	With the skill
The newcomer reads the README, does the steps by hand, makes mistakes, rages, posts a YouTube video to bash Ocarina	Sequential steps, verified one by one
No check that everything really works	Smoke-check confirms
`CLAUDE.local.md` often forgotten	The skill forces its creation

`profile-environment` — the engagement latitude#

setup-environment wires the mechanics. profile-environment answers a different question: how much latitude does the human actually grant the LLM on this SUT?

The whole skill battery has a silent default answer — “maximum”. The Holy Book was authored against CURA, an open-source public demo with hardcoded public credentials, so the defaults read: read the SUT’s source, drive a throwaway probe against the live app, research the ecosystem on the open web, public credentials. A real engagement is narrower.

profile-environment runs a profiling interview across seven latitude dimensions, resolved with the human (stakeholder decisions, not code-derivable facts):

Dimension	Question
Source access	Can the LLM read the SUT’s source?
Live-system probing	Can it drive a throwaway probe against the live app?
Data sensitivity	Demo data, or real / regulated PII?
Egress & confidentiality	Is open-web research allowed? Is there an NDA?
Security-testing ceiling	Where is the active-testing hard line?
Autonomy & approval cadence	Sign-off before runs?
Repo / CI / PR change surface	What may it touch?

It emits a tracked CLAUDE.profile.md appendix that setup-environment concatenates into the suite’s CLAUDE.md. It is a ratchet toward restriction — it only ever tightens the max-latitude defaults and the security hard line, never loosens them.

Run it at the start of any engagement that isn’t the open public-demo case (a client site, an internal app, an NDA, a live-PII SUT), and re-run it when the terms change (demo → client, staging → prod, an NDA lands, the repo goes private).

“Scriptable onboarding”#

A project must be bootstrappable by following a recipe. No tribal knowledge, no “oh yeah you have to do that too”.

Holy Book quotes:

Onboarding steps (venv, pip install, the skill battery copied into Claude Code, ruff / mypy / pre-commit, runner smoke-check) live in setup-environment.

Ocarina is dense, immediately operational and strict. Built so that both humans and LLMs can understand its core and usage without friction.

Link with the “auditable in an afternoon” philosophy#

See ../../11-independence/02-auditability.md

Scriptable onboarding is the prelude to the audit: without being able to run the project, you can’t understand it.