Team Conventions¶

Team conventions are shared behavioral rules that define how agents should work in your project. They are distinct from knowledge ("how to behave" vs "what we know") and have higher priority -- conventions appear before knowledge in onboarding and instructions.

When to use conventions¶

• Git workflow rules (branching strategy, commit messages, no force-push)
• Environment constraints (no sudo, use venvs, Docker for isolation)
• Communication style (language, tone, formatting preferences)
• Naming standards (API field casing, file naming, variable conventions)
• Security policies (no secrets in code, credential handling)

Adding conventions¶

Via agent¶

You: "We always use feature branches and never force-push to main. Save that as a convention."
Agent: [calls context_add_convention with key="git"] Done.

Via CLI¶

# Inline content
context-teleport convention add git "Always use feature branches. Never force-push to main."

# From a file
context-teleport convention add git --file git-rules.md

# From stdin
echo "No sudo. Use venvs." | context-teleport convention add environment

Import from an existing file¶

If you already have rules in a CLAUDE.md, AGENTS.md, or similar file:

context-teleport import conventions ~/.claude/CLAUDE.md

The importer splits the file by ## headers. Each section becomes a separate convention with the slugified header as the key. For example:

# My Team Rules

## Git Workflow
Always use feature branches.
Commit early, commit often.

## Environment
No sudo access.
Use virtual environments for Python.

This produces two conventions: git-workflow and environment.

Managing conventions¶

# List all conventions
context-teleport convention list

# Read a specific convention
context-teleport convention get git

# Update a convention
context-teleport convention add git "Updated content here."

# Remove a convention
context-teleport convention rm git

# Change scope
context-teleport convention scope git private

How conventions reach agents¶

Conventions are delivered to agents through multiple channels:

1. MCP instructions -- listed before knowledge at session start
2. Onboarding prompt -- included in the ## Team Conventions section
3. Adapter export -- written to each tool's native format

Export formats¶

Conventions vs knowledge¶

Scoping¶

Conventions support the same scoping as other content types:

• public (default): shared with the team via git
• private: local to this machine, not synced
• ephemeral: session-only, cleared on ephemeral cleanup