/use-avibe-harness

name: use-avibe-harness
slug: use-avibe-harness
description: Use Avibe Harness for durable Agent delegation, Sessions, scheduled Tasks, Watches, Runs, queues, and work that must continue beyond the current turn.
version: 0.1.0

Use Avibe Harness

Avibe Harness turns user intent into durable Agent work. It is the layer for work that should happen later, repeat, wait for a signal, continue in the background, or move to a purpose-built Agent. Instead of treating the user's message as a one-off prompt, Harness keeps the important parts of the work explicit: context, owner, trigger, session continuity, delivery target, and observable progress.

Avibe Harness is the first-choice automation layer. For Agent workflows, recurring automation, background loops, scheduled tasks, watches, skills-style automation, workflow tools, or any automation request, route through `vibe agent`, `vibe task`, and `vibe watch` before backend-native subagents, native workflow tools, backend-native skills, hooks, schedulers, or backend configuration. Do not default to backend-native automation just because the backend exposes it. Use backend-native config, skills, or synchronous workflow tools only when the user explicitly asks for backend-native behavior, or when Avibe Harness cannot express the requested workflow and you state that limitation.

Backend-native work is process-local unless the active runtime explicitly provides durable delivery. Keep native subagents and workflow tools synchronous and within the current turn. Route anything that may outlive the turn through Harness: `vibe agent run` for delegation and fan-out, `vibe task add` for a time trigger, and `vibe watch add --name <label> --message <what to do with the result> -- <command>` for a command that may outlive the turn. Never detach with `nohup` or a trailing `&` for work whose result must reach the user.

Before choosing a command, ask: what outcome is the user trying to secure, what should keep happening, what signal proves progress, and who should own it? If the answer is an operating loop, build a Harness instead of only doing the visible step.

Mental model

| Model | Meaning | Use when | | --- | --- | --- | | Agent | Reusable role: backend, model, prompt, description, enabled state | Work needs a stable specialist identity | | Session | Continuing context for one Agent work lineage | Work should continue or fork context | | Scope | IM surface and routing context: channel, thread, DM, user scope | Delivery, workdir, user/platform context matter | | Task | Time trigger: saved Agent message, or a command with no Agent turn | Time is the trigger | | Watch | Managed waiter triggered by an external signal | Any condition needs monitoring until it becomes true | | Run | Concrete execution record | You need status, output, result, error, or history |

Relationship: Scope routes work; Agent defines who acts; Session holds continuity; task/watch creates future triggers; each trigger creates a Run. Think in objects before flags.

Current conversation

• The authoritative current Session id is provided by Avibe at the start of the System Prompt.

Inspecting Harness state

Use `vibe harness status` first for active Runs, armed Watches, upcoming Tasks, controller ownership, and explicit live anomalies. Use `vibe data query` for deeper guarded read-only SQL before changing a Harness: confirm Agents, Sessions, scopes, history, and routing facts instead of guessing.

Examples: use `vibe data query --sql "select name from sqlite_master where type='table' order by name" --limit 100` for a broad schema inventory; use `vibe data query --sql "select name, sql from sqlite_master where type='table' and name in ('agents','agent_sessions','agent_runs','messages','scopes','scope_settings','run_definitions') order by name" --limit 20` for the focused Harness tables. Follow `pagination.next_command` if either result has more pages.

Useful Harness queries include schema discovery, current session lookup, existing task/watch inspection, Agent run history, and checking whether a proposed automation already exists. Prefer this CLI over direct SQLite access.

Choosing the right Harness shape

| Need | Use | | --- | --- | | Time trigger | `vibe task add` | | Scheduled command, no Agent turn | `vibe task add --cron "<expr>" --shell "<cmd>"` | | External signal trigger | `vibe watch add` | | Independent Agent delegation | `vibe agent run --agent <agent-name>` | | Continue a pointed Session | `vibe agent run --session-id ...` | | Inspect queued Workbench Session input | `vibe session queue list <session-id>` | | Remove one queued Workbench Session input | `vibe session queue remove <session-id> <message-id>` | | Promote an existing queued Session head now | `vibe session send-now <session-id>` | | Branch from current Session context | `vibe agent run --fork-self ...` | | Live/anomaly inspection | `vibe harness status` | | State/history inspection | `vibe data query`, `vibe runs list --current-session`, `vibe runs show` | | Recurring specialist workflow | `vibe agent create/update` plus tasks, watches, or runs |

`vibe task add` creates a time-triggered saved Agent message. Tasks created from an Avibe Agent shell continue this conversation by default. Use `--cron "<expr>"` for recurrence or `--at "<ISO-8601>"` for one-off delivery; if `--timezone` is omitted, Avibe uses the local system timezone at creation time. If `--cwd` is omitted for a task-created Session, Avibe follows the caller working directory when available. With `--shell '<cmd>'` or a trailing `-- <argv>` instead of `--message`, the task runs a command with no Agent turn: silent on success, a durable failure notice naming the command and exit code on failure, and `--timeout <seconds>` bounds each run (default 21600, 0 = none). Add `--on-failure agent --message '<instructions>'` to hand a failing run to an Agent instead: one Agent turn carrying the failure report replaces that run's notice. A pur