propagator — cross-repo infrastructure for llamaclaw

Scripts that distribute shared infrastructure across every repo in the llamaclaw org. Boot hooks, worktree healers, parity audits, push-to-all utilities.

Why this repo exists

The llamaclaw org has 13+ sibling repos (esml, yoda, tide, kronos, turboquant, perseus, autoresearch, luci, installer, deploy, intersphinx, the umbrella itself, and this propagator). When we need to land the same piece of shared infrastructure — a Claude Code hook, a CI snippet, a security config — in all of them, doing it by hand is how things drift.

This repo is the single source of truth for cross-repo operations. The individual pieces of infrastructure (the actual hook scripts, the healer) also live where they are used; this repo’s scripts propagate them.

Origin

Created 2026-04-18 after the boot-bridge severance post-mortem revealed that only 1 of 13 llamaclaw repos had the Ghajini boot hooks correctly wired. The propagation script in this repo landed hooks on the other 12 in a single run, with 0 failures.

Full post-mortem lives at llamaclaw/yoda → yodavision/mistakes/boot_bridge_worktree_severance_20260418.md.

Scripts

Script

Purpose

bin/propagate_boot_hooks.sh

Copy Claude Code boot hooks + settings.json + healer to every llamaclaw repo, commit on dev, push, ff main.

bin/audit_boot_hooks.sh

Report which repos have/lack Ghajini boot hooks — dry-run status check.

bin/heal_worktree_hooks.sh

Idempotent worktree healer (canonical copy; individual repos also embed this).

Run from this repo’s root:

./bin/audit_boot_hooks.sh                      # safe read-only status
./bin/propagate_boot_hooks.sh                  # propagate everywhere
./bin/propagate_boot_hooks.sh /custom/umbrella # non-default umbrella dir

Expected directory layout

~/llamaclaw-migrations/llamaclaw-umbrella/   ← UMBRELLA_DIR (default)
  ├── esml/               ← clones of each llamaclaw repo
  ├── yoda/
  ├── tide/
  ├── kronos/
  ├── …
  └── propagator/         ← this repo

Override the umbrella dir with LLAMACLAW_UMBRELLA=/path ./bin/... or as a positional arg.

Source of truth for hook content

Hook scripts are sourced from esml-dev/.claude/hooks/*.sh (the Claude Code project that originated them). The propagator reads those files and distributes them. If the canonical location changes, update SRC_ROOT in bin/propagate_boot_hooks.sh.

Design notes

  • Idempotent: re-running a propagator when no files changed is a no-op. Commits only land when content actually differs.

  • Rebase-first push: if a remote branch has parallel-Yoda commits, the script pulls –rebase and retries. Only force-push on explicit opt-in (never by default).

  • Per-repo respect: if a repo is in a detached HEAD or has an unusual branch setup, the script skips it with a logged reason rather than trying to be clever.

  • dev → main ff: after pushing dev, the script tries git push origin dev:main. If main has diverged, this fails cleanly and is reported; no force-push.

Further reading

  • docs/SIGNIFICANCE.md — per-repo stake: why the boot bridge matters for yoda, luci, perseus, kronos, turboquant, and every other sibling repo. Each section names the specific failure mode the hooks prevent.

  • docs/HOW_TO.md — common recipes: audit, propagate, override source, add new cross-repo operation, recover from bad propagate.

Lint

./bin/lint.sh   # shellcheck + shfmt on all .sh files

CI runs the same on every push to dev or main (see .github/workflows/lint.yml).

License

GPL-3.0-or-later, matching the rest of the llamaclaw ecosystem.