Rules

Rules are the core configuration unit in AgentsMesh. Each rule is a Markdown file with optional YAML frontmatter stored in .agentsmesh/rules/.

The root rule

_root.md is the only required file. It is always applied regardless of target, scope, or glob.

---
root: true
---

# Project Guidelines

- Write tests before implementation.
- Max 200 lines per file.
- Use TypeScript strict mode.
- Prefer pure functions over classes.

Note

The filename _root.md is reserved. AgentsMesh always treats it as always-on and required.

Additional rules

Additional rules live alongside _root.md and can be scoped by target, glob pattern, or left unscoped (applied to all targets).

Unscoped rule (all targets)

---
description: Security conventions
---

Never log sensitive data. Validate all external inputs.
Use parameterized queries. Avoid `eval()`.

Target-scoped rule

---
description: Frontend conventions
targets: [cursor, claude-code]
globs: [src/components/**/*.tsx]
---

Use functional components with hooks. No class components.
Prefer Tailwind utility classes over custom CSS.

Scoping and shared root files

Several targets read the same root instruction file (AGENTS.md). A rule scoped with targets: to one of them still lands in a file every one of them reads, because one file cannot differ per target. AgentsMesh keeps every scoped rule and warns that the scoping was widened, rather than dropping one target’s rule. To keep a rule genuinely private to one tool, scope it to a target that writes its own rule files (for example cursor → .cursor/rules/).

Codex CLI rule with instruction variant

---
description: Codex execution rule
codex_emit: execution
codex_instruction: override
---

Always run `pnpm typecheck` before committing.

Frontmatter reference

Field	Type	Description
root	boolean	Always-applied rule. Required for _root.md.
description	string	Human-readable rule name shown in tool menus.
targets	string[]	Limit rule to specific tools. Empty = all targets. See the supported tools matrix for valid IDs.
globs	string[]	File patterns this rule applies to (tool-dependent). Uses gitignore-style glob syntax. Claude Code reads a rule’s scope from paths:, so generate writes globs there as paths, and import --from claude-code reads paths (a list or a comma-separated string) back into globs.
trigger	string	Windsurf activation mode: always_on, model_decision, glob, manual.
codex_emit	string	Codex CLI instruction type: advisory or execution.
codex_instruction	string	Codex nested instruction format: set to override to opt in; omit for the default.

Tool-specific behavior

Rules are mapped to each tool’s native format during generation. See the Rules row in the supported tools matrix for per-target support levels and the generate output locations for target directory mappings.

A rule with globs goes to Windsurf once, as .windsurf/rules/<name>.md with trigger: glob and a globs: line: Windsurf reads the scope from globs (one string, several patterns joined by commas) and ignores a singular glob:. agentsmesh import --from windsurf reads globs as a string or a list, and the older glob:, and keeps a brace pattern such as *.{ts,tsx} whole. Windsurf also reads a <dir>/AGENTS.md as a rule for that whole folder, so AgentsMesh does not write one for Windsurf: it would load the rule twice and apply it to more files than its globs name. agentsmesh import --from windsurf still reads a <dir>/AGENTS.md you wrote by hand as a rule for that folder.

Some targets fold additional rules into a root or aggregate instruction file. In those cases AgentsMesh wraps each embedded rule in a managed embedding block so repeated generation does not append duplicates and import can restore the rule to .agentsmesh/rules/*.md.

File naming

Rule filenames become the rule identifier in tool menus. Use kebab-case descriptive names:

.agentsmesh/rules/
  _root.md
  security.md
  frontend-react.md
  backend-api.md
  testing.md

No name collisions are allowed. AgentsMesh lints for duplicate rule names during agentsmesh lint.