boma/docs/runbooks/claude-code-setup.md

# Runbook — Claude Code setup (per machine)

The repo carries the project's Claude Code config that *travels with git* —
`.claude/commands/`, `.claude/hooks/`, and `.claude/settings.json` (hooks,
permissions, and the **declared** plugin set). But **plugins and MCP servers are
local per machine** — they are not synced by your Claude account and not stored in
git (see ADR-014, "Reproducibility of the toolchain"). So a fresh clone needs a
one-time setup. This runbook is that setup.

## 1. Plugins (the active set)

The repo's `.claude/settings.json` declares `extraKnownMarketplaces` +
`enabledPlugins`, so on a fresh clone Claude Code should **prompt** you to trust the
marketplace and install the set. If it doesn't, install them explicitly:

```text
/plugin marketplace add anthropics/claude-plugins-official
/plugin install superpowers@claude-plugins-official
/plugin install context7@claude-plugins-official
/plugin install terraform@claude-plugins-official
/plugin install claude-md-management@claude-plugins-official
```

| Plugin | Why it's in the set |
|---|---|
| `superpowers` | Brainstorm → ADR, writing-plans, subagent-driven development, TDD — the project methodology |
| `context7` | Up-to-date, version-matched library docs (ADR-014) |
| `terraform` | boma provisions with Terraform (ADR-006) |
| `claude-md-management` | The project is doc/ADR-governance heavy |

**Intentionally not installed:** `code-simplifier` (little code to simplify in a
YAML/docs repo) — dropped as a kaizen "bias-to-remove."

## 2. Plugins to enable *when* the work starts (deferred)

Don't install these until their trigger lands — then add them here and to
`enabledPlugins`:

| Plugin | Enable when |
|---|---|
| `security-guidance`, `semgrep` | Building `/security-review` (TODO 8.5) — semgrep does IaC scanning |
| `playwright` | Web services exist to test headlessly (TODO 2.2) |
| `hookify` | Authoring the next guard hook |
| `skill-creator` | Building the next skill (`/security-review`, `/retro`) |

## 3. Other local prerequisites

- **`rbw` (Vaultwarden client)** — install and `rbw unlock` once per session; the
  vault password client and the pre-commit vault guard depend on it (ADR-002).
- **The venv-activate hook** — this repo expects the Python `.venv` active for Bash
  commands. If you use the user-level `~/.claude/hooks/activate-venv.sh` pattern,
  replicate it; otherwise `source .venv/bin/activate` per session after `make setup`.
- **Forgejo registry login (for image pushes)** — `make caddy-image-push` /
  `molecule-image-push` need the Docker daemon authenticated to
  `forgejo.nyumbani.baobab.band`. Run **`make registry-login`** once per machine: it reads
  `vault.forgejo.registry_token` from the vault and does `docker login --password-stdin`
  (no interactive prompt, so an agent can complete a push). The token is operator-minted
  (Forgejo → Settings → Applications → Generate Token, package read+write) and set via
  `make edit-vault`; until then `registry-login` prints how to obtain it. (2026-06-17 kaizen.)

## 4. A note on user-level settings

The dangerous-mode permission prompt (`skipDangerousModePermissionPrompt`) is a
*personal* `~/.claude/settings.json` preference, not carried here. Given ADR-002's
"operator/agent error" threat, prefer leaving that prompt **on** unless you
deliberately rely on bypass mode.

## Environment gotchas

Migrated from `docs/FRICTION.md` by the 2026-06-10 kaizen review — surprises that bite
on this kind of host/toolchain:

- **Hooks (and any new `.claude/settings.json`) added mid-session don't activate until a
  Claude Code restart.** The settings watcher only tracks settings files that existed at
  session start; opening `/hooks` and dismissing does *not* load them. Fresh sessions
  load them normally — restart after adding a hook.
- **pre-commit stashes *unstaged* changes before running hooks**, so a partial commit of
  interdependent files can revert one and fail (e.g. an `ansible.cfg` change left
  unstaged). Commit interdependent changes together, or stage the config change first.
- **`rbw sync` is required after adding a Vaultwarden item before `rbw get` finds it**
  (the local cache is stale otherwise).
- **This shell is zsh** — unquoted `$VAR` does *not* word-split, so a variable holding a
  file list is passed as a single argument. Use explicit args/arrays.

## Verifying

After setup, a quick check: the project commands (`/review-repo`, `/capacity-review`,
`/lint`, `/deploy`, `/new-role`) and the `superpowers` skills should be available, and
`context7` / `terraform` MCP tools should resolve.