diff --git a/.llm/exports/.state/.gitkeep b/.cursor/hooks/.gitkeep similarity index 100% rename from .llm/exports/.state/.gitkeep rename to .cursor/hooks/.gitkeep diff --git a/.cursor/hooks/CURSOR-HOOKS.md b/.cursor/hooks/CURSOR-HOOKS.md new file mode 100644 index 00000000..e5306926 --- /dev/null +++ b/.cursor/hooks/CURSOR-HOOKS.md @@ -0,0 +1,7 @@ +# `.cursor/hooks/` + +Optional Cursor project hook scripts. Add `.cursor/hooks.json` at the repo root when you enable hooks. + +- Scripts in this directory are referenced from `hooks.json` (not committed until you need hooks). +- Prefer skills and rules for static guidance; hooks automate events (shell gates, session setup, and so on). +- See Cursor hooks documentation and **abcmemory** skill. diff --git a/.llm/exports/github-copilot/.gitkeep b/.cursor/prompts/.gitkeep similarity index 100% rename from .llm/exports/github-copilot/.gitkeep rename to .cursor/prompts/.gitkeep diff --git a/.cursor/prompts/CURSOR-PROMPTS.md b/.cursor/prompts/CURSOR-PROMPTS.md new file mode 100644 index 00000000..b19e9e3b --- /dev/null +++ b/.cursor/prompts/CURSOR-PROMPTS.md @@ -0,0 +1,8 @@ +# `.cursor/prompts/` + +Reusable agent-facing prompt snippets (abcmemory). One topic per kebab-case `.md` file. + +- Use for copy-paste or @-reference blocks that are not full skills or rules. +- Do not put human plan/history templates here — use `.llm/templates/` instead. +- When the user says **abcremember** with prompt-shaped guidance, prefer this directory. +- See **abcmemory** skill and [LLM-TEMPLATES.md](/.llm/templates/LLM-TEMPLATES.md). diff --git a/.cursor/rules/CURSOR-RULES.md b/.cursor/rules/CURSOR-RULES.md new file mode 100644 index 00000000..94922355 --- /dev/null +++ b/.cursor/rules/CURSOR-RULES.md @@ -0,0 +1,7 @@ +# `.cursor/rules/` + +Cursor rules (`.mdc` files): always-applied or glob-scoped agent constraints. + +- Use `alwaysApply: true` for repo-wide conventions (for example `architecture-tier-dependencies.mdc`); use `globs` when rules apply only to certain paths. +- Prefer skills for long workflow docs; keep rules focused. +- See **llm-cursor-source** and [DOCS-DEVELOPMENT-LLM.md](/docs/development/llm/DOCS-DEVELOPMENT-LLM.md). diff --git a/.cursor/rules/abcmemory-vocabulary.mdc b/.cursor/rules/abcmemory-vocabulary.mdc new file mode 100644 index 00000000..629fd844 --- /dev/null +++ b/.cursor/rules/abcmemory-vocabulary.mdc @@ -0,0 +1,29 @@ +--- +description: User vocabulary abcmemory and abcremember for Cursor guidance files +alwaysApply: true +--- + +# abcmemory / abcremember vocabulary + +## abcmemory + +**abcmemory** means the committed files Cursor uses for agent guidance in this repo — **only** under `.cursor/` and the repo root files Cursor reads: + +- `.cursor/skills/**` +- `.cursor/rules/**` +- `.cursor/prompts/**` +- `.cursor/hooks/**` and `.cursor/hooks.json` (when present) +- `.cursorrules` +- `.cursorignore` + +## Not abcmemory + +**`.llm/`** (plans, history, templates, context) is a **planning workspace**, not agent memory. Do not treat it as a second abcmemory tree. + +Also not abcmemory unless you explicitly ask: `docs/`, `.github/`, and ad-hoc paths. + +## abcremember + +When the user says **abcremember**, **create or update** the best-fit abcmemory file(s) under **`.cursor/`** (or `.cursorrules` / `.cursorignore`): prefer updating existing guidance when the instruction extends the same topic; create a new skill, rule, or prompt only when no suitable file exists. Then follow that guidance in future work. Do **not** write to `.llm/` unless they explicitly say to remember something there. + +For placement and workflow details, see `.cursor/skills/abcmemory/SKILL.md`. diff --git a/.cursor/rules/app-internal-import-aliases.mdc b/.cursor/rules/app-internal-import-aliases.mdc new file mode 100644 index 00000000..749f75c7 --- /dev/null +++ b/.cursor/rules/app-internal-import-aliases.mdc @@ -0,0 +1,38 @@ +--- +description: App-internal TypeScript path aliases must match the full apps// directory name +globs: + - "apps/api/**/*.ts" + - "apps/management-api/**/*.ts" + - "apps/api/tsconfig*.json" + - "apps/management-api/tsconfig*.json" + - "apps/api/vitest.config.ts" + - "apps/management-api/vitest.config.ts" +alwaysApply: false +--- + +# App internal import aliases + +Node apps under `apps/` use a **TypeScript path alias** for imports from their own `src/` tree. The alias prefix must match the **full app directory name** under `apps/` — not abbreviations. + +## Do + +| App directory | Alias prefix | Example | +| ----------------------- | --------------------- | ------------------------------------------------------------ | +| `apps/api/` | `@api/*` | `import { config } from '@api/config/index.js'` | +| `apps/management-api/` | `@management-api/*` | `import { config } from '@management-api/config/index.js'` | + +Configure in each app's `tsconfig.json` `paths` and mirror the prefix root in `vitest.config.ts` for tests. When the build uses alias rewriting, keep `tsc` + alias rewrite aligned with dist output. + +## Don't + +- Do not abbreviate directory names (`@mgmt-api`, `@m-api`, etc.). +- Do not use npm workspace names (`@metaboost/api/*`) for in-app imports — those are for cross-package deps only. + +## Distinction + +- **`@metaboost/*`** — published/workspace packages under `packages/` +- **`@/*`** — internal imports within one deployable app + +## Note + +When adding or extending `paths` in an app, update this table if a new Node app is introduced under `apps/`. diff --git a/.cursor/rules/app-local-ui-wrappers.mdc b/.cursor/rules/app-local-ui-wrappers.mdc new file mode 100644 index 00000000..09bd762a --- /dev/null +++ b/.cursor/rules/app-local-ui-wrappers.mdc @@ -0,0 +1,16 @@ +--- +description: Extract app-local thin wrappers when identical @metaboost/ui + i18n configuration repeats (2+ callsites in one app). +globs: + - "apps/web/src/**/*.tsx" + - "apps/management-web/src/**/*.tsx" +alwaysApply: false +--- + +# App-local configured UI wrappers + +When the **same** configured usage of `@metaboost/ui` (including **`next-intl`** strings for `aria-label`, titles, or messages) appears in **two or more** places **within** `apps/web` or **within** `apps/management-web`, extract a thin client component under that app’s `src/components/**` that wires translations and forwards props. + +- Keep wrappers **app-local** until **both** apps need the same wiring; then consider `packages/ui` plus app wrappers for copy (see workspace **i18n** rules). +- Do **not** use bare `export { X } from '@metaboost/ui'` as a substitute — wrappers must bind meaningful app conventions. + +See **`reusable-components`** skill for the full rubric. diff --git a/.cursor/rules/architecture-tier-dependencies.mdc b/.cursor/rules/architecture-tier-dependencies.mdc new file mode 100644 index 00000000..4bea29bd --- /dev/null +++ b/.cursor/rules/architecture-tier-dependencies.mdc @@ -0,0 +1,11 @@ +--- +description: Package tier dependency order — lower tiers cannot depend on higher +alwaysApply: true +--- + +# Architecture tier dependencies + +Lower tiers cannot depend on higher tiers in the monorepo package graph. + +Full tier table, directory layout, and app descriptions: +[.llm/context/architecture.md](/.llm/context/architecture.md) (contributor reference). diff --git a/.cursor/rules/build-order-doc-sync.mdc b/.cursor/rules/build-order-doc-sync.mdc new file mode 100644 index 00000000..2b3f7cbf --- /dev/null +++ b/.cursor/rules/build-order-doc-sync.mdc @@ -0,0 +1,24 @@ +--- +description: Keep build order dependency-safe and docs synced when build orchestration changes. +globs: + - package.json + - scripts/ci/run-workspaces.mjs + - .github/workflows/ci.yml +alwaysApply: false +--- + +# Build order and docs sync + +Use the **build-order** skill (`.cursor/skills/build-order/SKILL.md`) and +[AGENTS.md](/AGENTS.md) / [.llm/context/architecture.md](/.llm/context/architecture.md) for the +current Metaboost sequence. + +## Required + +- Preserve dependency-safe staged build execution (`npm run build:packages` before apps). +- Keep root `build` aligned with package/app build sequencing. +- Update contributor docs when build orchestration behavior changes. + +## Prohibited + +- Do not reintroduce all-workspace root build execution that can violate workspace dependency order. diff --git a/.cursor/rules/commands-from-metaboost-root.mdc b/.cursor/rules/commands-from-metaboost-root.mdc index 1031c827..d49bc28f 100644 --- a/.cursor/rules/commands-from-metaboost-root.mdc +++ b/.cursor/rules/commands-from-metaboost-root.mdc @@ -10,6 +10,7 @@ Always provide runnable terminal commands relative to the Metaboost repository r ## Do - Use root-invoked workspace commands (for example `npm run