Install

Prerequisites

Required:

  • uv — drives the plugin's Python tooling. The bin/booping wrapper is uv run --project booping-python booping ..., so every skill load goes through uv.
  • git — the plugin assumes a git working tree for branching, diffs, and commit attribution during the develop and code-review playbooks.
  • mdcheck — the markdown structure checker. The groom playbook checks every milestone file with it, and booping specs check validates records with it. Install it from the markdown-checker crate (needs a Rust toolchain); the crate named mdcheck is an unrelated tool.

Optional:

  • A cross-review agent — set core.groom_playbook.cross_review_agent in your config and the groom playbook hands the drafted plan to that agent for a second-model review before presenting it to you. With no agent configured the step is skipped silently — the rest of the loop is unaffected.

Install the prerequisites:

# macOS
brew install uv git

# Linux (Debian/Ubuntu)
sudo apt install -y git
curl -LsSf https://astral.sh/uv/install.sh | sh

# both
cargo install markdown-checker --version 0.1.2 --locked

Plugin install

Inside Claude Code, register the marketplace once and install the plugin:

/plugin marketplace add A/claude-booping
/plugin install booping@booping

Update later with /plugin update booping (or from the /plugin UI).

Create the project vault

cd into the target repository and run:

/playbook setup

The setup playbook takes the repo from any starting state to a working booping project in one conversation, and every phase already satisfied on entry is detected and skipped rather than redone — a re-run on a wired-up project reports the state instead of changing it.

It runs in two steps:

  1. Machine level — when booping is not yet initialized, it asks for your preferred home dir (default ~/Claude/), writes the machine config at ${XDG_CONFIG_HOME:-~/.config}/booping/config.yaml, and makes the home dir exist as a git repo. When the machine config names no global specs namespace yet, it asks for one (default $USER) and stores it as core.specs.tiers.global.namespace; then it creates the global specs tier at <home_dir>/_specs/.
  2. Project level — it asks where the vault lives (the default <home_dir>/{project}/, kept outside the repo, or a repo-local directory recorded via the .booping marker's vault_path: key), the project name, and marker visibility; then creates the vault tree, writes the .booping marker, symlinks a repo-local vault into the home dir, and seeds sprints.md; last, it sets up the project specs tier — by default the vault root itself, where the record type directories sit beside plans/, so nothing is created; a tier you keep in the repo is created there and linked from <vault>/specs.

The created vault:

  • plans/ — sprint plans authored by the groom playbook, executed by the develop playbook.
  • retrospectives/ — standalone retrospectives authored by the retro playbook, consumed by the learn playbook.
  • notes/ — your own free-form notes (untouched by booping).
  • sprints.md — an Obsidian Bases fence over the vault's plans/*/index.md files; seeded once, evaluated live by Obsidian.
  • .gitignore — vault-level ignores, including the .booping.log the CLI writes at the vault root.
  • .booping — marker file (written in the repo root, not the vault) telling booping which vault to resolve.

For the full directory tour (including plan_templates/, review_templates/, sprints.md, and config.yaml), see Vault.

Verify

After setup, run /playbook inside the same repo. It should list the shipped playbooks — groom, develop, retro, learn, code-review, project-manager, setup, migrate, playbook-authoring — with no STOP notice, which is your signal that the vault resolved and you're ready to run your first groom.