neotoma / rules

---
description: "Load when modifying rule/command sources: pre-commit runs setup_cursor_copies when staged; edit source in docs/ or foundation only; do not use --no-verify to bypass."
alwaysApply: false
---

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

# Cursor Rules Sync Rule

Ensures `.cursor/rules/` and `.cursor/commands/` remain synchronized with their source files in `docs/` or `foundation/agent_instructions/`.

## Implementation

**Automated:** Rule and command syncing is enforced by a pre-commit hook that runs when source files change.

**Hook:** `scripts/linters/cursor_rules_sync_pre_commit.sh` (configured in `.pre-commit-config.yaml` as `cursor-rules-sync`)

**How it works:**
1. When files matching `docs/**/*.mdc` or `foundation/agent_instructions/cursor_rules/**/*.mdc` or `foundation/agent_instructions/cursor_commands/**/*.md` are staged, the hook runs automatically
2. Script executes `foundation/scripts/setup_cursor_copies.sh` (or repo equivalent)
3. Updated `.cursor/rules/` and `.cursor/commands/` files are staged automatically
4. Commit proceeds with synced files

**Manual execution:**
```bash
# Run the setup script directly
./foundation/scripts/setup_cursor_copies.sh

# Or via command
/setup_cursor_copies
/sync_cursor_files copies
```

## Agent Actions

Agents do NOT need to manually run `/setup_cursor_copies` after editing rule sources — the pre-commit hook handles this automatically.

When creating or modifying rule/command sources:
1. **Edit source files only** — in `docs/` or `foundation/agent_instructions/`, never `.cursor/`
2. **Commit changes** — pre-commit hook will sync `.cursor/` automatically
3. If editing outside of a commit (rare), run the setup script manually

## Source File Locations

**Foundation rules and commands:**
- Source: `foundation/agent_instructions/cursor_rules/*.mdc`, `foundation/agent_instructions/cursor_commands/*.md`
- Copies: `.cursor/rules/`, `.cursor/commands/` (synced via setup script)

**Repository rules and commands:**
- Source: `docs/**/*_rules.mdc`, `docs/**/*_command.md`
- Copies: `.cursor/rules/`, `.cursor/commands/` (synced via setup script)

## Constraints

- **MUST NOT** edit files in `.cursor/rules/` or `.cursor/commands/` directly
- **MUST** edit source files in `docs/` or `foundation/agent_instructions/`
- **MUST** respect the pre-commit hook (do not use `--no-verify` to bypass)
- If hook fails, fix the issue and retry commit

## Related Files

- `scripts/linters/cursor_rules_sync_pre_commit.sh` — Pre-commit hook implementation
- `.pre-commit-config.yaml` — Hook configuration (cursor-rules-sync)
- `foundation/scripts/setup_cursor_copies.sh` — Setup script (invoked by hook)
- `.cursor/rules/cursor_rules_editing.mdc` — Rule about not editing .cursor/ directly