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
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 1 \
--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.jsonIn the current CLI, this command runs locally without backend admission or provider credentials. It writes a versioned JSON result that can be inspected by a person or passed to the next CLI command.
The generated acceptance check still comes from a category template. The success criterion in your own task brief does not make this version generate a tailored check, so 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
{
"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
vidbyte-cli --format json agents suggest handoff --input suggestions.json --idea idea-001 > handoff.jsonThis field excerpt is from the same actual output. The packet also includes decisions, context references, assumptions, steps, deliverables, dependencies, capabilities, and a return-report request. Those context references identify inputs; the packet does not bundle the original files or their contents. Pass those 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
{
"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 the current run produced:
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 group | Why it helps |
|---|---|
| Goal and state | Preserves the requested outcome and caller-supplied completed or in-progress work. |
| Decisions and limits | Carries settled decisions, constraints, and available executor capabilities as separate fields. |
| References and assumptions | Names required context and assumptions. The referenced source files and context bodies are not bundled; pass them along when the executor needs to inspect them. |
| Finish line | Includes suggested steps, deliverables, dependencies, and acceptance checks. |
| Control | Names 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 which decisions are settled, which work is already done, what evidence to produce, 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
The JSON packet contains decisions, constraints, dependencies, and capabilities. Its convenience execution_prompt is shorter: it includes the goal, action, reason, state, steps, acceptance checks, stop conditions, authority, and report request, but omits some structured fields such as explicit decisions and constraints. If those details affect the work, pass the JSON packet to the executor or copy the omitted details into its task. The person handing it off must also provide the 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.
The current suggestion can be generic
The CLI currently generates category templates and orders them with deterministic goal-word overlap. It does not yet turn the supplied context into a tailored plan. Reject or rewrite a vague first action 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 rendered prompt is shorter than the packet
The JSON handoff carries decisions, constraints, dependencies, and capabilities. The convenience execution_prompt omits some of those fields. Pass the structured packet when that context matters, or copy the missing details into the task yourself.
See the CLI command reference for current flags and the agent setup guide for downstream agent setup.