From abb5c7a12f5d99b88ece34cb7b0230c4c13909f5 Mon Sep 17 00:00:00 2001 From: sjat Date: Thu, 4 Jun 2026 21:41:54 +0200 Subject: [PATCH] Make the Claude Code toolchain reproducible (TODO 10.7) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .claude/settings.json | 32 +++++++++++++++ CLAUDE.md | 1 + docs/TODO.md | 13 +++--- docs/runbooks/claude-code-setup.md | 65 ++++++++++++++++++++++++++++++ 4 files changed, 105 insertions(+), 6 deletions(-) create mode 100644 docs/runbooks/claude-code-setup.md diff --git a/.claude/settings.json b/.claude/settings.json index 1853e42..bbf8f01 100644 --- a/.claude/settings.json +++ b/.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": [ { diff --git a/CLAUDE.md b/CLAUDE.md index 9b3cd93..7822535 100644 --- a/CLAUDE.md +++ b/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` | diff --git a/docs/TODO.md b/docs/TODO.md index f047b64..e45d12d 100644 --- a/docs/TODO.md +++ b/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` diff --git a/docs/runbooks/claude-code-setup.md b/docs/runbooks/claude-code-setup.md new file mode 100644 index 0000000..d745bdd --- /dev/null +++ b/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.