Project Setup Guide

Project Setup Guide

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

Two worlds, labelled. Each step shows the path a command belongs to: Terminal (a shell, outside any session) or Slash command (typed in a Claude Code session). The tooling commands cdi, cdl, cdp, and cdb are terminal-only PATH entrypoints (deployed to ~/.claude/bin, #1193) with no slash equivalent; where a step does have both forms — cdprov ↔ /provision, dev-up ↔ /dev-up — both are shown as a labelled pair.

1. Initializing a New Project

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

Terminal:

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

Slash command: /provision runs the cdprov step inside a Claude Code session. (cdi is terminal-only — it wires up .claude/ before a session exists, so it has no slash form.)

Fresh clone? Run the two commands above right after cloning — provisioned symlinks are derived state and do not arrive via checkout (#1479): they are gitignored by a cdprov-managed block, so a just-cloned project has none until cdi + cdprov refresh materialize them. cdprov status listing [unlinked] items on a fresh clone is that pre-refresh state, not breakage.

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:

Terminal:

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:

Terminal: (cdl is a terminal-only command — no slash form)

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

Or grab everything at once:

Terminal:

cdl --all

Reconciling the manifest after the project changes

When the project itself has moved — a new capability in docs/vision.md, a CI workflow added, a stack dropped — re-derive the manifest instead of hand-editing it (#1880):

Terminal:

cd ~/Sites/my-project
cdprov reconcile                  # dry run: + would-add (with why) / - would-remove, nothing written
cdprov reconcile --apply          # apply: one-item delta at L2+ fast-paths end-to-end,
                                  #        multi-item delta or L1 opens a review PR
cdprov reconcile --apply --allow-remove   # also drop would-remove items (never by default)

cdprov --diff --infer is the same dry run. A second reconcile right after an applied one reports no delta. Would-remove items are withheld until you pass --allow-remove (or answer yes interactively); items pinned in _meta.manual are never removal candidates.

4. Linking Specific Items

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

Terminal: (cdl is a terminal-only command — no slash form)

# 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:

Terminal: (cdp is a terminal-only command — no slash form)

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

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

Recommended Pattern

The safest workflow is develop → test → promote:

1. Develop a new tool in a low-risk project (e.g., bodmail)
2. Test it thoroughly in that project
3. Promote to BoB: cdp .claude/commands/my-tool.md
4. 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:

Terminal: (cdb is a terminal-only command for the tooling/symlink dashboard — no slash form; the /dashboard slash command shows PM status, a different view)

# 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:

Terminal:

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

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

Terminal:

cdl agents drupal-expert
cdl agents cloudflare-expert

To verify everything is healthy:

Terminal:

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:

Terminal: (the manifest/seed setup is shell-only; the final dev-up has a slash pair — see below)

# 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 (Terminal entrypoint)
dev-up . --verbose

Slash command: /dev-up brings the dev environment up from inside a Claude Code session — the session-side pair of the dev-up terminal entrypoint.

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:

Slash command: (these are session-only — they need the conversation context, so there is no terminal form)

/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.

See Also

• new-machine-setup.md — Setting up BoB on a fresh machine
• dev-lifecycle.md — Dev environment IaC (server, seeds, test users)
• warp-drive.md — Autonomous development loop
• natural-language-guide.md — BoB terminology reference
• CLAUDE.md — Full architecture and configuration docs