Create Rule

Creating Rules in ORG2

Rules are markdown files injected into the agent's system prompt on every turn. They encode project conventions, coding standards, or personal preferences.

CC alignment: mirrors .claude/rules/ in Claude Code. ORG2 native paths: .orgii/rules/ (project), ~/.orgii/rules/ (global), ~/.orgii/personal/rules/ (personal — OS Agent / channel sessions only).

Before You Begin

Determine:

1. Purpose: What should this rule enforce or teach?
2. Scope: Always apply, or only for specific files/paths?
3. Location: Global, Project, or Personal?

If you have conversation context, infer the rule content from what was discussed.

Storage Locations

Mirrors the "Source" picker in MarkdownRuleForm exactly. Do not write a "personal" rule into ~/.orgii/rules/ — that path is the Global broadcast bucket and the rule will leak into every coding session.

Tip: .cursor/rules/*.mdc files can be imported into .orgii/rules/ via the import flow in Settings → Rules. They are not the native storage location.

Rule File Format

---
description: Brief description of what this rule does
globs: "**/*.ts"
alwaysApply: false
---

# Rule Title

Your rule content here...

Frontmatter Fields

Rule Configurations

Always Apply (project-wide standards)

---
description: Core coding standards for this project
alwaysApply: true
---

Apply to Specific Files

---
description: TypeScript conventions
globs: "**/*.ts,**/*.tsx"
alwaysApply: false
---

Apply to a Directory

---
description: Backend API conventions
globs: "src/api/**"
alwaysApply: false
---

Best Practices

• Under 100 lines: Keep rules concise — the agent reads them on every turn
• One concern per rule: Split large rules into focused files
• Actionable: Write like clear internal docs, not policies
• Concrete examples: Show correct and incorrect patterns with code blocks
• No redundancy: Don't repeat what the agent already knows

Example

---
description: Error handling standards for TypeScript
globs: "**/*.ts,**/*.tsx"
alwaysApply: false
---

# Error Handling

Always propagate errors — never silently swallow them:

\`\`\`typescript
// Bad — swallows the error
try {
await fetchData();
} catch (\_e) {}

// Good — propagate with context
try {
await fetchData();
} catch (err) {
throw new DataFetchError("Unable to retrieve data", { cause: err });
}
\`\`\`

Use typed error classes, not string messages.

Checklist

• File placed at the right scope: ~/.orgii/rules/ (Global, all sessions), <project>/.orgii/rules/ (Project), or ~/.orgii/personal/rules/ (Personal — OS Agent / channel sessions only)
• Frontmatter has description and either alwaysApply: true or a globs pattern
• Content is under 100 lines
• Includes at least one concrete code example
• Rule does not duplicate existing project rules