@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-agent-instructions-analyze/references/docs/cursor-rules-files.md

@@ -0,0 +1,510 @@
+# Cursor Rules System -- Deep Research Synthesis
+
+> **Research date:** 2026-02-19
+> **Primary source:** Official Cursor documentation at `cursor.com/docs/context/rules`
+> **Secondary sources:** Community references, cross-validated (see Source Index)
+
+---
+
+## Table of Contents
+
+1. [Overview and Architecture](#1-overview-and-architecture)
+2. [File Format Specification (.mdc)](#2-file-format-specification-mdc)
+3. [Frontmatter Fields -- Complete Reference](#3-frontmatter-fields----complete-reference)
+4. [Rule Types and Activation Modes](#4-rule-types-and-activation-modes)
+5. [Rule Scopes: Project, User, and Team](#5-rule-scopes-project-user-and-team)
+6. [AGENTS.md Integration](#6-agentsmd-integration)
+7. [Rule Precedence and Loading](#7-rule-precedence-and-loading)
+8. [Legacy .cursorrules File](#8-legacy-cursorrules-file)
+9. [Cursor 2.2+ Folder-Based Format (RULE.md)](#9-cursor-22-folder-based-format-rulemd)
+10. [Notepads vs Rules](#10-notepads-vs-rules)
+11. [Best Practices from Official Docs](#11-best-practices-from-official-docs)
+12. [Limitations](#12-limitations)
+13. [Source Index](#13-source-index)
+
+---
+
+## 1. Overview and Architecture
+
+**Source: cursor.com/docs/context/rules (official)**
+
+Rules provide system-level instructions to Cursor's Agent. The official documentation explains the core rationale:
+
+> "Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level."
+
+When rules are activated:
+
+> "Rule contents are included at the start of the model context."
+
+Rules bundle prompts and instructions that persist across chat sessions, removing the need to repeat project conventions, style preferences, or architectural constraints in every interaction.
+
+---
+
+## 2. File Format Specification (.mdc)
+
+**Source: cursor.com/docs/context/rules (official), community references**
+
+### Supported Extensions
+
+The official documentation states:
+
+> "Cursor supports `.md` and `.mdc` extensions. Use `.mdc` files with frontmatter to specify `description` and `globs` for more control over when rules are applied."
+
+- **`.mdc` files** -- Markdown with YAML frontmatter for structured metadata control
+- **`.md` files** -- Plain markdown without frontmatter; simpler but less activation control
+
+### File Structure
+
+An `.mdc` file has two sections:
+
+1. **YAML frontmatter** (delimited by `---`) containing metadata
+2. **Markdown body** containing the rule instructions
+
+```yaml
+---
+description: "Brief explanation of rule purpose"
+alwaysApply: false
+globs: ["src/**/*.ts", "lib/**/*.ts"]
+---
+
+# Rule Title
+
+Rule content in markdown format.
+
+- Instruction one
+- Instruction two
+
+## Code Examples
+
+Reference files with @filename.ts syntax.
+```
+
+### File References
+
+Rules support the `@filename.ts` syntax to include external files in the rule context, enabling templates and reusable code snippets without duplicating content.
+
+### Naming Convention
+
+Community best practice (mer.vin source):
+
+- Use **kebab-case**: `code-style-guide.mdc`
+- Choose descriptive names indicating purpose
+- Group related rules: `code-style-javascript.mdc`, `code-style-python.mdc`
+
+---
+
+## 3. Frontmatter Fields -- Complete Reference
+
+**Source: cursor.com/docs/context/rules (official)**
+
+The official documentation defines **three** frontmatter fields. No additional fields are documented.
+
+### `description` (string)
+
+- **Purpose:** A concise explanation of the rule's purpose.
+- **Used by:** The Agent, to determine whether to apply the rule when in "Apply Intelligently" (agent-requested) mode.
+- **Required for:** "Apply Intelligently" type rules -- without a description, the Agent has no basis for deciding relevance.
+- **Example:** `description: "Python coding guidelines for backend services"`
+
+### `alwaysApply` (boolean)
+
+- **Purpose:** Controls whether the rule is automatically included in every chat session.
+- **Values:** `true` or `false`
+- **When `true`:** The rule is included in every chat session regardless of context. Any `globs` listed are parsed but effectively ignored in this mode.
+- **When `false`:** The Agent decides based on the `description` field and/or `globs` pattern.
+- **Official quote:** "The rule will be applied to every chat session."
+
+### `globs` (string or string array)
+
+- **Purpose:** File path patterns determining when the rule is automatically attached.
+- **Format:** Standard glob patterns.
+- **Examples:** `"*.tsx"`, `["src/**/*.ts", "lib/**/*.ts"]`, `"src/components/**/*"`
+- **Behavior:** "Auto-applies when matching files are referenced" in conversation.
+
+### Activation Mode Matrix
+
+The activation mode is determined by the **combination** of frontmatter fields:
+
+| Configuration                                       | Resulting Mode                                            |
+| --------------------------------------------------- | --------------------------------------------------------- |
+| `alwaysApply: true`                                 | **Always** -- included in every session                   |
+| `alwaysApply: false` + `globs` set                  | **Auto Attached** -- included when matching files appear  |
+| `alwaysApply: false` + `description` set (no globs) | **Agent Requested** -- Agent decides based on description |
+| No frontmatter / none of the above                  | **Manual** -- user must @-mention the rule                |
+
+### Fields NOT in Official Documentation
+
+The following field names appear in some community discussions but are **not confirmed in official Cursor documentation** as of this research date:
+
+- **`agentRequested`** -- not an official frontmatter field. Agent-requested behavior is achieved by setting `alwaysApply: false` with a `description` and no `globs`.
+- **`manual`** -- not an official frontmatter field. Manual mode is the default when no activation metadata is present.
+
+The official docs use a UI-based "type dropdown" in the Cursor Settings interface to control rule type, which maps to the three frontmatter fields above.
+
+---
+
+## 4. Rule Types and Activation Modes
+
+**Source: cursor.com/docs/context/rules (official)**
+
+The official documentation defines four application modes:
+
+### Always Apply
+
+> "Apply to every chat session."
+
+- **Frontmatter:** `alwaysApply: true`
+- **Use case:** Universal project standards, architectural constraints, language preferences.
+- **Behavior:** Included in context for every Agent interaction regardless of what files are being discussed.
+
+### Apply Intelligently (Agent Requested)
+
+> "When Agent decides it's relevant based on description."
+
+- **Frontmatter:** `alwaysApply: false`, `description` set, no `globs`
+- **Use case:** Rules that are only relevant in certain conversational contexts.
+- **Behavior:** The Agent reads the rule's `description` and decides whether to load the full rule content into context. This is a two-step process: the Agent first sees descriptions of available rules, then requests full content for relevant ones.
+
+### Apply to Specific Files (Auto Attached)
+
+> "When file matches a specified pattern."
+
+- **Frontmatter:** `globs` set with file patterns
+- **Use case:** Language-specific or directory-specific conventions.
+- **Behavior:** Automatically included when files matching the glob pattern are referenced in the conversation.
+
+### Apply Manually
+
+> "When @-mentioned in chat (e.g., `@my-rule`)."
+
+- **Frontmatter:** None of the activation fields set (or no frontmatter at all).
+- **Use case:** Specialized rules needed only on demand.
+- **Behavior:** User explicitly invokes the rule by typing `@rule-name` in the chat.
+
+---
+
+## 5. Rule Scopes: Project, User, and Team
+
+**Source: cursor.com/docs/context/rules (official)**
+
+### Project Rules
+
+> "Stored in `.cursor/rules`, version-controlled and scoped to your codebase."
+
+- **Location:** `.cursor/rules/` directory in the project root.
+- **Format:** `.mdc` or `.md` files.
+- **Version control:** Yes -- intended to be committed to the repository.
+- **Scope:** Applies to all users working on the project.
+- **Organization:** Can use subdirectories for hierarchical organization.
+
+```
+.cursor/rules/
+  code-style.mdc
+  testing.mdc
+  frontend/
+    components.mdc
+    styling.mdc
+```
+
+### User Rules
+
+> "Global to your Cursor environment. Used by Agent (Chat)."
+
+- **Location:** Configured in **Cursor Settings** (Settings > General > Rules for AI).
+- **Storage:** Managed through the Cursor Settings UI, **not** a file-system directory.
+- **Scope:** Apply across all projects for the individual user.
+- **Format:** Plain text entered in the settings interface.
+- **Important limitation:** "User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They are only used by Agent (Chat)."
+
+**Note:** The official documentation does NOT specify a `~/.cursor/rules/` directory for user rules. User rules are managed exclusively through the Cursor Settings UI. Multiple community sources confirm this -- user rules are not file-based.
+
+### Team Rules
+
+> "Team-wide rules managed from the dashboard. Available on Team and Enterprise plans."
+
+- **Location:** Cursor team dashboard (cloud-managed).
+- **Scope:** Organization-wide, apply to all team members.
+- **Enforcement options:**
+  - Enable rules immediately vs. draft status.
+  - Require enforcement to prevent users from disabling them.
+- **Access:** Administrators manage through the Cursor dashboard.
+
+---
+
+## 6. AGENTS.md Integration
+
+**Source: cursor.com/docs/context/rules (official)**
+
+Cursor natively supports AGENTS.md as a first-class alternative to `.cursor/rules`:
+
+> "AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to `.cursor/rules`."
+
+### Key Characteristics
+
+- **Format:** Plain markdown, no frontmatter required.
+- **Location:** Project root or subdirectories.
+- **Nested support:** Official documentation confirms: "Nested AGENTS.md support in subdirectories is now available."
+- **Hierarchy:** Instructions from nested files combine hierarchically with more specific instructions taking precedence.
+
+```
+project/
+  AGENTS.md           # Global project instructions
+  frontend/AGENTS.md  # Frontend-specific instructions
+  backend/AGENTS.md   # Backend-specific instructions
+```
+
+### AGENTS.md vs .cursor/rules
+
+| Aspect                   | AGENTS.md                              | .cursor/rules         |
+| ------------------------ | -------------------------------------- | --------------------- |
+| Format                   | Plain markdown                         | .mdc with frontmatter |
+| Activation control       | Always on                              | Four activation modes |
+| Glob targeting           | No                                     | Yes                   |
+| Agent-requested          | No                                     | Yes                   |
+| Complexity               | Simple                                 | More configurable     |
+| Cross-tool compatibility | Works with Claude Code, Windsurf, etc. | Cursor-specific       |
+
+AGENTS.md is positioned as "a simple alternative" for projects that do not need fine-grained activation control. It is also the recommended format for cross-tool compatibility since Claude Code, Windsurf, and other AI coding tools also read AGENTS.md.
+
+---
+
+## 7. Rule Precedence and Loading
+
+**Source: cursor.com/docs/context/rules (official)**
+
+### Precedence Order
+
+The official documentation specifies a clear precedence chain:
+
+> "Rules are applied in this order: Team Rules -> Project Rules -> User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts."
+
+**Highest to lowest priority:**
+
+1. **Team Rules** -- organization-wide, managed by admins
+2. **Project Rules** -- `.cursor/rules/` directory and AGENTS.md
+3. **User Rules** -- individual user settings
+
+### Discovery and Loading
+
+Rules are discovered through:
+
+1. **Manual creation:** "New Cursor Rule" command in the command palette.
+2. **Cursor Settings:** Settings > Rules, Commands interface.
+3. **File system scanning:** Cursor scans `.cursor/rules/` and project root for AGENTS.md.
+4. **Remote import:** Rules can be imported from GitHub repositories.
+5. **Agent Skills:** Treated as agent-decided rules.
+
+### Merging Behavior
+
+All applicable rules from all scopes are merged together. When conflicting guidance exists between scopes, the higher-precedence source wins. Within the same scope, all matching rules are included (there is no documented mechanism for one project rule to override another project rule).
+
+---
+
+## 8. Legacy .cursorrules File
+
+**Source: cursor.com/docs/context/rules (official)**
+
+### Current Status
+
+> "The `.cursorrules` (legacy) file in your project root is still supported but will be deprecated."
+
+### Migration Path
+
+> "We recommend migrating to Project Rules or to AGENTS.md."
+
+The legacy `.cursorrules` file:
+
+- Located at the **project root** (not in `.cursor/rules/`).
+- Single file, no frontmatter support.
+- No activation mode control (always applied).
+- Still functional as of this writing but deprecated since Cursor ~0.45.
+- Will be removed in a future version.
+
+### Migration Strategy
+
+1. Move content from `.cursorrules` to one or more `.mdc` files in `.cursor/rules/`.
+2. Add appropriate frontmatter to control activation.
+3. Alternatively, rename to `AGENTS.md` if simple always-on behavior is sufficient.
+4. Delete the `.cursorrules` file.
+
+---
+
+## 9. Cursor 2.2+ Folder-Based Format (RULE.md)
+
+**Source: awesome-cursor-rules-mdc GitHub reference, community reports**
+
+**Important caveat:** This information comes from community sources, not the primary official documentation page. It may reflect beta/preview behavior or a format transition in progress.
+
+As of Cursor version 2.2, a new folder-based rule format was introduced:
+
+> "As of 2.2, `.mdc` cursor rules will remain functional however all new rules will now be created as folders in `.cursor/rules`."
+
+### New Structure
+
+Instead of individual `.mdc` files, each rule becomes a **folder** containing a `RULE.md` file:
+
+```
+.cursor/rules/
+  code-style/
+    RULE.md
+  testing/
+    RULE.md
+  frontend-components/
+    RULE.md
+```
+
+### RULE.md Format
+
+The `RULE.md` file uses the same frontmatter fields (`description`, `globs`, `alwaysApply`) and markdown body as `.mdc` files. The folder structure provides:
+
+- Better organization and maintainability.
+- Potential for rule-specific assets alongside the RULE.md.
+- Improved readability in file explorers.
+
+### Backward Compatibility
+
+Legacy `.mdc` files continue to work. The change affects how the Cursor UI creates **new** rules (via "New Cursor Rule" command), not how existing rules are read.
+
+---
+
+## 10. Notepads vs Rules
+
+**Source: Community articles (adamtheautomator.com, frontendmasters.com)**
+
+### What Notepads Are
+
+Notepads are persistent repositories for coding instructions and context within Cursor. They function as reusable context documents accessible from the Explorer sidebar that can be referenced in chat conversations.
+
+Unlike temporary chat sessions where context vanishes:
+
+> "This context is temporary though. Close your editor or start a new chat, and these rules disappear. That's where Notepads come in."
+
+### Key Differences from Rules
+
+| Aspect          | Rules                                        | Notepads                          |
+| --------------- | -------------------------------------------- | --------------------------------- |
+| Activation      | Automatic (various modes)                    | Manual (@-reference only)         |
+| Storage         | File system (`.cursor/rules/`) or Settings   | Cursor UI (Explorer sidebar)      |
+| Version control | Yes (project rules)                          | No -- local to Cursor instance    |
+| Sharing         | Via repo (project) or dashboard (team)       | Not shareable across team members |
+| Scope           | System-level instructions                    | Reference material and context    |
+| Token usage     | Always-on rules consume tokens every session | Only when explicitly referenced   |
+
+### When to Use Each
+
+**Use Rules when:**
+
+- Standards should apply automatically.
+- Instructions should be version-controlled.
+- Team-wide enforcement is needed.
+- Behavior should be consistent across all sessions.
+
+**Use Notepads when:**
+
+- Context is needed only on demand.
+- Content is personal or not team-wide.
+- You want to minimize token usage.
+- Storing reference material, templates, or architectural notes.
+
+### How to Reference Notepads
+
+Type `@notepad-name` in chat to include a notepad's content in the conversation context.
+
+---
+
+## 11. Best Practices from Official Docs
+
+**Source: cursor.com/docs/context/rules (official)**
+
+### Size and Scope
+
+> "Keep rules under 500 lines."
+
+> "Split large rules into multiple, composable rules."
+
+### Quality Principles
+
+> "Good rules are focused, actionable, and scoped."
+
+> "Provide concrete examples or referenced files."
+
+> "Avoid vague guidance. Write rules like clear internal docs."
+
+> "Reference files instead of copying their contents -- this keeps rules short" and prevents staleness.
+
+### Philosophy
+
+> "Start simple. Add rules only when you notice Agent making the same mistake repeatedly."
+
+### What to Avoid
+
+The official documentation explicitly warns against:
+
+> "Copying entire style guides: Use a linter instead."
+
+> "Documenting every possible command: Agent knows common tools."
+
+> "Adding instructions for edge cases that rarely apply."
+
+> "Duplicating what's already in your codebase: Point to canonical examples."
+
+### Rule Organization Recommendations
+
+1. **One purpose per file** -- each rule should address a single concern.
+2. **Use glob patterns** for language-specific or directory-specific rules rather than making everything always-on.
+3. **Use Agent Requested mode** for rules that are only sometimes relevant to save context window space.
+4. **Include code examples** showing both correct and incorrect patterns.
+5. **Reference files** with `@filename` syntax instead of copying content.
+
+---
+
+## 12. Limitations
+
+**Source: cursor.com/docs/context/rules (official)**
+
+### Feature Scope
+
+Rules do NOT apply to:
+
+- **Cursor Tab** (autocomplete suggestions).
+- **Other AI features** beyond Agent (Chat).
+
+### User Rules Specifically
+
+> "User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They are only used by Agent (Chat)."
+
+### Context Window
+
+Rules consume context window space. Always-on rules with large content reduce the available context for actual code and conversation. This is a practical reason to:
+
+- Keep rules concise.
+- Use targeted activation modes (globs, agent-requested) instead of always-on.
+- Split large rule sets into composable pieces.
+
+No specific maximum size is documented beyond the "500 lines" recommendation.
+
+---
+
+## 13. Source Index
+
+### Primary Official Source
+
+- **Cursor Rules Documentation** -- `https://cursor.com/docs/context/rules`
+  - Fetched via `markdown.new` proxy and direct URL on 2026-02-19.
+  - Contains: rule types, frontmatter fields, precedence, AGENTS.md, legacy support, best practices, limitations.
+
+### Community and Secondary Sources
+
+- [awesome-cursor-rules-mdc reference](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/cursor-rules-reference.md) -- Cursor 2.2 folder-based format details
+- [Cursor IDE Rules Deep Dive (mer.vin)](https://mer.vin/2025/12/cursor-ide-rules-deep-dive/) -- Technical specification details, naming conventions
+- [Cursor Rules (cursor101.com)](https://cursor101.com/cursor/rules) -- User rules location, glob patterns
+- [Cursor Notepads for Coding Standards (adamtheautomator.com)](https://adamtheautomator.com/cursor-notepads-coding-standards/) -- Notepads functionality and usage
+- [Notepads course (frontendmasters.com)](https://frontendmasters.com/courses/pro-ai/notepads/) -- Notepads vs rules comparison
+- [What are Cursor Rules (workos.com)](https://workos.com/blog/what-are-cursor-rules) -- User rules storage clarification
+- [Cursor AI Complete Guide 2025 (medium.com)](https://medium.com/@hilalkara.dev/cursor-ai-complete-guide-2025-real-experiences-pro-tips-mcps-rules-context-engineering-6de1a776a8af) -- General overview
+- [Cursor AI Rules Guide 2026 (promptxl.com)](https://promptxl.com/cursor-ai-rules-guide-2026/) -- Modern setup practices
+
+### Notes on URL Structure
+
+- `docs.cursor.com/context/rules` now redirects (308 Permanent Redirect) to `cursor.com/docs`. The canonical documentation URL is `cursor.com/docs/context/rules`.
+- `docs.cursor.com/context/rules-for-ai` also redirects to `cursor.com/docs`. There is no separate "rules-for-ai" page; the functionality has been consolidated into the main rules documentation.