.cursorrules

# Metaboost Repo Rules

## Stack

- Node.js 24+, TypeScript strict, npm workspaces

## Architecture

Lower tiers cannot depend on higher (see `.cursor/rules/architecture-tier-dependencies.mdc`; full table in `.llm/context/architecture.md`).

## Code Quality

- No `any` types
- **Shared UI:** Prefer `@metaboost/ui` for reusable primitives in web and management-web. When both apps overlap, implement once in `packages/ui` and **prefer the web app's existing visual baseline** when merging styles unless a11y/product docs say otherwise (see `.cursor/rules/prefer-shared-ui-web-management.mdc`, **`reusable-components`**, and **`ui-component-promotion`** when adopted).
- Follow `tsconfig.base.json`
- Use ESM formatting: **Tier A** uses `.js` specifiers on relative TS imports (NodeNext); **Tier B** (`apps/web/src`, `apps/management-web/src`) stays extensionless until Turbopack parity — [docs/development/tooling/DOCS-DEVELOPMENT-TOOLING-IMPORT-SPECIFIERS.md](docs/development/tooling/DOCS-DEVELOPMENT-TOOLING-IMPORT-SPECIFIERS.md). Prefer `"type": "module"` where applicable.
- Prefer `import type` for type-only imports instead of value imports
- **Strict equality**: Use `===` and `!==` only (no `==` or `!=`). For "not null or undefined" use `x !== null && x !== undefined` (or optional chaining / truthiness where appropriate).
- **Avoid type assertions (`as`)**: Prefer proper types, optional chaining, type guards, or narrowing so the type system enforces correctness. Use `as` only when there is no better way (e.g. necessary escape hatch); keep such use minimal and documented.
- **Named exports**: Prefer named `export` in TypeScript modules; avoid `export default` when a named export works. Framework-required defaults (e.g. Next.js `page.tsx`) are the exception. See `.cursor/skills/prefer-named-exports/SKILL.md`.
- **CSS `var()`:** Do not use fallback arguments in SCSS/CSS (`var(--token, …)`); see `.cursor/rules/css-custom-properties-no-var-fallbacks.mdc`.

## Commands / Terminal

- **Commands from repo root**: When giving terminal or npm commands, always give them **relative to the monorepo root**. Use `npm run <script> -w @metaboost/<workspace> -- [args]` instead of instructing users to `cd apps/api` (or similar) first. See `.cursor/rules/commands-from-metaboost-root.mdc`.
- **Copy button**: Always put runnable commands in a **fenced code block** (e.g. `bash ... `) so the IDE shows a copy button. Do not give only inline commands when the user may want to run them.

## Formatting Rules

### Quote Styles

- **JavaScript/TypeScript/JSON/CSS**: Single quotes (`singleQuote: true`)
- **YAML files**: Double quotes (override in `.prettierrc.json`)
- Run `npm run lint:fix` or `npm run prettier:write` to auto-fix

---

## LLM WORKFLOW

### Context Gathering

For substantial requests, ask first:

- "What's the goal?"
- "GitHub issue?"

### Issue Linking

Ask once at start: "Related GitHub issue?"

### Scope Management

Warn if drifting: "This seems outside scope. Continue?"

### Agent/plan work: operator-only git and publish

- **Git operations = `git` + `gh`.** Do not run write/publish commands (`git push`, `gh pr create`, `gh pr merge`, releases, etc.) unless the user explicitly asks for a specific command in that message.
- Implement locally; give the operator copy-pasteable `git` and `gh` commands in a fenced `bash` block. See **operator-only-git-operations** rule.

### Agent/plan work: do not run tests

- **Do not run** test or verification commands (e.g. `make e2e_test_web`, `npm run test`, `npm run lint`) during agent or plan implementation.
- **Only instruct the user** to run those commands after your work is done; provide the exact command(s) in a fenced `bash` block. See **response-ending-make-verify** skill.
- **E2E verification commands:** Always give commands that **skip API tests** by default (do not add `E2E_API_GATE_MODE=on`). Only add `E2E_API_GATE_MODE=on` when the change affected API or integration tests. The Makefile default is `E2E_API_GATE_MODE=off`.
- **Final COPY-PASTA prompt:** When you complete the last step in a plan set, assume the operator ran all COPY-PASTA prompts back-to-back without running tests. End the response with **all** cumulative verification commands for the whole set (deduped; see **response-ending-make-verify** and **plan-files-convention** skills).

### User vocabulary

User vocabulary **abcmemory** / **abcremember**: see `.cursor/rules/abcmemory-vocabulary.mdc` and `.cursor/skills/abcmemory/SKILL.md`.

---

## PLAN MANAGEMENT

**Plans must be under 300 lines.** Plans live in `.llm/plans/active/` (not `.cursor/plans/`).

If over 300: STOP, split into sub-plans, save in `.llm/plans/active/`, then work sequentially. For file layout, use **plan-files-convention** skill.