fleetq-run-experiment

name	fleetq-run-experiment
description	Create, run, monitor, and recover a FleetQ experiment through its 20-state pipeline via MCP tools or the REST API.

Run a FleetQ experiment

An experiment is FleetQ's unit of autonomous work: it moves through a 20-state pipeline (scoring → planning → building → approval → executing → metrics → evaluation) with budget enforcement and an audit trail at every step.

Requires a working connection — see the fleetq-connect skill first.

Create and start

MCP tools:

Tool	Purpose
experiment_create	Create the experiment.
experiment_start	Move it out of draft into the pipeline.
experiment_get	Read current state, stage, and cost.
experiment_list	Enumerate experiments for the team.

REST equivalent:

POST {{APP_URL}}/api/v1/experiments
POST {{APP_URL}}/api/v1/experiments/{id}/transition
GET  {{APP_URL}}/api/v1/experiments/{id}

Monitor progress

• experiment_steps — per-step execution detail.
• experiment_stage_telemetry — timing and stage-level metrics.
• experiment_cost — credits consumed so far.
• experiment_valid_transitions — which transitions are legal right now. Call this before attempting a transition; the state machine rejects anything not in the map.

Intervene

Situation	Tool
Needs to stop temporarily	experiment_pause / experiment_resume
Needs to stop permanently	experiment_kill
A stage failed and you want another attempt	experiment_retry
A specific step failed	experiment_retry_from_step (resets that step and everything downstream)
Long-running work was interrupted	experiment_resume_from_checkpoint
You want to redirect it mid-flight	experiment_steer
You want to understand a failure	experiment_diagnose

Rules that will bite you

• Transitions are validated. ExperimentTransitionMap rejects illegal moves — always check experiment_valid_transitions rather than guessing.
• Terminal states are final: completed, killed, discarded, expired. There is no transition out; create a new experiment.
• Budget is enforced before execution. An experiment pauses automatically when the team's credit balance cannot cover the reservation (reservations use a 1.5× multiplier). Check budget_summary first if you expect long runs.
• Approval gates block execution. If the experiment enters awaiting_approval, a human (or an agent with approval permission) must act via approval_approve before it proceeds.