/setup

name: setup
description: First-run setup for the Mycelium plugin. Creates project-state directories (.claude/canvas, .claude/diamonds, .claude/memory, .claude/harness) and minimal starter files in the user's project. Optionally provisions opencode runtime support (a starter scaffold) when opencode is detected or requested, and declares the gates in .vibe/hooks.toml when Mistral Vibe is. Idempotent — re-running on an initialized project is a no-op. Run this once after installing the Mycelium plugin and before invoking other skills.
metadata:
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Mycelium plugin setup

First: are Mycelium's hooks running here? (v0.286.0)

Run `find .claude/state/hooks-alive "${TMPDIR:-/tmp}/mycelium-hooks-alive-$(id -u)" -mmin -60 2>/dev/null`. If it prints a path (since v0.318.0 the hooks also stamp the temp folder in a project with no Mycelium state yet, where they do nothing else), say nothing about it and go on. If it prints nothing, Mycelium's hooks did not run in this session: its gates and the rules it gives the agent at session start are off, and nothing else will say so. Tell the user in one line before anything else: "Mycelium's hooks are not running in this session, so its gates are off. On Codex CLI, open `/hooks`, trust Mycelium's hooks and start a new session; on Claude Code, check the plugin is enabled in `/plugin`." Then carry on with this skill.

When this skill runs, do the following sequence. The skill is designed to be safe to re-run — every step is idempotent.

Then: can the gates read the canvas? (v0.290.0)

The safety gates read YAML, so they need a Python with PyYAML. Claude Code installs a plugin's Node packages but not its Python ones, and documents `${CLAUDE_PLUGIN_DATA}` as the place for a plugin's installed dependencies. Check first; install only if it is missing, and only with the user's yes:

python3 -c "import yaml; print('PyYAML', yaml.__version__)" 2>/dev/null \
  || "${CLAUDE_PLUGIN_DATA}/pyenv/bin/python" -c "import yaml; print('PyYAML (Mycelium env)', yaml.__version__)" 2>/dev/null \
  || echo "PyYAML missing"

**If it prints a version, say nothing and go on.** If it prints `PyYAML missing`, tell the user plainly: *"Mycelium's safety gates cannot read your project without PyYAML, so they refuse new source files and releases until it is there. I can install it for Mycelium only, in the plugin's own data directory (`${CLAUDE_PLUGIN_DATA}/pyenv`, removed when the plugin is uninstalled), pinned to the version Mycelium's CI tests. Shall I?"* On a yes:

python3 -m venv "${CLAUDE_PLUGIN_DATA}/pyenv" \
  && "${CLAUDE_PLUGIN_DATA}/pyenv/bin/python" -m pip install --quiet --disable-pip-version-check "PyYAML==6.0.3" \
  && "${CLAUDE_PLUGIN_DATA}/pyenv/bin/python" -c "import yaml; print('installed PyYAML', yaml.__version__)"

Report the last line verbatim. On a no, say what stays refused, and that `pip3 install pyyaml` for their own `python3` works as well. **Never install without asking**: it downloads a package, and the pin is exact (6.0.3, the version `requirements-ci.txt` pins) so what is installed is what CI tested. If `${CLAUDE_PLUGIN_DATA}` did not expand (a runtime other than Claude Code), use `pip3 install pyyaml`.

Step 1: Detect initialization state

Check whether the user's project already has Mycelium project-state. The signal that initialization has happened:

test -f "${CLAUDE_PROJECT_DIR:-.}/.claude/diamonds/active.yml"

If the file exists, print:

> "Mycelium project state is already initialized. Existing canvas, diamonds, and memory are preserved. Run `/mycelium:diamond-assess` to see current state."

**Then offer the move to the decision log, if any diamond still records only its phase** (v0.303.0, DL-1368 S3). Run the dry run and show what it prints:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/migrate_phase.py" --project-dir "${CLAUDE_PROJECT_DIR:-.}"

If it lists diamonds to migrate, ask whether to write it, and run it again with `--write` only on a yes. It rewrites each diamond's phase history as reconstructed decisions, a learning delivery as a reconstructed exposure record, and the old L2/L3 shape as the new fields, and it refuses anything the scale locks read as a change. If it prints "nothing to migrate", say nothing about it.

Then exit. Do NOT touch existing files except through that script, on the user's yes.

If the file does NOT exist, continue to Step 2.

Step 2: Create project-state directory structure

Resolve the project root: use `$CLAUDE_PROJECT_DIR` if set, else fall back to `pwd`. (Claude Code sets it automatically; non-Claude-Code agents may not.)

Create these directories in the user's project (using Bash `mkdir -p`):

<project_root>/.claude/canvas/
<project_root>/.claude/diamonds/
<project_root>/.claude/memory/
<project_root>/.claude/harness/
<project_root>/.claude/evals/
<project_root>/.claude/jit-tooling/

These directories hold project-specific state that the user's project owns and commits to git. Framework reference content (skills, hooks, theory gates) lives in the plugin cache and is not duplicated here.

**`.claude/state/` is Mycelium's runtime state, and it must not be committed by accident (v0.226.0).** Until this version the paragraph here said the directory was "created and owned by Claude Code itself" and that "Mycelium does not write to it". That was false: the plugin's hooks and scripts write there on almost every tool call: `read-log.jsonl` (every path the agent opened), `change-log.jsonl`, the guard ledgers, session stamps, the advisory ledger. Nothing git-ignored it in plugin form, so a new user's first commit carried all of it, and a public push pu