diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 7e8dd6c..5799b9d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,7 +1,5 @@
 name: ci
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
 jobs:
@@ -10,6 +8,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bunx biome ci .
-      - run: bun test
+      - uses: extractions/setup-just@v2
+      - run: just install
+      - run: just check
diff --git a/AGENTS.md b/AGENTS.md
index 80b4b9a..f3681e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,7 +38,7 @@ test/
 KeyEvent → translateKey() → handleInsertKey/handleNormalKey/handleVisualKey() → HandlerResult { consume, actions[] }
                                     ↓                                                         ↓
                              mutates VimState                                       applyActions() in index.ts
-                          (count, pendingOp, mode)                                  dispatches commands via setTimeout
+                          (count, pendingOp, pendingChar, mode)                                  dispatches commands via setTimeout
 ```
 
 Handlers in `vim.ts` are pure — they take state + key + event, mutate state, return actions. They never touch `api`. The only file that calls `api.keymap.dispatchCommand` is `index.ts`.
@@ -90,10 +90,17 @@ To add a new motion that works with operators:
 ```bash
 just dev       # Launch OpenCode with the plugin (uses OPENCODE_TUI_CONFIG=dev-tui.json)
 bun test       # Run characterization tests
+just check     # Lint + tests (used in GitHub Actions)
 ```
 
 The `dev-tui.json` config is picked up only by `just dev`. Running `opencode` normally in this directory does not load the plugin.
 
+## Git Workflow
+
+All changes go through pull requests. Direct pushes to `main` are blocked. CI (`just check`) must pass before merge. PRs are squash-merged — the PR title becomes the commit on `main`.
+
+Branch naming: `type/description` — e.g. `feat/replace-char`, `fix/escape-handling`. Types match commit prefixes (`feat`, `fix`, `refactor`, `chore`, `test`, `docs`).
+
 ## Code Conventions
 
 **Pure functions over side effects.** Handlers return data (actions), callers apply effects. This makes the core logic testable without mocking.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d58ba88..083ccd8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,7 +3,7 @@
 ## Development setup
 
 ```bash
-npm install      # install deps
+just install     # install deps
 just dev         # launch OpenCode with the plugin loaded
 just check       # run lint + tests
 ```
@@ -19,6 +19,28 @@ Running `opencode` directly in this directory won't load the plugin. You need `j
 
 See `AGENTS.md` for operator+motion combos and other patterns.
 
+## Pull requests
+
+All changes go through pull requests — direct pushes to `main` are blocked.
+
+### Branch naming
+
+Use `type/description` with lowercase, hyphen-separated words:
+
+- `feat/replace-char`
+- `fix/escape-handling`
+- `chore/update-deps`
+
+Types match commit prefixes: `feat`, `fix`, `refactor`, `chore`, `test`, `docs`.
+
+### Workflow
+
+1. Create a branch: `git checkout -b feat/your-feature`
+2. Make changes, run `just check` locally.
+3. Push and open a PR against `main`.
+4. CI runs `just check` (lint + tests). It must pass before merge.
+5. PRs are squash-merged. The PR title becomes the commit message on `main`.
+
 ## Commit messages
 
 Conventional-ish prefixes: `feat:`, `fix:`, `refactor:`, `chore:`, `test:`, `docs:`.
@@ -47,9 +69,9 @@ Releases are manual.
 6. Bump `VERSION` in `src/version.ts` to match.
 7. Update the version tag in `README.md`'s install snippet.
 8. Run `just check`.
-9. Commit: `Release vX.Y.Z: <one-line summary>`.
-10. Tag: `git tag vX.Y.Z`
-11. Push: `git push origin main vX.Y.Z`
+9. Open a PR with the release changes. Title: `Release vX.Y.Z: <one-line summary>`.
+10. After CI passes, squash-merge the PR.
+11. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`
 12. Create a GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z" --latest --notes "<changelog section for this version>"`
 
 ## Distribution
diff --git a/justfile b/justfile
index 6581ce5..53e0c59 100644
--- a/justfile
+++ b/justfile
@@ -2,7 +2,7 @@
 
 # Install dependencies
 install:
-    npm install
+    bun install
 
 # Run tests
 test:
@@ -10,7 +10,7 @@ test:
 
 # Check formatting and lint
 lint:
-    bunx biome check .
+    bunx biome ci .
 
 # Auto-fix formatting and lint
 lint-fix: