| name | setup |
| description | One-time setup for anvil: install and configure beads (bd or br) operator-scoped, verify the table-stakes tooling (git, gh + auth, claude), stand up the out-of-repo state under ~/.anvil, and PROVE the install imposed nothing on any target repo. Use when the operator first installs the anvil plugin, when bd/br is missing, or when /anvil:plan or /anvil:dispatch complains that beads isn't set up. |
anvil setup
You are standing up the operator-scoped, non-invasive substrate that the rest
of anvil depends on. When you are done, bd ready works, all state lives under
~/.anvil/ and $BEADS_DIR, and nothing has been written into any target
repository — no .beads/ file, no CLAUDE.md edit, no repo setting.
This is also a measurement. anvil exists to test (Forge ADR-0030) whether a
bare-parts stack can deliver repo-untouched, worktree-safe planning. So as you go,
record exactly what setup imposed — that log is the experiment's primary
result, not a side note.
Consent rules (read first)
Setup mutates the operator's machine (installs binaries) and possibly their
shell profile. It must NEVER mutate a target repo. Therefore:
- Ask before any system-level install (
brew install, cargo install,
go install, downloading a release binary). Show the exact command first.
- Ask before editing the shell profile (
~/.zshrc etc.). Offer to do it;
don't do it silently.
- Never write into a target repo, and never invoke the
forge binary.
anvil uses only bd/br, git, gh, and claude.
Step 1 — Detect the environment
uname -s
command -v brew cargo go gh git claude 2>/dev/null
Note the platform and which package managers exist — you'll pick the beads
install method from this.
Step 2 — Verify the table-stakes tooling
These are not anvil's job to install, only to verify and guide:
- claude — present by definition (you are running inside it). Confirm
claude --version.
- git — required. If missing, stop and tell the operator to install it.
- gh — required for the dispatch/review loop. Check
gh --version and
gh auth status. If gh is missing, offer (with consent) brew install gh
(macOS) or point to https://cli.github.com. If it's installed but not
authenticated, tell the operator to run gh auth login themselves (it's
interactive — suggest they type ! gh auth login in the session).
Step 3 — Install beads (the one thing anvil specifically needs)
Check first — it may already be present:
command -v bd && bd --version
command -v br && br --version
If neither is present, install one. Prefer bd (Go/Dolt) — it has the
richest operator-scope story (BEADS_DIR git-free mode + contributor-mode
out-of-repo planning), which is exactly what anvil leans on. Fall back to br
(Rust/SQLite). Pick the method by what Step 1 found, and ask before running it:
Tell the operator which binary you installed and why. If both bd and br are
already present, prefer bd and say so.
Honest note for the operator: when bd set up agent integration in the past
it edited CLAUDE.md/hooks — exactly the imposition anvil avoids. Do NOT
run any bd setup/bd init --with-claude style command that writes into a
repo or a CLAUDE.md. We initialize beads ONLY in the out-of-repo $BEADS_DIR
(next step). If a beads subcommand insists on touching a repo, that's a finding
for the operator-scope log — record it, don't work around it by committing.
Step 4 — Stand up the operator-scoped store
Run the bundled bootstrap. It creates $BEADS_DIR (default ~/.anvil/beads)
and ~/.anvil/specs/, and runs bd init (or br init) inside $BEADS_DIR,
never in a repo:
${CLAUDE_PLUGIN_ROOT} is NOT expanded in skill text, so discover the plugin root
first, then run the bundled bootstrap:
ANVIL_PLUGIN_ROOT="$(find "$HOME/.claude/plugins" "$HOME/repositories" "$HOME/repos" "$HOME/src" \
-type f -name install-beads.sh -path '*anvil/bootstrap*' 2>/dev/null | head -1 \
| xargs -r dirname | xargs -r dirname)"
echo "anvil plugin root: $ANVIL_PLUGIN_ROOT"
"$ANVIL_PLUGIN_ROOT/bootstrap/install-beads.sh"
The script prints the operator-scope checklist — keep its output. You'll persist
ANVIL_PLUGIN_ROOT in the next step so the other skills can locate the workflows.
Step 5 — Persist BEADS_DIR and ANVIL_PLUGIN_ROOT
Every anvil skill and workflow honors $BEADS_DIR, and the workflow-invoking skills
(/anvil:critique, /anvil:dispatch) resolve their bundled scripts via
$ANVIL_PLUGIN_ROOT (because ${CLAUDE_PLUGIN_ROOT} is unusable from skill text —
see Step 4). Persist both:
export BEADS_DIR="$HOME/.anvil/beads"
export ANVIL_PLUGIN_ROOT="$ANVIL_PLUGIN_ROOT"
Offer to append these to their shell profile (~/.zshrc on this platform) — and
ask before editing it. If they decline, tell them to export them themselves;
skills fall back to ~/.anvil/beads for BEADS_DIR and to a find over
~/.claude/plugins for the plugin root, but persisting is more reliable.
Step 6 — Prove zero repo imposition (the decisive check)
This is the experiment's question #1. From inside a REAL target repo the operator
names (ideally a worktree-heavy one), confirm the stack reads/writes its
frontier without touching the repo:
cd <some target repo>
git status --porcelain > /tmp/anvil-before
BEADS_DIR="$HOME/.anvil/beads" bd ready
ls -a .beads 2>/dev/null && echo "IMPOSITION: .beads dir present in repo!"
git status --porcelain > /tmp/anvil-after
diff /tmp/anvil-before /tmp/anvil-after && echo "CLEAN: repo untouched ✓"
Record honestly:
operator-scope log
[ ] Installing beads touched NO target repo (expected: pass)
[ ] `bd ready` from inside a repo created nothing in it (expected: pass)
[ ] No .beads/ file appeared in the repo or any worktree (expected: pass)
[ ] No CLAUDE.md / repo setting was modified (expected: pass)
[ ] Worktrees do NOT each need their own committed file (expected: pass)
Any box that fails is not a bug to patch around — it's the answer to whether the
operator-scoped differentiator is real or just config. Surface it to the operator.
Step 7 — Report
Tell the operator, concisely:
- Which beads binary is installed (
bd/br) and its version.
- Where state lives (
$BEADS_DIR, ~/.anvil/specs/).
gh auth status and any remaining manual step (e.g. gh auth login).- The operator-scope log result.
- Next step:
/anvil:plan to draft and lock the first spec.
What you must never do
- Install anything, or edit the shell profile, without showing the command and
getting consent first.
- Write a
.beads/ file, a CLAUDE.md, or any file into a target repo or worktree.
- Run a
bd/br subcommand that edits a repo's CLAUDE.md or settings.
- Invoke the
forge binary. anvil is the bare-parts stack — it has no Forge.
- Silently "fix" an imposition by committing it. Log it instead.
