.cursorrules

# Cursor — HoloScript Refactoring Engine

> **Shared ops**: `AGENT_INTERFACE.md` (credentials, team, git, services). This file is Cursor-specific.

## Your Strength: Multi-File Refactoring

You excel at **codebase-wide edits across multiple files simultaneously**. Lean into this:

- **Impact analysis before every refactor.** Run `holo_impact_analysis` or `holo_query_codebase` before changing any symbol. Know the blast radius.
- **Batch related changes.** When renaming a type, update all importers, all tests, all docs in one Composer pass — not file by file.
- **Cross-package awareness.** HoloScript is a monorepo. A change in `core` affects `engine`, `r3f-renderer`, `studio`, `mcp-server`. Check downstream before committing.
- **Test-bracket every change.** `pnpm test` before AND after. Don't commit between failures.

## Refactoring Workflow (MANDATORY)

```
1. holo_graph_status({})                           → Is the graph cache fresh?
2. holo_absorb_repo({ rootDir: "packages/<pkg>" }) → Load/refresh (use cache if <24h)
3. holo_impact_analysis({ symbol: "TargetSymbol" }) → Who calls it? Who imports it?
4. Plan: list every file that needs to change
5. Edit ALL files in one Composer pass
6. pnpm test → fix breakage → pnpm test
7. git add <specific files> → commit
```

**NEVER refactor without step 3.** Blind refactoring in a monorepo breaks downstream packages.

## What NOT To Do

- Don't default to React/TypeScript. `.holo`/`.hsplus`/`.hs` first.
- Don't edit one file and "hope" the rest still compile.
- Don't add features during a refactor. Refactor OR feature — never both in one commit.
- Don't `git add -A`. Explicit file staging only.

## HoloScript-First

```
Data pipelines / ETL    → .hs
Behaviors / traits      → .hsplus
Scenes / compositions   → .holo
Tooling / infra         → .ts (last resort)
```

## Cross-Package Impact Map

When you change a file in one package, these downstream packages likely break:

| Changed | Check |
|---------|-------|
| `core/src/traits/*` | `engine`, `r3f-renderer`, `studio`, `mcp-server` |
| `core/src/compiler/*` | `cli`, `mcp-server`, `studio` |
| `core/src/parser/*` | Everything that parses `.hs`/`.hsplus`/`.holo` |
| `engine/src/*` | `r3f-renderer`, `studio` |
| `framework/src/*` | `mcp-server`, `studio` |
| `mcp-server/src/*` | All agents using MCP tools |

## Key Refactoring Patterns

### Rename a Type (cross-package)

```
1. holo_query_codebase({ query: "callers", symbol: "OldTypeName" })
2. Note every file path returned
3. Edit: rename in definition file
4. Edit: update every importer (from step 1)
5. Edit: update every test that references it
6. pnpm test --filter @holoscript/core && pnpm test --filter @holoscript/engine
```

### Move a Function to a Different Module

```
1. holo_impact_analysis({ symbol: "functionName" })
2. Create export in new location
3. Re-export from old location (temporary, for one commit)
4. Update all importers to new path
5. Remove re-export from old location
6. pnpm test
```

### Add a New Trait

```
1. Create trait handler in core/src/traits/
2. Register in VRTraitSystem.ts
3. Add trait name to constants/<category>.ts
4. Export from traits/index.ts
5. pnpm test --filter @holoscript/core
```

## MCP Tools for Refactoring

| Tool | When |
|------|------|
| `holo_impact_analysis` | Before ANY symbol rename/move/delete |
| `holo_query_codebase` | Find callers, callees, imports |
| `holo_generate_refactor_plan` | Graph-informed refactoring plan |
| `holo_scaffold_code` | Generate test/interface/module scaffolds |
| `holo_run_tests_targeted` | Run vitest on specific files |
| `holoscript_code_health` | Health score before/after refactor |

## Quick Trait Reference

```
interaction   @grabbable @throwable @clickable @hoverable @draggable @pointable
physics       @collidable @physics @rigid @kinematic @trigger @gravity
visual        @glowing @emissive @transparent @reflective @animated @billboard
networking    @networked @synced @persistent @owned @host_only
economics     @wallet @nft_asset @token_gated @marketplace
iot           @iot_sensor @digital_twin @mqtt_bridge
simulation    @thermal_simulation @structural_fem @hydraulic_pipe
```

## Repair edges in-flight

Refactoring drags you across many files — you WILL pass stale edges: a dead path,
a drifted stat, a `.gitignore` gap, a hook pointing at a deleted file. **Fix the
cheap, reversible ones in the same turn** (don't read past them); flag the
expensive/destructive ones via `/room` board. Verify first (`git log --since='48h'
-- <path>`) — a peer may have just fixed it. Never hardcode "current reality"
(tool/trait counts, versions) — reference the live query. Full norm:
`~/.ai-ecosystem/CLAUDE.md` → Autonomy → "Repair edges in-flight".

## Team Participation

HoloMesh team API is REST at `mcp.holoscript.net/api/holomesh` (auth: `HOLOMESH_API_KEY` from `.env`).

Join on workspace open:
```bash
node ~/.ai-ecosystem/hooks/team-connect.mjs --once --name=cursor --ide=cursor
```
Background mode: `--daemon` for heartbeat every 60s + board refresh every 5min.
See `AGENTS.md` for the full agent interface.