Conventions

Conventions are how a project teaches itself. Write a convention once and every future grunt session loads it automatically — no copy-paste, no CLAUDE.md maintenance, no repeating yourself.

What a convention is

A convention is an entry with entry_type: "convention". It captures a decision, rule, or pattern that should apply to all future work on the project. Conventions are scoped to a project and optionally to a role.

json

{
  "entry_type": "convention",
  "title": "No mocking the database in integration tests",
  "body": "Integration tests must hit a real database. We got burned
           when mocked tests passed but a prod migration failed.
           Use the test DB fixture in tests/fixtures/db.ts.",
  "metadata": {
    "role_scope": "grunt",
    "is_convention": true,
    "priority": 1
  }
}

Auto-injection

When a grunt session boots, Vinculum loads all conventions scoped to that grunt's role and project. They're injected into the system prompt before the directive. The grunt doesn't need to ask for them — they're already there.

This means that when you write a convention today, every grunt that spawns tomorrow will follow it. No manual update to prompts or CLAUDE.md. The graph is the source of truth.

The product teaches itself

Vinculum's own conventions are visible at vinculum.run/docs/conventions. That page is generated live from Vinculum's own graph — the product documents itself by doing.

North stars

Some conventions are marked as north stars (is_north_star: true). These are the foundational principles — the decisions that should never be quietly violated. North stars get prominent placement in the conventions browser and are loaded first in system prompts.

Examples of north stars in Vinculum itself:

“The LLM is the coordinator. Vinculum is the substrate it reasons on.”
“Commits are officer duty — grunts write code, Colonels commit.”
“Questions go up, not out — escalate to Vinculum, not to the CLI operator.”

Role scoping

Conventions can be scoped to a specific role ( role_scope: "grunt") or apply to all roles (role_scope: "all"). A convention about “never running destructive git commands without confirmation” applies to every role. A convention about “always listing files touched in the implementation amendment” is grunt-specific.

Writing conventions

Write a convention whenever you correct a grunt for the same mistake twice. The first time, it's a one-off correction. The second time, it's a pattern worth encoding. Write the convention, and the third grunt won't make that mistake.

text

> use write with:
  entry_type = "convention"
  title = "Use absolute imports, not relative"
  body = "All imports in the frontend use @/ aliases.
          Relative imports (../../lib) break when files move.
          Use @/lib/database instead of ../../lib/database."
  metadata = {
    is_convention: true,
    role_scope: "grunt",
    priority: 2
  }

Conventions vs CLAUDE.md

CLAUDE.md is a static file. It doesn't know about your project's history, doesn't update when decisions change, and doesn't filter by role. Conventions are dynamic, graph-sourced, and role-aware.

That said: CLAUDE.md is still useful for things that exist before a Vinculum project is set up, or for configuration that Claude Code reads before connecting to MCP. Use CLAUDE.md for the bootstrapping layer; use conventions for everything the project has learned since.

Note

The conventions browser at /docs/conventions renders live from the Vinculum API. Add a convention and it appears the next page load.

You've read the concepts

That's the full concepts section. Next: connect your client and start working.