Create and run a task

This guide takes you from “I have a thing to do” all the way to a change you can merge, step by step.

1. Frame the task

Write the task description the way you’d brief a careful colleague. Name the file, name the convention, name the constraint. The more exact you are, the better the result.

A good brief:

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.

A weak one:

Improve settings logging.

2. Start the run

Kick off the task with one command:

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

Want the dashboard open alongside the terminal? Add --ui:

vibe run "..." --ui

A Flow is the routine of steps Vibestrate works through. If the work warrants the extra rigor, pick a heavier one:

vibe run "..." --flow quality-arbitration

Override the AI provider for just this run:

vibe run "..." --provider claude

3. Watch, or walk away

Vibestrate runs through plan → architect → execute → validate → review → fix → verify on its own. You can watch each phase in the terminal or the dashboard, or close the terminal and check back later. The run keeps going as long as Vibestrate’s process is alive.

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

4. Inspect the result

See what landed, then dig into the details:

vibe status                  # what landed
vibe replay <runId>          # full read-only inspector

Or open the dashboard’s Git tab to read the diff inline.

5. Merge it yourself

Vibestrate does not push and does not merge. The run leaves the diff on its branch in the worktree, and the final call is yours.

Before you decide, you can ask the merge advisor:

vibe integrate advise <runId>

It is read-only and deterministic. It gives you risk flags first (did any check actually run? does the change touch protected files?), then the dry-run conflict report, the branch topology, and a recommendation: finish now, stage on an integration branch, or resolve conflicts first. Nothing is merged, no branch is touched. Add --json to emit the full advice for scripts. The same window lives on the dashboard’s Merge page.

When the advisor suggests staging is configurable. It is suggestion-only and never blocks:

vibe config set merge.advisor.suggestIntegrationBranchWhen.filesTouched 40
# also: .protectedPaths (true/false), .behindMain <commits>

For a deeper look, run vibe integrate analyze <runId> (or click the Analyze deeper button on the Merge page). This optional read-only pass has a local provider read the run’s diff against main and report semantic risk that a textual merge check can’t 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 (secret-like files suppressed, secret-shaped tokens removed), and the result is cached under the run.

Then you decide. The branch is yours to take in one of three directions:

To get a human review or just share the branch:

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

To merge it locally instead:

git checkout main
git merge --ff-only vibestrate/<runId>-<slug>

Or to abandon it:

vibe abort <runId>
# worktree is preserved for inspection; remove when you're done

Related

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