Documentation

Task

The plain-language brief you hand Vibestrate. One sentence kicks off a full plan, build, review, verify run.

A Task is what you want done, written in plain language, the way you would brief a capable colleague. You say what you want. Vibestrate works out the steps.

vibe run "Add structured logging to the settings save handler"

That one line is a complete Task. You don’t list files or set an order. The Flow decides the steps and your Crew does the work. The Task is just the brief.

What happens when you submit one

A Task becomes a run: one supervised process you can watch and audit. In order, the orchestrator:

Reads your projectLanguage, package manager, and the validation commands it will trust later.

Picks Flow and CrewThe default Flow unless you choose another, with its seats matched to your Crew's roles.

Opens a clean workspaceA fresh git worktree, so nothing touches your real project until you say so.

Drives the stagesPlan, build, validate, review, fix, verify, looping back through fix when the review asks, up to a limit.

Stops at a verdictIt never pushes and never merges. The diff is yours to land.

That ends at one of three outcomes:

merge_readyThe change is ready for you to keep.

blockedIt needs a decision from you.

failedSomething went wrong mid-run.

Every prompt, output, metric, and decision is written under .vibestrate/runs/<runId>/, so a finished run reads back as a record, not a black box. See Run state for the status list and Workflow for the stage-by-stage path.

You commit one thing, the Task. The orchestrator commits it to the whole flow. The clearer the Task, the cleaner everything downstream.

The Task is the yardstick

The description goes into every agent’s prompt, at every stage. The planner plans from it. The executor builds from it. The reviewer checks the result against it. One sentence is what the run measures itself against.

Plausible in, plausible-but-wrong out. A vague Task does not just plan vaguely. The reviewer then approves that vague plan, because it is checking against the same vague brief. Tighten the Task and the whole chain sharpens.

A Task does not pick your model or set how hard it thinks. That belongs to your Crew and its Profiles. A Task says what to build. The Crew decides who builds it and how much horsepower they get. Change the Task to change the goal; change the Crew to change the muscle.

A good Task vs a weak one

The contrast is the whole lesson. Same goal, two briefs.

A good Task Names the file, names the library, states the constraint up front. The planner gets a concrete anchor, and the reviewer gets a real bar to check against.

A weak Task The planner guesses. The reviewer critiques its own guess. You get a diff that is plausible and probably wrong.

A good Task:

vibe run "Add structured logging to the settings save handler in src/server/routes/settings.ts. Use the existing logger from src/lib/logger.ts. Include the user id and the changed keys, but never the values."

A weak Task:

vibe run "Improve logging"

Checklists: break a Task into items

A Task can hold an ordered checklist of items, the concrete breakdown of the work. Items live inside the card, so the context stays in one place instead of scattering across small cards.

vibe tasks checklist add  <taskId> "/health returns json"
vibe tasks checklist add  <taskId> "test the endpoint"
vibe tasks checklist list <taskId>
vibe tasks checklist check <taskId> <itemId>      # mark done
vibe tasks checklist status <taskId> <itemId> in_progress
vibe tasks checklist move <taskId> <itemId> 1     # reorder (1-based)

The same actions live on the task detail page in Mission Control: add, check off, edit, drag-reorder, remove. Each item carries a status: pending, in_progress, done, or blocked.

Open a step

A checklist entry is a step - a unit of work in its own right, not just a line of text. Open one from the checklist to get its detail drawer: the step’s own authoring (title, and for supervised tasks its objective, acceptance check, and file hints), its status, the run and one-line outcome that executed it, and a comment thread scoped to that step.

The parent task owns the shared scaffolding - the context every run is grounded in, the Crew that does the work, the git branch, and any blocking tasks. The step drawer shows those as inherited from the parent, read-only, because a checklist runs in one worktree on one branch: every step shares one container. To change them, edit the parent. A plain task’s step has no per-step run of its own (a plain task runs holistically); its run and outcome appear once you run the task supervised.

Opening a step is distinct from detaching it. Detach (the old “promote”) spins a step off into its own independent card with derivedFrom pointing back - a separate, deliberate action for when a piece of work has outgrown the checklist.

To draft a checklist instead of writing one by hand, let an assist propose it:

vibe tasks enhance <taskId>            # read-only: prints a proposed checklist
vibe tasks enhance <taskId> --apply    # append the proposed items

Enhance is a one-shot, read-only assist. It proposes an ordered breakdown; you decide whether to add it. The model never writes to the board on its own.

Pick up: run the whole checklist

Once a Task has a checklist, pick it up to run every item in one worktree:

vibe tasks pickup <taskId>          # continuous: items back-to-back
vibe tasks pickup <taskId> --step   # pause between items for review

“Run checklist” on the task does the same. Under the hood this runs the built-in pickup flow: one holistic plan, then a micro-plan and implement band per item, then one holistic review. Each item commits on its own, stamped with the item id so it can be reverted alone. A compact summary of each finished item carries forward, so later items have context without re-reading every diff. Status and commit sha are written back as the run goes. Execution is linear and stops on the first failing item.

Per-item review: the `pickup-review` flow

For higher-stakes checklists, use pickup-review instead of the default pickup:

vibe tasks pickup <taskId> --flow pickup-review

pickup-review adds a review panel and an arbiter inside the per-item band - after the implementer writes each item, the panel reviews that item’s diff, and a bounded per-item fix loop runs before the item commits. This means each item is reviewed in isolation, with full context of only that item’s change.

Configurable lenses. The panel runs two lenses by default: correctness (logic, type-safety, edge cases) and security-risk (injection, auth gaps, data exposure), both aimed at the active persona if one is set. You can change which lenses review each item: set checklistReview.lenses on the flow, or checklistReviewLenses on a crew (precedence: crew > flow > default). The lens vocabulary is closed (correctness, tests, security-risk, authz, secrets, injection, ux-ia, accessibility, visual-consistency, performance); each selected lens becomes one read-only reviewer per item (up to the parallel fan-out limit of 4 lenses per panel), and the arbiter weighs them all.

Cost. Each item runs the panel independently: two reviewer turns and one arbiter turn per item, on top of the normal implement band. For a 10-item checklist that is 30 extra turns. Use pickup-review when correctness per item matters more than speed.

Cap-and-continue. If an item’s fix loop ends with findings still open, the run continues (it never hard-aborts a checklist mid-stream), but that item is flagged as not merge-ready. The gap is surfaced item by item in vibe assurance, vibe audit, and the dashboard verdict panel. A run that ends with any open-findings item cannot reach merge_ready until the gap is resolved. Nothing passes silently.

Each item keeps its own arbitration ledger, so findings from item 3 never bleed into item 7.

”Needs testing”: when a human should look

A reviewer or verifier can end a run with a non-blocking advisory: the change is fine to ship, but a human should eyeball something a model cannot perceive, like layout, animation, or UX feel. The run still reaches a normal verdict; it is not stuck like an approval gate. The card is flagged Needs testing with a one-line reason. Resolve it with a verdict: “Looks good” marks the Task Done, “Needs work” reopens it. The flag shows as a banner on the task and a badge on the board.

A checklist step is a piece of what to build - a unit of work inside the Task. It is not a Flow phase (plan, implement, review); a Flow phase is run by a seat, and is a different concept. Same word, different layer: a checklist step is what to build, a Flow phase is how a run is structured.

Practical tips

One outcome per Task. Two unrelated changes make the review noisy and the diff hard to ship.
Name the surface. A file path, a module, a feature flag. Give the planner an anchor.
State the constraint. If “don’t touch X” matters, say so in the Task, not after the diff lands.
Put stable context in skills. Conventions, security rules, and domain language belong in skills, not in every prompt.

Flow - the recipe a Task runs through.
Workflow - the stages a Task moves through.
Run state - the statuses a Task accumulates.
Worktree - where a Task’s edits live before you merge.