Vine

Zero-Cost Rift Copy-on-Write Workspaces & Zero-Mirage Git Weaving for Autonomous AI Agents

Vine provides zero-drag workspace virtualization, polyglot build-cache normalization, and mechanical + semantic verification gates for parallel AI coding agents.

Core Concepts

• Strands: Instantaneous Rift copy-on-write workspace clones (vine new <task_id>). Uses rift for zero-cost snapshot cloning (in ~9s with 0 extra disk blocks) and git worktree for monolithic fallback (in ~280ms).
• Universal CoW Vendoring: Clones dependency caches (deps, node_modules, vendor) in <80ms without physical disk duplication.
• Polyglot Build Cache Layer: Auto-activates non-destructive .envrc normalizing ccache, sccache, uv clone mode, and nimcache.
• The Three-Key Gate: Ensures zero "Green Mirage" by requiring Key 1 (in-memory mechanical git merge-tree exit 0), Key 2 (live compiler & test suite exit 0), and Key 3 (independent adversarial audit ratification via vine audit).
• Weaving: Fast-forwards verified strands back into the canonical trunk (vine weave).

Documentation for Humans & AI Agents

Vine provides comprehensive workspace, gate, and build cache specifications:

Core Protocols & Architecture

• Strand Lifecycle Specification: Zero-cost Rift Copy-on-Write strands, directory isolation, .vine.json runtime manifest, and collision detection.
• Three-Key Gate Specification: Zero "Green Mirage" philosophy, Key 1 mechanical merge-tree + Key 2 live test discovery cascade + Key 3 independent adversarial code audit ratification and cryptographic gate tokens.
• Polyglot Build Cache Normalization: Non-destructive .envrc chaining, Ccache, Cargo target, uv clone links, and Nimcache unification.
• CLI Reference Manual: Complete catalog of all Vine commands (new, status, collisions, gate, submit, audit, weave, list, sync, prune).
• Configuration Architecture: Layered configuration hierarchy, workspace paths, and gate options.
• Agent Constitution & Invariants (AGENTS.md): Workspace isolation rules, sovereign worker allocation, and Three-Key discipline.

Standalone Yet Designed for the Axiomantic Triad

Vine is completely standalone and can be used on its own for zero-cost Rift copy-on-write workspace cloning, .envrc build-cache normalization, and Three-Key gate verification on any git repository.

[!NOTE]

Quick Note: Using Garden as your High-Level Swarm Wrapper

Looking for the high-level multi-agent conductor? Use Garden.
While vine provides isolated branch workspaces (strands) and the Three-Key Gate, Garden is the high-level umbrella framework. Simply start a session in your favorite coding harness (Antigravity, Claude Code, OpenCode) and type "garden: I want to build [feature]". Garden conducts an intake interview, generates clean 10-backtick prompt cards for your terminal tabs, and coordinates all workers over Rhizo and Vine!

However, Vine is designed from the ground up to pair seamlessly with Rhizo and Garden:

• Rhizo (Transport & Concurrency): Inter-agent messaging bus, monotonic fencing locks, and task queues over Redis.
• Vine (Workspaces & Verification): Zero-cost Rift copy-on-write strands, polyglot build-cache normalization, and the Three-Key integration gate (git merge-tree mechanical + compiler/test suite semantic checks + independent adversarial audit ratification).
• Garden (Swarm Methodology & High-Level Wrapper): Conversational project intake interview, prompt-bootstrapped worker fleets (10-backtick cards), 3-stage empirical dialectical pump (research, architecture, audit), and master ceremonial implementation planning.

Installation

1. For AI Coding Assistants (Recommended)

Install the skills globally (-g) across all your coding assistants (Claude Code, Antigravity, Cursor, Codex, OpenCode, etc.):

# Recommended: Install the complete multi-agent triad globally
npx skills add -g axiomantic/rhizo
npx skills add -g axiomantic/vine
npx skills add -g axiomantic/garden

(Each skill automatically self-bootstraps its native CLI binary if it is not already installed on your system).

To install only Vine:

npx skills add -g axiomantic/vine

2. Standalone CLI Installation

Install the compiled CLI tools directly onto your $PATH:

# Install all three tools:
npm install -g @axiomantic/rhizo @axiomantic/vine @axiomantic/garden rift-snapshot

# Or install Vine alone:
npm install -g @axiomantic/vine rift-snapshot

[!TIP] Zero-Install Run via NPX: In restricted or containerized environments where global installation is unavailable, you can run any command directly without installing:

npx -y @axiomantic/vine <command>

3. Repository Coordination Guide

Install the Vine strand coordination protocol directly into any project's AGENTS.md:

vine guide install

Quickstart

# Spin up an isolated strand for a task
vine new task-1049 --repo ~/Development/PebbleOS --branch feat/display-driver

# Inspect dynamic strand lifecycle and commit delta
vine status --json

# Forecast cross-strand file footprint overlap before conflicts happen
vine collisions

# Reconcile upstream canonical trunk changes into strand
vine sync

# Verify mechanical and semantic correctness inside the strand
vine gate

# Weave clean strand into canonical trunk
vine weave

# Prune completed or merged strands
vine prune --apply

CLI Reference

Configuration & Environment Variables

[!TIP] For the complete specification of vine.toml, .vine.json runtime state schemas, and environment variables, see the Vine Configuration & Manifest Reference.

Vine provides zero-config defaults that can be customized via vine.toml or environment variables:

Example vine.toml

[project]
primary_branch = "main"

[strand]
venv_policy = "prompt"
vendor_dirs = ["deps", "node_modules", "vendor", ".zig-cache"]

[verification]
test_command = "pytest -v tests/"

Multi-Agent Triad Workflow

When orchestrating teams of multiple AI assistants operating simultaneously across strands, pair Vine with Rhizo and Garden:

• Distributed Mutexes & Fencing: Use rhizo lock file:<path> --fencing to prevent concurrent collisions on non-mergeable schema files or migrations.
• Synchronized Task Queues: Agents claim work via rhizo claim queue:<project>:tasks --lease 1800 and report status back over the Redis bus.
• Full Ceremony Conduct: Use garden to direct persona deliberations, generate 10-backtick worker prompt cards, and drive implementation plans.
• Zero Dirty Commits: Rhizo, Vine, and Garden enforce complete decoupling of agent identity from directory paths.

Repository Guide Integration

Install the Vine guide into any repository's AGENTS.md:

# Defaults to AGENTS.md in the current working directory:
vine guide install

# Or specify a custom target path:
vine guide install /path/to/AGENTS.md