DOCS · DISPATCH
ALL DOCS FIG. 15 · DWG VC-015

Dispatch Schema (vibecrafted.dispatch.v1)

TOML reference for dispatch plans: meta, policy, phases, cuts, verify matchers, recovery, and placeholder rendering.

Canonical source — docs/public/dispatch/dispatch-schema.md

Dispatch Schema (vibecrafted.dispatch.v1)

A dispatch plan is a TOML file with schema = "vibecrafted.dispatch.v1" at the top level. The parser fails closed: schema violations refuse the whole plan with a list of errors. Validate with vibecrafted dispatch <plan> --doctor before launching.

Minimal plan

schema = "vibecrafted.dispatch.v1"

[meta]
name = "my-line"
repo = "~/projects/my-app"

[common]
text = """
Repo: {repo}
Durable artifact plane: {reports_dir}
Baton: {baton}
"""

[[cuts]]
id = "c1-first-cut"
agent = "codex"
workflow = "implement"
prompt = "Implement cut {id} in {repo}."

  [[cuts.verify]]
  run = "cd {repo} && make test"
  expect = { contains = "passed", exit_code = 0 }

Top-level fields

FieldRequiredMeaning
schemayesMust be exactly "vibecrafted.dispatch.v1"
[meta]yesPlan identity and paths
[policy]noSupervisor behavior (defaults below)
[common]noText prepended to every cut prompt
[workflow_map]noAlias → supported workflow mapping ([workflows] accepted)
[[phases]]noNamed phase groups for cuts
[[cuts]]yesAt least one cut
[execution]noTyped execution envelope; fails closed on unknown fields (advanced, subject to change)
[proof]noOpaque payload passed to workers verbatim; dispatch never interprets it

[meta]

KeyRequiredMeaning
namenoPlan name
repoyesRepository path, rendered into {repo}
descriptionnoFree text
baselinenoTable, e.g. { branch = "main", head = "<sha>" }
reports_dirnoRendered into {reports_dir}
trackernoTracker path, rendered into {tracker}

reports_dir and tracker are optional. When set, they must live under the canonical global artifact plane (~/.vibecrafted/artifacts or $VIBECRAFTED_HOME/artifacts) after path normalization. Prefix matches such as ~/.vibecrafted/artifacts-typo are not that plane. Traversal (artifacts/../../.codex) and existing symlink escapes are resolved even when the destination file does not yet exist, then checked against the directory boundary. If symlink resolution raises, the path is not admitted as the canonical artifacts plane. New dispatch writes that omit them allocate there:

~/.vibecrafted/artifacts/<org>/<repo>/YYYY_MMDD/{plans,reports,...}

Provider-specific roots (~/.claude, ~/.codex, ~/.gemini, ~/.cursor) and repo-local .vibecrafted paths fail doctor. The canonical artifacts plane itself is accepted.

[policy]

KeyDefaultValues / meaning
repair_rounds0Repair attempts after a failed cut
on_critical_fail"break"break | continue
on_noncritical_dep_fail"stop"stop fences queued cuts after an unverified non-critical contract; continue explicitly permits expendable failures
on_timeout"fail"repair | fail | continue
concurrency1> 1 requires allow_concurrency = true
allow_concurrencyfalseAlso accepted: enable_concurrency, parallel_enabled
verify_executor"supervisor"Who runs verifiers
require_commitfalseRequire a commit from the worker
allow_idempotent_existingtrueAccept already-satisfied cuts

[policy.await]

[policy]
await = { poll_s = 90, timeout_min = 90 }
KeyDefaultMeaning
poll_s90Seconds between worker polls
timeout_min90Minutes before the timeout policy applies

[[phases]]

Optional named groups. title is required and must be unique; detail is free text. When any phases are declared, a cut’s phase must match one of the titles.

[[cuts]]

KeyRequiredMeaning
idyesUnique cut id, rendered into {id}
agentnoFleet agent (claude, codex, agy, junie, grok, cursor)
workflowyesMust resolve (via workflow_map) to a supported workflow
phasenoPhase title, when phases are declared
prompt / briefone requiredInline prompt, or a brief file path (resolved relative to the plan file; must exist)
extranoText appended after the brief/prompt
modeno"write" (default) or "read"
mutationREAD cutsforbid | allow-report-only | allow — doctor requires it on every READ cut
observationalnotrue marks an observational READ cut (observe accepted); the only case where verify may be omitted
criticalnotrue makes failure subject to on_critical_fail
modelnoModel pin for the cut’s agent
verifyusuallyArray of verifier tables (below)
recoveryno{ on = "[!]", goto = "<cut-id-or-phase>", max_loops = <int> } — goto must name an existing cut or phase
depends_onnoCut id array. A cut becomes ready only after every dependency settles successfully; cycles and unknown ids fail parse
basenoPer-cut worktree base: "<sha>", "<branch>", or "cut:<cut-id>". Absent = the plan baseline (below)
integratornotrue names an exclusive WRITE cut that alone may modify the main checkout
compile_embargonoBoolean, default false. Structural WRITE worker posts an unverified checkpoint and defers all executable gates
closes_embargonoCheckpoint cut ids; only a WRITE integrator may declare closure, and every id must be a compile_embargo dependency

Embargo is plan-owned. An integrator cannot itself declare compile_embargo. Checkpoint claims include SHA, owned scope, and every skipped hook or security control. They remain [~]; their declared commands are deferred, not certified. Each skipped control must map to an exact declared verifier command. An unknown hook obligation blocks closure until the plan declares that command. The writer uses the union of integrator and checkpoint declared verifiers in the assembled runtime root; a claim cannot supply executable commands. A closure integrator may assemble its named checkpoint dependencies while they are unverified. It records W2_STRUCTURALLY_CLOSED for the exact assembled SHA and restores full gates. Only the canonical writer’s full verification against that SHA can close the embargo and settle [x]. Payloads cannot grant closure authority or choose a smaller set of gates.

Scheduling and checkout contract

The supervisor parses depends_on as a DAG. It launches all ready workers up to policy.concurrency. By default, a failed or unknown contract stops admission of every queued cut, including cuts without a dependency edge. Already active siblings finish and keep their evidence; they are not terminated by this fence. Repair rounds run before the supervisor decides whether a contract is verified. An integrator is exclusive for the repository and never overlaps another active cut.

Plans that deliberately tolerate an expendable non-critical cut must explicitly set on_noncritical_dep_fail = "continue". Its failure stays in the baton. Critical cuts retain their separate on_critical_fail policy. Worker completion alone never releases the default fence: supervisor verification must be green.

Every non-integrator cut receives:

checkout  ~/.vibecrafted/worktrees/<org>/<repo>/YYYY_MMDD/<cut-id>
branch    cut/<cut-id>
target    <checkout>/target

CARGO_TARGET_DIR is always the cut’s own <checkout>/target. A symlink, escape, ambient shared Cargo target, dirty reused checkout, or wrong branch is a hard refusal. Cold compilation is an accepted isolation cost; a future compiler cache must remain content-addressed and must not merge target dirs.

The scheduler receipt ledger lives under ~/.vibecrafted/control_plane/dispatches/<run-id>/receipts.json and exposes queued, launching, active, reported, verified, integrating, settled, failed, and stopped transitions together with worktree, target, artifact, report, dependency, slot, integration, gate, commit, and cleanup evidence.

Resume with --resume <run-id>. The supervisor consumes receipts and Git ancestry, awaits a still-live process instead of launching a duplicate, and refuses to guess when a dead launch has no report. Remove settled checkout payloads explicitly:

vibecrafted dispatch plan.dispatch.toml --cleanup-settled <run-id>

Branches and durable reports remain. Active cuts are never cleaned.

Per-cut base

depends_on orders time only: a dependent cut still starts its worktree from the plan baseline and never sees its predecessor’s commits. base orders the tree. Each form:

base = "<sha>"        # worktree from that commit (must be reachable in meta.repo)
base = "<branch>"     # worktree from that local branch, pinned at resolution time
base = "cut:w1-02"    # worktree from that cut's delivered_commit_sha (settled receipt)
  • A cut:<id> base requires <id> in the cut’s depends_on — the dependency orders time, the base orders ancestry. The supervisor resolves it at launch, after the dependency settles; --dry-run --json reports it as "<pending: cut-id>".
  • The doctor refuses a cut: base without the matching depends_on, an unknown target, a cycle through base (same check as depends_on), and a sha/branch that is not reachable in meta.repo (“base not reachable in meta.repo”).
  • An explicit base is frozen: the living-tree descendant follow that may advance the plan baseline never applies to base, and --resume keeps the base recorded on the cut’s receipt instead of re-resolving a moved ref.
  • An integrator cannot declare base — it works on the main checkout.
  • Every cut receipt records base_ref (the declaration), base_sha (the resolved commit), and base_source (plan | sha | branch | cut).
  • No base = the plan baseline, exactly as before; existing plans parse and run unchanged. See examples/dispatch/stacked-cuts.dispatch.toml.

[[cuts.verify]]

Each verifier runs a shell command and matches its output. A command must exit with code 0 unless expect.exit_code explicitly declares a different code for a negative-path probe; matching text alone cannot hide a failed command:

[[cuts.verify]]
run = "cd {repo} && make test"
expect = { contains = "passed", not_contains = "FAILED", matches = "[0-9]+ passed", exit_code = 0 }
MatcherTypeMeaning
containsstringOutput contains the substring
equalsstringTrimmed output equals the string
matchesstringOutput matches the regex (validated at parse time)
not_containsstringOutput does not contain the substring
exit_codeintegerCommand exit code equals the value

run is required and must not contain hard-stop commands — the parser refuses --no-verify, git reset --hard, git clean, destructive remote push (force / trunk / delete / tags), rm -rf /, and release invocations. A non-destructive git push origin HEAD of a feature branch is allowed. Outward-facing merge, deploy, and publish still belong to the operator, not to a verifier shell.

Placeholder rendering

Prompts (common.text, prompt/brief body, extra) and verifier run commands render these placeholders:

PlaceholderValue
{repo}Resolved worker checkout; main checkout only for an integrator
{id}Cut id
{agent}Cut agent
{workflow} / {resolved_workflow}Declared / mapped workflow
{reports_dir}Canonical durable artifact root
{tracker}meta.tracker
{baton}Accumulated baton state as JSON — prompts only, never verifier commands

Anything not listed in these tables is not part of the v1 schema. When in doubt, --doctor is the authority: it reports every unknown or invalid field by path (for example cuts[2].verify[0].expect.exit_code).

Brief frontmatter: agent: must equal cuts[].agent

When a cut’s brief (or an inline prompt that itself begins with YAML frontmatter) names an agent:, that value must equal the cut’s cuts[].agent — the selected fleet provider. vibecrafted dispatch --doctor and launch refuse a mismatch with:

cuts[N].model: frontmatter agent conflicts with selected provider

This is independent of cuts[].model. The brief’s agent: is the fleet agent (claude, codex, agy, junie, grok, cursor); the cut must name the same agent. A model pin may still live on the brief as model: or on the cut as model.