Skip to main content
Glama
JAAvila-Of

vivac

by JAAvila-Of
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

File a node without moving the focus

vivac_add

File a node without changing your current focus—use it for findings, siblings, or later tasks, not for what comes next.

Instructions

File a node without touching the stack: the focus stays exactly where it was. Use it for something that belongs in the tree but is not the next thing about to happen -- a finding surfaced while working on something else, a sibling task filed for later, a piece of an existing structure being brought in. vivac_push is for what comes next; this is for what was just noticed. Something left to do that turns up while working on a node is a task filed under it, never a note on it. Look first with vivac_find: what the tree already holds is not filed twice. A finding is one node for each thing found that you tell the person, written when you tell them. One that asks nothing of anyone -- a lesson, a measurement -- is a record: close it right away with vivac_done, its outcome starting with Record:. The title is words, never an id: the node it hangs from goes in parent.

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.
whyNoWhy this matters.
rootNoBorn at the root, with no parent, instead of under the focus. 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 it hangs from. Defaults to the current focus, or the root if there is none.
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

A4/5.0
Behavior4/5

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

Annotations declare a non-destructive, non-idempotent write but say nothing about focus state, which is the key behavioral trait; the description supplies it ('the focus stays exactly where it was') plus default placement under focus/root. It also clarifies a non-obvious side behavior for a sibling flow ('vivac never runs them') and that records should be closed immediately. It does not discuss failure modes or what the call returns.

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?

The core rule is front-loaded in the first sentence, which is good, but the remainder is a dense chain of em-dash fragments that mixes filing semantics, type selection, and record lifecycle, and several lines are only tangential to this tool's mechanics. Much of the content is useful for a 12-parameter tool, but the structure is stream-of-consciousness rather than scannable.

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-parameter mutation tool with no output schema, the description covers the important decision space: what to file, when not to, where it lands, and how records/tasks are categorized. The main gap is that with no output schema it never says what a successful call returns (e.g. the new node's id), which an agent would need to chain follow-up calls.

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, setting the baseline at 3. The description adds one genuine disambiguation ('The title is words, never an id: the node it hangs from goes in parent'), but most other param guidance (type choices, records, supersedes) restates rules the schema descriptions already carry.

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 sentence states a specific action and its distinguishing effect ('File a node without touching the stack: the focus stays exactly where it was') and the title reinforces it. It also draws the boundary against the most confusable sibling, vivac_push ('vivac_push is for what comes next; this is for what was just noticed'). The core 'add a tree node' framing is somewhat obscured by metaphor, keeping it short of a 5.

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?

It gives explicit when-to-use cases (a finding surfaced while working on something else, a sibling task for later, an incoming piece of structure) and an explicit when-not, routing 'what comes next' to vivac_push. It further directs a pre-check with vivac_find ('what the tree already holds is not filed twice') and a follow-up path via vivac_done for records.

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