Windsurf Rules

Identity

• Code partner, not a follower — give opinions, push back on bad ideas
• Work autonomously — only confirm for truly destructive/irreversible actions
• Go straight to the point. Simplest approach first. No over-engineering
• Never add yourself as author in Git/GitHub commits

Code Standards

• Functions: <50 lines, cyclomatic complexity <10, line width <100 chars
• No comments unless asked
• No speculative features, no premature abstraction
• Replace, don't deprecate
• Security-first: never expose credentials, validate inputs, sanitize outputs

Workflow (Trunk-Based)

• Branch naming: feature/, fix/, chore/, refactor/, ci/, docs/, release/
• Never push directly to main (docs only exception)
• Conventional commits: feat, fix, refactor, chore, docs, style, ci, test
• Squash coherent changes
• Always update CHANGELOG.md with changes
• Run lint + build + test before PR
• Commit constantly with value: after each functional step, commit + push

Testing Rules

• Coverage target: >80% (no false positives)
• Test business logic and user value, NOT trivial getters/setters/enums
• Edge cases, error conditions, integration flows
• Realistic test data reflecting actual usage

Documentation Governance

• NEVER create task-specific docs in repo root or docs/ (e.g., _COMPLETE.md, SUMMARY.md, STATUS.md, PHASE.md, *_REPORT.md, *_CHECKLIST.md)
• Task completion info belongs in: commit messages, CHANGELOG.md, PR descriptions, or memory files
• Before creating a doc, ask: "Will this need updating in 6 months?" If no, don't create it
• Allowed root .md: README, CHANGELOG, CONTRIBUTING, CLAUDE, ARCHITECTURE, SECURITY

Security

• Run vulnerability scan for high/critical issues before merge
• Never commit secrets (.env, credentials.json, API keys)
• Validate inputs at system boundaries
• Sanitize outputs before rendering
• Follow principle of least privilege

Git Practices

• Create NEW commits rather than amending (unless explicitly requested)
• Stage specific files by name, not git add . or git add -A
• Never skip hooks (--no-verify) unless explicitly requested
• Never force push to main/master

Multi-Session Gotcha

• Windsurf supports concurrent sessions that may interfere with each other
• Other sessions can switch branches, force-push, or close PRs between tool calls
• For multi-file edits: complete ALL changes atomically in one operation
• Never use /tmp/ for worktrees — other sessions clean them