---
description: How to create and maintain project rules
globs:
alwaysApply: false
---

# Creating Rules

Rules live in two places and are kept in sync via symlinks:

- `.cursor/rules/<rule-name>.mdc` — source of truth (Cursor format)
- `.claude/rules/<rule-name>.md` — symlink pointing to the cursor file

## Workflow

**1. Write the rule in `.cursor/rules/`**

```
.cursor/rules/my-rule.mdc
```

**2. Create a symlink in `.claude/rules/`**

```bash
ln -s ../../.cursor/rules/my-rule.mdc .claude/rules/my-rule.md
```

The `../../` prefix is required because the symlink lives two levels deep.

**3. Verify**

```bash
ls -la .claude/rules/my-rule.md
# → .claude/rules/my-rule.md -> ../../.cursor/rules/my-rule.mdc
```

## Rule File Format

```markdown
---
description: One-line summary of what this rule covers
globs:
alwaysApply: false
---

# Rule Title

Short intro paragraph.

## Section

Concrete guidance with examples.
```

- Set `alwaysApply: true` only for rules that apply to every file in the project.
- Use `globs` to scope a rule to specific paths (e.g. `packages/viewer/**`).

## Good Practices

- Keep rules under 500 lines. Split large rules into smaller focused files.
- Include concrete examples or reference real files with `@filename`.
- Add a rule when the same mistake has been made more than once — not preemptively.
- Prefer showing a correct example over listing prohibitions.

## Existing Rules

| Rule | Covers |
|---|---|
| `creating-rules` | This file — how to add rules |
| `renderers` | Node renderer pattern in `packages/viewer` |
| `systems` | Core and viewer systems architecture |
| `tools` | Editor tools structure in `apps/editor` |
| `viewer-isolation` | Keeping `@pascal-app/viewer` editor-agnostic |
| `scene-registry` | Global node ID → Object3D map and `useRegistry` |
| `selection-managers` | Two-layer selection (viewer + editor), events, outliner |
| `events` | Typed event bus — emitting and listening to node and grid events |
| `node-schemas` | Zod schema pattern for node types, createNode, updateNode |
| `spatial-queries` | Placement validation (canPlaceOnFloor/Wall/Ceiling) for tools |