Create and run a task

This guide takes you from “I have a thing to do” to a change you can merge. Mission Control is the primary surface; the commands below are the automation path, and each section names the screen that does the same thing.

vibe run "Add retry with backoff to the uploader" --ui

Write the task description the way you would brief a careful colleague. Name the file, the convention, the constraint.

Good. Add audit logging to the settings save handler at src/server/routes/settings.ts. Use the existing auditLogger from src/lib/audit.ts. Log the user id and the keys changed - never the values.

Weak. Improve settings logging.

New run, at the bottom of the sidebar, opens the composer. Five sections, and the defaults are the answer to four of them:

• Task - the brief you just wrote.
• Flow - Auto unless you disagree with what it picks.
• Inputs - any params the chosen flow declares.
• Crew - which roster takes it.
• Configuration - Permission, Unattended, a Tuning pair of Concise and Auto-pick flow, and the Supervisor persona.

Start run launches it as a detached process, so it outlives the browser tab and you can close the window.

From a terminal:

vibe run "Add audit logging to the settings..."

Three flags cover most of what you would otherwise change in Configuration - open the dashboard alongside, take a heavier Flow, or use a different model:

# dashboard alongside the terminal
vibe run "..." --ui

# a heavier flow than the default
vibe run "..." --flow quality-arbitration

# a different model for this run
vibe run "..." --profile <id>

vibe profile list shows the profile ids your project has. Unlike Start run, vibe run does the work in the terminal you started it from, so that terminal has to stay alive.

Open the run from the sidebar and the Live timeline tracks the steps as they happen, beside Live metrics and Changed files. Watching is optional - the run does not need you - but it is the fastest way to learn the shape. See Inspect a run in flight.

The default flow is four steps, and Vibestrate works through them on its own:

The implementer’s turn ends with a scoped self-review of its own diff. When the review asks for changes, the findings go back to that same implement step rather than to a separate fixer seat, and implement, validate and review run again - three passes at most, the first implementation plus two redos. There is no verify step: merge-ready is an approved review over passing validation. The deep flow is the one that keeps an architecture pass, a dedicated fixer and an independent verify gate. Those names are the step ids too, so the review’s own write-up is at artifacts/flows/review/output.md in the run’s folder.

When the run finishes, it lands in one of four states:

The Runs page lists every run. Open one and the status card says where it got to; the Inspect section below it has seven tabs - Tree, Steps, Events, Artifacts, Validation, Terminal and Replay - and the diff and the files it touched are under Artifacts.

To read the change on its own, the Source page’s Changes tab shows the diff inline, file by file.

From a terminal:

vibe status            # every run, oldest first
vibe replay <runId>    # read-only, one run

Vibestrate does not push or merge (see the safety guarantees). The run leaves the diff on its branch in the worktree, and the final call is yours.

The Source page’s Merge tab is where you make it. Pick the run and it fetches the merge advice: a headline, a recommendation chip - finish-now, stage-on-integration-branch or resolve-first - any warning flags, and tiles for how far ahead and behind main the branch is and how many files it touches.

Three buttons act on it:

• Analyze the diff - the optional deeper pass, described below. Reads only.
• Integrate this run - brings the branch onto an integration branch.
• Complete merge to main - the last step, and it asks first.

The advice is read-only and deterministic: same run, same answer, no model in the loop. Nothing is merged and no branch is touched until you press one of the last two.

From a terminal, the same advice:

vibe integrate advise <runId>

It prints the headline, the risk flags (does the change touch protected files? did any check actually run?), the branch’s position against main, which checks passed, and the recommendation with its reason. --json emits the full advice for scripts.

When it suggests staging is configurable, suggestion-only and never blocking. Three thresholds decide it; these are the defaults in project.yml, editable on More > Config or with vibe config set:

merge:
  advisor:
    suggestIntegrationBranchWhen:
      filesTouched: 25
      protectedPaths: true
      behindMain: 50

Analyze the diff, or vibe integrate analyze <runId>, has a local provider read the run’s diff against main and report semantic risk a textual merge check cannot see: concurrency, error handling, missing tests. It is advisory prose, never a merge verdict, and it never changes the deterministic recommendation. Before the provider sees it the diff is byte-capped and redacted, and the result is cached under the run.

The branch is yours to take in one of three directions:

cd ../.vibestrate-worktrees/<runId>
gh pr create      # review by a human
git push          # just share the branch

# or merge it locally
git checkout main
git merge --ff-only vibestrate/<runId>

# or abandon it; the worktree is preserved for
# inspection, remove it when you're done
vibe abort <runId>

• Inspect a run in flight.
• Pause, resume, abort.
• Debug a failed run.