From ba32338645ba46131bf877a51d7f8c1274b6e787 Mon Sep 17 00:00:00 2001 From: Ross Date: Wed, 8 Apr 2026 19:09:17 +0300 Subject: [PATCH 1/2] Added Git Copilot rules --- .github/commands/start-dev.md | 17 +++++++++++++++++ .github/commands/test-watch.md | 14 ++++++++++++++ .github/commands/verify-ci.md | 18 ++++++++++++++++++ .github/rules/conventions.md | 8 ++++++++ .github/rules/data-restore.md | 7 +++++++ .github/rules/do-not-touch.md | 9 +++++++++ .github/rules/excalidraw-app.md | 7 +++++++ .github/rules/i18n-locales.md | 7 +++++++ .github/rules/packages-element-math.md | 7 +++++++ .github/rules/project-architecture.md | 7 +++++++ .github/rules/security.md | 7 +++++++ .github/rules/testing.md | 7 +++++++ dev-docs/ab-validation-rules.md | 11 +++++++++++ onboarding-docs/AGENTS.md | 12 ++++++++++++ onboarding-docs/CLOUDE.MD | 12 ++++++++++++ 15 files changed, 150 insertions(+) create mode 100644 .github/commands/start-dev.md create mode 100644 .github/commands/test-watch.md create mode 100644 .github/commands/verify-ci.md create mode 100644 .github/rules/conventions.md create mode 100644 .github/rules/data-restore.md create mode 100644 .github/rules/do-not-touch.md create mode 100644 .github/rules/excalidraw-app.md create mode 100644 .github/rules/i18n-locales.md create mode 100644 .github/rules/packages-element-math.md create mode 100644 .github/rules/project-architecture.md create mode 100644 .github/rules/security.md create mode 100644 .github/rules/testing.md create mode 100644 dev-docs/ab-validation-rules.md create mode 100644 onboarding-docs/AGENTS.md create mode 100644 onboarding-docs/CLOUDE.MD diff --git a/.github/commands/start-dev.md b/.github/commands/start-dev.md new file mode 100644 index 0000000..3236d4d --- /dev/null +++ b/.github/commands/start-dev.md @@ -0,0 +1,17 @@ +# start-dev + +Start local development in this repository. + +```zsh +yarn install +yarn dev +``` + +For docs only: + +```zsh +cd dev-docs +yarn install +yarn start +``` + diff --git a/.github/commands/test-watch.md b/.github/commands/test-watch.md new file mode 100644 index 0000000..af1b757 --- /dev/null +++ b/.github/commands/test-watch.md @@ -0,0 +1,14 @@ +# test-watch + +Run tests in watch mode. + +```zsh +yarn test +``` + +Run app tests explicitly: + +```zsh +yarn test:app +``` + diff --git a/.github/commands/verify-ci.md b/.github/commands/verify-ci.md new file mode 100644 index 0000000..eca2e91 --- /dev/null +++ b/.github/commands/verify-ci.md @@ -0,0 +1,18 @@ +# verify-ci + +Run the local checks that should match CI expectations. + +```zsh +yarn lint +yarn typecheck +yarn test +``` + +If you touch docs: + +```zsh +cd dev-docs +yarn lint +yarn build +``` + diff --git a/.github/rules/conventions.md b/.github/rules/conventions.md new file mode 100644 index 0000000..2ae8f78 --- /dev/null +++ b/.github/rules/conventions.md @@ -0,0 +1,8 @@ +# conventions + +- Keep changes small and focused. +- Follow existing naming and folder conventions. +- Prefer TypeScript and immutable values (`const`, `readonly`). +- Use optional chaining and nullish coalescing when applicable. +- Avoid broad refactors unless requested. + diff --git a/.github/rules/data-restore.md b/.github/rules/data-restore.md new file mode 100644 index 0000000..995f292 --- /dev/null +++ b/.github/rules/data-restore.md @@ -0,0 +1,7 @@ +# data-restore + +- Do not modify persisted data formats without migration strategy. +- Keep backward compatibility for serialized scene/app data. +- Validate restore/load behavior when touching import/export paths. +- Add regression tests when changing restoration logic. + diff --git a/.github/rules/do-not-touch.md b/.github/rules/do-not-touch.md new file mode 100644 index 0000000..bc01f27 --- /dev/null +++ b/.github/rules/do-not-touch.md @@ -0,0 +1,9 @@ +# do-not-touch + +Sensitive areas require explicit approval before edits: + +- Build/release scripts under `scripts/`. +- Firebase rules/config under `firebase-project/`. +- CI workflows under `.github/workflows/`. +- Any security-sensitive config or key handling. + diff --git a/.github/rules/excalidraw-app.md b/.github/rules/excalidraw-app.md new file mode 100644 index 0000000..2747551 --- /dev/null +++ b/.github/rules/excalidraw-app.md @@ -0,0 +1,7 @@ +# excalidraw-app + +- Keep UI changes scoped to `excalidraw-app/`. +- Prefer functional React components and hooks. +- Follow existing state patterns (Jotai/app state conventions). +- Add/adjust tests for behavior changes in app flows. + diff --git a/.github/rules/i18n-locales.md b/.github/rules/i18n-locales.md new file mode 100644 index 0000000..000381e --- /dev/null +++ b/.github/rules/i18n-locales.md @@ -0,0 +1,7 @@ +# i18n-locales + +- Never hardcode user-facing strings when a locale key exists. +- Update relevant locale resources when adding new UI text. +- Keep keys stable; avoid unnecessary renames. +- Verify fallback behavior for missing translations. + diff --git a/.github/rules/packages-element-math.md b/.github/rules/packages-element-math.md new file mode 100644 index 0000000..c4fb686 --- /dev/null +++ b/.github/rules/packages-element-math.md @@ -0,0 +1,7 @@ +# packages-element-math + +- Keep `packages/element` and `packages/math` changes minimal and benchmark-aware. +- Prefer low-allocation, high-throughput paths for geometry/math code. +- Use shared types from `packages/math/src/types.ts` (use `Point` type where applicable). +- Add tests for numeric edge cases and precision-sensitive logic. + diff --git a/.github/rules/project-architecture.md b/.github/rules/project-architecture.md new file mode 100644 index 0000000..7415f1b --- /dev/null +++ b/.github/rules/project-architecture.md @@ -0,0 +1,7 @@ +# project-architecture + +- Preserve package boundaries under `packages/`. +- Avoid introducing circular dependencies. +- Keep public APIs stable; document breaking changes. +- Place features in the most local module instead of cross-cutting edits. + diff --git a/.github/rules/security.md b/.github/rules/security.md new file mode 100644 index 0000000..02b37aa --- /dev/null +++ b/.github/rules/security.md @@ -0,0 +1,7 @@ +# security + +- Never commit secrets, tokens, or credentials. +- Validate and sanitize untrusted inputs. +- Prefer least-privilege configuration changes. +- Flag dependency security concerns and propose safe upgrades. + diff --git a/.github/rules/testing.md b/.github/rules/testing.md new file mode 100644 index 0000000..9e1396a --- /dev/null +++ b/.github/rules/testing.md @@ -0,0 +1,7 @@ +# testing + +- Add or update tests for every behavior change. +- Prioritize regression tests for bug fixes. +- Keep tests deterministic and isolated. +- Use `yarn test:app` for app-level verification when relevant. + diff --git a/dev-docs/ab-validation-rules.md b/dev-docs/ab-validation-rules.md new file mode 100644 index 0000000..e796fe1 --- /dev/null +++ b/dev-docs/ab-validation-rules.md @@ -0,0 +1,11 @@ +# AB validation rules + +This document defines baseline validation expectations for AB-style checks in docs and implementation notes. + +## Core rules + +- Keep validation rules explicit and testable. +- Prefer deterministic checks over heuristic checks. +- Include clear failure messages with remediation hints. +- Track rule ownership when introducing new checks. + diff --git a/onboarding-docs/AGENTS.md b/onboarding-docs/AGENTS.md new file mode 100644 index 0000000..52c6dc3 --- /dev/null +++ b/onboarding-docs/AGENTS.md @@ -0,0 +1,12 @@ +# AGENTS + +## Purpose + +This file documents which AI agents/tools are used in this repository and where. + +## Current environment + +- Primary assistant: GitHub Copilot in JetBrains. +- Project-wide defaults: `.github/copilot-instructions.md`. +- Additional scoped docs: `.github/commands/`, `.github/rules/`, `dev-docs/`. + diff --git a/onboarding-docs/CLOUDE.MD b/onboarding-docs/CLOUDE.MD new file mode 100644 index 0000000..4d2226b --- /dev/null +++ b/onboarding-docs/CLOUDE.MD @@ -0,0 +1,12 @@ +# CLOUDE + +## Note + +This file mirrors the onboarding role of `CLAUDE.md` from other setups. +For this repository, guidance is stored in: + +- `.github/copilot-instructions.md` +- `.github/commands/` +- `.github/rules/` +- `onboarding-docs/AGENTS.md` + From b362b59ca6d6bf79b0b8ae3de0073f5d0a0c9ff4 Mon Sep 17 00:00:00 2001 From: Ross Date: Wed, 8 Apr 2026 19:23:38 +0300 Subject: [PATCH 2/2] added form for bundle --- .github/commands/start-dev.md | 9 ++-- .github/commands/test-watch.md | 11 +++-- .github/commands/verify-ci.md | 15 +++--- .github/rules/conventions.md | 17 +++++-- .github/rules/data-restore.md | 15 ++++-- .github/rules/do-not-touch.md | 17 +++++-- .github/rules/excalidraw-app.md | 14 ++++-- .github/rules/i18n-locales.md | 14 ++++-- .github/rules/packages-element-math.md | 16 +++++-- .github/rules/project-architecture.md | 13 ++++-- .github/rules/security.md | 13 ++++-- .github/rules/testing.md | 16 +++++-- dev-docs/ab-validation-rules.md | 38 ++++++++++++--- excalidraw-app/package.json | 1 + onboarding-docs/AGENTS.md | 64 +++++++++++++++++++++++--- onboarding-docs/CLOUDE.MD | 11 +++-- 16 files changed, 216 insertions(+), 68 deletions(-) diff --git a/.github/commands/start-dev.md b/.github/commands/start-dev.md index 3236d4d..18bb987 100644 --- a/.github/commands/start-dev.md +++ b/.github/commands/start-dev.md @@ -1,17 +1,18 @@ # start-dev -Start local development in this repository. +Custom command for local development startup in GitHub Copilot environment. + +## Steps ```zsh yarn install -yarn dev +yarn start ``` -For docs only: +Docs site only: ```zsh cd dev-docs yarn install yarn start ``` - diff --git a/.github/commands/test-watch.md b/.github/commands/test-watch.md index af1b757..2c2c99a 100644 --- a/.github/commands/test-watch.md +++ b/.github/commands/test-watch.md @@ -1,14 +1,15 @@ # test-watch -Run tests in watch mode. +Custom command to run app tests in watch mode. + +## Steps ```zsh -yarn test +yarn test:app ``` -Run app tests explicitly: +Single pass mode: ```zsh -yarn test:app +yarn test:app --watch=false ``` - diff --git a/.github/commands/verify-ci.md b/.github/commands/verify-ci.md index eca2e91..9d29d2f 100644 --- a/.github/commands/verify-ci.md +++ b/.github/commands/verify-ci.md @@ -1,18 +1,19 @@ # verify-ci -Run the local checks that should match CI expectations. +Custom command to run local checks closest to CI gates. + +## Steps ```zsh -yarn lint -yarn typecheck -yarn test +yarn test:typecheck +yarn test:code +yarn test:app --watch=false ``` -If you touch docs: +If docs were changed: ```zsh cd dev-docs -yarn lint +yarn install yarn build ``` - diff --git a/.github/rules/conventions.md b/.github/rules/conventions.md index 2ae8f78..47120da 100644 --- a/.github/rules/conventions.md +++ b/.github/rules/conventions.md @@ -1,8 +1,15 @@ # conventions -- Keep changes small and focused. -- Follow existing naming and folder conventions. -- Prefer TypeScript and immutable values (`const`, `readonly`). -- Use optional chaining and nullish coalescing when applicable. -- Avoid broad refactors unless requested. +- Keep changes small and scoped to the requested behavior. +- Follow existing folder and naming patterns before introducing new abstractions. +- Prefer TypeScript with immutable values (`const`, `readonly`). +- Use optional chaining (`?.`) and nullish coalescing (`??`) where it reduces branching. +## How to verify + +```zsh +yarn test:code +``` + +- Confirm no new lint violations. +- Confirm changed files follow existing naming conventions. diff --git a/.github/rules/data-restore.md b/.github/rules/data-restore.md index 995f292..8f9609c 100644 --- a/.github/rules/data-restore.md +++ b/.github/rules/data-restore.md @@ -1,7 +1,14 @@ # data-restore -- Do not modify persisted data formats without migration strategy. -- Keep backward compatibility for serialized scene/app data. -- Validate restore/load behavior when touching import/export paths. -- Add regression tests when changing restoration logic. +- Do not change persisted data shape without a migration plan. +- Keep backward compatibility for scene/app restore paths. +- Add regression coverage when import/export or restore logic changes. +## How to verify + +```zsh +yarn test:app --watch=false +``` + +- Open an older scene JSON and confirm it loads without runtime errors. +- Re-export and re-import the same scene; confirm element count and bindings stay stable. diff --git a/.github/rules/do-not-touch.md b/.github/rules/do-not-touch.md index bc01f27..f0a4c74 100644 --- a/.github/rules/do-not-touch.md +++ b/.github/rules/do-not-touch.md @@ -1,9 +1,16 @@ # do-not-touch -Sensitive areas require explicit approval before edits: +Sensitive paths require explicit approval before edits: -- Build/release scripts under `scripts/`. -- Firebase rules/config under `firebase-project/`. -- CI workflows under `.github/workflows/`. -- Any security-sensitive config or key handling. +- `.github/workflows/` +- `firebase-project/` +- release/build automation under `scripts/` +- secret management or environment configuration flows +## How to verify + +- Run a diff scoped to sensitive paths and confirm no accidental edits. + +```zsh +git --no-pager diff -- .github/workflows firebase-project scripts +``` diff --git a/.github/rules/excalidraw-app.md b/.github/rules/excalidraw-app.md index 2747551..ecb3c5f 100644 --- a/.github/rules/excalidraw-app.md +++ b/.github/rules/excalidraw-app.md @@ -1,7 +1,13 @@ # excalidraw-app -- Keep UI changes scoped to `excalidraw-app/`. -- Prefer functional React components and hooks. -- Follow existing state patterns (Jotai/app state conventions). -- Add/adjust tests for behavior changes in app flows. +- Keep UI/product behavior changes isolated inside `excalidraw-app/` when possible. +- Use functional components and hooks; do not break hook rules. +- Prefer existing state patterns already used in the app. +## How to verify + +```zsh +yarn test:app --watch=false +``` + +- Smoke-test the changed flow in local app start. diff --git a/.github/rules/i18n-locales.md b/.github/rules/i18n-locales.md index 000381e..b3d1652 100644 --- a/.github/rules/i18n-locales.md +++ b/.github/rules/i18n-locales.md @@ -1,7 +1,13 @@ # i18n-locales -- Never hardcode user-facing strings when a locale key exists. -- Update relevant locale resources when adding new UI text. -- Keep keys stable; avoid unnecessary renames. -- Verify fallback behavior for missing translations. +- Do not hardcode user-facing strings if localization keys are expected. +- Keep translation keys stable; avoid unnecessary renames. +- When adding UI text, update related locale entries. +## How to verify + +```zsh +yarn locales-coverage +``` + +- Check that newly added keys exist in required locale files. diff --git a/.github/rules/packages-element-math.md b/.github/rules/packages-element-math.md index c4fb686..69bb361 100644 --- a/.github/rules/packages-element-math.md +++ b/.github/rules/packages-element-math.md @@ -1,7 +1,15 @@ # packages-element-math -- Keep `packages/element` and `packages/math` changes minimal and benchmark-aware. -- Prefer low-allocation, high-throughput paths for geometry/math code. -- Use shared types from `packages/math/src/types.ts` (use `Point` type where applicable). -- Add tests for numeric edge cases and precision-sensitive logic. +- Keep `packages/element` and `packages/math` changes bounded and benchmark-aware. +- Prefer low-allocation implementations in geometry/math hotspots. +- Use shared types from `packages/math/src/types.ts` (`Point` for coordinates). +- Add tests for edge cases and precision-sensitive operations. +## How to verify + +```zsh +yarn --cwd ./packages/math test +yarn --cwd ./packages/element test +``` + +- Run targeted tests for changed geometry paths if available. diff --git a/.github/rules/project-architecture.md b/.github/rules/project-architecture.md index 7415f1b..5ba481f 100644 --- a/.github/rules/project-architecture.md +++ b/.github/rules/project-architecture.md @@ -1,7 +1,14 @@ # project-architecture - Preserve package boundaries under `packages/`. -- Avoid introducing circular dependencies. -- Keep public APIs stable; document breaking changes. -- Place features in the most local module instead of cross-cutting edits. +- Avoid circular dependencies between packages and app layers. +- Keep public APIs stable unless a breaking change is explicitly requested. +## How to verify + +```zsh +yarn test:typecheck +yarn test:code +``` + +- Confirm imports remain one-directional according to existing boundaries. diff --git a/.github/rules/security.md b/.github/rules/security.md index 02b37aa..a5475d0 100644 --- a/.github/rules/security.md +++ b/.github/rules/security.md @@ -1,7 +1,14 @@ # security - Never commit secrets, tokens, or credentials. -- Validate and sanitize untrusted inputs. -- Prefer least-privilege configuration changes. -- Flag dependency security concerns and propose safe upgrades. +- Treat all external input as untrusted and validate/sanitize it. +- Prefer least-privilege settings for config changes. +- Upgrade vulnerable dependencies with minimal blast radius. +## How to verify + +```zsh +git --no-pager grep -nE "(api[_-]?key|secret|token|password)" -- ':!yarn.lock' +``` + +- Ensure no new sensitive literals were introduced. diff --git a/.github/rules/testing.md b/.github/rules/testing.md index 9e1396a..1e53cbe 100644 --- a/.github/rules/testing.md +++ b/.github/rules/testing.md @@ -1,7 +1,15 @@ # testing -- Add or update tests for every behavior change. -- Prioritize regression tests for bug fixes. -- Keep tests deterministic and isolated. -- Use `yarn test:app` for app-level verification when relevant. +- Every behavior change must include updated or new tests. +- Bug fixes require at least one regression test when feasible. +- Keep tests deterministic and independent. +## How to verify + +```zsh +yarn test:app --watch=false +yarn test:typecheck +yarn test:code +``` + +- Confirm changed code paths are covered by at least one automated test. diff --git a/dev-docs/ab-validation-rules.md b/dev-docs/ab-validation-rules.md index e796fe1..e2b2979 100644 --- a/dev-docs/ab-validation-rules.md +++ b/dev-docs/ab-validation-rules.md @@ -1,11 +1,35 @@ -# AB validation rules +# A/B validation rules -This document defines baseline validation expectations for AB-style checks in docs and implementation notes. +## Goal -## Core rules +Validate whether the repository guidance format is usable for GitHub Copilot workflows (A) versus Cursor-oriented layout assumptions (B). -- Keep validation rules explicit and testable. -- Prefer deterministic checks over heuristic checks. -- Include clear failure messages with remediation hints. -- Track rule ownership when introducing new checks. +## Test scenario +- Scope: docs-only setup for agent rules and commands. +- Inputs: command docs, rule docs, onboarding docs. +- Success criteria: + - At least 6 rule files with `How to verify` section. + - At least 2 custom command docs. + - Onboarding docs clearly describe project context and conventions. + +## Variant A (GitHub Copilot structure) + +- Paths used: `.github/commands/`, `.github/rules/`, `onboarding-docs/`. +- Result: + - 9 rule files present, each with `How to verify`. + - 3 command docs present. + - `AGENTS.md` and `CLOUDE.MD` present. +- Status: PASS. + +## Variant B (Cursor-only path expectation) + +- Paths expected: `.cursor/commands/`, `.cursor/rules/`. +- Result: + - Not applied in this repository by design. + - Would duplicate the source of truth and diverge from Copilot instructions. +- Status: FAIL (intended). + +## Conclusion + +Use Variant A as the canonical setup for this repository because the active tooling is GitHub Copilot, not Cursor. diff --git a/excalidraw-app/package.json b/excalidraw-app/package.json index 0c8446b..80c2fe7 100644 --- a/excalidraw-app/package.json +++ b/excalidraw-app/package.json @@ -52,6 +52,7 @@ "build:preview": "yarn build && vite preview --port 5000" }, "devDependencies": { + "cross-env": "7.0.3", "vite-plugin-sitemap": "0.7.1" } } diff --git a/onboarding-docs/AGENTS.md b/onboarding-docs/AGENTS.md index 52c6dc3..69714b4 100644 --- a/onboarding-docs/AGENTS.md +++ b/onboarding-docs/AGENTS.md @@ -1,12 +1,64 @@ # AGENTS -## Purpose +## Project context -This file documents which AI agents/tools are used in this repository and where. +- Repository: Excalidraw monorepo. +- Main areas: + - `excalidraw-app/` - main web app. + - `packages/` - shared libraries (`common`, `math`, `element`, `excalidraw`, `utils`). + - `examples/` - integration and usage examples. + - `dev-docs/` - documentation site and internal docs. -## Current environment +## Active assistant environment -- Primary assistant: GitHub Copilot in JetBrains. -- Project-wide defaults: `.github/copilot-instructions.md`. -- Additional scoped docs: `.github/commands/`, `.github/rules/`, `dev-docs/`. +- Primary assistant: GitHub Copilot (JetBrains workspace). +- Canonical AI guidance file: `.github/copilot-instructions.md`. +- Command docs: `.github/commands/`. +- Rule docs: `.github/rules/`. +## Common commands + +```zsh +yarn start +yarn build +yarn test:app --watch=false +yarn test:typecheck +yarn test:code +``` + +Docs workflow: + +```zsh +cd dev-docs +yarn install +yarn start +``` + +## Architecture notes + +- Keep package boundaries explicit; avoid circular dependencies. +- Prefer local changes near feature ownership (avoid broad cross-cutting edits). +- Treat serialized/imported scene data compatibility as a stability contract. + +## Coding conventions + +- TypeScript-first for new code. +- Favor immutable data (`const`, `readonly`) and small focused components. +- Use optional chaining (`?.`) and nullish coalescing (`??`) where helpful. +- For math-related changes, use shared types from `packages/math/src/types.ts` and prefer `Point`. + +## Quality gates + +- Minimum local verification before PR: + +```zsh +yarn test:typecheck +yarn test:code +yarn test:app --watch=false +``` + +- Build gate: + +```zsh +yarn build +``` diff --git a/onboarding-docs/CLOUDE.MD b/onboarding-docs/CLOUDE.MD index 4d2226b..b2c7ffa 100644 --- a/onboarding-docs/CLOUDE.MD +++ b/onboarding-docs/CLOUDE.MD @@ -1,12 +1,17 @@ # CLOUDE -## Note +## Purpose -This file mirrors the onboarding role of `CLAUDE.md` from other setups. -For this repository, guidance is stored in: +Compatibility onboarding note for teams that previously used `CLAUDE.md`-style files. + +## Source of truth in this repository - `.github/copilot-instructions.md` - `.github/commands/` - `.github/rules/` +- `dev-docs/ab-validation-rules.md` - `onboarding-docs/AGENTS.md` +## Important + +Do not create parallel Cursor-only rule trees for this repo unless explicitly required. This repository is configured for GitHub Copilot-first workflows.