Team rules
Team rules are conventions you write once in your Team Context that reach every AI coworker on your team, in every repo, in every coding tool: Claude Code, Codex, Cursor, Gemini, Droid, OpenCode, Amp, and Goose. One file replaces a copy per repo per tool, and there is nothing left to drift.
One design system, three repos
Say your team ships a desktop app, a mobile app, and a website: three repos, one visual language. The spacing scale, color tokens, typography, and component naming have to hold across all three, or the product stops looking like one product.
Today you have two options, and both leak. Paste the conventions into each repo's local rule files (.claude/rules/, .cursor/rules/, AGENTS.md) and watch the copies drift, or re-explain them at the start of every session. There is no clean way to sync rules between repositories, and a rule written for Claude Code never reaches the coworker on Cursor.
A team rule fixes both problems at once. Write tokens.md once in Team Context, and the ox CLI delivers it to every AI coworker in all three repos at session start, whichever tool that coworker runs.
Where team rules live
Team Context is a git repo on your machine. Team rules are markdown files under agents/rules/, one concern per file. Subdirectories are walked, so organize them as the library grows.
Run ox status to see the exact path for your team, then open it in your editor if you prefer.
Team rule, repo rule, or personal rule?
Every rule has a natural home. Pick it by asking who the rule applies to, not where you happen to be typing.
| Put it in | When | Who it reaches |
|---|---|---|
Team Context: agents/rules/<topic>.md | It applies to your team's work in general: design tokens, testing philosophy, security policy, review conventions, language idioms | Every coworker, every repo, every coding tool |
The repo: .claude/rules/<topic>.md (or your tool's equivalent) | It's specific to this one codebase: its paths, services, schemas, build steps | Anyone who clones this repo and uses that tool |
Your home directory: ~/.claude/rules/<topic>.md | It's a personal preference you don't want to impose on the team | You |
If you've been sharing Claude Code rules across your team by committing them to each repo's .claude/rules/, the test is whether the rule mentions anything only that codebase has. If it doesn't, it's a team rule. When you edit a .claude/rules/ file that reads as generally applicable, your AI coworker should offer to publish it to the team as well.
Write a team rule
Each rule is a markdown file with YAML frontmatter. Only name and description are required.
---
name: ds-component-naming
description: Shared design-system components use the Ds prefix and the same name in every repo.
---
**Why:** the desktop app, mobile app, and website ship the same components. When `DsButton`
is `PrimaryButton` in one repo and `Button` in another, nobody can search across them and
the design team has no single name to reference.
**How to apply:**
- Prefix shared components with `Ds`: `DsButton`, `DsCard`, `DsDialog`.
- Use the identical name in all three repos, including tests and stories.
- A new shared component gets its name in the design-system catalog before it lands anywhere.Write the body the way you'd brief a new coworker: why the rule exists, then how to apply it. The description is the one line your AI coworker sees in every session, so make it the line that tells it when to open the file.
Frontmatter fields
| Field | Required | Values | What it does |
|---|---|---|---|
name | yes | kebab-case identifier | Stable handle for cross-references and superseded-by |
description | yes | one short line | Shown in the rule catalog every session |
repos | no | list of owner/repo slugs | Omit for all team repos. Set it to limit the rule to those repos |
globs | no | path patterns | Which files the rule is about. Omit for any file |
audience | no | ai, human, both | Default ai. human rules never enter AI coworker context |
visibility | no | always, indexed, hidden | Default indexed. How much of the rule loads each session |
status | no | active, draft, superseded-by:<name> | Default active. draft and superseded rules stay out of sessions |
from-discussion | no | discussion id | Links the rule to the recorded discussion that decided it |
Control how much context a rule costs
Every rule reaches your AI coworker through ox agent prime, and every token it loads competes with the actual work. visibility: decides how much of a rule loads.
| Value | What loads each session | Use it for |
|---|---|---|
indexed (default) | Name, description, and path. Your AI coworker reads the full file when the task calls for it | Almost everything |
always | The full body, inlined, every session | Short rules that must never be missed: security, escalation |
hidden | Nothing, unless the rule is named explicitly | Drafts, archived rules, work in progress |
always costs context in every session, on every repo, for every coworker on the team. Keep it rare, and keep those rules to a paragraph or two. A substantive rule belongs in indexed; your AI coworker opens it when the description matches the task.
ox agent list reports the cumulative tokens delivered into AI coworker sessions, split three ways: what the ox CLI itself injects, what your team's content adds (including always rule bodies), and what the project's own AGENTS.md adds. If the team bucket is climbing into the thousands, demote some rules to indexed.
Scope a rule to file types with globs:
Some rules are about certain files, not certain repos. The design system's token rule is one: it applies in all three repos, but only when someone is editing styles or components.
---
name: ds-tokens
description: Use the shared spacing, color, and type tokens; never hardcode values.
globs: ["**/*.css", "**/*.tsx"]
---
**Why:** a hardcoded `#1a1a1a` or `13px` in any of the three repos drifts the moment the
palette or the scale changes.
**How to apply:**
- Spacing: the 4px scale, `--space-1` through `--space-8`. No arbitrary pixel values.
- Color: tokens only (`--color-surface`, `--color-accent`). No hex literals.
- Type: `--text-body` and `--text-heading-*`. Never set `font-size` directly.Both forms parse, so use whichever you already have:
globs: ["**/*.css", "**/*.tsx"] # list form, same shape as repos:
globs: **/*.css,**/*.tsx # comma form, same shape as Cursor rule filesglobs: is advisory today. Your AI coworker sees the scope next to the rule in its session context and applies the rule when the files it's working on match. Native path-triggered loading, where the coding tool itself loads the rule the moment a matching file is opened, arrives with rule sync-out. A rule you scope now gains that automatically.
repos: and globs: are independent axes. The combination most teams need is the one that had no expression before: applies everywhere, but only to certain files.
| Any file | Scoped with globs: | |
|---|---|---|
All team repos (no repos:) | Escalation policy, review conventions | Design tokens (**/*.css,**/*.tsx), Go error-wrapping idioms (**/*.go), migration rules (migrations/**) |
Some repos (repos: set) | "The billing service is PCI scope" | Schema rules in the two repos that own schemas |
Roll out to one repo first with repos:
Omit repos: and a rule applies to every repo on the team. To pilot a rule before the whole team lives with it, name the repo you want to start in.
---
name: ds-tokens
description: Use the shared spacing, color, and type tokens; never hardcode values.
repos: ["acme/mobile-app"]
globs: ["**/*.css", "**/*.tsx"]
---Once it holds up there, delete the repos: line and push. The same file now reaches the desktop app and the website with no other change. While you're still drafting, status: draft keeps a rule out of sessions entirely.
Publish to your team
Team Context is a git repo the ox CLI keeps in sync, so publishing a rule is a commit and a push.
On their next session, every AI coworker on the team sees the new rules: the full body for always, a catalog entry for indexed. Nothing to install, nothing to copy into other repos.
Who a team rule reaches:
- Every coworker who runs the ox CLI in a repo connected to the team. Coworkers who don't use the ox CLI won't see it, the same way
.claude/rules/only reaches Claude Code users. - Every AI coworker those coworkers use. The rule loads through
ox agent prime, which works the same for every supported coding agent.
For Claude Code, the ox CLI also installs a pointer rule so Claude Code knows to look in Team Context, instead of copying every team rule into every clone.
The same reference is available offline with ox guide team-rules. Team skills (reusable workflows, as opposed to conventions) are on the way; this page covers rules.
What's next
- Team Context: everything else that lives alongside your rules, and how AI coworkers read it
- How it works: the prime, work, capture loop that delivers rules at session start
- Supported coding agents: every tool team rules reach, and its integration tier
- SageOx + Claude Code: the installed rules and hooks specific to Claude Code
- ox guide: read this reference in your terminal with
ox guide team-rules