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

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

# 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

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:

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:

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

1. Runs a final test
2. Merges (L2: creates PR / L3: direct merge to master)
3. Asks “Continue to next task?”
4. If yes → discovers next approved issue
5. 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

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

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

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

Graceful stop does:

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

Hard reset does:

1. Deletes the state file
2. 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:

1. It files a GitHub Issue labeled todo, assigned to you, describing the decision needed
2. Skips the blocked item and continues to the next chunk
3. 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

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

{
  "_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:

1. ~/.claude/scripts/doc-keeper/sync.js --root . --apply runs and applies every fix_kind: mechanical finding (component counts, label naming, etc.).
2. ~/.claude/scripts/doc-keeper/audit.js --root . --fail-on-drift re-audits.
3. 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).
4. 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):

{
  "_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:

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

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

Preflight check

Run the preflight checker to verify all dependencies are installed:

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

warp status

If stale, reset it:

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:

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

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:

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.