sjat/boma

sjat abb5c7a12f Make the Claude Code toolchain reproducible (TODO 10.7)

Reviewed the Claude Code config against boma's capabilities and committed a
reproducible, leaner toolchain:

- .claude/settings.json now declares extraKnownMarketplaces + enabledPlugins so a
  fresh clone prompts to install the active set: superpowers, context7, terraform
  (we use TF, ADR-006), claude-md-management (doc/ADR-heavy). Drops code-simplifier.
- Adds a conservative, read-only/verify permissions allowlist (git status/diff/log,
  make lint/test/check, pytest, rbw unlocked, ls/cat/rg/find) — mutations and
  outward/destructive commands stay gated, consistent with ADR-002.
- docs/runbooks/claude-code-setup.md: per-machine bootstrap, the deferred
  enable-when plugins (security-guidance/semgrep, playwright, hookify, skill-creator),
  rbw/venv prerequisites, and a note to keep the dangerous-mode prompt on.

Closes TODO 10.7. Plugin install remains a per-machine /plugin action (no native
auto-install).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-04 21:41:54 +02:00

2.9 KiB

Raw Blame History

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.

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.

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.

2.9 KiB Raw Blame History