Project Setup Guide

How projects interact with BoB — from initialization to ongoing maintenance.

1. Initializing a New Project

Run cdi (universal items) and cdprov (manifested registry items) in the project you want to connect to BoB:

cd ~/Sites/my-project
cdi                              # Symlinks universal commands, agents, hooks
cdprov                           # Provisions registry items per the manifest
# Or pass an explicit path: cdi /path/to/project

cdi is the wiring step — it creates .claude/ and the universal symlinks. cdprov reads BOB_SOURCE/provisions/<project>.json (falling back to _default.json) and adds symlinks for every registry skill, command, and agent the project declares. The two are split because universal items don’t need a manifest, but registry items do.

What `cdi` Creates

.claude/
├── commands/          ← Symlinks to BOB_SOURCE/commands/
├── hooks/             ← Symlinks to BOB_SOURCE/hooks/
├── agents/            ← Symlinks to BOB_SOURCE/agents/
└── settings.json      ← Hook configuration + project metadata

Workflow agents (solution-architect, project-historian, lessons-extractor) are always included.

Safe to Re-run

Running cdi on an existing project is non-destructive:

Existing symlinks are skipped
Local files are preserved
Only missing components are added

2. What Gets Linked vs What’s Auto-Available

Component	Symlinks Needed?	Why
Skills	No	Auto-loaded from `~/.claude/skills/` (deployed from BOB_SOURCE)
Commands	Yes	Must exist in project’s `.claude/commands/`
Agents	Yes	Must exist in project’s `.claude/agents/`
Hooks	Yes	Referenced by path in project’s `settings.json`
Scripts	No	Referenced by absolute paths

Skills are the exception. Drop a skill into BOB_SOURCE/skills/, deploy, and every project can use it immediately — no symlinks, no linking step.

Everything else needs a symlink from the project’s .claude/ directory pointing back to the source in BOB_SOURCE.

3. Pulling Updates from BoB

Pull the latest source and deploy:

cd ~/projects/bigbrain && git pull
bash scripts/deploy.sh

Existing symlinks auto-propagate. Project symlinks point to BOB_SOURCE, so changes there are picked up instantly. The deploy step syncs skills and other auto-loaded content to ~/.claude/.

New items need linking. If BoB gains a new command or agent that your project doesn’t have yet, you’ll need to link it:

cd ~/Sites/my-project
cdl commands new-command
cdl agents new-agent

Or grab everything at once:

cdl --all

4. Linking Specific Items

Use cdl to link individual items from BoB into your current project:

# Link a command
cdl commands start-work

# Link an agent
cdl agents drupal-expert

# Link a hook
cdl hooks check-branch.sh

# See what's available
cdl --list
cdl --list agents

# Link ALL missing global items
cdl --all

What `cdl --all` Includes

All global commands
All global hooks
Workflow agents (solution-architect, project-historian, lessons-extractor)

What `cdl --all` Does NOT Include

Domain expert agents — link individually as needed (cdl agents drupal-expert)
Skills — they don’t need symlinks (already auto-available)

Status Indicators

Symbol	Meaning
`✓`	Successfully linked
`○`	Already linked (skipped)
`!`	Local file exists (not overwritten)
`✗`	Global item not found

5. Promoting Local Improvements to BoB

When you develop something useful in a project and want to share it globally, use cdp:

cdp .claude/commands/my-command.md
cdp .claude/agents/my-agent.md
cdp .claude/hooks/my-hook.sh
cdp .claude/skills/my-skill/        # Promotes entire directory

What Happens

Copies the file/directory to BOB_SOURCE/<type>/
Removes the local file
Creates a symlink pointing to the new global copy in BOB_SOURCE

Recommended Pattern

The safest workflow is develop → test → promote:

Develop a new tool in a low-risk project (e.g., bodmail)
Test it thoroughly in that project
Promote to BoB: cdp .claude/commands/my-tool.md
Link into other projects: cdl commands my-tool

Supported Types

Path Pattern	Promotes To
`commands/*.md`	`BOB_SOURCE/commands/`
`agents/*.md`	`BOB_SOURCE/agents/`
`hooks/*.sh`	`BOB_SOURCE/hooks/`
`skills/*/`	`BOB_SOURCE/skills/` (auto-available after deploy)

6. Checking Sync Status

Use cdb to see what’s linked and what’s missing:

# Full dashboard (global inventory + project summary)
cdb

# Matrix view: every global item vs every project
cdb --matrix

# Detailed check for a specific project
cdb --check ~/Sites/my-project

# Just global inventory
cdb --global-only

# Just project summaries
cdb --projects-only

Reading the Matrix

Global Item                    bodmail      nanawall
───────────────────────────── ──────────── ────────────
Commands
  journal                      ●            ●
Hooks
  check-branch.sh              ●            ●
  strip-ai-boilerplate.sh      ✗            ✗

Symbol	Meaning
`●` green	Symlinked to global
`○` blue	Local file (same name as global, but not linked)
`✗` red	Missing from project
`◆` yellow	Local-only (exists in project, not in global)

The matrix also shows Local-Only Items — things in your project that don’t exist in BoB. These are candidates for promotion via cdp.

7. Re-syncing Broken Links

Symlinks can break if:

You moved the project directory
You re-cloned the project on a different machine
~/.claude/ was re-deployed from BOB_SOURCE

Fix it with:

cd ~/Sites/my-project
cdl --all

This re-creates all standard symlinks. For domain expert agents, link them individually:

cdl agents drupal-expert
cdl agents cloudflare-expert

To verify everything is healthy:

cdb --check ~/Sites/my-project

8. Dev Environment Setup (Optional)

Set up the IaC dev lifecycle so the project’s dev environment is always testable:

# Copy the dev manifest template (from BOB_SOURCE or deployed BOB_HOME)
cp "$BOB_SOURCE/templates/dev.json" ./dev.json

# Customize: edit server command, port, health endpoint, auth adapter
vi dev.json

# Set up seed data
mkdir -p seed/
cp "$BOB_SOURCE/templates/seed/users.json" ./seed/
cp "$BOB_SOURCE/templates/seed/001-base-data.sql" ./seed/
cp "$BOB_SOURCE/templates/seed/002-sample-entities.sql" ./seed/
# Customize the SQL for your schema

# Test it
dev-up . --verbose

This gives you:

/dev-up — bring the dev environment to fully testable state on demand
Warp-drive auto-manages dev health during autonomous coding
Standardized test users across all projects (admin@test.local / admin123)
Seed data covering all entity lifecycle states

See dev-lifecycle.md for the full guide.

9. Product Planning Workflow

Once a project is initialized, use the product hierarchy to plan and track work:

/vision              Create docs/vision.md — product vision & strategy
/capability          Create a capability (epic) as a GitHub Issue
/requirement         Create a requirement with acceptance criteria
/warp-drive          Autonomous coding loop (picks up approved requirements)

Start with /vision to establish why the product exists, who it’s for, and where it’s going. Then break the vision into capabilities, capabilities into requirements, and let warp-drive handle the rest.