Have claude replace copilot-instructions.md with an improved AGENTS.md

Author: J-Fields

.github/copilot-instructions.md

@@ -0,0 +1,58 @@
+# VSCodeVim — Agent Instructions
+
+VSCodeVim is a VS Code extension (TypeScript) that emulates Vim modal editing. It targets both desktop and web VS Code environments.
+
+## Build & Test
+
+```bash
+yarn build-dev       # Fast dev build
+yarn build           # Production build
+yarn watch           # Rebuild on file changes
+
+yarn build-test && yarn test   # Run tests locally (close all VS Code instances first)
+npx gulp test                  # Run tests in Docker (preferred)
+npx gulp test --grep <REGEX>   # Run filtered tests in Docker
+
+yarn lint            # Check code style
+yarn lint:fix        # Auto-fix linting issues
+yarn prettier        # Format code
+```
+
+## Architecture
+
+**Event flow:** Key press → `extension.ts` → `ModeHandler.handleKeyEvent()` → action matching → `runAction()` → `updateView()`
+
+Key directories:
+
+- `src/actions/` — All command/motion/operator implementations; large consolidated files (e.g. `insert.ts`, `search.ts`) are intentional
+- `src/actions/plugins/` — Emulated Vim plugins (easymotion, surround, sneak, commentary, etc.)
+- `src/mode/modeHandler.ts` — Central state machine; one instance per open editor
+- `src/state/vimState.ts` — Per-editor state (cursor, registers, mode, history)
+- `src/state/recordedState.ts` — Transient state for the current operation; resets after each action
+- `src/cmd_line/` — Ex command (`:`) parsing and execution
+- `src/configuration/` — Settings loading and validation
+- `src/neovim/` — Optional Neovim process integration for Ex commands
+- `src/platform/node/` and `src/platform/browser/` — Platform-specific abstractions
+- `test/` — Mirrors `src/` structure; uses Mocha + Sinon + `@vscode/test-electron`
+
+**Three action base classes:**
+
+- `BaseMovement` — Updates cursor only; returns `Position` or `IMovement` (start+end for text objects)
+- `BaseCommand` — Modifies `VimState` beyond cursor movement
+- `BaseOperator` — Combines with a movement (e.g. `d{motion}`, `c{motion}`)
+
+## Conventions
+
+- TypeScript `strict: true` + `noImplicitOverride: true` — always use the `override` keyword when overriding parent methods
+- `IMovement` interface (not just `Position`) is required when a motion needs to return a range (e.g. text objects like `aw`, `i{`)
+- Platform abstraction via `/src/platform/` — never call Node.js APIs directly; use the abstraction layer so web VS Code works
+- Settings precedence: Ex-commands → user/workspace VS Code settings → defaults
+- `.vimrc` support is remaps-only — no full Vimscript execution
+- Actions are registered by decorating classes; see existing action files for the pattern
+
+## References
+
+- [CONTRIBUTING.md](.github/CONTRIBUTING.md) — Setup, architecture deep-dive, release process
+- [README.md](README.md) — All supported settings, emulated plugins, keybindings
+- `gulpfile.js` — Build/test/release automation tasks
+- `package.json` — Extension manifest, all configuration schema definitions (40+ settings)