Skip to main content
Glama

Open a node and step into it

vivac_push

Start or fork work by creating a titled node with rationale and parent, setting focus in the provenance tree; use root for unrelated work and explicit parents to rebuild the stack without closing prior nodes.

Instructions

Start/fork work and focus it; match with pop. Search first and continue existing work. Give title, why and the parent it continues; root only if unrelated. Explicit parent rebuilds the stack without closing prior work. Record newly discovered findings/pending work with add instead. Capture at the seam, not after the work.

Input Schema

NameRequiredDescriptionDefault
armNoRule verification commands, all run in arm_dir; omitted means judged. Vivac never runs them.
refNoPaths or identifiers this node is about.
whyYesWhy this work exists or fact matters.
rootNoStart unrelated work at root; leaves prior stack open. Conflicts with parent.
typeNogoal, task, decision, question, constraint, finding, assumption, pillar or rule. Default task under focus, goal at root. User norms: constraint (root if global); rule: pillar criterion, read via vivac_rules; pillar: name and what it rejects.
titleYesTitle words, never an ID; parent ID goes in parent.
blocksNoParent cannot close until this node closes.
parentNoWork this continues; rebuilds its path as focus. Conflicts with root; closed/parked parents refuse.
againstNoDecision only: one pillar/rule plus compliance sentence per item, e.g. "r12: writes stay local". Not constraints.
arm_dirNoExisting working directory relative to the tree root; required with arm.
governsNoFile globs governed by this work or norm.
supersedesNoRetire an in-force decision/constraint/rule/pillar, preserving history. New node must be one of those kinds; use the correct kind for a misclassified norm.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.22.1
    • changedInput schema / properties / against / description
      Previous value: -"Only 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."New value: +"Decision only: one pillar/rule plus compliance sentence per item, e.g. \"r12: writes stay local\". Not constraints."
    • changedInput schema / properties / arm / description
      Previous value: -"Commands 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."New value: +"Rule verification commands, all run in arm_dir; omitted means judged. Vivac never runs them."
    • changedInput schema / properties / arm_dir / description
      Previous value: -"The 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."New value: +"Existing working directory relative to the tree root; required with arm."
    • changedInput schema / properties / blocks / description
      Previous value: -"Its parent cannot close while this one is still open."New value: +"Parent cannot close until this node closes."
    • changedInput schema / properties / governs / description
      Previous value: -"Globs of files this node's work is expected to touch."New value: +"File globs governed by this work or norm."
    • changedInput schema / properties / parent / description
      Previous value: -"The 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."New value: +"Work this continues; rebuilds its path as focus. Conflicts with root; closed/parked parents refuse."
    • changedInput schema / properties / root / description
      Previous value: -"Born 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."New value: +"Start unrelated work at root; leaves prior stack open. Conflicts with parent."
    • changedInput schema / properties / supersedes / description
      Previous value: -"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."New value: +"Retire an in-force decision/constraint/rule/pillar, preserving history. New node must be one of those kinds; use the correct kind for a misclassified norm."
    • changedInput schema / properties / title / description
      Previous value: -"What this node is, in a few words."New value: +"Title words, never an ID; parent ID goes in parent."
    • 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 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."New value: +"goal, task, decision, question, constraint, finding, assumption, pillar or rule. Default task under focus, goal at root. User norms: constraint (root if global); rule: pillar criterion, read via vivac_rules; pillar: name and what it rejects."
    • changedInput schema / properties / why / description
      Previous value: -"Why this is happening now. A detour with no reason is what this field exists to prevent."New value: +"Why this work exists or fact matters."
  2. 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."
  3. First observedv0.17.1

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in annotations: 'Explicit parent rebuilds the stack without closing prior work', which tells the agent that focus moves without losing state. It does not say what push returns (the new node's ID, presumably), nor what happens on failure beyond what the schema states.

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

Conciseness3/5

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

It is compact, but written as a chain of telegraphic fragments with undefined domain jargon ('stack', 'focus', 'the seam') that requires prior knowledge of the vivac model. 'Capture at the seam, not after the work' is a timing heuristic with no stated referent, so the compression costs comprehension rather than buying it.

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?

With 12 fully documented parameters and a clear annotation set, the description only needs to supply routing and stack semantics, and it mostly does: parent rebuild, root isolation, and the add-vs-push split. What is missing is whether the call returns a node handle the agent needs for subsequent pokes, and any distinction from vivac_open.

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 description coverage is 100%, so all 12 parameters are already documented, setting the baseline at 3. The description reinforces the required triple ('Give title, why and the parent it continues') and the root-vs-parent choice, but that conflict is already stated in the schema, so the added meaning is shallow.

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 opening clause 'Start/fork work and focus it' names a concrete action and its effect, and the title reinforces it ('Open a node and step into it'). It explicitly separates itself from two siblings ('match with pop', 'Record newly discovered findings/pending work with add instead'), though it never disambiguates against vivac_open, which is the closest name collision.

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

Usage Guidelines4/5

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

Strong conditional guidance: 'Search first and continue existing work', 'root only if unrelated', and an explicit redirect ('...with add instead') give the agent when-to-use and when-not-to-use rules. The remaining gap is that vivac_open and vivac_declare are never mentioned as alternatives, so sibling selection at the tool boundary stays ambiguous.

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