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>

.claude/settings.json

@@ -1,5 +1,37 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "extraKnownMarketplaces": {
+    "claude-plugins-official": {
+      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
+    }
+  },
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "terraform@claude-plugins-official": true,
+    "claude-md-management@claude-plugins-official": true
+  },
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(make lint:*)",
+      "Bash(make test:*)",
+      "Bash(make check:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(rbw unlocked)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(rg:*)",
+      "Bash(find:*)"
+    ]
+  },
   "hooks": {
     "PreToolUse": [
       {

CLAUDE.md

@@ -206,3 +206,4 @@ Single-contributor, trunk-based (no merge requests / approval gates):
 | Adding a new role      | `docs/runbooks/new-role.md`           |
 | Adding a new host      | `docs/runbooks/new-host.md`           |
 | Rotating vault secrets | `docs/runbooks/rotate-secrets.md`     |
+| Claude Code setup (per machine) | `docs/runbooks/claude-code-setup.md` |

docs/TODO.md

@@ -79,12 +79,13 @@
     4. ~~How do we make sure agents always use the latest official documentation for the technologies etc. we use?~~ DECIDED — ADR-014 (facts → version-matched docs, cited + stamped; best practices → translated per ADR-013; risk-based triggers; graceful fallback to WebFetch).
     5. Always subagent driven?
     6. When AI deploys, i.e. runs playbooks etc., should we make a methodology so that it does not have to poll all the time or review all the output. Perhaps something about the MAKE method could provide only the relevant feedback?
-    7. **Reproducible agent toolchain** (surfaced by ADR-014) — plugins/MCP
-       (`context7`, `superpowers`, `deep-research`, `claude-code-guide`) live under
-       `~/.claude/` per machine; they are NOT synced by account nor carried by git, so
-       a fresh clone lacks them. Make them reproducible from the repo:
-       `extraKnownMarketplaces` + `enabledPlugins` in `.claude/settings.json` + a
-       bootstrap note/script. Tie into control-node/AI setup (items 5 and 7).
+    7. ~~Reproducible agent toolchain (surfaced by ADR-014).~~ DONE — repo
+       `.claude/settings.json` declares `extraKnownMarketplaces` + `enabledPlugins`
+       (active set: superpowers · context7 · terraform · claude-md-management) and a
+       conservative permissions allowlist; bootstrap procedure in
+       `docs/runbooks/claude-code-setup.md`. Deferred plugins listed there with
+       triggers. (Plugin install is still a per-machine `/plugin` action — no native
+       auto-install.)
 
 11. **Kaizen loop** — set up ~2026-06-06 (one week from now).
     1. Build `/retro`: reads `docs/FRICTION.md` + recurring `/review-repo`

docs/runbooks/claude-code-setup.md

@@ -0,0 +1,65 @@
+# 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`.
+
+## 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.