Warp Drive

Autonomous development loop for Claude Code. Picks up approved work from GitHub Issues, breaks it into chunks, codes, tests, commits, and reports — with minimal human intervention.

TL;DR

bash

# Inside Claude Code
/warp-drive 42       # work on issue #42
/warp-drive          # auto-discover next approved issue
/stop-warp-drive     # graceful stop

# From any terminal
warp status          # check on the loop
warp stop            # abort from outside

Where It Fits

Warp Drive operates at the bottom of the product hierarchy (vision → capability → requirement → chunks). It picks up requirements (not capabilities or vision) and turns acceptance criteria into commits. Each requirement is a GitHub Issue with checkboxes; warp-drive works through them one commit at a time.

Installation

Prerequisites

These must be installed on your machine:

Dependency	Check	Install
Node.js	`node --version`	nodejs.org
jq	`jq --version`	`brew install jq`
GitHub CLI	`gh --version`	`brew install gh`
Git	`git --version`	`brew install git`

BoB Framework

Warp Drive is part of BoB (Big ol' Brain), the global Claude Code tooling framework at ~/.claude/. If you have BoB installed, warp-drive is already available. The key files:

~/.claude/
├── bin/warp                              # CLI (this is new)
├── commands/warp-drive.md                # /warp-drive slash command
├── commands/dev-up.md                    # /dev-up slash command
├── skills/stop-warp-drive/SKILL.md       # /stop-warp-drive skill
├── scripts/warp-drive/state-machine.js   # State machine engine
├── scripts/dev-lifecycle/                # Dev environment IaC scripts
│   ├── dev-up.sh                         # Full lifecycle orchestrator
│   ├── health-check.sh                   # Lightweight health probe
│   ├── provision-users.sh                # Test user provisioning
│   └── check-seed-coverage.sh            # Seed data coverage gate
├── hooks/warp-drive-gate.sh              # Blocks commits outside committing phase
├── hooks/warp-drive-inject.sh            # Resumes state on session start
├── hooks/warp-drive-edit-tracker.sh      # Doom loop detection
├── hooks/warp-drive-pre-exit.sh          # Self-verification before phase advance
├── hooks/warp-drive-stop.sh              # Blocks exit when report is pending
├── templates/dev.json                    # Dev manifest template
├── templates/seed/                       # Seed data templates
└── docs/warp-drive.md              # This file

Add warp to your PATH

Add this to your ~/.zshrc (or ~/.bashrc):

bash

# BoB CLI tools
export PATH="$HOME/.claude/bin:$PATH"

Then reload: source ~/.zshrc

Verify: warp help

Hook Registration

The warp-drive hooks are registered in ~/.claude/settings.json automatically. If you're setting up from scratch, the hooks need entries in:

Hook Type	File	Purpose
SessionStart	`warp-drive-inject.sh`	Resume from last phase
PreToolUse (Bash)	`warp-drive-gate.sh`	Block commits outside committing phase
PreToolUse (Bash)	`warp-drive-pre-exit.sh`	Self-verification before phase advance
PostToolUse (Edit\|Write)	`warp-drive-edit-tracker.sh`	Track edits, detect doom loops
PostToolUse (Edit\|Write)	`warp-drive-docs-detector.sh`	Auto-detect doc edits → advance state
PostToolUse (Bash)	`warp-drive-commit-detector.sh`	Auto-detect git commit → advance state
Stop	`warp-drive-stop.sh`	Block exit when report is pending

If hooks aren't registered, warp-drive still works — you just lose the safety rails (commits could happen at the wrong time, doom loops won't be caught, auto-detection won't fire, etc.).

First-Time Setup

1. Initialize your project with BoB tooling

bash

cdi -y /path/to/your/project

This creates the .claude/ directory structure in your project. If you skip this, /automation will run it for you.

2. Set automation level

Inside Claude Code, in your project directory:

/automation level 2

This writes permission rules to .claude/settings.local.json. Warp-drive requires Level 2 or 3.

Level	Who It's For	Merge Strategy
Level 2 (Trusted Dev)	Active development, you review PRs	Creates PR for review
Level 3 (Autonomous)	Trusted mode, minimal intervention	Direct merge to master

3. Create work items

Create a requirement as a GitHub Issue:

/requirement

This creates an issue with acceptance criteria checkboxes, labeled req. When ready for warp-drive, add the approved label:

bash

gh issue edit 42 --add-label approved

4. Create a feature branch (Level 2 only)

/start-work

Level 3 auto-creates branches. Level 2 requires you to start one first.

5. Launch

/warp-drive 42       # work on issue #42
/warp-drive          # auto-discover next approved issue

Running Warp Drive

Starting a session

From inside Claude Code, in your project directory:

/warp-drive                  # finds next issue with labels: req + approved
/warp-drive 42               # works on issue #42 specifically
/warp-drive --area billing   # works the whole 'billing' workstream (see below)

Warp-drive checks prerequisites (automation level, branch, test command), then enters the loop.

Area batching

Within a single repo, issues for distinct workstreams — a module, a feature, a capability rollout — are intermixed. An area:<slug> label tags every issue in one workstream (a capability owns the slug; its child requirements inherit it), so you can warp-drive the cluster as a unit instead of hand-picking issue numbers (#260).

/warp-drive --area billing

narrows discovery to req + approved + area:billing and works those requirements in priority order, one per cycle. Manage and inspect areas with the helper:

bash

~/.claude/scripts/area-labels.sh list              # existing area:* labels
~/.claude/scripts/area-labels.sh issues billing    # preview the cluster (status overview)
~/.claude/scripts/area-labels.sh ensure billing    # idempotently create/refresh the label

See the handbook's Area labels section for the full convention.

What you'll see

Once running, warp-drive works through phases automatically. At Level 2/3, it only interrupts you for project decisions — architecture questions, ambiguous requirements, new dependencies, or scope expansion. Everything else is autonomous.

Each chunk produces:

Code changes implementing 1-3 acceptance criteria
A test run
A conventional commit (feat(scope): description)
A chunk report filed as a GitHub Issue

When it finishes

After all chunks are done, warp-drive:

Runs a final test
Merges (L2: creates PR / L3: direct merge to master)
Asks "Continue to next task?"
If yes → discovers next approved issue
If no → files a session summary and exits

The warp CLI

The warp command is a terminal tool for observing and controlling warp-drive from outside Claude Code. Think of it as docker ps for the autonomous loop.

Commands

bash

warp status          # What phase is it in? What issue? How many commits?
warp log             # Full phase transition history
warp config          # Show workflow settings for this project
warp stop            # Graceful abort (moves to aborted phase)
warp stop --hard     # Emergency reset (deletes state file)
warp session start <branch>   # Start an integration-branch stream (see below)
warp session end              # Clear the session branch
warp session status           # Resolved branch config
warp finalize [--dry-run]     # Ship the integration branch to main
warp help            # Help text

warp status

Shows the live state of the loop:

WARP DRIVE ACTIVE
  Project:  bodmail
  Phase:    coding
  Issue:    42
  Branch:   feature/issue-42-email-parser
  Level:    2
  Area:     email
  Chunk:    2 / 5

  Commits:  1    Chunks: 1    Tests: 3    Reports: 1

  Started:  2026-02-18T14:30:00Z
  PID:      12345

If the Claude session has ended but the state file remains, it shows (stale).

The Area: line appears only when the session is area-scoped (/warp-drive --area <slug>); an unscoped run omits it (#613).

Live/watch mode (#612). Pass --watch (aliases: --live, -w) to re-render the status on a fixed interval instead of printing once — handy parked in a tmux/iTerm split:

warp status --watch                 # refresh every 2s (default)
warp status --watch --interval 5    # refresh every 5s
warp status -w                      # short alias

--interval <seconds> tunes the cadence (default 2s; non-numeric or sub-1s input falls back to the default). The view redraws in place (no scroll spam) and exits cleanly when the session ends, goes stale, or is aborted — leaving a one-line summary on screen. With no active session it prints the usual "No active session" message and exits. Ctrl-C exits cleanly and restores the cursor.

warp stop

From outside Claude Code, warp stop transitions the state machine to the aborted phase. The next time Claude Code starts in that project, it picks up the abort and runs cleanup (WIP commit, abort report).

warp stop --hard deletes the state file immediately. No cleanup, no report. Use this when the state file is corrupted or you just want a clean slate.

warp log

Shows every phase transition with timestamps:

Phase History (bodmail)

  #  Phase                     Event               Time
  ── ──────────────────────── ─────────────────── ─────────────────────
   0  prerequisites             init                2026-02-18T14:30:00Z
   1  discovering               prerequisites_ok    2026-02-18T14:30:05Z
   2  planning                  work_selected       2026-02-18T14:30:12Z
   ...

warp config

Shows the current workflow tuning for the project — automation level, RDB status, and all _workflow settings with their defaults.

Integration-branch streams

By default warp-drive merges (or PRs) each requirement to main on its own. For a cluster of related requirements — a capability rollout, a multi-part feature — you often want to accumulate them on one branch and ship once. That's an integration-branch stream (capability #268).

When to use it

The requirements are tightly coupled (shared files, a staged feature) and you'd rather review/ship them as a unit than as N separate merges.
You want main to stay clean until the whole stream is green, with a single consolidated PR (L2) or one rebase+merge (L3) at the end.

Use a plain per-requirement merge (the default with no session branch) for independent issues.

The workflow

bash

# 1. Open the stream — creates the branch off main and records it as _branch.session
warp session start integration/billing-rollout

# 2. Run the loop over the cluster (each requirement merges into the session branch, not main)
#    e.g. /warp-drive --area billing   (or pass issue numbers)

# 3. Inspect at any point
warp session status        # main / session / current / merge target & strategy

# 4. Ship the accumulated branch in one shot
warp finalize --dry-run    # preview the exact git/gh commands
warp finalize              # L2: one consolidated PR --base main   |   L3: rebase onto main, merge, push

# 5. (If finalize didn't already) clear the stream
warp session end           # removes _branch.session; the git branch is left untouched

How merging changes

When a session branch is set, merge_target != main, and _workflow.session_merge is local (the default), the merging phase accumulates locally: it merges each requirement's child branch into the session branch per merge_strategy, pushes the session branch, deletes the child branch, and never touches main / opens no PR. This applies at both Level 2 and Level 3.

Set _workflow.session_merge to pr to keep the legacy behavior (a PR or direct-to-main merge per requirement) even with a session branch. With no session branch set, behavior is unchanged regardless of the value.

`session_merge`	session branch set	`merging` behavior
`local` (default)	yes	merge child → session, push session, delete child; main untouched
`pr`	yes	per-requirement PR (L2) / direct-to-main (L3)
any	no	unchanged legacy behavior

finalize safety

warp finalize refuses to run when there is no integration branch or while a warp-drive session is mid-stream (it only proceeds with no active state or at awaiting_continue/completed, so it never ships a half-done requirement). On a conflict, push, or auth failure it aborts cleanly and leaves _branch.session intact so you can fix and retry. --dry-run prints the exact commands without executing them.

How It Works

The State Machine

Warp-drive is a phase-based state machine backed by a persistent JSON file at .claude/.warp-drive-state.json in your project. Hooks enforce phase ordering — commits are blocked outside the committing phase, session exit is blocked without a report.

Phase Flow

prerequisites → discovering → planning → chunking
    ↓
  coding → updating_docs → testing → committing → reporting
    ↑                                                  ↓
    └──────────── next chunk ←──── chunk_complete ─────┘
                                        ↓ (all done)
                          requirement_complete → merging
                                                   ↓
                                          awaiting_continue
                                           ↙          ↘
                                   discovering    session_ending
                                  (next task)      (done)

  ─── Circuit-breaker checkpoint ──────────────────────────────
  any phase ──(phase_timeout |               ┌─ budget_continue → coding
              retry_exceeded |               │
              coding_cycles_exceeded |       │  (resume work)
              no_progress |                  │
              total_chunks_exceeded |        │
              session_timeout)──→ budget_exceeded ─┤
                                                   │
                                                   └─ budget_abort → aborted
                                                      (give up & clean up)
  ─────────────────────────────────────────────────────────────

The state machine routes any phase into budget_exceeded when an enforced budget trips (see Configuration for the trigger reasons). From budget_exceeded, a budget_continue event resumes coding; budget_abort moves to aborted. The aborted phase has its own cleanup events: abort_resolved (cleanup OK → completed), abort_cleanup_failed (cleanup failed → completed anyway), and restart (back to idle).

Phase Details

Phase	What Happens	Advances When
prerequisites	Checks automation level (2+), branch (not main), test command; runs the baseline-docs check (greenfield README/runbook/CLAUDE.md gap → unapproved `req`, non-blocking)	All checks pass
discovering	Runs `gh issue list --label approved` to find work	Issue selected
planning	Reads issue, drafts approach if complex (>3 ACs or architecture decisions)	Plan ready
chunking	Splits work into commit-sized pieces (max 3 ACs each)	Chunks defined
coding	Implements the current chunk's acceptance criteria	Code complete
updating_docs	Checks off completed ACs in the GitHub Issue	Hook auto-detects
testing	Runs project test suite; retries up to 3 alternatives on failure	Tests pass
committing	Creates conventional commit; hook auto-detects	Commit created
doc_drift_check (opt-in)	Runs `/doc-sync` (mechanical fixes) and `/doc-audit --fail-on-drift` after the commit. Active when `_workflow.doc_drift_gate=true`.	`drift_clean` → reporting / `drift_blocked` → coding
reporting	Files chunk report as GitHub Issue; adds an "Iteration trail" section when the chunk took >1 verify attempt (#589)	Report filed
chunk_complete	Checks if more chunks remain	Next chunk or done
requirement_complete	Final test, close issue via PR	Merge ready
merging	L2: push + PR / L3: rebase + push master	Merged
awaiting_continue	Asks: "Continue to next task?"	User responds
session_ending	Files session summary, notifies, cleans up state	Done

Automation Levels in Practice

Behavior	Level 2	Level 3
Branch creation	You create via `/start-work`	Auto-creates `feature/issue-NN-title`
Merge strategy	Creates PR for review	Direct merge to master
Decisions	Asks for architecture, scope, ambiguity	Same
Continue prompt	"Continue to next task?"	Same
File operations	Auto-approved	Auto-approved
Destructive git	Blocked (force push, reset --hard)	Blocked (force push, reset --hard)

Self-Verification

Before advancing past key phases (code_complete, tests_passed, requirement_done), a hook injects a verification prompt forcing Claude to re-read the original acceptance criteria and confirm each one is genuinely satisfied — not just that code exists.

Doom Loop Detection

A PostToolUse hook tracks how many times each file is edited during a phase. If any file exceeds the threshold (default: 5 edits), a warning is injected. This catches infinite edit cycles where Claude keeps tweaking the same file without making progress.

No-Progress / Stall Detection

Distinct from the raw retry caps, the state machine watches for stagnation on the coding ↔ testing and coding ↔ doc_drift_check loops (#267). On every tests_failed / drift_blocked it computes two signatures:

a diff signature — a hash of git diff HEAD plus the untracked-file list (captures whether any code changed since the last attempt), and
a failure signature — a hash of the short failure string passed via --data '{"failure":"…"}' (the failing test name or first error line).

A per-chunk stall counter increments only when both are unchanged since the previous attempt — i.e. the same failure with no new diff. Any change to either (different error, or the diff moved) is treated as legitimate slow progress and resets the counter to zero. This is the key distinction the raw coding_cycles count can't make: it halts on stagnation, not on attempts.

When the counter reaches max_no_progress (default 3), an enforced no_progress budget issue trips the circuit breaker into budget_exceeded. At Level 3 this is a mandatory human checkpoint — the loop will not spin on an unsolvable chunk burning budget; it stops and asks. budget_continue clears the guard and resumes; budget_abort cleans up. The counter also resets whenever a new chunk begins or the loop makes real headway (tests_passed, drift_clean).

Always pass the failure signature on tests_failed/drift_blocked; without it the detector falls back to the diff signature alone (still catches "no code changed", just less precisely).

Cost Budget

The circuit breaker also enforces a spend ceiling (#587). Token usage is tracked per chunk and per session; checkBudgets() compares the cumulative session total against max_session_tokens and, when crossed, emits an enforced cost_budget_exceeded issue that routes to budget_exceeded — the same mandatory Level-3 checkpoint as the other hard limits. This closes the gap where a runaway loop could burn budget while staying under every count-based cap.

Token count is the primary signal. The check reads token_usage.session_total when captured, else the running sum of chunk_snapshots, so it trips mid-session on accumulated spend rather than only at session end.
max_session_usd is optional/secondary — an estimated-dollar ceiling via token-report's shared cost model. Prefer the token ceiling; the dollar estimate is best-effort.
Disabled by default. Both ceilings default to 0 (off), so existing sessions are unaffected unless you configure them under _workflow in settings.local.json.
The budget_exceeded checkpoint reports actual spend vs ceiling (e.g. cost_budget_exceeded: 1500 tokens exceeded 1000 tokens) and offers the usual budget_continue (extend) / budget_abort choice.

Stopping and Resuming

Stopping

From inside Claude Code:

/stop-warp-drive              # Graceful: WIP commit, abort report, cleanup
/stop-warp-drive reset        # Hard: delete state file immediately

From any terminal:

bash

warp stop                     # Graceful abort
warp stop --hard              # Hard reset

Graceful stop does:

Transitions to aborted phase
Creates a WIP commit for uncommitted changes
Files an abort report as a GitHub Issue
Cleans up the state file

Hard reset does:

Deletes the state file
That's it — uncommitted work stays in the working tree

Resuming

Warp-drive auto-resumes. When you start a new Claude Code session in a project that has a .warp-drive-state.json, the SessionStart hook injects the current phase context and Claude picks up where it left off.

If the state is stale (the original Claude process has ended), the session still resumes — it just notes the staleness.

The Stop Hook

When you try to exit Claude Code (/exit, Ctrl+D, etc.) during an active warp-drive session:

Report pending? Exit is blocked. File the chunk report first.
Other active phase? Exit is allowed with an advisory: "Consider running session end protocol before stopping."

Remote Mode (RDB)

For autonomous sessions where you're away from the terminal.

Setup

/rdb on

This enables the Remote Decision Bridge. All decisions go to Telegram instead of the terminal, and every phase transition sends a notification.

What you get on Telegram

Phase transition notifications: [warp-drive] coding -- chunk 2/5 for #42
Decision prompts when Claude needs input
Completion notice: [warp-drive] session ending -- 4 commits, 3 chunks

Decision Timeout

If warp-drive needs your input (terminal or Telegram) and you don't respond within 10 minutes:

It files a GitHub Issue labeled todo, assigned to you, describing the decision needed
Skips the blocked item and continues to the next chunk
If nothing else to do, transitions to session ending

You'll find the TODO in your issue list when you're back.

Going AFK

Tell Claude you're stepping away — it treats that as /rdb on:

"I'm going to grab lunch, keep going"

Dev Environment Integration

When a project has a dev.json at its root, warp-drive automatically manages the dev environment throughout the coding loop.

What happens

Phase	Action	Script
prerequisites	Full dev-up: start server, run migrations, seed data, provision users	`dev-up.sh "$(pwd)" --verbose`
coding	Seed coverage check (advisory — warns if schema changed without seed data)	`check-seed-coverage.sh "$(pwd)"`
chunk_complete	Fast health check before next chunk	`dev-up.sh "$(pwd)" --check`
chunk_complete (recovery)	Full dev-up if health check fails	`dev-up.sh "$(pwd)" --verbose`

Dev health as a blocker

If the dev server goes down during coding and can't be recovered after 2 attempts, warp-drive treats it as a blockable event and escalates (see Recovery).

Setting up dev.json

bash

# Copy template and customize
cp ~/.claude/templates/dev.json ./dev.json
vi dev.json

The template has sensible defaults for SvelteKit + Cloudflare Workers projects. Customize the server.command, server.port, server.health, seed, and auth sections for your stack.

Seed data in the loop

Warp-drive encourages additive seed data: when a chunk adds new database entities or lifecycle states, the check-seed-coverage.sh gate advises adding seed data in the same commit. This ensures dev is always testable with realistic data across all entity states.

Skipping dev lifecycle

Projects without dev.json skip all dev lifecycle steps — the integration is fully opt-in. Set _workflow.dev_health_check: false to disable even when dev.json exists.

See dev-lifecycle.md for the full IaC dev lifecycle reference.

Configuration

All settings live in .claude/settings.local.json under _workflow. Edit directly or view with warp config.

Setting	Default	Purpose
`max_acs_per_commit`	3	Max acceptance criteria per chunk
`test_before_commit`	true	Run tests before each commit
`auto_merge`	true	L3: auto-merge to master
`max_phase_minutes`	30	Timeout per phase before budget warning
`max_coding_cycles`	3	Max code/test retries per chunk
`max_retries_per_chunk`	5	Max total retries before escalation
`max_no_progress`	3	No-progress stall halt: consecutive identical failed attempts (same failure, no new diff) before routing to `budget_exceeded`. See No-Progress / Stall Detection
`max_edits_per_file`	5	Doom loop detection threshold
`pre_exit_verification`	true	Self-check before phase advance
`decision_timeout_minutes`	10	Minutes before filing TODO issue
`heartbeat_on_commit`	true	RDB notify on each commit
`reconcile_per_chunk`	true	Auto-correct progress counters
`dev_health_check`	true	Run dev-up health check between chunks
`dev_seed_check`	true	Run seed coverage advisory during coding
`max_total_chunks`	20	Circuit breaker: max chunks per session (hard limit)
`max_session_minutes`	480	Circuit breaker: max session duration in minutes (hard limit)
`max_session_tokens`	0 (disabled)	Circuit breaker: max cumulative session tokens before routing to `budget_exceeded`. `0` disables the check, so existing sessions are unaffected unless configured. Token count is the reliable spend signal; trips mid-session on the accumulated chunk total. See Cost Budget.
`max_session_usd`	0 (disabled)	Circuit breaker: optional/secondary estimated-dollar ceiling (via token-report's cost model). `0` disables it. Use `max_session_tokens` as the primary signal.
`phase_timeout_enforcement`	`warn`	How `max_phase_minutes` breaches are handled: `warn` (advisory only), `block` (reject the offending transition until elapsed time recovers), or `abort` (route through `budget_exceeded` and auto-abort)
`doc_drift_gate`	`false`	When `true`, the slash command fires `commit_with_doc_gate` after each commit, routing through the `doc_drift_check` phase before reporting. Mechanical drift is auto-fixed via `/doc-sync`; high-severity audit findings route the loop back to `coding`. See Doc Drift Gate.
`baseline_docs_check`	`true`	At `prerequisites`, detect missing scaffolding docs on greenfield projects and file an unapproved `req` per gap (`documentation,baseline-doc`). Never authors docs (CAP-15 non-goal); idempotent; non-blocking. See Baseline Docs Check.
`baseline_docs`	`["readme","runbook","claude"]`	Which baseline docs are required.
`baseline_docs_max_commits`	25	Greenfield gate: skip the check on repos with more commits than this. `0` = always run.
`baseline_docs_auto_approve`	`false`	When `true`, filed tracking issues also get the `approved` label, so warp-drive writes the doc itself in a later cycle (crosses the human-authored-narrative boundary).

phase_timeout_enforcement is the only budget threshold whose enforcement mode is configurable — retry_exceeded, coding_cycles_exceeded, no_progress, total_chunks_exceeded, and session_timeout are always enforced (they always route through budget_exceeded). Set phase_timeout_enforcement to warn (the default) for ordinary use and to block or abort only when you actively want phase-level timeouts to halt the loop.

For the full budget system, circuit breaker behavior, token capture pipeline, cost estimation, and reporting tools, see Token Monitoring & Budget System.

Verification Gates

You can configure custom shell commands that must pass before phase transitions:

json

{
  "_workflow": {
    "verification_gates": {
      "code_complete": ["make lint"],
      "tests_passed": ["make type-check"]
    }
  }
}

If a gate command fails, the transition is blocked and Claude must fix the issue before advancing.

Doc Drift Gate

When _workflow.doc_drift_gate=true, the loop routes through a new doc_drift_check phase between committing and reporting:

committing → (commit_with_doc_gate) → doc_drift_check
                                         ↙               ↘
                              drift_clean              drift_blocked
                                  ↓                         ↓
                              reporting                  coding
                            (proceed normally)     (fix high-severity drift)

Inside the gate:

~/.claude/scripts/doc-keeper/sync.js --root . --apply runs and applies every fix_kind: mechanical finding (component counts, label naming, etc.).
~/.claude/scripts/doc-keeper/audit.js --root . --fail-on-drift re-audits.
If audit exits zero (no high-severity drift), the loop emits drift_clean and proceeds to reporting. Any sync edits are staged into a follow-up commit (or amended into the chunk commit, depending on policy).
If audit exits non-zero, the loop emits drift_blocked and returns to coding so Claude can address the high-severity findings before retrying the chunk.

The gate is opt-in (doc_drift_gate=false by default) for backward compatibility. When it's off, the standard committed → reporting transition still runs.

The advisory hook hooks/doc-drift-warning.sh runs after every successful git commit — even when the gate is disabled — and warns when a commit touches tooling source paths (skills/, commands/, agents/, hooks/, bin/, scripts/, Makefile) without touching any *.md. That hook is non-blocking; the gate above is.

Baseline Docs Check

The Doc Drift Gate above keeps existing docs accurate. The baseline-docs check addresses the complementary gap: a greenfield project that never gets baseline scaffolding docs in the first place (a real miss observed on a fresh MVP scaffold — an operations runbook and project CLAUDE.md were never produced).

At prerequisites, scripts/warp-drive/baseline-docs-check.sh checks for a README, an operations runbook (RUNBOOK.md, runbooks/*.md, or docs/runbook*.md), and a CLAUDE.md. For each missing doc it files a GitHub issue labelled req,documentation,baseline-doc,p3-medium — without approved, so a human gates the writing.

Design boundaries (why it only surfaces the gap):

Never authors narrative. Consistent with the CAP-15 non-goal — README/CLAUDE.md/runbook prose stays human-authored. The loop files a tracking issue; a human (or, with baseline_docs_auto_approve=true, a later cycle) writes it.
Idempotent. An open baseline-doc issue for a given doc is never refiled, so re-running prerequisites across sessions never duplicates.
Non-blocking. The check emits JSON and the loop continues regardless — it is advisory, never a gate.
Greenfield-scoped. The baseline_docs_max_commits gate (default 25) skips mature repos, which already have these docs or have deliberately chosen otherwise. Set it to 0 to always run.

Configure via the baseline_docs* keys in Configuration. Disable entirely with baseline_docs_check=false.

Reasoning Budget

Control Claude's reasoning effort per phase (the "reasoning sandwich" pattern — high reasoning for planning/verification, standard for implementation):

json

{
  "_workflow": {
    "reasoning_budget": {
      "planning": "high",
      "coding": "standard",
      "testing": "high"
    }
  }
}

See Token Monitoring & Budget System for the full per-phase default table and how reasoning levels are applied.

What Gets Created

Artifact	Where	Labels
Commits	Feature branch (conventional commit format)	—
Chunk reports	GitHub Issues	`warp-drive`
Session summary	GitHub Issue	`session-summary`, `warp-drive`
Lessons learned	GitHub Issues	`lesson`, `warp-drive`
Decisions made	GitHub Issues	`decision`, `warp-drive`
Deferred bugs	GitHub Issues	`bug-deferred`, `warp-drive`
TODO (timeouts)	GitHub Issues	`todo`, `warp-drive`
Abort reports	GitHub Issues	`warp-drive`, `session-summary`
PR (Level 2)	GitHub PR via `gh pr create`	—

GitHub labels are created automatically on first run (warp-drive, lesson, decision, risk, bug-deferred, session-summary).

Recovery

If a session is lost (crash, worktree deletion, etc.), use the disaster recovery CLI:

bash

# Check current state
~/.claude/scripts/lib/cdr.sh status

# Re-initialize tooling (clone from remote, re-run cdi)
~/.claude/scripts/lib/cdr.sh recover /path/to/project

# Emergency state reset (deletes warp-drive state file)
~/.claude/scripts/lib/cdr.sh reset /path/to/project

Commit hash recovery

Warp-drive records commit hashes in the state file (commit_hashes[]). If the state file survives but the worktree is lost, cherry-pick commits from the remote:

bash

git fetch origin
git cherry-pick <hash1> <hash2> ...

Preflight check

Run the preflight checker to verify all dependencies are installed:

bash

~/.claude/scripts/lib/preflight-check.sh

This checks: jq, node, git, gh auth, hook file existence, and core scripts.

Troubleshooting

"Automation level must be 2 or 3"

Run /automation level 2 inside Claude Code first. This sets up permissions in .claude/settings.local.json.

"Must not be on main/master"

Run /start-work to create a feature branch (Level 2), or let Level 3 auto-create one.

Warp-drive won't start — "Active session exists"

A previous session didn't clean up. Check if it's stale:

bash

warp status

If stale, reset it:

bash

warp stop --hard

Commit blocked — "only allowed during committing phase"

The gate hook is working correctly. Claude tried to commit outside the committing phase. This usually means a phase was skipped. Check the state:

bash

warp log

Can't exit Claude Code — "report is missing"

The stop hook blocks exit when a commit was made but no chunk report was filed. Tell Claude to file the report, or if you need to force exit, kill the terminal.

Doom loop warning

Claude keeps editing the same file. The edit tracker caught it. This usually means the approach isn't working. Claude should try an alternative strategy or escalate.

State file is corrupted

bash

warp stop --hard

This deletes the state file. Your code changes are still in the working tree. Start a new session when ready.

warp command not found

Add ~/.claude/bin to your PATH:

bash

echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Internals Reference

Moved to reference — see Warp-Drive State Reference for the state file, state-machine CLI, and transition table.

Warp Drive ​

TL;DR ​

Where It Fits ​

Installation ​

Prerequisites ​

BoB Framework ​

Add warp to your PATH ​

Hook Registration ​

First-Time Setup ​

1. Initialize your project with BoB tooling ​

2. Set automation level ​

3. Create work items ​

4. Create a feature branch (Level 2 only) ​

5. Launch ​

Running Warp Drive ​

Starting a session ​

Area batching ​

What you'll see ​

When it finishes ​

The warp CLI ​

Commands ​

warp status ​

warp stop ​

warp log ​

warp config ​

Integration-branch streams ​

When to use it ​

The workflow ​

How merging changes ​

finalize safety ​

How It Works ​

The State Machine ​

Phase Flow ​

Phase Details ​

Automation Levels in Practice ​

Self-Verification ​

Doom Loop Detection ​

No-Progress / Stall Detection ​

Cost Budget ​

Stopping and Resuming ​

Stopping ​

Resuming ​

The Stop Hook ​

Remote Mode (RDB) ​

Setup ​

What you get on Telegram ​

Decision Timeout ​

Going AFK ​

Dev Environment Integration ​

What happens ​

Dev health as a blocker ​

Setting up dev.json ​

Seed data in the loop ​

Skipping dev lifecycle ​

Configuration ​

Verification Gates ​

Doc Drift Gate ​

Baseline Docs Check ​

Reasoning Budget ​

What Gets Created ​

Recovery ​

Commit hash recovery ​

Preflight check ​

Troubleshooting ​

"Automation level must be 2 or 3" ​

"Must not be on main/master" ​

Warp-drive won't start — "Active session exists" ​

Commit blocked — "only allowed during committing phase" ​

Can't exit Claude Code — "report is missing" ​

Doom loop warning ​

State file is corrupted ​

warp command not found ​

Internals Reference ​

Warp Drive

TL;DR

Where It Fits

Installation

Prerequisites

BoB Framework

Add warp to your PATH

Hook Registration

First-Time Setup

1. Initialize your project with BoB tooling

2. Set automation level

3. Create work items

4. Create a feature branch (Level 2 only)

5. Launch

Running Warp Drive

Starting a session

Area batching

What you'll see

When it finishes

The warp CLI

Commands

warp status

warp stop

warp log

warp config

Integration-branch streams

When to use it

The workflow

How merging changes

finalize safety

How It Works

The State Machine

Phase Flow

Phase Details

Automation Levels in Practice

Self-Verification

Doom Loop Detection

No-Progress / Stall Detection

Cost Budget

Stopping and Resuming

Stopping

Resuming

The Stop Hook

Remote Mode (RDB)

Setup

What you get on Telegram

Decision Timeout

Going AFK

Dev Environment Integration

What happens

Dev health as a blocker

Setting up dev.json

Seed data in the loop

Skipping dev lifecycle

Configuration

Verification Gates

Doc Drift Gate

Baseline Docs Check

Reasoning Budget

What Gets Created

Recovery

Commit hash recovery

Preflight check

Troubleshooting

"Automation level must be 2 or 3"

"Must not be on main/master"

Warp-drive won't start — "Active session exists"

Commit blocked — "only allowed during committing phase"

Can't exit Claude Code — "report is missing"

Doom loop warning

State file is corrupted

warp command not found

Internals Reference