66 lines
2.9 KiB
Markdown
66 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.
|