key skills

.cursor/rules/creating-rules.mdc

@@ -0,0 +1,76 @@
+---
+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 |