Ask your agent to do the work

The requests on these pages

02A task page opens with a block you can copy into any agent that has the vibevm skill: it names the thing, states the result, and mentions no secrets. Under it, needs lists what the agent must have (the skill, network access, a token in the environment), outcome says what you will see when it worked, and the assert lines are commands that must succeed afterwards. The asserts are the point: an agent's answer cannot be checked by its wording, but a command's exit code can. Run them yourself, or ask the agent to run them and show you the results.

03 Prompt first. Any action in VibeVM is done by an agent or by hand, and the agent is the main road. A scenario page opens with a prompt block: the plain request in the user's voice, self-contained (coordinates, paths and registry named, never implied), one prompt for one outcome, free of secrets, neutral to the agent (it works for any agent with the vibevm skill), at most sixty words; beside it needs (what the agent must have) and outcome (what the person sees when it worked), and at least one assert — a shell command that must exit zero after the agent's work, because a prompt cannot be checked by its output the way a shell example can. A prompt without an assert on a scenario page is a style-linter error; an illustrative prompt on an explanation page is marked assert="none". vibe doc check --prompts runs every prompt through the configured agent runner ([doc.prompts] runner) in a clean temporary directory with the fixture and then runs the asserts; it is not part of the panel — it runs in the prose phase before acceptance, as a sample in the monthly loop, and in full at reconciliation. The skill vibevm-docs takes a page's prompt as the task when the user asks for what the page describes.

04A request that includes a step that cannot be undone, publishing or deleting, says that the agent must confirm before that step. Keep that line when you adapt a request.

How vibe knows an agent is calling

05vibe behaves the same whether a person or an agent types the command, with one refinement. An agent identifies itself with --invoked-by <name> or the environment variable VIBE_INVOKED_BY. Every machine-readable report then carries that name, so logs show who did what. The installed skill tells the agent to pass it. In a script, --unattended answers every confirmation and refuses to open any interactive wizard.

06 Decision. Mode is not a global flag the user sets; it is inferred per operation from how vibevm was reached and what backend is available.

Two ways for an agent to reach vibe

07An agent can run vibe as a command, one process per call, which is the natural way for a quick question or a wide scan. Or it can talk to vibe mcp serve, a persistent server registered by vibe mcp install, which answers questions about the project's packages and can run the same operations without spawning a shell each time. The operation is defined once; which door the agent uses is the agent's choice, and the skill teaches it the heuristic.

08 Decision. A reasoning/agentic operation is defined once, as a transport-agnostic core (the Intent-producing function over a project context), and exposed by two thin adapters:

When vibe hands the job back

09vibe has no model inside it. When an operation needs reasoning, such as explaining a project in prose, vibe does not attempt it: it composes an instruction and parks it in the project's relay mailbox, .vibe/agentic/command.md. The agent then runs vibe command, which prints the instruction and clears the mailbox, and carries it out with its own model. There is no automatic write-back: if the result should reach vibe, the agent runs the command that records it.

10 Decision. When a reasoning operation runs under the relay backend, it does not act. It writes an Intent — a markdown prompt with light frontmatter (id, source command, created-at, status) — to a single-slot mailbox, the project-local .vibe/agentic/command.md (§3), and returns a pointer telling the caller to drain it.

11 MVP carries no write-back (req r4): the relay is fire-and-forget.

12 The consumer seam is one command, vibe command: it prints the pending Intent to stdout and clears the slot (consume-on-read; the spent intent is archived to .vibe/agentic/command.done.md).

13 Decision. The first vibe agentic operation, explain, exercises the whole relay with zero real risk. Run under an agent, it parks an Intent to .vibe/agentic/command.md of roughly:

vibe agentic explain --path hello-vibe

intent queued — run `vibe command` to fetch it, then carry it out

vibe command --path hello-vibe

---
vibevm-intent: pending
source: agentic explain
---

# Explain this project

Detected in this project: vibe.toml.

Explain this project to a developer seeing it for the first time, in at most three short paragraphs of plain prose.

Work from these sources, in priority order:
1. `README.md` at the project root — read it and summarise what the project is and does.
2. `vibe.toml`, if present — fold in what its structure reveals: the package `kind`, what the project `requires`, and what it `provides`.

If `README.md` is absent, say so in one clause and explain from `vibe.toml` alone. If neither is present, state that the project carries no description and stop. Do not invent features the sources do not support — prefer "the sources don't say" over guessing. Lead with the explanation; no preamble.

16The same handshake governs the build steps a project declares as agent work: when vibe runs under an agent, such a step is parked as a task for the agent to perform, and the same command resumes once the declared outputs exist. Under a person at a terminal, vibe can instead call a configured model provider, and pays for it only when the step actually runs.

17 In agent_mode = "agent" (detected via env — the CLAUDECODE/VIBE_AGENT genre — or forced by --agent-mode), vibe does NOT call an LLM. It parks the work and hands it to the hosting agent: for each agent execution it writes a task file under .vibe/agentic/outbox/<run>/<execution>.md — the resolved prompt, the envelope's prose projection, and the output contract (paths + acceptance) — then prints a fenced vibe-agent-tasks block naming the run id and every task file, and exits the phase with engine status delegated (the handler reply vocabulary remains ok|fail|skip; chain pauses and nothing downstream runs). The hosting agent performs the tasks, writes the outputs, and re-invokes the same phase: vibe finds the outputs, validates them against the contract, marks satisfied executions done and continues — exact-run resumability, no special resume verb. The parking place and relay posture are PROP-018's agentic-relay genre extended from one command to a phase's worth of tasks. An MCP surface (lifecycle_run/lifecycle_tasks) is a second adapter over the same state/outbox, not a second mechanism and not an autonomous development loop (§4.6).

Edge cases and rules

18Running vibe command with an empty mailbox prints that nothing is pending; it is safe to call at any time.

19 Re-running with an empty slot prints "no pending command" and exits 0.

20Run with no agent around it and no built-in engine, an operation that needs reasoning fails loudly and says to run it under an agent; an operation that needs none runs as usual.

21 reached standalone with no engine (today) → a reasoning operation fails loud with "this needs an inference backend; run me under an agent, or wait for the built-in engine," and a non-reasoning operation runs normally.

22Every subsystem of vibe has a complete algorithmic mode; a model only ever improves a result, and each such enhancement is off unless the operator switches it on.

23 Every core VibeVM subsystem retains a complete algorithmic mode. An LLM may improve quality when the operator explicitly enables that feature; credentials, endpoint presence, provider configuration or construction never activate a feature. VibeVM remains useful with no provider, no API access and no agent host.

24An agent that reads this manual by address, rather than through a skill, finds the same requests in the plain-text form of each page; the pages are published for machines as much as for people.