Project Orchestration Handbook

The encyclopedic guide to running projects with BoB (Big ol’ Brain). For humans and agents.

This handbook is the human-facing how-to. For under-the-hood architecture and internals, see PROJECT-MANAGEMENT-REFERENCE.md. For deep dives on individual subsystems, see the See Also section.

The Big Picture
Quick Start
Setup & Lifecycle
The Product Hierarchy
Dev Environment Lifecycle
Manual Workflow
Autonomous Workflow (Couch Mode)
Parallel Work (cdfork)
Reporting & Continuous Improvement
Skill Glossary
Agent Glossary
Slash Command Glossary
Shell Command Glossary
Hooks Reference
Files & Layout
Troubleshooting
See Also

1. The Big Picture

What BoB is

BoB (Big ol’ Brain) is a global Claude Code tooling framework. Skills, agents, slash commands, hooks, scripts, and templates live in a single source-of-truth git repo and get distributed to every project via deploy + symlink.

When someone says Bob, BoB, big brain, or big ol’ brain, they mean this framework. See bob-identity.md for the full identity definition.

Source of truth → runtime

BOB_SOURCE (~/projects/bigbrain)        <- Source of truth (git repo)
    │
    │   scripts/deploy.sh   (sync)
    ▼
BOB_HOME (~/.claude/)                   <- Runtime (Claude Code reads here)
    │
    │   cdi  (per-project init: symlinks)
    ▼
.claude/  (in each project)             <- Project-level entry points

Layer	Location	Purpose
BOB_SOURCE	`~/projects/bigbrain`	Edit here. One git repo. Single source of truth.
BOB_HOME	`~/.claude`	Where Claude Code reads at runtime. Synced from src.
Project	`<repo>/.claude/`	Per-project symlinks to BOB_HOME items + local items

The Prime Directive

Everything BoB manages must be declarative, version-controlled, reproducible, idempotent, and observable — with every piece of state owned by exactly one source of truth.

Full text and approved patterns: prime-directive.md.

Work tracking lives in GitHub Issues

Every project’s vision lives in docs/vision.md. Everything below the vision lives in GitHub Issues — capabilities, requirements, bugs, decisions, lessons, session summaries, and TODOs. There are no REQ-*.md, BUG-*.md, SOL-*.md, or PM index files. If someone tries to create one, stop them.

Component types at a glance

Type	Source path	Loading model
Universal skill	`BOB_SOURCE/skills/`	Auto-loaded everywhere by Claude Code
Universal command	`BOB_SOURCE/commands/`	Symlinked into each project’s `.claude/commands/` by `cdi`
Universal agent	`BOB_SOURCE/agents/`	Symlinked into each project’s `.claude/agents/` by `cdi`
Universal runbook	`BOB_SOURCE/runbooks/`	Referenced by absolute path; not symlinked
Registry skill	`BOB_SOURCE/registry/skills/`	Provisioned per-project via manifest (`provisions/<project>.json`)
Registry command	`BOB_SOURCE/registry/commands/`	Same — opt-in per project
Registry agent	`BOB_SOURCE/registry/agents/`	Same — opt-in per project
Hook	`BOB_SOURCE/hooks/`	Wired up in `~/.claude/settings.json` by event
Script	`BOB_SOURCE/scripts/`	Invoked by absolute path from skills, commands, hooks, or shell
Template	`BOB_SOURCE/templates/`	Copied (not symlinked) into projects, then customized
Provision manifest	`BOB_SOURCE/provisions/`	Declares which registry items a project gets

2. Quick Start

2A. Brand-new project

cd ~/Sites/my-project           # Project must be a git repo
 
cdi                             # Wire up .claude/ symlinks
cdprov                          # Provision skills/commands/agents from manifest
claude                          # Start Claude Code
 
# Inside Claude:
/vision                         # Living doc: why, who, where (docs/vision.md)
/capability                     # First feature spec (GitHub Issue, label: cap)
/requirement                    # Acceptance criteria (GitHub Issue, label: req)
# Approve a requirement: add the `approved` label

2B. Existing project

cd ~/Sites/my-project
cdb                             # Sanity-check tooling status
cdprov --status                 # See what's provisioned
claude

Inside Claude:

/what-next                      # Tells you the next sensible work item

2C. Couch mode (autonomous)

claude -a3 -rdb                 # Level 3 + Telegram bridge

Inside Claude:

/warp-drive                     # Picks up next approved requirement and goes

Phone nearby. Decisions land in Telegram. /stop-warp-drive to abort cleanly.

2D. Parallel work clusters

cdfork fork feat/a feat/b feat/c        # 3 worktrees, 3 tmux windows, 3 warp-drives
cdfork fork --from-issues 4              # Auto-pick 4 approved requirements
cdfork status                            # See every active worktree
cdfork drop feat/a                       # Tear down one cleanly

3. Setup & Lifecycle

3.1 First-time install on a machine

git clone git@github.com:paulirv/bigbrain.git ~/projects/bigbrain
cd ~/projects/bigbrain
 
scripts/bob-install.sh           # Adds BoB shell wrapper + aliases to your shell rc
source ~/.zshrc                  # (or ~/.bashrc) — picks up wrapper + aliases
 
scripts/deploy.sh --first-run    # Sync source → ~/.claude/ for the first time

What bob-install.sh adds to your shell rc:

claude shell wrapper — intercepts -a1 / -a2 / -a3 (automation level) and -rdb (Telegram), then exec’s the real claude CLI.
Aliases: cdprov, cdr, cdfork.

3.2 Deploying changes from BOB_SOURCE → BOB_HOME

deploy.sh is the only sanctioned way to update ~/.claude/. Direct edits to ~/.claude/ are anti-pattern — you’d lose them on the next deploy.

scripts/deploy.sh --dry-run      # Preview what would change
scripts/deploy.sh                # Apply
scripts/deploy.sh --first-run    # First-deploy mode (cleans up legacy .git/ in BOB_HOME)
scripts/deploy.sh --force        # Skip confirmation prompts

Machine-specific files are protected and never overwritten:

~/.claude/settings.json
~/.claude/settings.local.json
~/.claude/CLAUDE.local.md

3.3 Per-project initialization (`cdi`)

cd <project>
cdi                              # Idempotent — safe to re-run

Creates <project>/.claude/ with symlinks to:

commands/ from ~/.claude/commands/
agents/ from ~/.claude/agents/
hooks/ referenced in settings.json
Templates (copied, not symlinked)

Skills are not symlinked — they’re auto-loaded globally from ~/.claude/skills/.

3.4 Provisioning registry items (`cdprov` + `/provision`)

Each project has a manifest at BOB_SOURCE/provisions/<project>.json declaring which registry skills, commands, and agents it uses (in addition to the universal set).

cdprov                           # Apply manifest — create symlinks to match
cdprov --status                  # What's in manifest vs. what's actually linked
cdprov --diff                    # Dry run — show planned changes
cdprov --refresh                 # Re-sync symlinks (drop stale, add missing)

Inside Claude (/provision):

/provision status
/provision add skill cloudflare-dev
/provision add command deploy
/provision add agent code-reviewer
/provision remove skill seo-auditing
/provision diff
/provision init                  # Bootstrap a manifest for a new project

Manifest shape (provisions/<project>.json):

{
  "_meta": { "project": "myproj", "stack": ["cloudflare-workers", "d1"] },
  "skills":   ["cloudflare-dev", "d1-expert"],
  "commands": ["deploy", "research"],
  "agents":   ["code-reviewer", "code-debugger"],
  "runbooks": []
}

Validate against schemas/manifest.schema.json.

3.5 Updating BoB

cd ~/projects/bigbrain
git pull                         # Get upstream changes
scripts/deploy.sh --dry-run      # Always preview first
scripts/deploy.sh                # Apply
make check                       # Verify nothing broke

3.6 Local overrides (gitignored)

<project>/.claude/CLAUDE.local.md — project notes that don’t get checked in.
~/.claude/CLAUDE.local.md — global notes that don’t sync.

These are loaded into context but never deployed or committed.

3.7 Verification (Makefile)

make is the IaC verification layer. Run any of these from BOB_SOURCE:

Target	What it checks
`make check`	All of: deps + schemas + symlinks + hooks + provisions
`make check-deps`	`node`, `jq`, `git`, `make` versions
`make check-schemas`	All `*.json` configs against JSON Schema definitions
`make check-symlinks`	Every symlink across registered projects resolves
`make check-hooks`	Every hook script in `settings.json` exists and is executable
`make check-provisions`	Each project’s actual symlink state matches its manifest
`make test`	Schema validator unit tests + warp-drive state machine tests + integration
`make ci`	`check` + `test` (what GitHub Actions runs)
`make doctor`	Diagnostic dump for triaging weirdness
`make help`	Print all targets

Current test counts (run make test for the live numbers):

Schema validator: 34 unit tests
Warp-drive state machine: 99 transition tests
Integration tests for all check scripts: 13

make ci is what GitHub Actions runs on push and PR to master. CI skips check-symlinks and check-provisions because those scan local project directories that don’t exist on the runner.

Doc-link sweep: scripts/checks/check-doc-links.sh validates every relative .md/.txt link across README.md, CLAUDE.md, and docs/**/*.md (excluding docs/archive/**, which is frozen historical content).

4. The Product Hierarchy

Vision & Strategy (docs/vision.md)        /vision
└── Capability  (GitHub Issue, label: cap) /capability
    └── Requirement (GitHub Issue, req)    /requirement
        └── Warp-drive chunks              automatic — individual commits

Level	Format	Command	Contains
Vision	`docs/vision.md`	`/vision`	Why, who, where, principles, non-goals, roadmap. Living doc.
Capability	GitHub Issue (`cap`)	`/capability`	User stories, success metrics, requirements checklist
Requirement	GitHub Issue (`req`)	`/requirement`	Description, acceptance criteria (checkboxes), priority, notes
Bug	GitHub Issue (`bug`)	`gh issue create --label bug`	Bug reports
TODO	GitHub Issue (`todo`)	auto-created by warp-drive timeout	Human action items

Labels

Label	Meaning
`cap`	Capability
`req`	Requirement
`bug`	Bug report
`todo`	Human action item
`approved`	Ready to work — picked up by `/warp-drive`
`in-progress`	Being worked on
`blocked`	Waiting on something
`implemented`	Code done, awaiting verification
`serial-only`	Excluded from `cdfork --from-issues` (pinch points)
`decision`	Architecture decision (created by `/journal decision`)
`lesson`	Lesson learned (created by `/journal lesson`)
`session-summary`	Session summary (created by `/session-summary`)
`p1-critical` / `p2-high` / `p3-medium` / `p4-low`	Priority

The approval workflow

/capability creates an issue (label cap).
Break it into requirements with /requirement (label req, with Part of #NN linking back to the capability).
Add approved when a requirement is ready to work.
/warp-drive picks the highest-priority req + approved issue not in progress.
When done, warp-drive flags it implemented and moves on.

What NOT to create

The following filename patterns are forbidden. They predate the GitHub Issues migration. Do not regenerate them:

REQ-*.md, SOL-*.md, BUG-*.md, RISK-*.md, INC-*.md, CR-*.md, UXR-*.md, STATUS-*.md
REQUIREMENTS-INDEX.md, SOLUTIONS-INDEX.md, backlog.md, traceability-matrix.md
.claude/project-management/, .claude/requirements/, .claude/journal/decisions/ (or lessons/, sessions/)

If a tool emits any of these, treat it as a bug and fix the tool.

Pinch points (mark `serial-only`)

Some work cannot be parallelized. Mark these requirements serial-only so cdfork --from-issues skips them:

Config / settings sync
Lockfile bumps
DB migrations
Compiled-asset rebuilds
Deploy steps

5. Dev Environment Lifecycle

Every project can declare its dev environment in dev.json. The /dev-up command (and bin/dev-up from a terminal) reads it and brings the environment to a fully testable state — server, migrations, seed data, test users, health check.

Full reference: dev-lifecycle.md.

5.1 The `dev.json` manifest

Lives at the project root. Sample at templates/dev.json. Schema at schemas/dev.schema.json.

{
  "server":     { "command": "npm run dev", "port": 5173, "health": "/api/health" },
  "migrations": { "command": "npm run migrate:dev", "auto_run": true },
  "seed":       { "directory": "seed/", "runner": "node", "order": "alphabetical" },
  "auth":       { "adapter": "d1", "users_file": "seed/users.json" },
  "access":     { "localhost": "http://localhost:5173" }
}

5.2 `/dev-up` and friends

Command	Purpose
`/dev-up`	Full lifecycle (server + migrations + seed + users + health)
`/dev-up --check`	Health probe only
`/dev-up --skip-seed / --skip-users / --skip-server`	Partial run
`/dev-up --regen-seed`	Discard cached seed and regenerate
`bin/dev-up`	Same, from a regular terminal
`bin/dev-health`	Shortcut for `dev-up --check`

5.3 Seed convention

Seed scripts live in seed/ — alphabetical execution order.
Seed data must cover all lifecycle states the domain defines (not just fresh records).
New features include their seed updates in the same commit.
Seed coverage gate: scripts/dev-lifecycle/check-seed-coverage.sh.

5.4 Standardized test users

seed/users.json declares test users, provisioned via pluggable auth adapters.

Adapter	Use when…
`d1`	Cloudflare D1 (SQLite)
`sqlite`	Local SQLite
`supabase`	Supabase auth
`script`	Custom provisioning script
`custom`	Inline command in `provision_command`

The superuser is consistent across every project: admin@test.local / admin123.

5.5 Integration with warp-drive

When dev.json exists, warp-drive automatically:

Calls dev-up before the first chunk
Verifies health between chunks
Auto-recovers on dev failure
Treats dev health failure as a blockable event

6. Manual Workflow

The day-to-day cycle when you’re at the keyboard.

/start-work          → branch off
… code …
/commit              → create a commit
/journal             → optional: capture a decision/lesson
/pr                  → optional: open a PR
/finish-work         → merge + cleanup
/session-summary     → close the session as a GitHub Issue

`/start-work`

`/commit`

Stages and commits with a generated message. The commit skill enforces:

No commits to master/main (use /start-work first)
Pre-commit hooks run (don’t bypass with --no-verify)
Commit message reflects the why, not just the what

`/pr`

Pushes branch and opens a PR with requirement traceability — links back to the GitHub Issue(s) the branch addresses.

Subactions: /pr create, /pr template, /pr link.

`/finish-work`

Merges current branch to master (Level 3) or opens a PR (Level 2), runs cleanup, deletes the local branch.

`/journal`

Create a journal entry as a GitHub Issue. Three types:

Subcommand	Label
`/journal decision <name>`	`decision`
`/journal lesson <name>`	`lesson`
`/journal session <name>`	`session-summary`

`/session-summary`

End-of-session writeup as a GitHub Issue. Captures what shipped, what’s next, decisions, lessons.

Built-in Claude Code commands you’ll use alongside

Command	Purpose
`/review`	Code review of pending changes
`/security-review`	Security review of pending changes
`/init`	Initialize a CLAUDE.md from existing codebase
`/clean_gone`	Clean up local branches that are gone on the remote
`/commit-push-pr`	Commit, push, and open PR in one go (built-in plugin)
`/loop`	Run a slash command on a recurring interval
`/schedule`	Cron-style scheduling for recurring agents

7. Autonomous Workflow (Couch Mode)

7.1 Automation levels

Level	Name	Start with	Default behavior
1	Supervised	`claude` / `-a1`	Confirm every tool that can change state
2	Trusted Dev	`claude -a2`	Auto-approve safe ops; PRs instead of direct merges
3	Autonomous	`claude -a3`	Minimize prompts; merge directly to master

Switch mid-session with /automation level <N>. See profiles/{supervised,trusted,autonomous}.json for the exact permission profiles.

7.2 `/warp-drive` — the autonomous development loop

This replaces /auto-loop. /auto-loop is legacy and will be removed.

/warp-drive               # Discover next approved requirement, work it
/warp-drive 42            # Work on issue #42 specifically
/stop-warp-drive          # Graceful stop

What it does each cycle:

Discover work (gh issue list --label approved --label req)
Plan implementation
Code (chunked: max 3 acceptance criteria per commit)
Test
Update issue (flip ACs, add labels)
Commit + journal
Merge (L3) or open PR (L2)
Ask “continue?” → loop or stop

Full deep-dive: warp-drive-guide.md.

7.3 The `warp` CLI (terminal observation)

Run from any shell — no Claude session needed:

warp status               # Phase, current chunk, recent activity
warp stop                 # Abort the loop from outside
warp help                 # All commands

7.4 `/what-next` — discover work without committing

Reads project state and proposes the next sensible work item. Use it when you’re not sure where to pick up.

/what-next

7.5 `/stop-warp-drive`

Inside Claude — graceful stop with proper cleanup. Don’t kill the session with Ctrl-C; let the skill flush state cleanly.

7.6 Remote Decision Bridge (`/rdb`)

When you’re away from the keyboard, RDB routes all decisions to Telegram via ask_remote/notify_remote.

/rdb on                   # Decisions go to Telegram
/rdb off                  # Back to terminal prompts
/rdb status               # Current state

Going AFK? Saying “I’m stepping away” is treated as /rdb on automatically.

7.7 Couch-mode checklist

claude -a3 -rdb (or -a2 -rdb)
/warp-drive started
Phone has Telegram open
Laptop plugged in and won’t sleep
At least one req + approved issue exists

7.8 Error handling

Warp-drive does 3 strikes on failed fixes before escalating.
Failures escalate to a Telegram prompt (RDB) or terminal (no RDB).
“Type ‘skip’” or “do whatever you think is best” are valid responses.
Repeated escalations create a todo-labeled issue for human follow-up.

8. Parallel Work (cdfork)

cdfork fans out N parallel /warp-drive sessions, one per branch, in isolated git worktrees + tmux windows. Tmux + git are the state — no daemon, no DB. If the orchestrator dies, your worktrees and commits survive.

Full reference: cdfork-guide.md.

8.1 Subcommands

Command	Purpose
`cdfork fork <branch>...`	Spawn one warp-drive per named branch
`cdfork fork --from-issues [N]`	Auto-pick N approved requirements; fan out
`cdfork status [--json]`	List worktrees + tmux + warp-drive state
`cdfork drop <branch> [--force]`	Tear down a worktree + tmux window
`cdfork drop --all [--force]`	Tear down every cdfork worktree for this repo
`cdfork pair --contract <p> --backend <r> --frontend <r> --branch <n>`	Cross-repo contract-driven mode
`cdfork-pair ...`	Standalone shape of `cdfork pair`
`cdfork help`	Show command summary

8.2 Worktree layout

For a repo at /path/to/<repo>/:

/path/to/<repo>.worktrees/<branch>/

Sibling, not nested — keeps Composer, Bundler, npm, etc. from getting confused.

8.3 When to use cdfork vs. a single warp-drive

Use cdfork when…	Use single `/warp-drive` when…
Multiple independent issues are `approved`	Single issue or tightly-coupled work
Work clusters don’t touch the same files	Issues touch shared config/migrations
You want to maximize throughput while AFK	Linear progression matters
You have CPU + RAM to spare	Single-threaded resource constraint

8.4 What `cdfork --from-issues` actually does

Runs gh issue list --label approved --label req (excluding serial-only)
Picks the top N (default 3) by priority + age
Derives a branch name per issue (e.g. req-42-add-auth)
Spawns one worktree + tmux window + warp-drive per branch

8.5 `cdfork pair` (cross-repo)

Designed for headless splits where backend + frontend share a contract. Anchor use case: nanawall.com Drupal-headless migration.

cdfork pair \
  --contract  ~/contracts/api-spec.yaml \
  --backend   ~/Sites/nanawall-api \
  --frontend  ~/Sites/nanawall-web \
  --branch    feat/product-listing

Two worktrees, two tmux windows, both warp-drives anchored to the same contract path.

8.6 Prerequisites

Tool	Why	Install
`git`	Worktrees	`brew install git`
`tmux`	Window management	`brew install tmux` (NOT installed by default)
`claude`	Spawned in each window	Claude Code CLI
`gh`	`--from-issues`	`brew install gh`
`jq`	Status JSON, issue filtering	`brew install jq`

Preflight runs before any worktree is touched and fails fast on missing deps.

9. Reporting & Continuous Improvement

9.1 Per-event reporting (GitHub Issues)

What	Command	Label
Architecture decision	`/journal decision <name>`	`decision`
Lesson learned	`/journal lesson <name>`	`lesson`
Session writeup	`/session-summary` or `/journal session <name>`	`session-summary`
Bug report	`gh issue create --label bug`	`bug`
Human action item	auto-created by warp-drive timeout	`todo`

9.2 `/rebob` — full state reconciliation

Think git fsck for project management. Examines ground truth (git log, file system, codebase) and reconciles all PM artifacts against it.

/rebob

Use it after long absences, before/after major refactors, or when state feels off.

9.3 `/trace-mining` — outer improvement loop

Analyzes past session journals to extract failure patterns, identify recurring harness gaps, and propose targeted improvements.

/trace-mining

Output feeds back into BoB — surfacing missing skills, broken hooks, or workflow friction. Pair with gh issue list --label lesson to mine accumulated learnings.

9.4 Registry-only continuous-improvement commands

Provision and use as needed (not universal — opt-in per project):

/research — Manage research projects (questions, sources, findings, decisions). Also available as a universal skill (research).
/retrospective — Standard / start-stop-continue / 4Ls retros.
/standup — Daily standup format.
/status — Status reports at quick / weekly / monthly cadence.

10. Skill Glossary

Skills give Claude specialized knowledge or workflow. Universal skills are auto-loaded everywhere; registry skills are opt-in per project.

10.1 Universal skills (`BOB_SOURCE/skills/`)

Skill	Purpose
`agent-builder`	Create and maintain agent definitions
`automation`	Switch automation level (L1/L2/L3) for current project
`code-expert`	TypeScript / SvelteKit / Cloudflare Workers / Hono / D1 / R2 / Vitest
`code-simplifying`	Reduce complexity, dedupe, refactor for clarity
`commit`	Git commit workflow (used by `/commit`)
`explaining-code`	Visual diagrams + analogies for code explanations
`pr`	Pull request workflow (used by `/pr`)
`rdb`	Toggle Remote Decision Bridge on/off
`research`	Generic research project management
`skill-creator`	Guide for creating new skills
`software-project-manager`	Strategic PM thinking (modern software delivery practices)
`stop-warp-drive`	Graceful warp-drive stop
`timelord`	Temporal accuracy guardian for documentation
`doc-audit`	Read-only documentation drift audit (#151)
`doc-sync`	Mechanical documentation drift fixes (#151)
`docs-site`	Provision and operate a Quartz 4 docs site (#153). Auto-deploy on doc changes via Cloudflare Pages (#155); see dev-lifecycle.md.

10.2 Registry skills (`BOB_SOURCE/registry/skills/`)

Provision per-project via cdprov or /provision add skill <name>.

Code & dev

cloudflare-dev — Cloudflare Workers development
d1-expert — Cloudflare D1 (SQLite) expertise
drupal-dev, drush — Drupal-specific
wordpress-dev — WordPress-specific
strapi-dev — Strapi headless
mcp-builder — Build Model Context Protocol servers

API & integration

api-designing — API design
kalshi-api — Kalshi-specific

Frontend & UX

frontend-design — Distinctive, production-grade UI
responsive-design — Responsive layout patterns
accessibility-auditing — WCAG 2.1 AA
ux-designing — UX design
visual-design — Visual design
visual-explainer — Visual explanations
web-artifacts-builder — Web component / page artifacts
theme-factory — Themes
design-systems — Design systems work
brand-guidelines — Brand application
information-architecting — IA

Audit & QA

performance-auditing — Web performance
seo-auditing — SEO audits
webapp-testing — Playwright-driven testing
user-research — User research projects

Deploy

deploy-cloudflare — Atomic Cloudflare Pages/Workers deploys (provides /deploy)

Document handling

docx, pdf, pptx, xlsx — Office document handling
image-processing — Image manipulation
token-report — Token usage reporting

11. Agent Glossary

Agents are specialized subagents the main Claude session can launch via the Task tool.

11.1 Universal agents (`BOB_SOURCE/agents/`)

Agent	When to use
`lessons-extractor`	After significant work — extract & document lessons learned
`project-historian`	Synthesize project history; answer “why did we…” questions
`requirements-analyst`	Capture or refine requirements; ensure testable acceptance criteria
`solution-architect`	Design solutions, compare alternatives, assess trade-offs

11.2 Registry agents (`BOB_SOURCE/registry/agents/`)

Code & architecture

code-expert — Deep TypeScript / Cloudflare-stack analysis
code-debugger — Bug diagnosis
code-reviewer — Code review
lead-dev-architect — Strategic technical guidance
unit-test-generator — Generate unit tests

Domain-specific

drupal-expert — Drupal 9/10
sentry-integration-expert — Sentry SDK integration

Audit

accessibility-auditor — WCAG 2.1 AA audits
seo-performance-auditor — SEO + performance
ahrefs-expert — Ahrefs SEO tools

ux-architect — UX design

PM-flavored

project-manager — Project planning / coordination
qa-strategist — Test strategy / DoD
risk-manager — Risk identification / mitigation
release-engineer — Deployment / release management
stakeholder-liaison — Stakeholder communication

12. Slash Command Glossary

By topic. Universal commands ship with every project. Registry commands need cdprov add per-project. Built-in commands ship with Claude Code itself.

12.1 Foundation (universal)

Command	Purpose
`/vision`	Create or update `docs/vision.md` (living strategy doc)
`/capability`	Create a capability as a GitHub Issue (label `cap`)
`/requirement`	Create a requirement as a GitHub Issue (label `req`)

12.2 Discovery (universal)

Command	Purpose
`/what-next`	Analyze project state, propose next work item

12.3 Manual development (universal)

Command	Purpose
`/start-work`	Create a feature/fix branch
`/commit`	Create a git commit
`/pr`	Open a PR with requirement traceability
`/finish-work`	Merge to master / open PR + cleanup
`/session-summary`	Close session as a GitHub Issue
`/journal`	Create decision/lesson/session issue

12.4 Autonomous (universal)

Command	Purpose
`/warp-drive [issue]`	The autonomous development loop
`/stop-warp-drive`	Graceful stop
`/auto-loop`	Legacy — predecessor of `/warp-drive`; will be removed

12.5 Parallel (universal)

Command	Purpose
`/cdfork`	Multi-agent worktree orchestration (subcommands match `cdfork` CLI)

12.6 Dev environment (universal)

Command	Purpose
`/dev-up`	Bring dev env to fully testable state

12.7 Maintenance (universal)

Command	Purpose
`/provision`	Manage provisioning (status / add / remove / refresh / diff / init)
`/rebob`	Full project state reconciliation
`/trace-mining`	Mine session journals for harness improvements

12.8 Skill toggles (universal)

Command	Purpose
`/automation`	Switch automation level
`/rdb`	Toggle Remote Decision Bridge

12.9 Registry / opt-in commands

Provision before use (cdprov add command <name>):

/research — Research project management
/deploy — Cloudflare atomic deploy (from deploy-cloudflare skill)
/release, /review-lessons, /ux-review — As provisioned

Older registry commands (/spec, /backlog, /risk, /bug, /incident, /change, /status, /dashboard, /standup, /retrospective, /solution) predate the GitHub-Issues hierarchy and are scheduled for removal. Do not use them on new work. Use /capability + /requirement + GitHub Issues with appropriate labels instead.

12.10 Built-in Claude Code & plugin commands

Always available, not BoB-specific:

Command	Purpose
`/init`	Initialize a CLAUDE.md from existing codebase
`/review`	Review pending changes
`/security-review`	Security review of pending changes
`/loop`	Run a slash command on a recurring interval
`/schedule`	Cron-style scheduling for recurring agents
`/clean_gone`	Clean up local branches that are gone on the remote (commit-commands plugin)
`/commit-push-pr`	Commit, push, open PR (commit-commands plugin)
`/help`	Built-in Claude Code help

Plugin command families also available: sentry:*, frontend-design:*, commit-commands:*. List them with /help inside Claude.

13. Shell Command Glossary

Every command runnable from a regular terminal.

13.1 BoB CLI aliases (set up by `bob-install.sh`)

Alias	Backed by	Purpose
`cdi`	`BOB_SOURCE/claude-init.sh`	Initialize project with BoB tooling
`cdb`	`BOB_SOURCE/claude-dashboard.sh`	Dashboard — tooling + symlink status
`cdp`	`BOB_SOURCE/claude-promote.sh`	Promote a local item to global registry
`cdl`	`BOB_SOURCE/claude-link.sh`	Link a global item into project
`cdprov`	`BOB_SOURCE/scripts/provision.sh`	Provision project from manifest
`cdr`	`BOB_SOURCE/scripts/lib/cdr.sh`	Claude Disaster Recovery — `cdr status / check / recover / reprovision / reset` (see backup-recovery.md)
`cdfork`	`BOB_SOURCE/bin/cdfork`	Parallel worktree orchestration

13.2 `claude` shell wrapper

The bob-install.sh wrapper intercepts custom flags before exec’ing the real claude CLI:

Flag	Effect
`-a1`	Set automation Level 1 (Supervised)
`-a2`	Set automation Level 2 (Trusted Dev)
`-a3`	Set automation Level 3 (Autonomous)
`-rdb`	Enable Remote Decision Bridge (Telegram)

Combine: claude -a3 -rdb is the canonical “couch mode” launch.

13.3 BoB scripts (`BOB_SOURCE/scripts/` and `bin/`)

Path	Purpose
`scripts/bob-install.sh`	Set up shell wrapper + aliases (idempotent)
`scripts/deploy.sh`	Sync BOB_SOURCE → BOB_HOME (`--dry-run`, `--first-run`, `--force`)
`scripts/provision.sh`	Provision project from manifest (called by `cdprov`)
`scripts/sync-requirements-index.js`	Legacy — predates GitHub Issues
`scripts/migrate-pm-to-issues.sh`	One-shot migration: PM markdown → GitHub Issues
`scripts/migrate-to-registry.sh`	One-shot migration to registry/
`scripts/cleanup-legacy-pm.sh`	Remove forbidden PM files
`scripts/dashboard-server.js`	Local dashboard server (`cds`)
`scripts/mission-control-server.js`	Multi-project mission-control server
`scripts/lib/preflight-check.sh`	Common preflight (deps, tools)
`scripts/lib/safe-json-write.sh`	Atomic JSON write helper
`scripts/lib/settings-write.sh`	Safe settings.json mutation
`scripts/checks/*.sh`	`make check-*` targets
`scripts/warp-drive/state-machine.js`	Warp-drive state engine
`scripts/cdfork/{fork,status,drop,pair,from-issues}.sh`	cdfork subcommand implementations
`scripts/dev-lifecycle/{dev-up,health-check,provision-users,seed-discover,seed-generate,check-seed-coverage}.sh`	Dev env IaC
`scripts/rebob/*.js`	`/rebob` engine
`scripts/cascade-engine/*.js`	Cascade rule engine
`scripts/autoloop/state-machine.js`	Legacy auto-loop state engine

13.4 `bin/` entrypoints (intended for direct PATH use)

Bin	Purpose
`bin/warp`	Human control plane for warp-drive (`warp status`, `warp stop`)
`bin/cdfork`	Parallel worktree orchestration (also exposed as `cdfork` alias)
`bin/cdfork-pair`	Cross-repo cdfork pair (standalone shape of `cdfork pair`)
`bin/dev-up`	Dev env lifecycle from a regular terminal
`bin/dev-health`	Shortcut for `dev-up --check`

13.5 Makefile targets

Run from BOB_SOURCE. See make help for the full list.

Verification: check, check-deps, check-schemas, check-symlinks, check-hooks, check-provisions Testing: test, test-checks, test-schemas, test-warp-drive Combined: ci (= check + test), doctor (diagnostic dump)

14. Hooks Reference

Hooks are shell scripts wired into Claude Code events via ~/.claude/settings.json. They run automatically at the right moment — never invoke them manually.

Hooks receive ALL data via stdin as JSON. There are no magic variable substitutions.

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

Template: templates/hooks/command-hook.sh. Requires jq.

14.1 Hooks by event

Event	Hook	Purpose
SessionStart	`temporal-context.sh`	Inject current date/time so Claude doesn’t drift
SessionStart	`autoloop-inject.sh` / `warp-drive-inject.sh`	Restore loop state on session resume
PreToolUse	`strip-ai-boilerplate.sh`	Strip generic AI prose from outgoing edits
PreToolUse	`check-branch.sh`	Block writes on `master`/`main`
PreToolUse	`session-branch-guard.sh`	Guard against committing to wrong branch
PreToolUse	`rdb-enforce-ask-remote.sh`	When `_rdb.enabled`, force `ask_remote` over `AskUserQuestion`
PreToolUse	`autoloop-gate.sh` / `warp-drive-gate.sh`	Block tool calls outside the current loop phase
PreToolUse	`validate-commit-message.sh`	Reject commits with generic / AI-boilerplate messages
PreToolUse	`validate-pr-requirements.sh`	PR must reference a requirement issue
PreToolUse	`validate-requirement-refs.sh`	Requirement IDs in commit messages must resolve
PreToolUse	`pre-release-checklist.sh`	Run before release commands
PreToolUse	`dev-auto-start.sh`	Auto-start dev server when project requires it
PostToolUse	`update-project-indexes.sh`	Regenerate any local indexes after edits
PostToolUse	`update-traceability-on-commit.sh`	Update traceability after commits
PostToolUse	`requirements-sync-reminder.sh`	Nudge to sync requirements index
PostToolUse	`risk-review-reminder.sh`	Nudge to review risks
PostToolUse	`warp-drive-edit-tracker.sh`	Track edits during a warp-drive chunk
PostToolUse	`warp-drive-commit-detector.sh`	Detect commits and advance the state machine
PostToolUse	`warp-drive-docs-detector.sh`	Detect doc changes and route to journal
Stop	`autoloop-stop.sh` / `warp-drive-stop.sh`	Persist state on session stop
Stop	`warp-drive-pre-exit.sh`	Cleanup before exit
Stop	`session-summary-reminder.sh`	Remind to capture session summary
Stop	`stop-notify-rdb.sh`	Notify Telegram when warp-drive stops

(Exact wiring lives in ~/.claude/settings.json. Use make check-hooks to verify all hook scripts exist and are executable.)

15. Files & Layout

15.1 BOB_SOURCE structure

BOB_SOURCE/
├── skills/              # Universal skills (auto-loaded)
├── commands/            # Universal slash commands
├── agents/              # Universal subagents
├── runbooks/            # Universal runbooks
├── registry/
│   ├── skills/          # Opt-in skills
│   ├── commands/        # Opt-in commands
│   ├── agents/          # Opt-in agents
│   └── runbooks/        # Opt-in runbooks
├── provisions/          # Per-project manifests (one JSON per project)
├── hooks/               # All hooks; wired in settings.json
├── scripts/             # CLI scripts, helpers, engines
├── bin/                 # PATH-friendly entrypoints
├── templates/           # Copied (not symlinked) into projects
├── schemas/             # JSON Schema for manifest, projects, settings
├── profiles/            # Permission profiles per automation level
├── docs/                # Guides (this file lives here)
├── tests/               # `make test` targets
├── claude-init.sh       # cdi
├── claude-dashboard.sh  # cdb
├── claude-promote.sh    # cdp
├── claude-link.sh       # cdl
├── settings.json        # Default settings shipped to BOB_HOME
├── CLAUDE.md            # Default project instructions
├── README.md
├── Makefile
└── bob-identity.md

15.2 Project-level structure

A typical project has:

my-project/
├── .claude/                # Created by cdi — symlinks into BOB_HOME
│   ├── commands/           # Symlinks
│   ├── agents/             # Symlinks
│   ├── settings.json       # Project-specific overrides (optional)
│   └── settings.local.json # Machine-specific, gitignored
├── CLAUDE.md               # Project instructions (committed)
├── CLAUDE.local.md         # Local notes (gitignored)
├── docs/
│   └── vision.md           # The living vision doc
├── dev.json                # Dev environment manifest
├── seed/                   # Seed scripts + users.json
└── ...

15.3 Forbidden patterns

Do not create these — they predate the GitHub Issues migration:

.claude/project-management/         ✗
.claude/requirements/               ✗
.claude/journal/decisions/          ✗  (use /journal decision)
.claude/journal/lessons/            ✗  (use /journal lesson)
.claude/journal/sessions/           ✗  (use /journal session)
REQ-*.md SOL-*.md BUG-*.md          ✗
RISK-*.md INC-*.md CR-*.md          ✗
UXR-*.md STATUS-*.md                ✗
REQUIREMENTS-INDEX.md               ✗
SOLUTIONS-INDEX.md                  ✗
backlog.md                          ✗
traceability-matrix.md              ✗

15.4 BOB_HOME (`~/.claude/`) — runtime only

Synced from BOB_SOURCE by deploy.sh. Don’t edit directly. Files protected from overwrite:

~/.claude/settings.json
~/.claude/settings.local.json
~/.claude/CLAUDE.local.md

16. Troubleshooting

16.1 Diagnostic commands

Symptom	Run this
”Is BoB healthy?”	`make check`
”Are my project’s symlinks ok?”	`cdb` then `cdb --check <project>`
”What is provisioned in this project?”	`cdprov --status`
”Does the manifest match reality?”	`cdprov --diff`
”Why is warp-drive stuck?”	`warp status`
”Is the dev env healthy?”	`bin/dev-health` or `/dev-up --check`
”Hook script missing?”	`make check-hooks`
”JSON config invalid?”	`make check-schemas`
”Stale state across the system?”	`/rebob`
”Lessons accumulating? Patterns?”	`/trace-mining`

16.2 State files

File	Owner	Notes
`<project>/.warp-drive-state.json`	warp-drive engine	Current chunk, phase, history
`<project>/.autoloop-state.json`	(legacy) auto-loop	Will be removed
`~/.claude/settings.local.json`	machine	`_rdb.enabled` lives here

16.3 Common problems

Problem	Fix
Hooks aren’t firing	`make check-hooks`; verify `~/.claude/settings.json` references existing scripts
Symlinks point to nowhere	`cdprov --refresh` or rerun `cdi`
Warp-drive won’t start	Check `warp status`; ensure at least one `req` + `approved` issue exists
Telegram silent (RDB on)	Check `~/.claude/settings.local.json` for `_rdb.enabled: true`; type something in terminal
`/auto-loop` did weird things	Stop using `/auto-loop` — switch to `/warp-drive`
Got prompt to create `REQ-NNNN.md`	Stop. That’s a regression. File a bug — work tracking is GitHub Issues
Tests stuck in fix loop	Warp-drive 3-strikes-out automatically; let it escalate
`cdfork` worktree won’t drop	`cdfork drop <branch> --force`; if that fails, manually `git worktree prune`
Deploy refuses to overwrite something	That’s by design — `settings.json`, `settings.local.json`, `CLAUDE.local.md` are protected

17. See Also

bob-identity.md — What “BoB” means
prime-directive.md — IaC principles, approved patterns, anti-patterns
warp-drive-guide.md — Full warp-drive deep-dive
cdfork-guide.md — Full cdfork deep-dive
dev-lifecycle.md — Full dev env lifecycle reference (also covers the docs-site lifecycle, #153)
orchestrator-guide.md — Registry metadata contract, recommendation engine, interview question bank (#157 family)
vision.md — BoB’s own vision document
PROJECT-MANAGEMENT-REFERENCE.md — Under-the-hood architecture (note: predates GitHub Issues migration; due for its own audit)
branch-config.md — Branch detection / configuration
automation-behavior.md — How automation levels behave
backup-recovery.md — Backup & recovery
new-machine-setup.md — Setup on a fresh machine
verification-system.md — make check deep-dive
token-monitoring.md — Token usage observability
pm-conventions.md — PM conventions (redirect stub; original archived 2026-05-07)
doc-audit-2026-05-07.md — Documentation audit methodology and gap list (use as a template for the next reconciliation cycle)
archive/ — Frozen historical PM docs (2026-02-pm/, 2026-05-pm/). Each archive subdir is dated and immutable; superseded docs leave a redirect stub at the original path. Excluded from the published docs site; browse on GitHub.

Last updated: 2026-05-07 — reconciled with doc audit (#144). Changelog: disambiguated cdr (Claude Disaster Recovery, not legacy reqs-index) in §13.1; surfaced live test counts and the doc-link sweep script in §3.7; added doc audit and archive subtree to §17 See Also.

🪴 Quartz 4.0

Explorer

PROJECT-ORCHESTRATION-HANDBOOK