| name | rule-authoring |
| description | Author path-scoped rule files for pi-rules. Use when: creating/editing .pi/rules/*.md or .claude/rules/*.md | "add a project rule" | "write a pi rule" | designing always-on conventions. Triggers: "rule", "convention", "paths". |
Rule Authoring
A rule file under .pi/rules/ or .claude/rules/ injects its body into the agent's context whenever a read, edit, or write tool fires on a path that matches its paths (or unconditionally, if no paths are specified).
The body ships on every match. Every saved sentence compounds across calls — terse rules are cheap, verbose rules are expensive. Aim for clarity first, then trim.
Frontmatter
| Field | Type | Required | Default |
|---|
description | string | always | — |
paths | string or string[] (picomatch) | optional | [] (always-on) |
Invariants:
- Absence of
paths = always-on rule. The rule fires on every read/edit/write.
- Presence of
paths = path-scoped rule. Only fires when the file path matches.
paths accepts a single string (comma-separated for multiple patterns), a YAML string array, or can be omitted.- The legacy
globs field is still accepted as a silent fallback but will emit a deprecation warning.
- Paths are project-relative. Symlinks dedup by realpath.
Style — terse but readable
Write like a concise teammate, not a research paper. Plain English; trim the filler.
| Do | Don't |
|---|
| Imperative: "Use X" | Second-person: "You should use X" |
| Tables for enumerations | Long bullet lists or paragraphs |
| State the rule, then the reason | Repeat the rule three ways |
| Code blocks for templates | Prose describing what a template looks like |
Drop:
- "please", "in order to", "make sure to"
- Restating the obvious ("when writing TypeScript, use TypeScript syntax")
- Closing summaries that paraphrase the rule
Target: ≤ 200 tokens per rule. Most rules need fewer.
Why bother
The rule body is prepended to the tool result for every matching call. A 400-token rule that fires 50 times a session adds 20k tokens. A 100-token rule does the same job for 5k. The savings compound.
Optimize for a human reading the rule once a month, not for character count. If a sentence earns its keep, leave it.
Examples
Project rule (path-scoped)
---
description: TypeScript style for src/.
paths:
- "src/**/*.ts"
---
Prefer named exports; no default exports.
Avoid `any` — use `unknown` and narrow.
Tests live in `tests/unit/`.
Always-on rule
---
description: Default voice.
---
Be terse. State the result; skip the preamble. No filler.
Multiple patterns (comma-separated)
---
description: API layer rules.
paths: "src/api/**/*.ts, src/services/**/*.ts"
---
Use RESTful conventions.
Implement proper error handling.
Avoid
- Long paragraphs when a table works.
- Second-person scolding ("you must", "you should never").
- Always-on rules for instructions that only matter sometimes — every tool call pays the cost.
- Duplicating bodies across files. Realpath dedup catches symlinks; it doesn't catch copy-paste.
Discovery surface
Roots checked, in order: <cwd>/.pi/rules, <cwd>/.claude/rules, ~/.pi/rules, ~/.claude/rules.
Edits during a session are picked up on the next file change (the matcher recompiles automatically).
Run /pi-rules doctor to see which rules are loaded and why others were skipped.
