BoB in One Day

Start here if you are new to BoB. In one working day you will set up a brand-new project, give it the tooling it needs, write your first requirement, hand it to the autonomous loop, watch the loop work, and read back what it did. Every command below is the same command the workday scenarios page narrates — this tutorial is rendered from that page, so the two cannot disagree.

← Tutorials · docs home

What you will build

A tiny project called hello-bob with one small feature shipped through BoB’s loop. The feature does not matter — pick something you could write yourself in ten minutes, such as “add a greet script that prints a greeting”. What matters is the path it travels: an idea becomes a requirement issue, the requirement is approved, warp-drive turns it into commits, and the loop files a report you can read at the end of the day.

By the evening you will have:

a git repository wired to BoB (.claude/ links, a manifest, labels);
one requirement issue with acceptance criteria, closed by the loop;
one or more commits on your main branch, each with a chunk report issue;
a session summary issue you can hand to a teammate;
a feel for where you stay in charge and where BoB carries the work.

The day is split into seven stops. Each stop tells you what to run, what you should see, and what just happened. Do them in order — each stop’s output is the next stop’s input.

Before you start

You need four things on the machine you will work on:

BoB installed and deployed. If bob is not on your PATH yet, follow first-time install and come back.
The GitHub CLI, signed in. BoB tracks all work as GitHub Issues, so gh must be able to create issues. Check with gh auth status.
Claude Code. The loop runs inside a Claude Code session.
About two hours of wall-clock time spread across the day. Most of it is the loop working while you do something else.

You do not need to know how BoB works inside. The tutorial explains each piece the first time you touch it, and links to the deeper page when there is one.

Where you are

You run this whole tutorial in a terminal: shell commands at the prompt, and Claude Code started with claude in the same window. That terminal is one of several places BoB can talk to you. The others are the Claude desktop app, Telegram (through the remote decision bridge) and your phone. Each has its own tutorial on the learning path; today you only need the terminal.

1. Morning — check the machine and create the project

Every BoB day starts on a machine that is in a known state. BoB is deployed from a source checkout into ~/.claude/, and if the two have drifted apart the loop can behave strangely later in the day. So the first command asks the machine a question before you ask it to do any work.

Then you make an empty project, put it under git, and let BoB wire it up. This tutorial takes the steps one at a time so you can see what each does; day to day, bob ready ~/projects/<name> does all of them in one command (see bob ready).

Run:

bob doctor
mkdir -p ~/projects/hello-bob && cd ~/projects/hello-bob
git init
gh repo create hello-bob --private --source .
bob init -y

What you should see.

bob doctor ends with a verdict line. A clean machine reports that every section converged. If it reports drift, it names the remediation — usually a deploy — and you should run that before going on.
git init creates the repository, and gh repo create gives it a GitHub remote. BoB refuses to work in a directory that is not a git repository, because every change it makes has to be reviewable — and it tracks work as issues, so the project needs a place on GitHub for them.
bob init -y prints the links it created under .claude/ (the universal commands and agents), a settings file for the project, and a port band — a small range of ports reserved for this project so its dev server never collides with another project’s.

What just happened. bob init did not copy BoB into your project. It linked it: the commands under .claude/commands/ are symlinks into ~/.claude/, so when BoB is updated your project picks the update up without you doing anything. The -y flag answers “yes” to every prompt, which is what you want the first time.

Checkpoint. Listing the project’s .claude/ commands directory shows symlinks, including the warp-drive and requirement commands, and the end of the bob init -y output reads Summary: 0 errors, 0 warnings followed by the link counts. If the directory is empty, re-run bob init -y and read its preflight section for the first line that is not [OK].

2. Morning — provision the tooling the project needs

The universal commands are the same in every project. Beyond them, BoB keeps a registry of domain skills, commands and agents — Cloudflare, Drupal, testing, release management and many more — and loads only the ones a project declares. The declaration is a small JSON manifest kept in the BoB source repository, one per project.

You could write the manifest by hand. Instead, let BoB look at the project and propose one:

bob provision --init --auto
bob ready
bob provision --status

What you should see.

bob provision --init --auto detects the project’s stack and writes a manifest from it, then links what the manifest declares. On an empty project there is nothing to detect yet, so it says No stack detected and starts from the default manifest — a handful of generally useful skills, commands and agents. That is fine: once the project has code, bob provision reconcile proposes what the code now implies.
bob ready converges everything else a warp-drive run expects: the standard issue labels (req, approved, the priorities) on your GitHub repository, the port band, the project manifests. It is idempotent — run it again at any time and it changes only what is missing. It ends with a verdict: READY, or NOT READY with one line per blocker and the command that fixes it. A labels blocker means the project has no GitHub remote yet; a host blocker is the same drift bob doctor reported.
bob provision --status lists every declared item and whether it is linked. Anything marked [unlinked] is declared but not yet present — the fix is always bob provision --refresh.

What just happened. The manifest is declared state: it lives in version control next to every other project’s manifest, and the links in your project are derived from it. That is BoB’s Prime Directive in one sentence — every piece of state has exactly one owner. The first manifest is written straight into the BoB source checkout’s provisions directory (the command prints the path), so commit it there like any other change. Later edits — bob provision add or remove of a single item — go through a reviewable path instead: a staged pull request, merged and applied for you at higher automation levels.

Checkpoint. bob provision --status names the manifest it read and, for skills, commands and agents, reports every declared item as provisioned — no [unlinked] rows.

3. Late morning — write the requirement

A requirement sits at the bottom of BoB’s product hierarchy. At the top is the vision, which says why the product exists and who it is for. Below it are capabilities, one feature each, and each capability splits into requirements, the testable pieces the loop builds. hello-bob is too small to need a vision or a capability, so today you start at the bottom. The next tutorial, Your First Product with BoB, starts at the top.

Now the actual work. In BoB, work is never a note in a file or a line in a chat — it is a GitHub Issue with a label that says what kind of work it is. The unit the loop picks up is a requirement: a description plus acceptance criteria written as checkboxes, each one testable.

Start Claude Code in the project (claude), then run:

/requirement

/requirement interviews you. Answer in plain language. When it asks for acceptance criteria, keep them small and checkable — for the greeting example:

“the greet script prints Hello, BoB! and exits 0”
“a test runs the script and checks its output”

It writes the issue with a priority label and, when there is a parent capability, a Part of #NN link. Note the issue number it prints.

A requirement is not work yet. It becomes work when a human approves it — that is the one gate BoB will not open for you. Approve it by adding the label (use the number /requirement printed):

gh issue edit 1 --add-label approved

What just happened. You drew the line between deciding and doing. The issue now carries req and approved, and that pair is exactly what the loop searches for. Everything that happens next is traceable back to this issue: commits reference it, reports link to it, and it closes when its criteria are met.

Checkpoint. gh issue view on your issue number shows the approved label and at least one unchecked acceptance-criteria box.

4. Midday — hand the requirement to warp-drive

warp-drive is BoB’s autonomous development loop. It takes an approved requirement and runs it through a fixed set of phases: plan, split into commit-sized chunks, and for each chunk code → update docs → test → commit → file a report; then merge and close. The phases are enforced by hooks — the loop cannot commit before tests pass or end a session without filing its report — so you do not have to watch it to keep it honest.

How much it asks you depends on the automation level you start Claude with. Choosing -a3 below is a decision about how often you want to be asked:

Level	Flag	What it asks you
1 — Supervised	`-a1`	Before every decision. The loop does not run at this level.
2 — Trusted Dev	`-a2`	Before anything destructive, and for any wording or priority. It reviews its plan with you and opens a pull request for you to merge.
3 — Autonomous	`-a3`	Only for destructive operations, rebase conflicts and genuine decisions such as a new dependency or an ambiguous criterion. It plans, merges and moves on alone.

The automation reference has the full rules. On a throwaway project, Level 3 shows the loop at its most characteristic. Start Claude at Level 3 and point the loop at your issue:

claude -a3

/warp-drive --issue 1

What you should see. The loop announces each phase as it enters it. Early on it runs a preflight — it grades this machine and this project — and if a check fails it files a todo issue naming the fix and stops, rather than working around the problem. Then it plans, cuts a feature/issue-NN-… branch, and starts the first chunk.

What just happened. You delegated. Passing the issue number scopes the run to that issue alone: when it is done, the loop ends instead of wandering off to other approved work. If it needs you, it asks in the terminal — or, if you turned the remote decision bridge on, on your phone.

Checkpoint. Within a few minutes the loop reports that it is in the coding phase for chunk 1. If it stopped at preflight instead, open the todo it filed, do what it says, and run /warp-drive again — it resumes where it stopped.

5. Afternoon — watch the loop from a second terminal

You do not have to sit in the Claude session to know what the loop is doing. The state of a run lives in a small file under .claude/, and BoB reads it for you. Open a second terminal in the project and run:

bob warp status --watch

What you should see. A panel that redraws in place every few seconds: the current phase, the issue and the run’s scope (how many of its issues are done), the automation level, the preflight verdict, counters for commits, chunks, tests and reports, and when the run started. As the loop moves from coding to testing to committing, the panel follows. Press Ctrl-C to stop watching — that stops the watcher, never the loop.

What just happened. Nothing — and that is the point. Watching is read-only. You can close this terminal, reopen it, or run the same command from another machine that can reach the project, and the loop never notices.

Checkpoint. The phase shown matches what the Claude session last announced.

6. Afternoon — open the live session graph

The status panel tells you where the loop is. The session graph shows the whole run: every phase it has passed through, how long each took, where it retried, and which chunks are done. In the second terminal:

bob warp viz

What you should see. BoB starts (or reuses) a small local dashboard server on the project’s reserved port and prints its URL. Open it in a browser. The graph updates as the loop advances. If you are on another machine on the same tailnet, bob warp viz --tailnet serves it on this machine’s Tailscale address instead of localhost.

What just happened. The dashboard reads the same state file the status panel does, so the two always agree. If the server was started before BoB was last updated, bob warp viz notices, restarts it, and tells you so.

Checkpoint. The page loads at the printed URL and shows the same phase as the status panel in your other terminal.

7. Evening — read back what happened

By the evening the loop has finished: the requirement’s boxes are ticked, its commits are on your main branch, and the issue is closed. The last step is the one that turns a day of work into something you — or a teammate tomorrow — can read in two minutes. In Claude:

/what-next --report

What you should see. A catch-up: what changed recently, the state of open work, a one-line health summary derived from the tracker, and a ranked list of what to do next. Alongside it, the loop has already filed its own records while it worked:

one chunk report issue per commit — what was built, what was decided, what was deferred;
a session summary issue with every requirement and bug the session completed and the tokens it used.

What just happened. The day’s work is now durable and queryable. Nothing lives only in a terminal scrollback: the requirement, its commits, its reports and the summary are linked GitHub Issues. Tomorrow’s first command reads them.

Checkpoint. Your requirement issue is closed, and the issue list shows a session-summary issue from today.

What you learned

Stop	You ran	BoB’s idea behind it
1	`bob doctor`, `bob init`	Check the machine first; link tooling, never copy it
2	`bob provision`	Declared state has one owner; links are derived from it
3	`/requirement`, the `approved` label	Work is an issue; a human opens the gate
4	`/warp-drive`	Phases are enforced, so delegation is safe
5	`bob warp status`	Observing a run never changes it
6	`bob warp viz`	One state file, many views
7	`/what-next`	Friction and progress end up in the tracker, not in prose

When something goes wrong

bob doctor reports drift. The source checkout and ~/.claude/ disagree. Run the remediation it names. BoB refuses to redeploy while a Claude Code session is running on the machine, so close other sessions first.
The loop stops at preflight. It filed a todo issue that names every failed check and the command that fixes it. Do the steps, add the completed label to the todo, and start /warp-drive again.
The loop says there is no work. The issue is missing the approved or req label, or it is already closed. Check with gh issue view.
A commit is refused. That is the commit gate: the loop only commits in its committing phase. Let the loop reach it; do not commit by hand during a run.
You need to stop the loop. Use /stop-warp-drive in the Claude session. It ends the run cleanly and still files the session summary.

Where to go next

Tomorrow, take the next tutorial, named below. It starts where today ended. The tutorials index lists the whole learning path in order.

Next tutorial: Your First Product with BoB — A working week on one small product: vision, capabilities, requirements, groom, flight plan, parallel runs, finalize and a tagged release.