/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. 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

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

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 exit. Do NOT touch existing files.

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 published a log of what their agent read. (The dogfood repo never noticed: it inherited a `.gitignore` inside that directory from the legacy templated install.)

Create the directory and its ignore file now, **only if the ignore file does not already exist: never overwrite one**:

mkdir -p <project_root>/.claude/state
[ -f <project_root>/.claude/state/.gitignore ] || cat > <project_root>/.claude/state/.gitignore <<'EOF'
# Mycelium runtime state: logs, ledgers and session stamps the hooks write during sessions.
# Not committed. Canonical project state lives in .claude/canvas/ and .claude/diamonds/.
*
!.gitignore
!README.md
# Kept under version control on purpose: these record a DECISION the user made, once per
# project, and a fresh clone should not be asked again.
!discovery-skip-ack
!brownfield-ack
!upstream.json
EOF

Tell the user in one line that you did it and why ("runtime logs stay out of git; your two recorded gate decisions stay in"). If the project already tracks files under `.claude/state/`, do NOT untrack them yourself; say which are tracked (`git ls-files .claude/state`) and let the user decide.

**Important — empty dirs and git**: directories that don't get a starter file in Step 3 (`canvas/`, `evals/`, `jit-tooling/`) are empty after Step 2 and would not survive a git commit. Drop a `.gitkeep` stub in each so they remain in the user's repo:

touch <project_root>/.claude/canvas/.gitkeep
touch <project_root>/.claude/evals/.gitkeep
touch <project_root>/.claude/jit-tooling/.gitkeep

Step 3: Write minimal starter files

Use the Write tool to create each file. Each file gets a small starter content, NOT a full canvas template — the canvas-population skills (`/mycelium:interview`, `/mycelium:canvas-update`, etc.) populate them when the user runs them.

**Note**: these files don't yet exist, so the Read-before-Write convention does NOT apply (it applies only to existing files). Use Write directly.

`.claude/diamonds/active.yml`

# Mycelium active diamonds state
# Populated by /mycelium:interview on first project-onboarding run.
# See plugin reference for diamond scales (L0 Purpose -> L5 Market).
project_type: ""
dogfood: false
active_diamonds: []
_meta:
  # Date a human last confirmed this file's content accurate. NOT "when the file
  # changed" — git already records that authoritatively, and a hand-maintained
  # copy of a machine-knowable fact can only drift away from it. Replaced a
  # top-level `last_updated` in v0.89.0.
  last_validated: null

`.claude/memory/corrections.md`

# Project corrections

Mistakes the agent made on this project, with prevention rules.
Populated as the project evolves. Read at the start of every task
(per Mandatory Pre-Task Protocol).

Empty until the first correction lands.

`.claude/memory/patterns.md`

# Project patterns

Successful patterns worth reusing on this project.
Populated as the project evolves.

Empty until the first pattern lands.

`.claude/harness/do-not-cite.yml`

Copy from `${CLAUDE_PLUGIN_ROOT}/harness/do-not-cite.yml`. It is the project's register of claims already investigated and ruled on, and `check_citations.py` reads it — via `/mycelium:canvas-health` and as a WARN in `validate_canvas` — report