Rules

Rules are short, named Markdown documents that tell Magic Coder how to do its job in this codebase or under your account — a code-review checklist, a release procedure, “always run make verify before claiming done,” a description of how a domain works. The agent reads them as guidance, similar to AGENTS.md, but as separate, individually-named units that can be loaded always or on demand.

Not the same as command permissions. This page is about Markdown content rules the agent reads. For shell-command allow/deny decisions, see Command permissions.

Where rules come from

Magic Coder loads rules from three places and merges them:

Source	Location	Loaded…
Workspace rules	<workspace>/.magic/rules/<category>/<name>.md	…when the workspace is trusted.
User rules	~/.magic/rules/<category>/<name>.md	…always.
Cloud (BridgeApp) rules	configured in BridgeApp	…always, while signed in.

Workspace rules override user rules of the same name; local rules override cloud rules of the same name.

Always-apply vs. on-demand

Each rule has an always_apply flag in its frontmatter:

• always_apply: true — the rule’s full content is loaded into the agent’s context at session start. Use for short, universally-relevant guidance you want to be unconditional.
• always_apply: false (default) — only the rule’s name and description are visible. The agent reads the body on demand by calling its read_rule tool when it judges the rule relevant.

Prefer always_apply: false for most rules. The agent is good at picking the right rule when it has clear names and descriptions, and it keeps your context window clean for actual work.

Reserve always_apply: true for the small handful of rules you want to guarantee are in scope — typically things like “always run lint before reporting done” that are short and applicable everywhere.

Authoring a rule

A rule is a Markdown file under .magic/rules/<category>/<name>.md. The category is just a subdirectory — use it to group related rules.

A minimal rule:

---
name: code-review
description: Standards we apply to every code review.
always_apply: false
---

# Code review

When reviewing code, check for:

- Unused imports / dead code
- Tests that cover the new behavior, including failure paths
- Public-API changes that are missing changelog entries
- Inputs that should be validated at the boundary
- Logging that includes enough context to debug a failure later

Reject the review if any of these are missing. Cite the specific line.

Frontmatter

Key	Required?	Notes
name	optional	The rule’s display name. If omitted, falls back to the first # Heading in the body, then to the file’s relative path (without .md).
description	optional	One-line summary used by the agent to decide whether the rule is relevant. If omitted, falls back to the first non-heading line of the body.
always_apply	optional	true to inject the body into context unconditionally, false (default) to require the agent to fetch it on demand.

File layout

<workspace>/.magic/rules/
├── common/
│   ├── code-review.md
│   └── tests-required.md
├── release/
│   ├── changelog.md
│   └── release-notes.md
└── domain/
    ├── billing.md
    └── auth.md

Or user-wide:

~/.magic/rules/
├── personal/
│   └── style.md
└── shared/
    └── release.md

The relative path under rules/ (minus .md) is the rule’s fallback name. So the file common/code-review.md becomes the rule named common/code-review unless frontmatter overrides it. Use frontmatter name: if you want a shorter command-friendly name.

Trust matters

Workspace rules are loaded only when the workspace is trusted. Until trust is granted, <workspace>/.magic/rules/ is ignored. User rules (~/.magic/rules/) are loaded regardless. See Workspaces & trust.

When to put a rule where

• Workspace — repo-specific guidance: the testing discipline, release procedure, domain quirks. Commit .magic/rules/ to source control so your team shares it.
• User — your personal style preferences, your default review checklist, anything you’d carry from project to project.
• Cloud (BridgeApp) — for org-wide rules that should follow your account across machines. Authoring cloud rules is done in BridgeApp directly today.

Rules vs. AGENTS.md

Both are Markdown context for the agent, but they’re shaped differently:

• AGENTS.md — one (or a few) document(s) describing the project: build commands, architecture, conventions, boundaries. Loaded automatically based on what you’re working on.
• Rules — many smaller, named units that the agent picks from based on relevance. Better for “the playbook for X” or “the standard for Y” than for a whole-project briefing.

Most repos benefit from both. Use AGENTS.md to brief the agent on the project; use rules to encode specific reusable disciplines.

Sharing rules

Workspace rules in <workspace>/.magic/rules/ ride along with the repo if you commit them. That’s the easiest way to give your team the same rule set. User rules are currently per-machine; cloud rules in BridgeApp are the way to share user-level rules across machines.