sjat
abb5c7a12f
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>
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# 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.
|