claude-booping CLAUDE.md

booping plugin — project guide

Claude Code plugin that grooms and executes plans across user projects. Plans and other run artifacts live in the per-project vault — ~/Claude/{project}/ by default, or a repo-local directory via the .booping marker's vault_path: key. Skills, agents, playbooks, templates, and config live in this repo.

One shipped skill (/playbook); everything procedural is a playbook it drives (groom, develop, code-review, retro, learn, setup, migrate, playbook-authoring).

Commands

• just lint / just typecheck / just pytest — ruff / basedpyright / pytest over booping-python/.
• just snapshots — diff committed playbook reports against a fresh hermetic render (writes nothing). just snapshots-accept [playbook] — the only writer of the committed reports.
• just mdcheck — structural rule checks over the rendered reports. Needs the mdcheck binary: cargo install markdown-checker (the crate named mdcheck is unrelated).
• just e2e [pytest args…] — run the txtar contract corpus through pytest, passing any arguments straight to it (just e2e -k config-get, just e2e --txtar-update); --txtar-update rebaselines the selected cases.
• just ci — everything CI runs, in order: lint typecheck pytest snapshots mdcheck e2e. Run before committing.
• just eval|smoke|regress <playbook>/<step> (or all) — promptfoo eval suites; just suites lists them. Runs on subscription auth (claude -p), never in CI; each run posts a sticky, advisory PR comment via scripts/eval-pr-comment.sh (EVAL_PR=0 opts out) — no commit status, no merge gate.
• just docs / just docs-serve — build / preview the public docs site.
• bin/booping <subcommand> --help — the single runtime CLI: render, render-playbook, playbook-state, playbook-transition, query, config-get, marker-set, scaffold, frontmatter-update, session-stats, debug-context.

Layout

• booping-python/ — uv Python project with the booping CLI. Source src/booping/, tests tests/, contract corpus e2e/ — cases plus a conftest.py configuring the pytest-txtar plugin, which owns the runner and the case-format spec (https://github.com/A/pytest-txtar); scaffold is verified there, not by the unit tests.
• bin/booping — the only product entry point: a shell wrapper exec'ing uv run --project booping-python booping "$@".
• scripts/ — dev tooling behind just: snapshots.py, mdcheck.py (uv inline Python), and the eval harness (eval-*.sh, report-*.jq). Not shipped to users.
• src/config.yaml — runtime config, single source of truth for structured data (macros, query specs, scaffold trees, task types, sprint scale, per-playbook agents). Heavily commented — read it for key semantics.
• src/templates/ — runtime skill/agent templates + _partials/, rendered at skill-load time. Edits are live, no rebuild.
• skills/<name>/SKILL.md, agents/<name>.md — hand-authored thin shells: frontmatter (including effort:) plus one !booping render src/templates/…`` line that pulls in the body at load time.
• playbooks/<name>/ — core playbooks. Also: _partials/ (shared fragments), _scripts/ (shared hook scripts), _lib/ (eval harness), _fixtures/vault/ (hermetic render fixture). Each playbook commits its rendered report at playbooks/<name>/_reports/output.md.
• playbooks/*/_specs/ — playbook-authoring run artefacts and design history; intentionally stale, not a spec of current behaviour.
• migrations/<NNN>_<slug>/migration.md — plugin-shipped vault migrations. Frontmatter id is the authority; a vault's applied watermark is the .booping marker's latest_migration key, and every render surface gates on it. Authoring primitives: query specs with root: core scan plugin-shipped files, numeric --where ordering (gt/lt), {{ booping.latest_migration }} in templates, marker writes via booping marker-set.
• docs/ — hand-authored plugin-internal fragments, lazy-loaded by skills via ${CLAUDE_PLUGIN_ROOT}/docs/<name>.md links. No build step.
• documentation/ — public docs site source (MkDocs → gh-pages on push to master). Hand-authored.