docs: add validation, planning, and git conventions

.cursor/rules/git-conventions.mdc

@@ -0,0 +1,62 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+# Git Conventions
+
+_Follow these conventions for commits, issues, and PRs._
+
+---
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>: <description> #<issue>
+```
+
+### Types
+
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation only
+- `style` - Formatting, no code change
+- `refactor` - Code change that neither fixes a bug nor adds a feature
+- `test` - Adding or fixing tests
+- `chore` - Maintenance tasks
+- `perf` - Performance improvement
+- `build` - Build system or dependencies
+- `ci` - CI configuration
+
+### Rules
+
+1. Use imperative mood: "add feature" not "added feature"
+2. Keep first line under 72 characters
+3. Add issue number after description if commit relates to an issue: `feat: add parser #5`
+4. Omit issue number if commit is unrelated to any issue
+5. No period at the end
+
+### Examples
+
+```
+feat: implement dice notation lexer #3
+fix: handle edge case in parser
+chore: update dependencies
+docs: add API documentation #12
+```
+
+## Issue Titles
+
+Follow same format without issue reference:
+
+```
+feat: <description>
+fix: <description>
+```
+
+## PR Titles
+
+Follow commit message format. Use the primary change type.

CLAUDE.md

@@ -36,6 +36,7 @@ Detailed rules in `.cursor/rules/`:
 - `testing.mdc` - Test patterns (Bun test runner, fast-check)
 - `rng.mdc` - RNG interface and MockRNG usage
 - `comments.mdc` - Documentation style
+- `git-conventions.mdc` - Commit, issue, and PR naming
 
 ## Testing Standards
 
@@ -44,6 +45,27 @@ Detailed rules in `.cursor/rules/`:
 - Co-locate tests with source: `foo.ts` → `foo.test.ts`
 - Target >90% statement coverage, 100% function coverage
 
+## Validation
+
+During iteration:
+
+```bash
+bun check:fix    # Typecheck + lint + format (with auto-fix)
+bun test         # Run tests
+```
+
+Before commit (mirrors CI):
+
+```bash
+bun validate     # typecheck + lint + format:check + build + test
+```
+
+Task is complete when `bun validate` passes with no errors.
+
+## Planning
+
+For complex tasks, start with plan mode. Ask clarifying questions before implementation.
+
 ## Skills
 
 - `npm-release` - Release to npm

package.json

@@ -54,6 +54,7 @@
     "build:types": "tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
     "test": "bun test",
     "test:ci": "bun test --bail",
+    "validate": "bun run check && bun run build && bun test:ci",
     "coverage": "bun test --coverage",
     "release:dry": "bun run check && bun run build && bun test",
     "prepublishOnly": "bun run release:dry"