A Graph Workflow describes step order as a dependency graph. Source artifact, published definition, and run instance have separate identities.

Source and publish

The source file (*.vibex-workflow.json) can be edited repeatedly in a workspace and committed to Git. At that point it is the authoring fact. Publish, after validation, produces an immutable definition version. A failed validation produces no new version. A run binds the definition version at start. Later source edits affect the next version only. An Automation that targets a workflow binds that exact version.

Opening the source enters Workflow Studio. A debug run can execute only the selected step, or continue downstream from it. Debug uses an isolated test worktree. A debug breakpoint belongs to that Debug run only.

Steps

An Agent step runs through a child conversation and real turns. Continuing the dialogue creates a new turn. A cancelled turn stays cancelled. An Approval step waits for an authorized principal. Retry creates a new attempt and keeps the old record.

A completion gate decides how a candidate output is accepted. On manual confirm, Studio derives a visible confirm node that opens the agent-step conversation. When continuing may repeat side effects and the system has no contrary proof, the run enters needs review. A person chooses continue or stop.

Run control

A run binds one definition version, a set of inputs, and a workspace. A new run can be derived from a chosen step of an existing run. The original run stays read-only. Upstream results that still match the contract can be reused.

Pause first stops scheduling new steps, then cancels in-flight turns, and enters a resumable paused state. File and external side effects that already happened stay. Continue opens a new turn in the original child conversation. Merge, push, and publish finish in the Git panel.

Controller and worker

A user may authorize a Controller Agent, separate from the worker that executes a step, to inspect node evidence, append input, or accept a candidate output through Workflow MCP. Every control action is auditable. Workflow MCP depends on a running Host. When the Host is unavailable, publish, debug, and run entries close.

An Automation is a versioned trigger config. On manual start or when the schedule fires, it starts one ordinary turn, or one published Workflow version. Target kind is chosen at create. Turn and workflow stay that kind for the lifetime of the row.

Target and isolation

A single-session target creates a real Turn each run. A workflow target binds a published exact version. After the source publishes again, older automations keep the version they already reference.

The default is an independent worktree per run. Sharing the project root is an explicit choice and must pass a clean tree and branch check. Merge, push, or publish during a run still happen in the Git panel.

Spec JSON can be copied. Import resolves project, agent, and workflow references on the current Host and leaves the row disabled until enable is confirmed. The spec omits database identity, secrets, and machine paths.

Engine owner

One data directory has one automation engine owner: the current Host. Only the owner claims due jobs. If the page says another host holds the engine, the view is read-only.

On Host startup, leftover direct-turn runs become Interrupted. Runs already attached to a Workflow run follow that run’s terminal state. The next fire is still schedule or manual. After downtime, at most the most recent missed schedule is backfilled. Finished runs and their independent worktrees are kept 30 days by default, under a per-directory space quota. Running jobs are kept.

Run records

Each fire produces an Automation run. Terminal state follows the durable fact of the matching Turn or Workflow run. The list can run now, open history, and cancel a running row. Unseen failures surface on the row.

A VibeX plugin package is installed, enabled, updated, and uninstalled under one identity. One package may contribute UI, agent, Host, and runtime at once. Install treats it as a product package. There is no prior split into “platform plugin” versus “agent plugin”.

Lifecycle

Discover or import yields a source package. That is not yet execution rights. Install accepts an exact version/digest as the Host’s immutable install. New installs start disabled. Enable is the durable intent to publish contributions. After enable, the Host produces an activation generation: an atomic snapshot of package, grants, Runtime locks, and ready contributions. A candidate generation is invisible until fully validated. A failed update keeps the previous complete generation.

Conversations that already exist keep the tool list from creation. Later new or rebound conversations receive new contributions.

Turning enable off stops new turns from using the package’s contributions. History in the event log stays. A third-party package can be uninstalled: membership, agent bindings, and Skill projections go away. Conversation and automation history remain. Built-in packages stay in the catalog. The switch only enables them.

Trust

Enabling a VibeX plugin package allows it to run workers and UI with the same local rights as the Host. Separate processes exist for lifecycle, hot reload, and crash isolation. Package layout, content index, and validation are in the developer docs.

Agent-native plugins (Codex / Claude Code package formats) are held by that agent’s storage and trust. VibeX may project a read-only view and forward install/enable when the adapter is reliable. Native trust and VibeX enablement are separate authorities.

How-to: Install and enable a Plugin.

Control plane

The plugin control plane is the sole fact source for install, grant, start/stop, update, diagnostics, rollback, and uninstall. It can also read projections of agent-native plugins. Additions and deletions in native directories still follow that agent. External disable or a broken link must be shown as-is.

Identity

Plugin identity is stable Publisher plus Plugin ID. Display name, folder name, and similar contents leave identity unchanged. Packages with the same ID and different publishers keep separate grants and data. A linked development plugin keeps following a user-chosen directory. After the source changes, contributions, grants, and identity must be revalidated. The development directory stays on disk.

Plugin contributions attach by type to different places in the product. Usability is judged per contribution. A Skill inside the package is one contribution among others. Each contribution has its own identity, type, compatibility conditions, and readiness.

Contribution	Attach point
Skill / MCP	Agent conversation; visible to that agent after Agent binding
App UI	Preview, settings page, commands, custom surface in a VibeX window
Workflow	Orchestration; publish path matches the source file in the repo
Host Worker	Host background; clients observe a projection
Runtime	Exact CLI / Binary / sidecar version, resolved and locked by the Host

Binding and readiness

Enable allows those contributions to be published. Missing runtime, missing binding, or an agent that rejects the contribution leaves it unready. All-agents binding intent projects compatible contributions onto current and future enabled agents that support the capability. Exclusions are stored separately.

A Skill projection is a controlled read-only entry written to the agent-native Skill location. A user Skill of the same name stays. A Plugin Command and an agent-native command may share a display name and remain distinct by source identity.

A remote workstation changes state on the Host. Companion and chat-channel plugin management lives in Settings → Plugins on the Host or a workstation desktop.

Runtime lock

A Runtime requirement is an author declaration. The install lock records the exact version the Host resolved, integrity, and probe evidence. A successful declaration and a spawned process still require a passing probe before ready. A Host-owned Runtime enters reclamation only after references drop to zero.

The Host family ships official product plugins marked VibeX built-in. They start disabled and stay in the catalog. After the runtime is on disk, enable still has to be turned on. Later new or rebound conversations receive injection. The switch lives on the plugin itself.

Plugin	Effect after enable
Session Enhance	Questions, live feedback, session lookup, and session control
Multi-agent	& as a delegation mention; depth and child defaults apply to delegated children
Workflow Creator	Source edit, validate, debug, and publish
VibeX Office	Skills, workflows, and read-only preview for DOCX / XLSX / PPTX
Plugin Development	Local SDK / CLI and optional development MCP; everyday use can leave it off

Delivery

Official MCP ships with the Host family. After the plugin is enabled, the Host injects the matching MCP into later new or rebound agent sessions and trims tools/list per session. Conversations already open keep the tool list from creation.

The four Session Enhance tools can be turned off individually in plugin config. Multi-agent enablement is delegation enablement. Workflow Creator depends on the running Host loopback gateway. Office preview uses the Host-locked officecli Runtime.

Config writes each package’s config.json and applies to later new sessions or new previews.

Relation to Settings

Session tools and the delegation master switch live on those plugins’ Config tabs. Settings → General leaves those switches on the plugin pages. Office preview idle timeout and Workflow Creator’s default completion policy also live in each package config.