BoB — Big ol' Brain

Appearance

Runbook: Project Onboarding ​

Purpose: Set up a new or existing project for BoB tooling management When to use: First Claude Code session on a project, or after cloning a BoB-managed repo Prerequisites: ~/.claude/ global tooling installed (run bob-install.sh if not) Estimated time: 5-10 minutes

Steps ​

1. Verify global tooling is installed ​

bash
test -f ~/.claude/CLAUDE.md && echo "BoB installed" || echo "Run bob-install.sh first"

Expected output: BoB installed

Decision point: If not installed, run $BOB_SOURCE/scripts/bob-install.sh first (or ~/projects/bigbrain/scripts/bob-install.sh), then return here.

2. Initialize project with global tooling ​

From the project root:

bash
cdi

Expected output: Symlinks created for commands, agents, hooks, and templates.

3. Check or create project manifest ​

bash
ls ~/.claude/provisions/$(basename $(pwd)).json 2>/dev/null && echo "Manifest exists" || echo "Need to create manifest"

Decision point: If manifest exists, go to step 5. If not, go to step 4.

4. Create project manifest ​

Auto-detect the project stack and generate a manifest:

bash
cdprov --init

Or manually create ~/.claude/provisions/<project>.json:

json
{
  "_meta": {
    "project": "<project-name>",
    "path": "/path/to/project",
    "stack": ["sveltekit", "cloudflare"]
  },
  "skills": [],
  "commands": [],
  "agents": [],
  "runbooks": []
}

5. Provision registry items ​

bash
cdprov

Expected output: Symlinks created for all manifest-declared registry items.

6. Set automation level ​

/automation level 2

Or level 3 for fully autonomous operation.

Expected output: settings.local.json updated with permissions.

7. Set up dev environment (if applicable) ​

Check if the project has a dev manifest:

bash
test -f dev.json && echo "dev.json found" || echo "No dev.json — skip or create from template"

Decision point: If dev.json exists, run /dev-up. If not and the project needs one, copy the template:

bash
cp ~/.claude/templates/dev.json ./dev.json
# Edit to match project's server, migrations, seed, and auth config

7a. Onboard the whole fleet's dev ports (one-time, #198) ​

Bulk-backfill deterministic dev port bands for every pre-#197 project at once (idempotent; review first): make port-migrate-dry then make port-migrate from BOB_SOURCE.

8. Verify setup ​

bash
cdb

Expected output: Dashboard showing all symlinks, provisioned items, and their status.

Troubleshooting ​

SymptomLikely CauseFix
cdi: command not foundShell profile not sourcedRun $BOB_SOURCE/scripts/bob-install.sh and restart shell
Symlinks broken after git pullcdi not re-run after global changesRun cdi again
Provision manifest not foundProject name doesn't matchCheck basename $(pwd) matches manifest filename
Wrong items provisionedManifest outdatedRun cdprov --status to compare, then edit manifest

Escalation ​

If this runbook doesn't resolve the issue:

  1. Check cdb output for broken symlinks and fix manually
  2. Run cdi with verbose output to diagnose: bash -x $(which cdi)