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:

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