/mycelium:start — combined first-time entry

When this skill runs, follow the flow below. The skill is designed so a first-time user goes from "plugin installed" to "holding a one-page brief on their idea" in a single invocation.

Step 1: Welcome (~30 seconds of context, then move on)

Output a short welcome before doing anything. Do NOT skip this — the install-to-here gap is the friction point this skill exists to address. The user just installed a 45-skill framework and has no context yet.

"Welcome to Mycelium.

Mycelium makes the agent think before it builds — it can't skip the hard questions; each step has to clear an evidence check first. Grounded in 30+ established product-thinking frameworks; you'll meet the relevant ones as they come up.

Two quick steps:

1. Set up Mycelium's files in .claude/ — about 10 seconds. Your existing files (CLAUDE.md, README, etc.) aren't touched; only a new .claude/ directory is added.
2. A 10-minute discovery brief: 4 questions about your idea, then a one-page brief covering who it's for, the biggest assumption, the biggest risk, and your next concrete move.

Let's begin."

Step 2: Detect existing state — HARD GATE

This must be the very first action after the welcome. Do NOT run any other Bash commands, Edit/Write operations, or "let me prepare the directories" reasoning before this gate fires.

Run exactly this check, and only this check:

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

• If exit code 0 (file EXISTS): the project already has Mycelium state. Skip directly to Step 4 routing output. Do NOT run setup. Do NOT run mkdir. Do NOT touch .gitkeep stubs. Setup-style operations on an already-initialized project waste tokens and trigger Read-before-Write tool errors when the agent then tries to write to existing files. Detected during 2026-05-09 plugin-form dogfood — the agent ran mkdir -p .claude/... before honoring this gate, then hit a Write error on active.yml and only then realized the project was initialized. The fix is structural: the gate is the first action.

• If exit code 1 (file does NOT exist): invoke the setup workflow inline. Follow the instructions in ${CLAUDE_PLUGIN_ROOT}/skills/setup/SKILL.md exactly — same Step 1 detection (which will fall through), Step 2 directory creation with .gitkeep stubs, Step 3 starter file writes, Step 5 confirmation message — but DEFER setup's Step 4 (the AGENTS.md prompt) to after the brief (see below). Do not duplicate the setup logic here; reference it.

AGENTS.md deferral (v0.56.0): in the /start composition, setup's Step 4 question does NOT fire before the interview. A first-time user's opening minutes must go to their idea, not to file administration — the 2026-07-02 roadmap dogfood run showed the AGENTS.md exchange consuming the first two conversational rounds before Question 1 was asked. Instead: after the brief is rendered and the depth menu is answered, IF <project_root>/AGENTS.md is absent or lacks a Mycelium section, ask setup's Step 4 question then (one exchange, at the natural pause). Setup's detect-first rule still applies: an AGENTS.md that already covers Mycelium is skipped silently. When /mycelium:setup is run standalone (not via /start), its Step 4 order is unchanged.

After setup completes, do NOT print setup's "Next:" line — this skill is the next step. Print:

"Setup done. Now: 4 questions about your idea, ~10 minutes."

Step 3: Run interview (universal-flow shape)

Invoke the interview workflow inline. Follow the instructions in ${CLAUDE_PLUGIN_ROOT}/skills/interview/SKILL.md from Phase 0 onward.

Because setup just ran, the canvas is empty — /interview's canvas-state detection will route to the Universal Brief Flow (the 4-question brief shape, not the legacy time-budget-routed ceremony). Render the brief, write canvas state, render the depth menu. Per opp-006 narration discipline in interview/SKILL.md, do not narrate phase numbers to the user — reference the outcome (e.g., "the brief", "the project-type question") instead of the phase index.

After the brief is rendered and the user picks a depth-menu option, the start skill is done. Hand off to whatever the user chose (/mycelium:assumption-test for "Test the biggest assumption", continued discovery for "Go deeper", graceful exit for "Stop for now", etc.).

Step 3b: Derive purpose properties (immediately after why/how/what land)

The why/how/what are not decoration — everything below is checked against them, so they have to be checkable. Propose a property list from what the user just wrote, then have them confirm it. Write to purpose.yml#purpose_properties. Full contract: docs/purpose-stance.md.

For each element, ask yourself: can I name a specific solution that would CONTRADICT this?

• Yes → it is a candidate property. Record verbatim, source (why/how/what), and the contradicting solution in contradicted_by.
• No → do not force one. Quality adjectives ("secure", "accessible", "fast", "simple") yield nothing checkable, because every candidate solution claims to satisfy them. Measured 2026-08-23: "accessible and secure" produced no checkable property at all.

When a word fails, ask the user — and offer candidates rather than an open question:

You said "secure". Which of these would you call a violation? (a) passwords stored in plaintext (b) no transport encryption (c) sessions that never expire (d) something else

Recognition is cheap; generation is not. If they answer, you have a property. If they cannot, record it as an aspiration (aspiration_reason) and say plainly: "'secure' stays undefined, so no solution will be checked against it." A skip is a recorded choice, never a blank.

The user marks binding: true on the few whose violation would break the product. Only those are ever checked. Set confirmed_by: human once they have.

This is NOT /mycelium:user-interview. That skill asks about specific past behaviour, which is right for discovering user needs and wrong here — this elicits a definition from the builder about their own intent, where the question is hypothetical by design.

Step 4: Routing for already-initialized projects

If Step 2 detected existing canvas state (the user has Mycelium installed already on this project), do NOT run setup or interview. Instead, print:

If the project has canvas state but no purpose.yml#purpose_properties, say so in the same breath — it existed before v0.120.0, so nothing below has ever been checked against its own why/how/what, and /mycelium:purpose-properties is the retrofit. One line, not a sales pitch.

"This project already has Mycelium state from [date of last write to .claude/diamonds/active.yml]. Last diamond touched: [scale, phase, confidence, name]. Three options:

1. Run /mycelium:diamond-assess to see current state and what to work on next.
2. Run /mycelium:interview to add a new idea as a sibling diamond on this product.
3. Stop and look around. Canvas files are in .claude/canvas/."

Then exit. The user picks the next move.

What this skill does NOT do

• Does NOT modify CLAUDE.md, README.md, CONTRIBUTORS.md, or LICENSE.
• Does NOT block or prompt at the welcome step — it's read-and-continue, not interactive.
• Does NOT replace setup or interview. They remain invocable directly. start is the convenience composition.
• Does NOT run on every session — only on first invocation. After the first run, canvas state exists and Step 2 routes to diamond-assess.

Why this skill exists

Without /mycelium:start, the first-time plugin user has to:

1. Run /plugin install mycelium@haabe-mycelium (Claude Code message: "installed")
2. Wonder what to do
3. Find /mycelium:setup (no obvious pointer at install time)
4. Run setup (gets a brief next-step message)
5. Run /mycelium:interview
6. Get value (the brief)

That's 5 typed commands and 2 cognitive gaps before value lands. The void between steps 1 and 5 is real friction.

/mycelium:start collapses 1→6 into 1→2 with a welcome message that gives the framework a 30-second introduction at exactly the moment the user has the question "what is this and what do I do." Setup+interview both still exist as separate skills for users who want them piecewise.

Theory grounding

• Norman: visible affordances at the moment of cognitive need (the welcome message at the install gate).
• Krug "Don't Make Me Think": one command instead of two, with explanation built in.
• Hashimoto regeneration zones: the welcome is generation-cheap context that the user can re-read or skip; doesn't add discipline cost to the actual work.
• Brownfield-additive principle (Bentes 2026-05-08): the start skill respects the same "no project root modification" constraint as setup — it adds project state without touching user-owned root files.

Source

The friction this skill addresses surfaced 2026-05-09 during the founder's smoke-test of the v0.20.x plugin form. The user reported: "the onboarding has worsened substantially since converting to plugin. The user is left in the unknown void for quite a bit."

Setup + welcome + immediate interview transition is the first response. If the welcome-as-text approach proves insufficient (subsequent dogfood reports the void persists), graduate to: SessionStart hook that detects first-run-after-install and emits the welcome unprompted.