README

BoB — Big ol’ Brain

Global Claude Code tooling framework. Skills, agents, slash commands, hooks, and scripts that sync across every project from a single source-of-truth git repo.

The full reference is PROJECT-ORCHESTRATION-HANDBOOK.md — the encyclopedic guide to running projects with BoB. This README is the doorway.

Architecture in one diagram

BOB_SOURCE (~/projects/bigbrain)        <- Source of truth (this repo)
    │   scripts/deploy.sh   (sync)
    ▼
BOB_HOME (~/.claude/)                   <- Runtime — Claude Code reads here
    │   cdi  (per-project init)
    ▼
.claude/  (in each project)             <- Per-project symlinks

Component	Universal	Registry	Loading
Skills	13	31	Universal: auto-loaded globally. Registry: provisioned per-project.
Commands	16	18	Symlinked into <project>/.claude/commands/ by cdi (universal) or cdprov (registry)
Agents	4	17	Symlinked into <project>/.claude/agents/ (same model as commands)
Hooks	26	—	Wired into ~/.claude/settings.json by event
Scripts, bin, templates, runbooks	—	—	Synced to ~/.claude/ by deploy.sh

Key features

• Warp Drive (/warp-drive) — autonomous development loop. State-machine driven; picks up req + approved GitHub Issues, chunks the work, codes, tests, commits, reports, merges. See warp-drive-guide.md.
• cdfork — fan out N parallel warp-drives across git worktrees + tmux windows for independent work clusters. See cdfork-guide.md.
• Manifest-driven provisioning — each project declares its registry items in provisions/<project>.json; cdprov reconciles symlinks against the manifest.
• Dev environment IaC — dev.json + seed/ + standardized test users (admin@test.local / admin123). /dev-up brings any project to fully testable state. See dev-lifecycle.md.
• Automation levels (/automation) — three permission tiers (Supervised / Trusted Dev / Autonomous), backed by JSON profiles in profiles/.
• Remote Decision Bridge (/rdb) — route decisions to Telegram for couch-mode operation.
• Verification (make check) — IaC validation: deps, schemas, symlinks, hooks, provisioning state.

CLI

Command	Purpose
cdi	Initialize a project with BoB tooling (per-project symlinks)
cdb	Dashboard — global tooling and project symlink status
cdp	Promote a local item to the global source
cdl	Link a global item into a project
cdprov	Provision a project from its manifest (add / remove / status / diff / refresh / init)
cdg / cds	Generate / serve a project dashboard
cdfork	Parallel worktree orchestration (fork, --from-issues, status, drop, pair)
claude (wrapper)	Intercepts -a1 / -a2 / -a3 (automation level) and -rdb (Telegram), exec’s the real claude CLI
warp	Observe / control warp-drive from a regular terminal (warp status, warp stop)
dev-up / dev-health	Run /dev-up from a regular terminal

Slash commands

Universal (always present):

/vision /capability /requirement /what-next /start-work /commit /pr /finish-work /journal /session-summary /warp-drive /stop-warp-drive /cdfork /dev-up /provision /rebob /trace-mining /automation /rdb

Plus 18 opt-in registry commands provisioned per-project (/research, /deploy, /release, etc.). Full list: handbook §12.

Setup on a new machine

git clone git@github.com:paulirv/bigbrain.git ~/projects/bigbrain
cd ~/projects/bigbrain
 
scripts/bob-install.sh           # Adds claude wrapper + cdprov/cdr/cdfork aliases
source ~/.zshrc                   # (or ~/.bashrc)
 
scripts/deploy.sh --first-run    # Sync source → ~/.claude/

Per-project: cd <project> && cdi && cdprov.

Full guide: new-machine-setup.md.

Updating BoB

cd ~/projects/bigbrain
git pull
scripts/deploy.sh --dry-run      # Preview
scripts/deploy.sh                # Apply
make check                       # Verify nothing broke

Verification

make check    # deps + schemas + symlinks + hooks + provisions
make test     # state-machine + schema-validator + integration tests
make ci       # check + test (what GitHub Actions runs)
make help     # full target list

Documentation

The handbook is the entry point. Topic-specific deep-dives:

Doc	Content
PROJECT-ORCHESTRATION-HANDBOOK.md	Encyclopedic reference for everything below
warp-drive-guide.md	Warp drive — install, CLI, internals, troubleshooting
cdfork-guide.md	Parallel worktree orchestration
dev-lifecycle.md	Dev environment IaC, seed convention, test users
token-monitoring.md	Token capture pipeline, budgets, cost reports
prime-directive.md	IaC principles, approved patterns, anti-patterns
vision.md	BoB’s own product vision and roadmap
verification-system.md	make check deep-dive
branch-config.md	Branch detection and merge strategy
backup-recovery.md	Disaster recovery
project-setup-guide.md	How a project interacts with BoB day-to-day
new-machine-setup.md	Fresh-machine install
NATURAL-LANGUAGE-GUIDE.md	”Bob” / “BoB” terminology reference
CLAUDE.md	Project instructions checked into the repo

License

Private repository for Insite Web Publishing, Inc.