VibeDev Flow Designer (Job Builder)

Goal

Turn a short “what I want to build” description into a real VibeDev job in the Store by using the VibeDev MCP planning tools.

This skill is for PLANNING mode only: you are producing planning artifacts that compile into steps. You are not implementing code changes.

Canonical Reference (don’t duplicate the spec)

When you need authoritative schema/behavior, open these repo docs instead of guessing:

• docs/07_doc_map.md (index)
• docs/00_overview.md (two-thread workflow + behavioral contract)
• docs/02_step_canvas_spec.md (conceptual StepTemplate)
• docs/03_gates_and_evidence.md (gate catalog + EvidenceSchema)
• docs/04_flow_graph_and_loops.md (retry/diagnose/escalate loop)

When you need what the MCP tools actually accept today (Pydantic models), open:

• vibedev_mcp/server.py (tool input shapes, defaults)
• vibedev_mcp/conductor.py (planning interview phases + required keys)

Workflow (PLANNING → READY)

0) Decide the minimal job shape

Collect (from the user request or a short follow-up):

• Title: short and specific
• Goal: 1–2 sentences, outcome-focused
• Repo context: existing repo vs greenfield
• Target environment: OS, runtimes, constraints (e.g., “Windows + Python 3.11”, “Node 20”)
• Out of scope: explicit bullets (prevents creep)

1) Create the job (conductor_init)

Call conductor_init with:

• title
• goal
• repo_root only if there is an existing repo and you know the absolute path
• optional policies

Recommended policies for reliable gating (safe defaults):

• evidence_schema_mode: "strict" (forces criteria_checklist when steps have acceptance criteria)
• keep enable_shell_gates: false unless the human explicitly opts in (command gates are powerful)

2) Drive the planning interview (conductor_next_questions / conductor_answer)

The conductor phases are enforced by required keys (see vibedev_mcp/conductor.py).

Answer questions by calling conductor_answer with an answers object containing keys like:

• Phase 1 (Intent & Scope):
  • repo_exists: boolean
  • out_of_scope: bullets (string or list; be consistent)
  • target_environment: string
  • timeline_priority: string (“MVP”, “robust”, etc.)
  • user_constraints (optional): string
• Phase 2 (Deliverables):
  • deliverables: list[str]
  • definition_of_done: list[str]
  • tests_expected (optional): string or list of commands
• Phase 3 (Invariants):
  • invariants: list[str] (use [] explicitly if none)
• Phase 4 (Repo context; only if repo_exists=true):
  • repo_root: absolute path string
  • key_files (optional)
  • entrypoints (optional)

Tip: For deliverables / DoD / invariants, you can also call dedicated tools: plan_set_deliverables, plan_set_definition_of_done, plan_set_invariants.

3) Compile a small, verifiable plan (plan_propose_steps)

Build an ordered list of small steps. Each step should be “one reviewable diff” maximum.

Each step is a StepSpec (see vibedev_mcp/server.py), with fields:

• title: short
• instruction_prompt: the executor prompt for that step (execution runway; keep it precise)
• expected_outputs: list of concrete things produced in that step (files/commands/notes)
• acceptance_criteria: list of checkable statements (“X exists”, “tests pass”, “no changes outside Y”)
• required_evidence: list of evidence keys required for this step (e.g., changed_files, commands_run)
• gates (optional): list of {type, parameters, description}
• remediation_prompt: what to do if rejected (retry guidance)
• context_refs: optional list of context block IDs (if you stored any via context_add_block)

How to write good steps (practical)

• Prefer 3–7 steps for most jobs; each step must be independently verifiable.
• Every step must include:
  • Scope boundaries (allowed paths / forbidden actions)
  • A success checklist (acceptance_criteria)
  • Evidence requirements (required_evidence)
• If you include command gates (command_exit_0, command_output_contains, command_output_regex):
  • You MUST set job policies:
    • enable_shell_gates: true
    • shell_gate_allowlist: ["<pattern1>", "<pattern2>", ...]
  • Otherwise the gate will deterministically fail as “blocked by policy”.

Default step skeleton (copy pattern)

Use this structure inside instruction_prompt:

1. Objective: (one sentence)
2. Non-negotiables: (repeat key invariants + step-specific constraints)
3. Allowed change surface: (paths / allowlist)
4. Tasks: (numbered, minimal)
5. Evidence required: (exact keys you will submit)
6. If stuck: (remediation)

4) Refine without replacing (plan_refine_steps)

After an initial plan, prefer targeted edits with plan_refine_steps:

• update a step’s prompt/criteria
• insert_before / insert_after to add a missing checkpoint
• delete to remove redundant steps

This keeps diffs small and avoids accidental plan churn.

5) Transition to READY (job_set_ready)

Once required artifacts exist (deliverables, invariants, DoD, steps + step order), call job_set_ready.

If it fails, inspect missing fields and go back to the planning interview or step proposal.

Common Failure Modes (and fixes)

• Command gates failing immediately: you included command gates but didn’t opt in via enable_shell_gates + shell_gate_allowlist.
• Steps too big: split into smaller steps and add a checkpoint step (e.g., “run tests + summarize evidence”).
• No real definition of done: rewrite DoD into checkable items (tests/commands/files).
• Invariants vague: rewrite as enforceable rules (“No changes outside X”, “No new deps”, “No refactors”).

Output Standard

When you finish planning, output a compact summary:

• job_id
• Deliverables (bullets)
• Definition of done (bullets)
• Invariants (bullets)
• Step list: step_id + title + one-line objective per step