Init

bonsai:init

Survey, delegate, then propose. Never write an artifact in this skill without showing it first.

Read ${CLAUDE_PLUGIN_ROOT}/reference/placement.md before proposing anything, and ${CLAUDE_PLUGIN_ROOT}/reference/etiquette.md before writing any user-facing output. Load git-strategy.md and thresholds.md when you reach the phases that need them.

Re-running is expected and must be idempotent: if .claude/bonsai/config.json exists, this is an upgrade — reconcile, report only what changed, and never duplicate a stanza or re-propose something in archive/.

Phase 0 — Pre-flight (one call, install only)

sh ${CLAUDE_PLUGIN_ROOT}/scripts/preflight.sh --project .

Returns the detected sh / git / python / gh, a tier from the degradation ladder, and a fix line for anything missing. The result is cached under .claude/bonsai/.state/, so a re-run costs nothing; pass --refresh only if the user says they've just installed a dependency.

tier	Do
full	Continue silently. Do not mention pre-flight at all
reduced	Continue. Say in one line which capability is degraded and give the fix verbatim
manual	Continue. Say plainly that observation is off, so the loop won't learn on its own
unsupported	Stop. Write nothing. Report the missing dependency and its fix, and say bonsai will install once it's available

Never a half-installed state: if installable is false, this skill ends here. bonsai does not install software on the user's machine — offer the fix, never run it. An absent gh is optional and worth at most a half-line, alongside the tier detection it weakens.

Phase 1 — Survey (one call)

sh ${CLAUDE_PLUGIN_ROOT}/scripts/survey.sh --project .

One JSON object covering instruction files and their line counts, rules and how many are paths:-scoped, skills/agents/hooks/MCP, auto-memory state, style tooling, git shape, and a verdict with the detected tier, mode, and whether /init or /doctor hand-off is needed.

Do not re-derive any of this by hand — no Read to count lines, no test -f, no git log pipelines. That's the determinism boundary (${CLAUDE_PLUGIN_ROOT}/reference/determinism.md), and re-deriving it costs the user tokens for an answer the script already has.

Two fields deserve attention: repo.style_tools disqualifies any style guidance those tools already enforce, and memory.auto_memory gates the whole observation loop.

Phase 2 — Delegate before building

bonsai does not reimplement native tooling. Apply this table, then stop and let the hand-off happen before continuing:

Found	Do
No CLAUDE.md anywhere	Hand off to /init. Try invoking it; if unavailable, tell the user to type /init, then re-run this skill. Do not author a first CLAUDE.md yourself
CLAUDE.md over 200 lines, or full of derivable content	Invoke /doctor — it already proposes trims. Only afterward propose paths:-scoped splits for what remains
Unused skills / MCP servers / plugins, or slow hooks	Invoke /doctor. It detects all of these
Auto memory disabled	Tell the user to enable it via /memory. Note plainly that observation won't work without it
AGENTS.md but no CLAUDE.md	Propose a CLAUDE.md containing @AGENTS.md. Never duplicate the content
.cursorrules / copilot instructions but no CLAUDE.md	Mention that /init reads these and will fold them in

/doctor is a bundled skill, so you can invoke it directly. /init is documented as a built-in command and may not be invocable — attempt it, fall back to asking, and assert nothing either way.

Phase 3 — Pick a mode

--guided / --express override; otherwise infer:

• express when the repo already shows harness fluency: paths:-scoped rules exist, or there are project skills/agents/hooks. Terse diffs, no teaching, no explanation of what a rule is.
• guided otherwise. Explain each proposal in one or two plain sentences: which mechanism, why that one, what it costs in resident context. Teaching is the deliverable here.

Either way, obey the etiquette budgets. Guided means clearer, not longer.

Phase 4 — Harvest

Delegate to the bonsai-scout subagent. Pass it the Phase 1 survey so it doesn't repeat the work. It returns candidate observations with evidence; it does not decide placement.

Skip the harvest entirely if the repo has no git history and no existing instruction files — there is nothing to learn from yet, and the steady-state loop will pick things up.

Phase 5 — Install bonsai itself

Ask once, showing exactly what will be written. The user invoked this skill, so installing bonsai is consented — but the resident-context stanza must still be shown verbatim before it lands.

1. .claude/bonsai/config.json — detected tier, mode, thresholds, git strategy
2. .gitignore — the exclusions from reference/git-strategy.md, appended to an existing .claude/ section rather than creating a second one
3. The five-line pointer in CLAUDE.md. Show it exactly as written in the README. If a ## Harness maintenance section already exists, reconcile it — never append a duplicate
4. Hooks in .claude/settings.json, merging into existing hook arrays rather than replacing them

If the user declines the pointer, everything else still works — /bonsai:promote and /bonsai:review are manual entrypoints. Say so and move on without arguing.

Phase 6 — Propose

Run each candidate through placement.md's gates and thresholds.md. Most candidates should die at Gate 0; that is the expected outcome, not a failure.

Write survivors to .claude/bonsai/proposals/<slug>.md using ${CLAUDE_PLUGIN_ROOT}/reference/templates/proposal.md. Each needs provenance, a resident-token delta, and an eval case. Write nothing to a real artifact path in this phase. /bonsai:review applies.

With --dry-run, print the proposals and write nothing at all.

Phase 7 — Report

At most ~12 lines. In express mode, at most 6.

bonsai 0.1.0 · team tier · express mode

Delegated   /doctor → 3 CLAUDE.md trims pending your review
Installed   config, .gitignore (4 entries), SessionEnd + SessionStart hooks
Proposed    2 artifacts — /bonsai:review
Skipped     6 candidates (below threshold or already covered by eslint)

Then stop. Do not summarize what bonsai is, restate the roadmap, or suggest next steps beyond the one command. If nothing needed doing, say that in two lines — finding a healthy repo is a success.