neotoma / rules

---
description: "Load when editing rules or commands: edit source in docs/ or foundation/agent_instructions/, never .cursor/rules or .cursor/commands; run setup_cursor_copies after editing."
alwaysApply: false
---

# ⚠️  DO NOT EDIT THIS FILE DIRECTLY
#
# This is a copy of: foundation/agent_instructions/cursor_rules/cursor_rules_editing.mdc
# Source of truth: foundation/agent_instructions/cursor_rules/cursor_rules_editing.mdc
#
# To edit this rule:
# 1. Edit the source file: foundation/agent_instructions/cursor_rules/cursor_rules_editing.mdc
# 2. Run '/setup_cursor_copies' to sync changes
#
# This file will be overwritten when running setup_cursor_copies.

# Cursor Rules Editing Rule

## Purpose

Ensures agents always edit the source files for cursor rules and commands, never the copies in `.cursor/rules/` or `.cursor/commands/` directories.

## Source of Truth Locations

**Foundation rules and commands:**
- Source: `foundation/agent_instructions/cursor_rules/` and `foundation/agent_instructions/cursor_commands/`
- Copies: `.cursor/rules/` and `.cursor/commands/` (created by `/setup_cursor_copies`)

**Repository rules:**
- Source: `docs/` subdirectories (e.g., `docs/foundation/`, `docs/conventions/`, `docs/developer/`)
- Copies: `.cursor/rules/` (created by `/setup_cursor_copies`)

**Repository commands:**
- Source: `docs/` subdirectories or repository-specific command locations
- Copies: `.cursor/commands/` (created by `/setup_cursor_copies`)

## Rule

**MUST NOT edit files in `.cursor/rules/` or `.cursor/commands/`**

These directories contain copies that are:
- Automatically generated by `/setup_cursor_copies`
- Overwritten when running `/setup_cursor_copies`
- Not the source of truth

## Agent Actions

### When Editing Rules or Commands

1. **Identify the source file:**
   - Foundation rules: `foundation/agent_instructions/cursor_rules/{name}.mdc`
   - Foundation commands: `foundation/agent_instructions/cursor_commands/{name}.md`
   - Repository rules: `docs/{subdirectory}/{name}_rules.mdc` or `docs/{subdirectory}/{name}_rules.md`
   - Repository commands: `docs/{subdirectory}/{name}_command.md` or repository-specific command locations

2. **Edit the source file directly**

3. **After editing, run `/setup_cursor_copies`** to sync changes to `.cursor/` directory

### Detecting Source Files

**For files in `.cursor/rules/` or `.cursor/commands/`:**
- Check the header comment (added by setup script) for source file path
- Header format:
  - `.mdc` files: YAML frontmatter comment style (`---` with `#` comments)
  - `.md` files: HTML comment style (`<!-- -->`)
- Look for pattern: `docs/{subdirectory}/*_rules.mdc` or `foundation/agent_instructions/cursor_rules/*.mdc`
- Use file naming pattern:
  - Foundation rules use original filenames (no prefix)
  - `{subdirectory}_{name}_rules.mdc` → `docs/{subdirectory}/{name}_rules.mdc`
  - Commands use original filenames (no prefix)

## Constraints

- MUST NOT edit files in `.cursor/rules/` or `.cursor/commands/`
- MUST edit source files in `docs/` or `foundation/agent_instructions/`
- MUST run `/setup_cursor_copies` after editing source files to sync changes
- MUST verify edits are in source files, not copies

## Forbidden Patterns

- Editing `.cursor/rules/*.mdc` or `.cursor/rules/*.md` directly
- Editing `.cursor/commands/*.md` directly (foundation commands or repository commands)
- Assuming `.cursor/` files are the source of truth
- Skipping `/setup_cursor_copies` after editing source files
- Removing header comments from copied files (they will be re-added by the script)

## Validation

Before committing rule or command changes:
- [ ] Changes are in source files (`docs/` or `foundation/agent_instructions/`)
- [ ] No changes were made to `.cursor/rules/` or `.cursor/commands/`
- [ ] `/setup_cursor_copies` has been run to sync changes
- [ ] All copied files in `.cursor/` have header comments (verify by checking first few lines)

## Related Documents

- `foundation/agent_instructions/cursor_rules/instruction_documentation.mdc` - How to document instructions
- `foundation/agent_instructions/cursor_commands/setup_cursor_copies.md` - Command to sync copies