Kickoff Flags

Warp-Drive Kickoff Flags

A warp-drive run can be configured at kickoff via slash/CLI flags instead of editing settings beforehand — most importantly the automation level (/warp-drive -f 4 / factor 4), plus the decision timeout, promotion ceiling, cost/token budget, area scope, a target issue, and the pre-flight --dry-run. Part of the Level 4 capability (#865); realizes use case #864.

This page is what the kickoff flags do to a run. The flags themselves — every state-machine.js subcommand and flag with its type, default and parser — are generated from the engine into Warp-drive state-machine flags (#2085); that page is the source of truth for spelling and validation.

Single parser (Prime Directive). scripts/warp-drive/kickoff.js is the one parser+validator for these flags, consumed by the /warp-drive command, the state-machine init, and bob warp status / bob warp config. The rule lives in exactly one place.

Flags

Flag	Effect	Validation
`-f <1-4>` / `--factor <n>` (alias `factor <n>`)	Automation level for the run (wins over `--level`).	integer 1–4
`--timeout <min>`	Decision-response timeout in minutes (`0` = workaround/stop).	integer ≥ 0
`--ceiling <pr\|external\|test\|prod>`	Promotion ceiling — the run never deploys past it.	enum
`--budget <usd>`	Cost ceiling in USD, enforced by the session breaker.	number ≥ 0
`--max-tokens <n>`	Token ceiling, enforced by the session breaker.	integer ≥ 0
`--area <slug>`	Restrict discovery to one workstream. The label name `area:<slug>` (as `area-labels.sh list` prints it) is accepted in place of the bare slug — the prefix is stripped once, case-insensitively, and the slug lower-cased, so it is never doubled into `area:area:<slug>` (#1954). The same normalization applies wherever an area is accepted: `discovery-cache.js`/`discover-queue.sh --area`, `flightplan.js build/scan --area`, `bob warp session start --area`, `area-labels.sh issues`, and the `work_selected` transition’s `area` data.	slug or `area:<slug>`
`--issue <N[,N...]>`	Scope the run to specific issue(s) — the run ends when they are done.	issue number(s)
`--flightplan <N>`	Run against a flight-plan issue — consume its ordered items in order, never widening, ticking each off (#1068). If the plan declares an integration branch, the kickoff opens/resumes that stream automatically (#1181); a conflict with a different pinned stream is refused.	single issue number
`--dry-run`	Pre-flight only — pre-classify + emit TODOs, author nothing (#878).	flag

Multi-item runs pin an integration branch by default (#4405). A kickoff with --flightplan, --area or more than one --issue, on a checkout whose _branch.session is empty, pins stream/<machine-id>-<YYYY-MM-DD> at init. It uses the same path as bob warp session start … --flightplan/--area. Every item merges into that branch, and main moves once, at bob warp finalize. The engine runs finalize at session_ended at Level 3; at Level 2 and 4 (where finalize opens a PR) the session summary names the command. A second checkout of the repo the same day pins <stream>-<worktree name>. A single-issue run, an unattended run and _workflow.auto_session_branch: false keep the per-item merge. See integration-branch streams.

Kickoff scope (#992)

--issue and --area are not just work selectors — they define the run’s scope, the boundary of what the kickoff authorized. The scope rule lives in one place, kickoffScope() in kickoff.js, and is consumed by the segmentation decision, the discovering phase, session resume (inject), and bob warp status:

Kickoff	Scope	The run ends when
`--flightplan <N>`	flightplan — the ordered items of flight-plan issue #N	the plan’s items are all checked or closed
`/warp-drive 261` / `--issue 261,262`	issues — only the listed issue(s)	all listed issues are done (or closed)
`--area <slug>`	area — the workstream’s approved queue	the area queue is empty
no issue, no area	unscoped — the full approved queue	the approved queue is empty

A flight plan is the most explicit “run exactly this ordered plan” intent and wins over --issue and --area; an issue list is the next-narrowest and wins over --area. A flightplan run consumes the plan issue (see the flight-plan how-to), ticking each item off as its requirement completes.

An issue-scoped run never widens to the approved queue: at each awaiting_continue boundary the segment decision computes “more work” within scope (the issue list minus session.completed_issues — a deterministic state-machine fact, no queue peek), so a scoped-and-done run routes to continue_no and ends cleanly instead of discovering the next approved issue or segmenting into a fresh self-spawned session. Issues completed by the run are recorded in session.completed_issues on entry to awaiting_continue, which is also what lets a resumed segment of a multi-issue scoped run pick up only the remaining scoped issues. bob warp status shows the scope (Scope: issues #261, #262 (1 done, 1 remaining) / full approved queue).

Floor safety (AC-04)

A flag can never push past the profile floor. The parser enforces this at the value level — the factor is bounded to 1–4, the ceiling to its enum, and numeric budgets to non-negative — and refuses an out-of-range request with usage help rather than silently clamping:

$ node scripts/warp-drive/kickoff.js parse -f 5
kickoff: invalid options —
  --factor must be an integer 1-4 (got "5") — a flag can never push past the profile floor
  ...usage...
# exit 2

The irreversible-action floor itself (profiles/full-auto.json, #867) is enforced by the profile regardless of any flag; a flag only ever narrows what a run may do, never widens it.

A4 cost ceiling required (#879)

A full-auto (Level 4) run must declare a spend ceiling before it starts — an unattended A4 session with no ceiling could burn unbounded budget while staying under every count-based cap. The ceiling comes from a kickoff flag (--budget <usd> or --max-tokens <n>) or project config (_workflow.max_session_usd / max_session_tokens). Without one, init refuses to start a Level 4 run:

$ warp-drive -f 4          # no --budget/--max-tokens and none in config
Level 4 (full-auto) requires a cost ceiling — pass --budget <usd> or --max-tokens <n>
at kickoff, or set _workflow.max_session_usd / max_session_tokens in settings.
# exit 2, no session started

Below Level 4 the gate never fires. The ceiling is enforced by the existing session cost breaker (cost_budget_exceeded, #587) — no new breaker: the per-run kickoff value wins over config, so --budget/--max-tokens is what the breaker checks. At kickoff the resolved ceiling is surfaced with a cost estimate (init response cost_ceiling): a typical session’s spend averaged over recent history (via the shared cost model) and how many such sessions fit under the ceiling, so the budget’s reach is visible before the run begins.

Persistence & surfacing (AC-03)

Chosen options are persisted to state.session.kickoff at init (only the set flags appear, so an unset flag never clobbers a default). They are surfaced by:

bob warp status — a Kickoff: line (e.g. timeout=15m ceiling=test budget=$5 dry-run), omitted when no kickoff flags were set.
bob warp config — a Kickoff (active run) section listing session.kickoff.

CLI

kickoff.js parse <flags> [--json] — validate/normalize a flag set. Exit 0 (valid; prints the normalized options + the state object init persists) or 2 (invalid; prints the errors + usage). The exit code lets the /warp-drive command gate before starting the loop.

Testing

make test-kickoff runs tests/test-kickoff.js — unit tests over the parser/validator (including the lenient embedding used by init and the out-of-range refusals) plus CLI exit-code tests. make test-a4-cost-ceiling runs tests/test-a4-cost-ceiling.js — the A4 required-ceiling gate, the init refuse/allow behaviour, and the existing breaker enforcing the kickoff ceiling. Both are deterministic and dependency-free.