October 5th, 2026

Turn an Engineering Goal Into a Reviewable Task Handoff

Vidbyte CLI

agent handoff

engineering tasks

acceptance checks

9 min read

Use Vidbyte CLI to frame a goal, inspect a next-action suggestion, and package the selected task for another agent—with the current limits made explicit.

A goal says what you want; an executor needs a bounded task

“Make the CLI easier for a new developer” gives a coding agent a destination, but leaves it to guess what already exists, which constraints matter, and how anyone will know the work is finished. If another agent takes over later, those guesses become hidden assumptions. A reviewable handoff makes the selected next action and its boundaries visible before implementation begins.

A one-line ticket can lose the current state; forwarding a long chat transcript can bury the decision that matters; re-explaining the task to a second agent can change its constraints. A task packet gives the person handing work off a short artifact to inspect and the next agent a structured starting point.

The Vidbyte CLI suggestion workflow has two separate steps. agents suggest run returns a ranked list of ideas and a handoff for each. After a person selects an idea, agents suggest handoff extracts that one packet. Neither command edits a repository or authorizes another agent to act.

Run the suggestion agent with enough context to review its answer

Generate and inspect a suggestion

This example asks for a tested quickstart. It includes a settled documentation decision, existing work, work in progress, a constraint, and what the downstream executor can do. The copy button above provides a reusable task brief with placeholders; fill it in for your own repository and pass the relevant context sources alongside the generated JSON.

Generate a suggestion batch

bash
vidbyte-cli --format json agents suggest run \ --goal "Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion." \ --category coordination \ --count 2 \ --decision "Keep the example within commands and features documented in the current CLI README." \ --constraint "Do not require a backend deployment or paid runtime admission." \ --completed "The CLI install and top-level command reference already exist." \ --in-progress "A separate docs refresh is being planned." \ --capability "The executor can inspect the local repository and run the documented CLI commands." \ > suggestions.json

On vidbyte-cli 0.3.4, the current PyPI release, this command runs each generator and critic turn on your own Codex or Claude Code, so OpenAI or Anthropic bills the model usage to your own account, and Vidbyte charges 1 cent for each suggestion you ask for before the run starts. It writes a versioned JSON result that can be inspected by a person or passed to the next CLI command.

In the CLI version that produced the excerpt below, the acceptance check came from a category template, and the success criterion in your own task brief did not make it tailored. Review and rewrite generic criteria before sending work to an executor.

Here is a field excerpt from the actual JSON result for this request. It proposes “Do the coordination step” and “Observable coordination outcome exists.” That is too vague to give to a coding agent as an implementation task. The example is useful because it shows why ranking and a complete JSON shape do not make an idea correct or ready.

Excerpt from the actual JSON suggestion result

JSON
{ "kind": "suggestions.result", "data": { "goal": "Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.", "ideas": [ { "id": "idea-001", "title": "Coordination: Create a tested CLI quickstart that", "first_action": "Do the coordination step for: Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.", "completion_criteria": "Observable coordination outcome exists." } ] } }

Extract one idea as a portable task packet

Extract the selected idea as a handoff

Once you select an idea ID, the handoff command validates the saved result and extracts the matching packet. This operation is local and makes no model call. It does not send the packet to another agent: you decide whether it is good enough, then pass the JSON and any referenced source material to your coding agent.

Extract the selected handoff

bash
vidbyte-cli --format json agents suggest handoff --input suggestions.json --idea idea-001 > handoff.json

This field excerpt is from the same actual output, so it shows the earlier CLI's packet. On vidbyte-cli 0.3.4 the packet holds the goal, suggested actions, the decisions the executor will face, things to consider, cited evidence, completion checks, dependencies, warnings, forbidden actions, stop conditions, and a return-report request. Cited context, including file text, is quoted only up to 4,096 characters per item, so pass the full sources separately when the coding agent must inspect them. Extraction preserves the generic action; it does not improve it.

Excerpt from the actual handoff JSON

JSON
{ "kind": "suggestions.handoff", "data": { "original_goal": "Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.", "current_state": "Completed: The CLI install and top-level command reference already exist. In progress: A separate docs refresh is being planned.", "constraints": ["Do not require a backend deployment or paid runtime admission."], "acceptance_checks": ["Observable coordination outcome exists."], "stop_conditions": [ "Done when acceptance checks pass.", "Stop on contradictory evidence.", "Stop when authority or prerequisites are missing." ], "authority": "not_granted_by_this_handoff" } }

If you choose the convenience execution_prompt field instead of the full JSON packet, this is the exact prompt that earlier run produced. vidbyte-cli 0.3.4 renders a longer prompt that prints every field of the packet:

Actual execution_prompt field

Goal: Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.
Action: Do the coordination step for: Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.
Why: A coordination move is due now for this goal.
State: Completed: The CLI install and top-level command reference already exist.. In progress: A separate docs refresh is being planned..
Steps:
- Do the coordination step for: Create a tested CLI quickstart that helps a new developer reach their first successful agent suggestion.
- Observable coordination outcome exists.
Acceptance:
- Observable coordination outcome exists.
Stop when:
- Done when acceptance checks pass.
- Stop on contradictory evidence.
- Stop when authority or prerequisites are missing.
Authority: not_granted_by_this_handoff
Report: Report outcome, evidence, and follow-ups to the calling agent.

What a handoff gives the next agent

A freeform sentence can carry the goal, but it often loses the project state around it. The typed handoff keeps several parts separate so the executor and reviewer can see what was supplied, what should happen next, and where the task must stop.

Field groupWhy it helps
Goal and statePreserves the requested outcome. Completed and in-progress work you supplied appears only where the idea cites it as evidence.
Decisions and limitsLists the decisions the executor will face, things to consider, warnings, and any --forbidden actions. Your --decision, --constraint, and --capability values appear only where the idea cites them as evidence.
EvidenceQuotes each cited context item with its source, cut to 4,096 characters. Pass the full files along when the executor needs to inspect them.
Finish lineIncludes suggested actions, dependencies, and completion checks.
ControlNames stop conditions and explicitly says the handoff grants no authority to execute.

With an existing Vidbyte coding agent, a person can review this packet, pass it in as task context with the referenced files, and ask the agent to return the requested evidence and follow-ups. The agent and reviewer then start from the same visible goal, state, constraints, and stop conditions. That can prevent task details from being lost between agents and gives the reviewer an explicit contract to check. The CLI only creates the packet; it does not dispatch the task or grant tools and permissions.

That structure can reduce repeated setup when work changes hands: the next agent can see the goal, the evidence the idea cites, what to check before calling the work done, and what should cause it to stop. The acceptance check gives a reviewer a question to answer instead of an “I’m done” claim. Those are workflow advantages, not measured time savings or proof that this current suggestion agent finds the best next step.

Pass the structured packet when details matter

In vidbyte-cli 0.3.4 the convenience execution_prompt prints every field of the packet: goal, action, summary, steps, decisions, things to consider, cited evidence, completion checks, dependencies, warnings, forbidden actions, stop conditions, authority, and report request. Your own constraints and settled decisions appear only where an idea cites them, so restate any that are missing in the executor's task. The person handing it off must also provide the full referenced files or source material.

Before implementation, make the proposed action specific enough to act on and make each acceptance check observable. If the current generated handoff stays generic, do not treat its “ready” label as approval; write the bounded task yourself and have the coding agent inspect the repository before editing.

Use the handoff when work needs context to survive a change of agent

This workflow is most useful when a broad engineering goal needs to be broken down, when project constraints or previous work matter, or when one agent will recommend work and another will implement it. For a tiny, obvious edit, a direct task may be shorter. For a complex task, the handoff's explicit checks and stop conditions give the person reviewing the plan a concrete place to challenge it.

A suggestion can still be generic

The excerpt in this walkthrough came from an earlier CLI that built ideas from category templates and deterministic goal-word overlap. Today a model running on your own Codex or Claude Code drafts and critiques each idea, but a first action can still be vague. Reject or rewrite it before handing it to a coding agent.

A handoff is not verification

Acceptance checks describe what to prove; they do not run tests or certify that the result passes. Ask the executor to report exact commands and outcomes, then inspect them yourself.

The packet carries only the context an idea cites

In vidbyte-cli 0.3.4 the execution_prompt prints every field of the packet, but your own constraints and settled decisions appear only where the idea cites them as evidence. Restate any that are missing before you hand the task off.

See the CLI command reference for current flags and the agent setup guide for downstream agent setup.

Run the handoff on your own goal

The Suggestion Agent charges its per-suggestion fee to your Vidbyte API balance before the run starts, while your own Codex or Claude Code bills the model usage to your provider account. Add usage first so the run is not refused.