BoB — Big ol’ Brain
BoB (Big ol’ Brain) is the name for this global Claude Code tooling framework. See bob-identity.md for the full identity definition.
The source repo (BOB_SOURCE, default ~/projects/bigbrain) is the single source of truth for all BoB tooling. It is deployed to ~/.claude/ (BOB_HOME) where Claude Code reads it at runtime.
For the encyclopedic guide, see PROJECT-ORCHESTRATION-HANDBOOK.md.
Architecture
BOB_SOURCE (~/projects/bigbrain) <- Source of truth (git repo)
├── skills/ <- 13 universal skills (auto-loaded globally)
├── commands/ <- 16 universal commands (symlinked into projects by cdi)
├── agents/ <- 4 universal agents (symlinked into projects by cdi)
├── runbooks/ <- Universal runbooks (procedural ops guides)
├── hooks/ <- 26 hooks (referenced by ~/.claude/settings.json)
├── registry/ <- NOT auto-loaded — provisioned per-project
│ ├── skills/ <- 31 domain skills (cloudflare-dev, frontend-design, etc.)
│ ├── commands/ <- 18 PM/workflow commands (research, deploy, retrospective, etc.)
│ ├── agents/ <- 17 specialist agents (code-reviewer, qa-strategist, etc.)
│ └── runbooks/ <- Domain-specific runbooks
├── provisions/ <- Per-project manifests (one JSON per project)
├── scripts/ <- CLI scripts, helpers, state-machine engine, dev-lifecycle
├── bin/ <- PATH-friendly entrypoints (warp, cdfork, cdfork-pair, dev-up, dev-health)
├── templates/ <- dev.json, seed/, hooks/ — copied (not symlinked) to projects
├── schemas/ <- JSON Schema for manifest, projects, settings
├── profiles/ <- Permission profiles per automation level (supervised, trusted, autonomous)
├── docs/ <- Guides (handbook lives here)
├── Makefile <- IaC verification entry point (make check / test / ci)
└── tests/ <- Schema validator + state-machine + integration tests
BOB_HOME (~/.claude/) <- Runtime directory (deployed)
├── skills/, scripts/, hooks/, etc. <- Synced from BOB_SOURCE by deploy.sh
├── settings.json <- Machine-specific (protected by deploy)
├── settings.local.json <- Machine-specific (protected; holds _automation, _rdb)
└── CLAUDE.md <- Deployed copy (special merge handling)
Prime Directive: Everything BoB manages must be declarative, version-controlled, reproducible, idempotent, and observable — with every piece of state owned by exactly one source of truth. See prime-directive.md.
| Type | Source (BOB_SOURCE) | Runtime (BOB_HOME) | Loading |
|---|---|---|---|
| Universal skills | skills/ | Synced by deploy.sh | Auto-loaded globally |
| Universal commands | commands/ | Symlinked by cdi from BOB_SOURCE | Per-project symlinks |
| Universal agents | agents/ | Symlinked by cdi from BOB_SOURCE | Per-project symlinks |
| Universal runbooks | runbooks/ | Synced by deploy.sh | Referenced by absolute path |
| Registry items | registry/ | Synced by deploy.sh | Provisioned per-project via manifest |
| Hooks | hooks/ | Synced by deploy.sh | Referenced in settings.json |
| Scripts | scripts/ | Synced by deploy.sh | Referenced by absolute path |
| Templates | templates/ | Synced by deploy.sh | Copied to projects, then customized |
Provisioning: Each project has a manifest at provisions/<project>.json declaring which registry items it needs. Run cdprov or /provision to manage. Universal items are always present; registry items are only loaded when provisioned.
Orchestrator (#157 family). Registry items declare orchestrator metadata in their frontmatter (applies_to.stacks, applies_to.project_types, recommended_for, category, default, required_with). The recommendation engine at scripts/orchestrator/recommend.js reads that metadata and produces a manifest from (detected stack, project type, capabilities). When the user asks “what should I provision?” or “is X applicable to this project?” — that’s the orchestrator’s question. Full reference: orchestrator-guide.md.
Deploying: Run scripts/deploy.sh to sync BOB_SOURCE → BOB_HOME. Use --dry-run to preview, --first-run on initial setup. Machine-specific files (settings.json, settings.local.json, CLAUDE.local.md) are never overwritten.
CLI
| Command | Purpose |
|---|---|
cdi | Initialize a project with BoB tooling |
cdb | Dashboard — view 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 | Generate a project dashboard |
cds | Dashboard server (auto-port per project) |
cdfork | Fan out parallel /warp-drive sessions into git worktrees + tmux windows. See cdfork-guide.md. |
cdfork-pair | Cross-repo contract-driven parallel mode |
warp | Observe / control warp-drive from a regular terminal (warp status, warp stop) |
dev-up / dev-health | Run /dev-up lifecycle / health probe from a regular terminal |
claude (shell wrapper) | Intercepts -a1 / -a2 / -a3 (automation level) and -rdb (Telegram), exec’s the real claude CLI |
Verification (Makefile)
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 listCRITICAL: Hooks Receive JSON via stdin
There are NO magic variable substitutions. Hooks receive ALL data via stdin as JSON.
# RIGHT — Read JSON from stdin:
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')| Hook Type | Extract Field |
|---|---|
| Bash PreToolUse | tool_input.command |
| Edit/Write PreToolUse | tool_input.file_path |
| Bash PostToolUse | tool_input.command, tool_output.exit_code |
Requires jq. Template: ~/.claude/templates/hooks/command-hook.sh. Full hook table: handbook §14.
Temporal Accuracy (Timelord)
All PM commands must verify dates via ~/.claude/skills/timelord/scripts/now.sh before writing. Never trust memory for dates — session context can become stale across midnight or long sessions.
Date formats: Files: YYYY-MM-DD, Prose: human-readable, Timestamps: ISO 8601. Week convention: ISO (Monday=1).
Work Tracking
All work is tracked via GitHub Issues on each project’s repo. No local PM files or indexes.
Do not create REQ-*.md, SOL-*.md, BUG-*.md, RISK-*.md, or any PM document files. Do not create REQUIREMENTS-INDEX.md, SOLUTIONS-INDEX.md, backlog.md, or traceability-matrix.md. The full forbidden-pattern list is in handbook §15.3.
Product Hierarchy
Vision & Strategy (docs/vision.md) /vision — living doc: why, who, where
└── Capability (label: cap) /capability — feature spec, user stories
└── Requirement (label: req) /requirement — acceptance criteria, testable work
└── Warp-drive chunks automatic — individual commits
| Level | Format | Command | Contains |
|---|---|---|---|
| Vision | docs/vision.md | /vision | Product vision, strategy, principles, non-goals, roadmap |
| Capability | GitHub Issue (cap) | /capability | User stories, success metrics, requirements checklist |
| Requirement | GitHub Issue (req) | /requirement | Description, acceptance criteria (checkboxes), priority, notes |
| Reporting | GitHub Issue | /journal | Decisions, lessons, session summaries |
| Bug | GitHub Issue (bug) | gh issue create --label bug | Bug reports |
| TODO | GitHub Issue (todo) | auto-created by warp-drive timeout | Human action items |
The vision doc is a living document, not an issue — it doesn’t get “closed.” Capabilities trace back to the vision. Requirements link to their parent capability via Part of #NN in the Notes section. Capabilities track child requirements as a checkbox list.
Priority labels: p1-critical / p2-high / p3-medium / p4-low
Workflow: cap + approved → ready to break into requirements. req + approved → picked up by /warp-drive.
Autonomous Development Workflow
When the user asks “what next?”, “what should we work on?”, or similar — check GitHub Issues via gh issue list --label approved on the relevant repo (or run /what-next).
At automation Level 2/3, the /warp-drive command orchestrates the full cycle: work discovery → code → document → test → commit → report → merge/PR → continue. Only prompt for project decisions (architecture, ambiguity, new deps, scope expansion).
For parallel work clusters across a repo, use cdfork (or the /cdfork slash command) to fan out N warp-drive sessions into isolated git worktrees + tmux windows. Subcommands: cdfork fork <branches...>, cdfork fork --from-issues [N], cdfork status, cdfork drop <branch>, cdfork pair for cross-repo contract-driven mode. Pinch points (config sync, lockfiles, migrations, compiled assets, deploy) must NOT be fanned out — label such issues serial-only so --from-issues excludes them.
See warp-drive-guide.md and cdfork-guide.md for the full references.
Dev Environment Lifecycle (IaC)
Every project can declare its dev environment in a dev.json manifest at the project root. The /dev-up command (and bin/dev-up from a regular terminal) reads this and orchestrates: start server → run migrations → seed data → provision test users → health check → report URL.
On-demand: Run /dev-up anytime to bring a project’s dev environment to fully testable state.
Warp-drive integration: When dev.json exists, warp-drive automatically calls dev-up before the first chunk, verifies health between chunks, and auto-recovers on failure. Dev health failure is a blockable event.
Seed data convention: Projects use a seed/ directory with idempotent scripts. Seed data must cover ALL lifecycle states the domain defines (not just fresh records). New features include seed data in the same commit.
Standardized test users: seed/users.json defines test users provisioned via pluggable auth adapters (d1, sqlite, supabase, script, custom). The superuser (admin@test.local / admin123) is consistent across all projects.
See dev-lifecycle.md for the full reference.
Remote Decision Bridge
Toggle RDB mode via /rdb on or the -rdb startup flag. When RDB is enabled (_rdb.enabled: true in settings.local.json), use ask_remote for ALL decisions — never fall back to AskUserQuestion. When the user says they’re stepping away, going AFK, or going remote, treat that as /rdb on. Use notify_remote for status updates during autonomous work. /rdb off switches back to terminal prompts.
Reporting (GitHub Issues)
| Type | Label | Created By |
|---|---|---|
| decision | decision | /journal decision or warp-drive reporting |
| lesson | lesson | /journal lesson or warp-drive reporting |
| session | session-summary | /session-summary or warp-drive session end |