PROP-018 — Agentic and standalone modes

1.1 The problem

• 03vibevm has commands that are pure algorithm (install, check, list) and commands that genuinely need reasoning (explain, build, review). The algorithmic ones already run from a bare terminal with no LLM (VIBEVM-SPEC.md §3.2).
• The reasoning ones raise a question of who does the reasoning, and how.

• 04vibevm is almost always invoked by a coding agent (Claude Code, OpenCode, Codex) that already holds a capable LLM, the live context, and the tools.
• For reasoning work in that setting the agent is the right executor — but vibevm is the right author of the task.
• vibevm carries stable, algorithmic knowledge of its own domain (the spec-driven model, the dependency and package rules, the discipline), so an instruction it composes is more informative and more trustworthy than one the agent would improvise from scratch.
• This PROP gives the two their natural roles — vibevm composes the domain-grounded instruction, the agent carries it out — and names the operating contexts so the codebase branches on them cleanly.
• vibevm can also reason with no agent present, via a built-in vibe-llm engine — VIBEVM-SPEC.md §10.4, far-backlog §6 — but that is standalone mode; it is not what makes agentic mode worthwhile.

1.2 The two modes — one axis

05The modes are not two codebases. They are one question: where does an operation's reasoning happen?

• 06agentic — vibevm is driven by a host agent during that agent's own work. For a step that needs reasoning, vibevm composes a domain-grounded instruction and delegates it back to the agent, which executes it on its LLM with the live context vibevm lacks. The split is by strength, not a workaround: the agent is the better executor in-session, vibevm the better author of the instruction. (Pure-algorithm operations still run directly — agentic is about the reasoning steps.)
• standalone — vibevm stands on its own. Reasoning runs on vibevm's own backend: algorithmic where the work allows, and — when vibe-llm lands — a built-in inference engine. Today the standalone backend has no LLM, so the only standalone functionality this PROP ships is the non-reasoning one: projecting skills into agents (§2.6).

• 07The unifying statement (§2.1): a mode is a choice of inference backend. Non-reasoning operations behave identically in both modes; reasoning operations branch on the backend.
• This is the seam everything else hangs off.

1.3 What this is NOT — PROP-006

• 08PROP-006 defines session operating postures: codewords ("move fast and break things") that change how an agent behaves within one work session (whether to pause for confirmation, how freely to spend tokens). Those govern the agent's conduct.
• PROP-018 modes govern where vibevm gets inference — a property of vibevm's execution, orthogonal to any session posture.
• A session can be in "move fast" posture while vibevm runs in agentic mode; the two never collide.
• Do not overload one onto the other.

2.1 A mode is a choice of inference backend

09req r1

• 10Decision. Mode is not a global flag the user sets; it is inferred per operation from how vibevm was reached and what backend is available.
• An operation declares whether it needs inference; if it does, the active backend decides the realisation:

• 11reached as a subprocess of an agent (CLI one-shot or MCP call) → the relay backend (§2.7): delegate the intent back to that agent.
• reached standalone with a built-in engine available (future) → the built-in backend: run inference in-process via vibe-llm.
• 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.
• Why: §1.2 ##UNIFYING-STATEMENT fixes what a mode is — "a mode is a choice of inference backend" — and §2.3 ##AFFINITY-OF-WORK fixes who chooses: "Affinity is a property of the work, not a user choice." Mode-by-inference is that same principle one level up: which backend can serve a call is a fact about the call's reach, not a preference.
• Considered and rejected: a global mode flag the user sets (--mode agentic|standalone or a vibe.toml key) — rejected: a user could then name a backend the operation has no affinity for, which the dispatcher must refuse anyway (##DISPATCHER-REFUSES), or name one that does not exist on this machine, which today is every standalone reasoning call (##REACH-STANDALONE-NO-ENGINE). The flag would be a way to ask for a refusal.
• Revisit when: BuiltinBackend ships over vibe-llm (##FB-BUILTIN-BACKEND, VIBEVM-SPEC.md §10.4) — from that day two backends can both serve one standalone call, and "what backend is available" stops determining the answer on its own. Observation point: the far-backlog item closing, i.e. a vibe-llm inference path in the workspace. Second clause: a reach appears that the inference cannot classify — a persistent console (##FB-CONSOLE) or an invocation through a wrapper that hides the agent parentage — observed as a mis-chosen backend in a bug report.

2.2 The pluggable inference backend

12req r2

• 13Decision. Inference sits behind one trait, InferenceBackend, so an operation never names a provider.
• An operation that needs reasoning constructs an Intent (a structured prompt + the inputs it needs) and hands it to the active backend.
• Two backends are foreseen:

• 14RelayBackend (agent mode) — vibevm authors the Intent and parks it for the calling agent to execute, returning "delegated" (§2.7). Not a stopgap: in agent mode the agent is the right executor.
• BuiltinBackend (standalone mode; far backlog §6) — runs the Intent on vibe-llm in-process, for when no agent is present.

• 15This is deliberately not over-built: the trait exists so reasoning operations are written once against an abstract backend, and the standalone engine slots in later without touching them.
• Operations with a single natural home (skill-install is standalone-only; a "rewrite this spec section" op may be agentic-only until the engine exists) simply do not offer the other backend (§2.3).

2.3 Per-operation backend affinity

16req r2

• 17Decision. Each operation declares an affinity: agentic-only, standalone-only, or both.
• Affinity is a property of the work, not a user choice — scanning a manifest is standalone-only (pure algorithm, needs no agent); a free-form "explain this project in prose" is agentic-only until the built-in engine exists; a task expressible either as a deterministic pass or as reasoning is both.
• The dispatcher refuses an operation invoked through a backend it has no affinity for, with a message naming the right one.

2.4 Agent-installable artifacts are declared separately from the package kind

18req r3

• 19Decision. A package declares which of its files are skills for agents in a dedicated manifest section — not by introducing a package kind of its own. The kind register (package_ref.rs, VIBEVM-SPEC.md §4.1) stays closed to skills.
• Why: skills can live inside a package of any kind and be structured any way. A tool package vim can ship the tool itself plus a skill for driving vim — one self-contained package, two artefact classes. Kind answers "what is this package"; the new section answers "what does it project into an agent."
• This unit's original text sketched MCP servers as a second any-kind section; that half is SUPERSEDED — MCP servers became their own mcp kind with their own laws, owner resolution 2026-07-07: PROP-027. The skill law here is unchanged.
• Considered and rejected: a fifth package kind for skills — explicitly rejected (##OOS-FIFTH-KIND): kind answers "what is this package" while the section answers "what does it project into an agent", and skills can live inside a package of any kind (##ANY-KIND-RATIONALE). MCP servers as a second any-kind section — proposed in this unit's original text and superseded: they became their own mcp kind with their own laws, owner resolution 2026-07-07 (PROP-027, ##MCP-HALF-SUPERSEDED). The skill law is unchanged; the MCP half is the counter-example that shows where the line falls.
• Revisit when: an agent-installable artefact class arrives that needs its own lifecycle laws — install / uninstall semantics, resolution or conflict rules of its own — rather than only a projection path. That is exactly the state that fired for MCP servers on 2026-07-07 (##MCP-HALF-SUPERSEDED), so the trigger has a worked precedent. Observation point: the kind register in crates/vibe-core (package_ref.rs) and VIBEVM-SPEC.md §4.1 — whose ##INV-VOCABULARY already anticipates app; the register growing is the fired state.

20The MVP section is an array-of-tables, matching the manifest's existing [[requires_any]] / [[registry]] / [[mirror]] shape:

[[skill]]
name        = "vim"                 # becomes the skill dir name in the agent
path        = "skills/vim"          # file or dir (relative to package root) = the skill body
description = "Drive vim from an agent"   # optional; shown in listings
agents      = ["claude", "opencode"]      # optional; default = all skill-supporting agents

22A reference-backed bridge MAY select its body from a declared external source, and any skill MAY add authenticated source resources below a dedicated subdirectory:

[[skill]]
name   = "codebase-design"
source = "upstream"
path   = "skills/engineering/codebase-design"
include = ["SKILL.md", "*.md"]

[[skill.resource]]
embedded_source = "upstream"
path    = "templates"
include = ["*.md"]
target  = "references/upstream"

24source and embedded_source name a manifest [[embedded_source]]. Absent source retains the package-root meaning. Resource targets are portable relative paths below references/; they cannot replace the local SKILL.md, scripts, or another resource. Include selection, case-fold collision checks and no-follow traversal apply before any agent directory is changed.

25A sibling [[mcp]] table (command / args / target agents) is specified the same way but is near-term, not MVP (§6) — the schema is reserved here so the vim-style "tool + mcp + skill" package is expressible end to end.

2.5 Skills are an orthogonal projection, not a delivery mode

26req r3

• 27Decision. Installing a skill into an agent is a projection: read the declared skill body from the package (in vibedeps/… once installed) or an external source authenticated by the package's matching lock record, and write it into each target agent's skill directory in that agent's own convention (.claude/skills/<name>/…, .opencode/skills/<name>/…, .agents/skills/<name>/… — the paths PROP-015 §2.6 already resolves).
• This is distinct from PROP-003 §2.5 subskill delivery (which materialises content into the project tree). Skill projection materialises out of the workspace, into the agent.
• The two share no code path beyond the Agent skill-path resolver.
• An external tree is projected only through the owning package declaration and matching vibe.lock pin. A direct path into the machine cache is not a package identity or installation surface and cannot bypass package ownership. The bridge slot remains the provider root; the external tree is a separately named content root carrying its own commit/hash/licence provenance.

2.6 Standalone MVP — vibe skill install

28req r3

29Decision. A new command family projects package-declared skills into agents, reusing PROP-015's agent machinery (Agent enum, detection, the idempotent skill writer, the per-(agent, scope) report records):

• 30vibe skill list — skills declared by installed packages.
• vibe skill install [--agent …] [--scope project|user|both] [<pkgref>] [<skill>…] — project skills into agents. Default: all declared skills; narrow with explicit skill names or a pkgref. Idempotent, --dry-run, confirm (or --assume-yes), per-(agent, scope) report — the same lifecycle and merge discipline as vibe mcp install (PROP-015 §2.7).
• vibe skill uninstall … — the inverse; strips only vibevm-projected skills, leaves foreign skill dirs untouched.

31This is the only standalone functionality v1 of this PROP ships. It needs no LLM, so it works today, agent-present or not.

2.7 The agentic relay — delegate intent back to the caller

32req r4

• 33Decision. 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.
• 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).
• Re-running with an empty slot prints "no pending command" and exits 0.

34Two properties make the two-step (produce → vibe command) worth its seam rather than just printing the intent from the producer:

1. 35Uniformity. Any vibevm command that discovers mid-run it needs reasoning parks an intent the same way — not only vibe agentic … commands. The agent learns one drain verb, not per-command stdout parsing.
2. Decoupling. Producer and consumer need not be the same invocation, which is what lets a future deterministic command (vibe build) park a reasoning step and exit, the agent draining it afterward.

• 36MVP carries no write-back (req r4): the relay is fire-and-forget.
• The calling agent orchestrates the conversation — if it wants vibevm to see the result, it arranges that with a follow-up command.
• The installed skill (§2.9) states this contract explicitly so agents do not wait for a channel that is not there. (Full bidirectional conversations are §6.)
• Why: the two-step seam buys two properties a direct print cannot, both stated at ##two-step-lead: uniformity — any command that discovers mid-run it needs reasoning parks an intent the same way, so an agent learns one drain verb rather than per-command stdout parsing (##SEAM-UNIFORMITY); and decoupling — producer and consumer need not be the same invocation, which is what lets a future deterministic command park a reasoning step and exit (##SEAM-DECOUPLING).
• Considered and rejected: printing the intent directly from the producer, with no vibe command seam — rejected for the two reasons above; it is cheaper by one command and forfeits both. A return channel (write-back) — deferred, not rejected: the MVP relay is fire-and-forget (##NO-WRITE-BACK), the calling agent orchestrates (##AGENT-ORCHESTRATES), and full bidirectional conversations are parked at §6 ##FB-CONVERSATIONS.
• Revisit when: either the single slot overflows — a producer runs while .vibe/agentic/command.md already holds an undrained intent, which the mailbox's own shape makes mechanically observable (##FILE-COMMAND-MD) — or the fire-and-forget contract starts costing a round trip, observed as an agent issuing a follow-up vibe … command whose only purpose is to hand a result back (the case ##SKILL-STATES-NO-CHANNEL tells agents not to expect). Either fires §6's ##FB-CONVERSATIONS.

2.8 One operation, two transports

37req r5

38Decision. 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:

• 39One-shot CLI (vibe agentic <op>) — stateless, one process per call. An intent is delivered through the §2.7 file relay. Best when vibevm is touched once and discarded — e.g. an agent scanning a directory of hundreds of vibevm projects for a quick fact. All per-session state (future conversation/context, §6) is lost on exit, by design.
• MCP server (vibe mcp serve, PROP-015 §2.1) — persistent, zero-latency, can hold session context. The same op is registered as an MCP tool; an intent is returned synchronously in the tool result, so no file mailbox is needed on this path. Best for sustained work inside one project.

• 40The choice is the agent's, by situation, and the skill (§2.9) teaches the heuristic.
• The core never knows which adapter called it.

2.9 The vibevm-usage skill teaches the protocol

41req r5

42Decision. The skill vibe mcp install already projects (skill_template.md) gains a section that teaches an agent:

• 43the transport heuristic (one-shot CLI for a quick/one-off or a wide scan; MCP server for sustained in-project work) — §2.8;
• the relay contract: some vibe … commands park reasoning instead of doing it; after such a command, run vibe command, then carry out the returned instruction yourself;
• there is no automatic write-back — if the result should reach vibevm, the agent issues the follow-up itself.

44The skill stays data, not code (PROP-015 §2.6).

2.10 vibe agentic explain — the MVP demonstrator

45req r4

46Decision. 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:

Task — explain this project. In ≤3 short paragraphs, tell the reader
what this project is and does. Sources, in priority order: (1) `README.md`
at the project root — summarise it; (2) if `vibe.toml` is present, fold in
what its structure reveals (the package `kind`, what it `requires`, what
it `provides`). If `README.md` is absent, say so and explain from
`vibe.toml` alone. Write for a developer seeing the repo for the first
time. Do not invent features the sources do not support.

• 48vibe agentic explain does no LLM work and reads no file content itself; it only composes the intent (it may check which of README.md / vibe.toml exist to tailor the prompt).
• The agent then runs vibe command, gets this instruction, and produces the explanation on its own LLM.
• Affinity: agentic-only until the built-in backend exists (§2.3).