Vis

vis

> An @enchanter-ai product — dependency-free, model-agnostic, dogfooded across the ecosystem.

The behavioral substrate for building durable AI agents — conduct, engines, taxonomy, and the math behind all three.

37 conduct modules. 12 engines. 21 failure codes. 9 recipes. Zero runtime dependencies.

> A 12-line paginate() function has an off-by-one. The PR title says "fix the off-by-one in pagination." The agent rewrites it as a Paginator class, adds a docstring nobody asked for, renames perPage to n, and slips the actual one-character fix onto line 4. Type-check passes. Tests pass. The bug is fixed, but the codebase grew a new pattern nobody decided on, and the diff buries the fix under 30 lines of unsolicited refactor (F04 task drift). > > vis is the four-stance conduct rule (think-first / simplicity / surgical / goal-driven) that turns the same task into a one-line diff: start = page * perPage → start = (page - 1) * perPage. The rule existed before this PR — the agent never saw it. After @shared/vis/packages/core/conduct/discipline.md lands in CLAUDE.md, instinct shifts at the lexical level. > > Tokens loaded: ~700. Modules pulled: 1. Refactors prevented: every PR after.

TL;DR

In plain English: Most agent stacks ship with prompts, tools, and hopes. The thing that actually keeps an agent from refactoring code you didn't ask it to touch, or pushing to main after you said not to, isn't another tool — it's a behavior rule that survives the long context. vis is the dependency-free pile of those rules, plus the math, taxonomy, and host recipes around them.

Technically: 37 conduct modules across 7 conduct packages (core / skills / orchestration / safety / web / memory / cost), plus a hooks package shipping 6 runtime advisory hooks (the enchanter-hooks plugin, installable via the vis marketplace). 12 algorithmic engines with paper-backed derivations (Aho-Corasick pattern detection, Shannon entropy, Beta-Bernoulli trust scoring, Markov drift, Hunt-Szymanski LCS, Zhang-Shasha tree-edit, Tarjan SCC, Wald SPRT, Jaccard-cosine boundary segmentation, contextual LLM bandit, agentproof DFA, sycophancy calibration). 21 named failure codes (F01–F21) with testable counters, mapped to a 5-axis hybrid taxonomy (memory / reflection / planning / action / system) and 21 incident-response runbooks. 9 adoption recipes (Claude Code, OpenAI Agents SDK, Cursor, LangChain, Pydantic-AI, BAML, raw system-prompt, eval-harnesses, stupid-agent-review). Zero runtime dependencies — pure prose + math, loadable into any system that accepts text instructions.

Origin

vis takes its name from the Latin word for binding-force — the substrate that makes a rule load-bearing instead of merely descriptive. In Roman jurisprudence vis was the binding authority behind a contract; in tabletop tradition (Ars Magica) vis was the raw magical material no spell could compile without. Both meanings carry the same idea: foundational substance that higher abstractions rely on but rarely name. The framework is dogfooded — vis runs on its own conduct while editing its own conduct; refusing drift, sycophancy, and silent failure is part of the contract, not a goal.

The question this framework answers: Is the rule actually load-bearing?

Who this is for

• Teams building production agents who have watched type-check-passing PRs ship runtime regressions, and want a conduct layer that survives a 200-turn context.
• Platform / infra engineers wiring multiple agent frameworks (Claude Code, OpenAI Agents SDK, Cursor, LangChain) who need one source-of-truth for behavior, not seven divergent rule sets.
• Reviewers tired of reviewing scope creep from over-helpful agent edits, who want surgical-changes enforced upstream of the diff.
• AI safety / alignment researchers wanting a flat F-code taxonomy plus a 5-axis structural mapping that compounds across observations.
• Adopters of a host framework (LangChain, BAML, Pydantic-AI) who need concrete wiring recipes, not blog-post pseudocode.

Not for:

• Single-shot prompts or weekend prototypes — loading 37 conduct modules into a 300-token task is overkill.
• Teams who've never observed a production agent drift, hallucinate a tool call, or refuse a benign request. The framework grows by patterns named after observed failures; if you haven't seen any, you don't need the counter yet.

Contents

• [Why this exists](#why-this-exists)
• [What's in the box](#whats-in-the-box)
• [Quickstart — 30 seconds](#quickstart--30-seconds)
• [Pick the modules that match your problem](#pick-the-modules-that-match-your-problem)
• [Wire it up](#wire-it-up)
• [What you actually get](#what-you-actually-get)
• [Before / after](#before--after)
• [Design principles](#design-principles)
• [What this won't do](#what-this-wont-do)
• [Resolved structural decisions](#resolved-structural-decisions)
• [Security & compliance roadmap](#security--compliance-roadmap)
• [Contributing](#contributing)
• [License](#license)
• [Acknowledgments](#acknowledgments)

---

Why this exists

Every team building agents rediscovers the same problems:

• "Why did Claude push to main even though we said not to?" — instruction attenuation in long contexts.
• "Why does it keep refactoring code I didn't ask it to touch?" — task drift, no surgical-changes rule.
• "Why is this trust score swinging so wildly?" — Beta-Bernoulli with no prior; one observation flips the verdict.
• "Why is the same bug recurring across sessions?" — no precedent log; the agent forgets what failed last week.
• "Why did our test suite pass but the migration break in prod?" — self-certification, no independent verification.
• "Why does the subagent keep ignoring the rules we wrote?" — descriptive prose doesn't enforce; conduct never reached the subagent.
• "Why are two of our agents working at cross-purposes?" — inter-agent misalignment, not in the original failure taxonomy.

The fixes for these are well-known to people who've shipped agents at scale. They're scattered across blog posts, internal docs, and folklore. vis consolidates them into a single dependency-free framework.

---

What's in the box

The repo is a packages-monorepo. Each package owns a slice of the framework (conduct rules, engines, taxonomy, recipes, tests) so adopters can pull just the area they need.

vis/
├── packages/
│   ├── core/                        ← foundation: layering invariants + canonical taxonomy + ABI tooling
│   │   ├── conduct/                 ← 20 baseline behavior modules (discipline, context, verification,
│   │   │                              delegation, tool-use, hooks, precedent, precedent-freshness,
│   │   │                              tier-sizing, doubt-engine, failure-modes, capability-fidelity,
│   │   │                              verdict-calibration, metacognition, reversibility-foresight,
│   │   │                              prior-art-discovery, substrate-consumption, sunk-cost-iteration,
│   │   │                              context-budget)
│   │   ├── taxonomy/                ← F01–F14 (generation / action / reasoning) + axes.md
│   │   ├── runbooks/                ← F01–F14 incident-response runbooks
│   │   ├── scripts/                 ← conduct-abi-check.sh, conduct-sync.sh
│   │   ├── glossary.md              ← unified terminology
│   │   ├── anti-patterns.md         ← cross-cutting catalog of what not to do
│   │   └── CLAUDE.md                ← repo-level instructions for agents editing core
│   ├── skills/                      ← author-facing skill conduct + host recipes
│   │   ├── conduct/                 ← formatting.md, skill-authoring.md
│   │   └── recipes/                 ← 8 adoption recipes (claude-code, openai-agents, cursor,
│   │                                  langchain, pydantic-ai, baml, system-prompt,
│   │                                  stupid-agent-review)
│   ├── orchestration/               ← multi-agent + engines
│   │   ├── conduct/                 ← eval-driven-self-improvement, multi-turn-negotiation,
│   │   │                              task-decomposition, inference-substrate
│   │   ├── engines/                 ← 12 algorithmic primitives (pattern-detection, entropy-analysis,
│   │   │                              trust-scoring, drift-detection, lcs-alignment, tree-edit,
│   │   │                              scc, sprt, boundary-segmentation, llm-bandit, agentproof,
│   │   │                              calibration)
│   │   ├── docs/                    ← self-test.md (A/B fixture methodology), vis-lock-spec.md
│   │   └── templates/               ← bootstrap.sh / .ps1, sessionstart hook, vis-verify.yml
│   ├── safety/                      ← multi-agent + alignment cluster, compliance & operator wiring
│   │   ├── conduct/                 ← refusal-and-recovery.md
│   │   ├── taxonomy/                ← F15–F21 (multi-agent + alignment)
│   │   ├── runbooks/                ← F15–F21 incident-response runbooks
│   │   ├── compliance/              ← SOC 2, ISO 42001, FedRAMP, NIST AI RMF readiness
│   │   ├── security/                ← pentest + synthetic-fire artifacts
│   │   └── operator-wiring-2026-05/ ← Day-1 Datadog / Sentry / PagerDuty / Slack / Splunk wiring
│   ├── web/                         ← web-fetched-evidence discipline
│   │   └── conduct/                 ← web-fetch, research-pipeline, source-discipline,
│   │                                  citation-verification, mcp-research-discipline,
│   │                                  adaptive-adversary-baseline, provider-resilience
│   ├── memory/                      ← memory hygiene
│   │   └── conduct/                 ← memory-hygiene.md
│   ├── cost/                        ← cost + latency + eval harnesses
│   │   ├── conduct/                 ← cost-accounting.md, latency-budgeting.md
│   │   └── recipes/                 ← eval-harnesses.md
│   └── hooks/                        ← runtime advisory hooks (the enchanter-hooks plugin)
│       ├── hooks/hooks.json         ← 6 hooks: SessionStart(compact) / PreToolUse / PostToolUse
│       ├── scripts/                 ← compact-checkpoint, secret-scan, config-self-edit-guard,
│       │                              reversibility-guard, debug-hygiene, post-write-validate
│       └── .claude-plugin/          ← plugin.json (installable via the vis marketplace)
├── docs/                            ← cross-cutting docs: architecture overview, ADRs
│                                       (0001 four-layers, 0002 taxonomy expansion),
│                                       CROSS_REPO_VERSIONING.md
├── roadmap-2026/                    ← security & compliance engagement packages
├── install.sh                       ← one-liner installer (full | starter | minimal)
└── package.json                     ← changesets meta-package for cross-repo versioning

Counts as of the latest tag: 37 conduct modules across core / skills / orchestration / safety / web / memory / cost · 12 engines in orchestration/engines/ · 21 failure codes split F01–F14 (core) and F15–F21 (safety) · 21 runbooks mirroring the F-codes · 9 recipes (8 in skills/recipes/ + cost/recipes/eval-harnesses.md) · 6 runtime advisory hooks in hooks/ (the enchanter-hooks plugin).

---

Quickstart — 30 seconds

One-liner installer (vendored copy at ./shared/vis, no .git footprint):

curl -fsSL https://raw.githubusercontent.com/enchanter-ai/vis/main/install.sh | sh

Pick a smaller install if you want less surface:

curl -fsSL https://raw.githubusercontent.com/enchanter-ai/vis/main/install.sh | sh -s -- --mode starter   # packages/core + packages/skills + packages/web
curl -fsSL https://raw.githubusercontent.com/enchanter-ai/vis/main/install.sh | sh -s -- --mode minimal   # packages/core only

Or as a git submodule (history preserved, pinned via parent repo):

curl -fsSL https://raw.githubusercontent.com/enchanter-ai/vis/main/install.sh | sh -s -- --submodule

Full options: install.sh --help.

---

Pick the modules that match your problem

Don't load everything. Start with the failure mode you're seeing, pull only the modules that counter it.

| You're seeing… | Pull these modules | |---|---| | Unsolicited refactors, scope creep | discipline.md | | Rules ignored deep in long sessions | discipline.md + context.md | | Test passes but prod breaks | discipline.md + verification.md | | Subagents going rogue | delegation.md + verification.md | | Same bug returns next week | precedent.md + failure-modes.md | | Token costs spiraling | tier-sizing.md + cost-accounting.md | | Working memory degrading across turns | context.md + memory-hygiene.md | | Subagent doesn't inherit conduct | delegation.md (Conduct propagation) | | Need runtime gates, not just rules | hooks.md (Starter patterns) + packages/skills/recipes/claude-code.md | | Latency unpredictable in long workflows | latency-budgeting.md | | Agent refuses benign requests / over-refuses | refusal-and-recovery.md | | Want to learn from observed failures | eval-driven-self-improvement.md + precedent.md | | User pressures across turns until you flip | multi-turn-negotiation.md + doubt-engine.md | | Doubt-engine F01-counter prose isn't measurable | packages/orchestration/engines/calibration.md | | Failure happened — need incident steps | packages/core/runbooks/F.md (F01–F14) or packages/safety/runbooks/F.md (F15–F21) | | Want to A/B-validate a module's impact | packages/orchestration/docs/self-test.md | | Evaluating agent conduct | packages/cost/recipes/eval-harnesses.md |

The production starter pack is discipline.md + context.md + verification.md + failure-modes.md — about 4k tokens, catches the long tail.

---

Wire it up

Claude Code

In your project's CLAUDE.md:

- @shared/vis/packages/core/conduct/discipline.md
- @shared/vis/packages/core/conduct/verification.md
- @shared/vis/packages/core/conduct/tool-use.md
- @shared/vis/packages/core/conduct/failure-modes.md

For runtime enforcement (not just description), wire hooks per [packages/skills/recipes/claude-code.md](packages/skills/recipes/claude-code.md) § Enforcement wiring. The framework now includes copy-paste shell skeletons in [packages/core/conduct/hooks.md](packages/core/conduct/hooks.md) § Starter patterns — PreToolUse deny, PostToolUse inject, Stop notify. Or install them ready-made — /plugin marketplace add enchanter-ai/vis then /plugin install enchanter-hooks@vis — the enchanter-hooks plugin ships 6 advisory, fail-open hooks (post-compaction checkpoint, secret scan, config self-edit guard, reversibility guard, debug-hygiene, syntax validation) that activate without editing settings.json.

OpenAI Agents SDK

from pathlib import Path
from agents import Agent

ROOT = Path("vendor/vis/packages/core/conduct")
modules = ["discipline", "verification", "tool-use", "delegation"]
instructions = "\n\n".join((ROOT / f"{m}.md").read_text() for m in modules)

agent = Agent(name="MyAgent", instructions=instructions, model="gpt-5", tools=[...])

Full guide: [packages/skills/recipes/openai-agents.md](packages/skills/recipes/openai-agents.md).

Cursor

Drop pointer rules into .cursor/rules/:

---
description: Coding discipline — think-first, simplicity, surgical, goal-driven
globs: ["**/*"]
alwaysApply: true
---

@.cursor/vis/packages/core/conduct/discipline.md

Full guide: [packages/skills/recipes/cursor.md](packages/skills/recipes/cursor.md).

Anything else (raw API, llama.cpp, Ollama, …)

system_prompt = "\n\n".join(
    (vis_root / "packages" / "core" / "conduct" / f"{m}.md").read_text()
    for m in ["discipline", "verification", "tool-use"]
)

Full guide: [`packages/skills/recipes/system-promp

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: enchanter-ai
• Source: enchanter-ai/vis
• License: MIT

Install and usage instructions live in the source repository linked above.