---
name: toolchain-bootstrap
effort: medium
description: >
  Install, verify, and wire the curated dev toolchain for this project. Detects
  the JS/TS stack, installs the best-in-class tools as devDependencies (Biome for
  format+lint+import, Vitest, tsc, Lefthook), writes their default config only
  when absent, records toolchain.installed_tools + toolchain.commands.* in
  baldart.config.yml, and proposes (never forces) a migration off any existing
  ESLint/Prettier/Jest/husky. Use when the user says /toolchain-bootstrap,
  "install the toolchain", "set up biome", or after enabling
  features.has_toolchain for the first time. Idempotent — re-running re-verifies
  and reports drift, never overwriting existing configs.
---

# Toolchain Bootstrap

Set up the curated dev toolchain so the quality gates (`/new`, `/qa`, `/check`,
`qa-sentinel`) run best-in-class tools instead of whatever the project happened
to have. Non-destructive throughout: configs are written only when absent and
incumbent tools are never installed over or removed.

## Project Context

**Reads from `baldart.config.yml`:** `features.has_toolchain`, `toolchain.installed_tools`, `toolchain.commands.*`, `toolchain.auto_verify`.
**Gated by features:** `features.has_toolchain` — this skill refuses to run when the flag is `false`, prompting the user to flip it via `npx baldart configure` first.
**Overlay:** loads `.baldart/overlays/toolchain-bootstrap.md` if present — project-specific tool choices or install commands.
**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.

## What This Skill Does

1. Reads `baldart.config.yml` and confirms `features.has_toolchain: true`.
2. Probes the cwd via `src/utils/toolchain-installer.js` to compute the clean
   recommendation (`recommend()`) and any incumbent-blocked migrations
   (`migrations()`).
3. Installs the recommended tools as **devDependencies** (`npm install -D -E`) —
   never global (these are project tools invoked via `npx`, unlike LSP servers).
4. Writes each tool's default config **only when absent** (`biome.json`,
   `lefthook.yml`) and registers Lefthook's `pre-commit` hook.
5. For incumbents (ESLint/Prettier/Jest/husky), PROPOSES a migration with a
   preview — never automatic, never touching the existing config (`.husky/` is
   never overwritten).
6. Writes `toolchain.installed_tools` + `toolchain.commands.*` to
   `baldart.config.yml`, then `certify()`s the set.
7. Prints a compact status and points to
   `framework/agents/toolchain-protocol.md` for runtime behavior.

## Workflow

1. **Refusal check.** If `features.has_toolchain: false` (or missing):
   ```
   This project hasn't opted in to the curated toolchain yet.
   Run `npx baldart configure` and answer YES to "Enable curated dev toolchain?"
   then re-run /toolchain-bootstrap.
   ```
   Stop here. Do not proceed.

2. **Probe.** Call the installer:
   ```
   node -e 'const T=require("./.framework/src/utils/toolchain-installer"); const t=new T(); console.log(JSON.stringify({hasPkg:t.hasPackageJson(),recommend:t.recommend(),migrations:t.migrations()},null,2))'
   ```
   If `hasPkg` is false, report "no package.json — JS toolchain not applicable"
   and stop. Otherwise show the recommended tools and any migrations.

3. **Confirm.** For the clean recommendation, default YES. For each migration,
   show what it replaces (and for Biome, the `npx biome migrate eslint/prettier
   --write` preview) and default NO.

4. **Install + config + commands.** Run the installer's `install`, `initConfigs`,
   then read back `commandsFor(activeTools())`. Capture failures into a "Skipped"
   bucket — never abort the whole skill on one failure.

5. **Persist.** Update `baldart.config.yml`:
   ```yaml
   toolchain:
     installed_tools: [biome, vitest, tsc, lefthook]
     commands:
       lint: npx biome check .
       format: npx biome format --write .
       typecheck: npx tsc --noEmit
       test: npx vitest run
       test_related: npx vitest related --run
     auto_verify: true
   ```

6. **Output.** A compact one-line-per-tool status, in the project's
   `identity.language` from `baldart.config.yml` (English default).

## Output Contract

A single short status block — never a multi-page report. Format:

```
Toolchain bootstrap:
  ✓ biome      (devDep 2.x, biome.json written, lint+format wired)
  ✓ vitest     (devDep, test + test_related wired)
  ✓ tsc        (typescript present, typecheck wired)
  ✓ lefthook   (devDep, lefthook.yml + pre-commit hook installed)
  · eslint     → migration available (declined): npx biome migrate eslint --write
Config updated: baldart.config.yml toolchain.installed_tools = [biome, vitest, tsc, lefthook]
Next: /qa, /new, qa-sentinel will now run these commands instead of the defaults.
```

## Notes

- This skill never edits source code. Its only side effects are devDependency
  installs, writing absent default configs, registering the Lefthook hook, and a
  YAML write to `baldart.config.yml`.
- Re-run safely. `recommend()`/`migrations()` are recomputed each time, configs
  are skipped when present, and already-usable tools are left untouched —
  additions / repairs are idempotent.
- `baldart doctor` is the unattended backfill: it installs missing tools
  (`toolchain-install`) and restores missing default config (`toolchain-init-config`).

## See Also

- `framework/agents/toolchain-protocol.md` — runtime command resolution + fallback.
- `framework/docs/TOOLCHAIN-LAYER.md` — full plumbing + lifecycle.
- `src/utils/toolchain-adapters/` — per-tool install/verify recipes.
