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 work node as the current focus, capturing all following work beneath it until popped; record why the detour started.

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 is never opened twice, and what turns up while on it is a node under it, not a note. 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 norm the person sets for the work from now on is a constraint, with root when it holds for all work, so every brief shows it. A rule is a line a pillar draws, read with vivac_rules when work is checked. 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.
supersedesNoAn earlier decision, constraint, rule or pillar this one replaces, while it is still in force: it becomes superseded and keeps its history. For a node filed with the wrong type, write the one it should have been and name the old one here. This node has to be one of those four types too.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.18.0
    • addedInput schema / properties / supersedes
      Added value: +{
+  "description": "An earlier decision, constraint, rule or pillar this one replaces, while it is still in force: it becomes superseded and keeps its history. For a node filed with the wrong type, write the one it should have been and name the old one here. This node has to be one of those four types too.",
+  "type": "string"
+}
    • changedInput schema / properties / type / description
      Previous value: -"goal, 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."New value: +"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Defaults to goal at the root, task otherwise. A norm the person sets for the work from now on is a constraint, with root when it holds for all work, so every brief shows it. A rule is a line a pillar draws, read with vivac_rules when work is checked. A pillar is titled with its name and what it restricts, in the project's own words."
  2. First observedv0.17.1

TDQS

A3.9/5.0
Behavior3/5

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

Annotations declare a non-read-only, non-destructive, non-idempotent mutation. The description adds context about stack rebuilding and the focus default, but this overlaps with what the schema already documents (e.g., parent rebuilds as the focus path). It doesn't add much beyond the structured fields—no mention of rate limits, auth, or side effects on existing nodes beyond what's in the schema.

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?

Well-structured with two clear paragraphs: first the core behavior and timing, then the focus/name requirement. Every sentence serves a purpose, though the final sentence could be tightened. Front-loaded with the primary action and rationale.

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 a complex 12-param mutation tool with no output schema, the description covers the critical usage timing, the prerequisite (vivac_find), and key parameter semantics. It leaves some gaps: no mention of return value format, pagination, or errors beyond refusal conditions already in schema. However, it's complete enough for an agent to invoke correctly given the rich schema descriptions.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all 12 parameters thoroughly, including type enums and complex behaviors like arm/arm_dir coupling and refusals. The description mostly reinforces schema content (e.g., mandatory 'why', 'parent' vs 'root') without adding new syntax or format details. Baseline 3 is appropriate.

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

Purpose4/5

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

The description states a specific verb and resource ('Open a node and step into it') and defines the operation's mechanism (focus shift, children attach until a matching pop). It distinguishes itself from siblings by naming vivac_find as the prerequisite, though it doesn't contrast with vivac_pop or vivac_add beyond the 'matching pop' reference.

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?

Explicitly states when to use ('the moment a new line of work starts or forks') and when not ('never after the fact'). Names the alternative workflow ('Look first with vivac_find') and clarifies that existing work is not opened twice. This is as complete as usage guidance gets.

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