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

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:

cdi

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

3. Check or create project manifest

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:

cdprov --init

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

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

5. Provision registry items

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:

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:

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

cdb

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

Troubleshooting

Symptom	Likely Cause	Fix
cdi: command not found	Shell profile not sourced	Run $BOB_SOURCE/scripts/bob-install.sh and restart shell
Symlinks broken after git pull	cdi not re-run after global changes	Run cdi again
Provision manifest not found	Project name doesn’t match	Check basename $(pwd) matches manifest filename
Wrong items provisioned	Manifest outdated	Run 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)