Skip to main content
Glama
JAAvila-Of

vivac

by JAAvila-Of
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Open a node and step into it

vivac_push

Open a new node and step into it so subsequent work is captured under it until a matching pop. Use it when starting or forking a line of work, with a required reason.

Instructions

Open a node and step into it: it becomes the focus, and everything captured next hangs from it until a matching pop. Call it the moment a new line of work starts or forks away from the current one -- a question that has to be settled before continuing, a detour worth its own trace -- never after the fact, once the reason for taking it has already faded. Look first with vivac_find: work the tree already holds goes under its node, never into a second one. The focus is wherever work was left, perhaps by another session and about something else, so name in parent the node this work continues, or pass root when it continues nothing. why is mandatory: a detour with no reason recorded is the failure this tree exists to catch.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
armNoCommands that verify this rule, one per entry, all run in arm_dir. Only for a rule; a rule without one is judged. vivac never runs them.
refNoPaths or identifiers this node is about.
whyYesWhy this is happening now. A detour with no reason is what this field exists to prevent.
rootNoBorn at the root, with no parent, instead of under the focus. The stack is left holding only the new node; nothing on it is closed, and the answer says how to get back. Refused together with parent.
typeNogoal, task, decision, question, constraint, finding, assumption, pillar or rule. Defaults to goal at the root, task otherwise. A pillar is titled with its name and what it restricts, in the project's own words.
titleYesWhat this node is, in a few words.
blocksNoIts parent cannot close while this one is still open.
parentNoThe node this work continues, when it is not the focus. The stack is rebuilt as that node's path, the way vivac focus does, and the new node opens under it; the answer says what left the stack. Refused together with root, and on a node that is closed or parked.
againstNoOnly for a decision: a pillar or rule it was judged against and a sentence on how it holds, as one entry: "r12: the write path stays local". Repeat for each one.
arm_dirNoThe folder every arm given here runs in, relative to the folder that holds .vivac: vivac, say, or . for that folder itself. Required with arm, refused without it. It has to exist.
governsNoGlobs of files this node's work is expected to touch.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.17.1

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare this is a non-idempotent mutation that is not destructive; the description adds substantial behavior beyond that: the stack push semantics, the requirement that it be matched by a pop, the root-vs-focus targeting, and the mandatory `why`. It stops short of describing permissions or failure modes on a closed/parked node (those live in the schema), so a 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and structured as action -> when -> routing -> params. Four dense sentences with some evocative framing ('a detour worth its own trace', 'once the reason... has already faded') that costs a little efficiency but earns its place by motivating the tool's constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutation tool with no output schema but 100% schema description coverage, the description supplies the mental model (focus stack, matching pop, parent/root targeting) an agent needs. Remaining gaps (exact refusal conditions, return payload) are adequately covered by the schema, so it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real value on the two most decision-critical params: `parent` names the node this work continues (or `root` when it continues nothing) and `why` is called out as mandatory. These reinforce the mutual exclusion and the required field beyond the raw schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with precise scope: 'Open a node and step into it: it becomes the focus, and everything captured next hangs from it until a matching pop.' This clearly separates it from siblings like vivac_pop (the matching counterpart), vivac_find (lookup) and vivac_open.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('the moment a new line of work starts or forks away'), when-not ('never after the fact, once the reason... has already faded'), and names the alternative 'Look first with `vivac_find`' with the condition that selects it. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools