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 bob init, bob link, bob promote, and bob dash status are terminal-only PATH entrypoints (deployed to ~/.claude/bin, #1193) with no slash equivalent; where a step does have both forms — bob provision ↔ /provision, bob dev up ↔ /dev-up — both are shown as a labelled pair.

1. Initializing a New Project

Run bob init (universal items) and bob provision (manifested registry items) in the project you want to connect to BoB:

Terminal:

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

Slash command: /provision runs the bob provision step inside a Claude Code session. (bob init 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 bob init + bob provision refresh materialize them. bob provision status listing [unlinked] items on a fresh clone is that pre-refresh state, not breakage.

bob init is the wiring step — it creates .claude/ and the universal symlinks. bob provision reads provisions/<project>.json from the operator repo — falling back to the legacy BOB_SOURCE/provisions/ copy until 2026-10-31, then to the product’s _default.json (#2270) 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 bob init 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 (owner/company filled from the operator profile, #2269)

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

Safe to Re-run

Running bob init 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: (bob link is a terminal-only command — no slash form)

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

Or grab everything at once:

Terminal:

bob link --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
bob provision reconcile                  # dry run: + would-add (with why) / - would-remove, nothing written
bob provision reconcile --apply          # apply: one-item delta at L2+ fast-paths end-to-end,
                                  #        multi-item delta or L1 opens a review PR
bob provision reconcile --apply --allow-remove   # also drop would-remove items (never by default)

bob provision --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 bob link to link individual items from BoB into your current project:

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

# Link a command
bob link commands start-work

# Link an agent
bob link agents drupal-expert

# Link a hook
bob link hooks check-branch.sh

# See what's available
bob link --list
bob link --list agents

# Link ALL missing global items
bob link --all

What bob link --all Includes

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

What bob link --all Does NOT Include

• Domain expert agents — link individually as needed (bob link 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 bob promote:

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

bob promote .claude/commands/my-command.md
bob promote .claude/agents/my-agent.md
bob promote .claude/hooks/my-hook.sh
bob promote .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: bob promote .claude/commands/my-tool.md
4. Link into other projects: bob link 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 bob dash status to see what’s linked and what’s missing:

Terminal: (bob dash status 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)
bob dash status

# Matrix view: every global item vs every project
bob dash status --matrix

# Detailed check for a specific project
bob dash status --check ~/Sites/my-project

# Just global inventory
bob dash status --global-only

# Just project summaries
bob dash status --projects-only

Reading the Matrix

Global Item                    bodmail      example-co
───────────────────────────── ──────────── ────────────
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 bob promote.

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
bob link --all

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

Terminal:

bob link agents drupal-expert
bob link agents cloudflare-expert

To verify everything is healthy:

Terminal:

bob dash status --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 bob 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)
bob dev up . --verbose

# Later: is it still healthy? (checks only — starts nothing)
bob dev health .

Slash command: /dev-up brings the dev environment up from inside a Claude Code session — the session-side pair of the bob 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 (superuser admin@test.local / admin123 by default; the operator profile may override it once, #2272)
• 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