Cursor rule

1---
2description: Git workflow, permissions, and all git message standards
3alwaysApply: true
4version: 2.1.0
5---
6 
7# Git Collaboration and Communication Standards
8 
9I am a careful steward of your git repository. I make changes to files but leave version
10control decisions to you. I can commit to main when you ask, but I'll seek confirmation
11before pushing to main or merging branches since these affect the shared repository.
12 
13## Core Identity
14 
15I work in your repository with these fundamental constraints: I make code changes but
16don't commit them unless you explicitly ask. When given permission, I can commit to
17main. Pushing to main or merging branches into main requires your confirmation. I work
18on feature branches when doing autonomous tasks. I treat your git history as permanent
19and important.
20 
21## How I Handle Git Operations
22 
23By default, I make all the code changes you need but leave them uncommitted in your
24working directory. This lets you review everything with `git diff` before deciding what
25becomes part of your permanent history. When you're ready, you tell me "please commit"
26and I'll create the commit with an appropriate message.
27 
28### Selective Staging
29 
30When you ask me to commit "your changes" or "my changes", I am surgical and precise:
31 
32**I only stage files I modified** - I use `git add` to stage only the specific files I
33changed in the current session. I never stage unrelated files or your other
34work-in-progress.
35 
36**Partial staging when needed** - If a file contains both my changes and your other
37unstaged work, I use `git add -p` (patch mode) to stage only the specific hunks I
38modified. This ensures I never accidentally commit your uncommitted work.
39 
40**Transparency before committing** - Before creating any commit, I tell you exactly
41which files or hunks I'm staging so you can verify I'm not including anything
42unintended.
43 
44**Tracking my changes** - I keep track of which files I've modified during our session
45using tool results and my actions. When asked to commit "just your changes", I stage
46only those specific files.
47 
48When you explicitly ask me to work autonomously in a git worktree following
49`git-worktree-task.mdc` as an `autonomous-developer.md`, I operate differently. I create
50a feature branch, make commits following your project's conventions, push to that
51feature branch, and open a pull request for your review. Even in this autonomous mode,
52pushing to main or merging into main requires your explicit confirmation.
53 
54## Message Generation with Git Writer Agent
55 
56For generating commit messages, PR descriptions, and branch names, I invoke the
57`git-writer` agent. The agent is a specialized Haiku-based assistant that reads these
58standards and generates appropriate messages. This preserves main context while ensuring
59consistent, high-quality git communication.
60 
61## Respecting Validation and Quality Checks
62 
63Git hooks and CI checks are guardrails that protect code quality. When they fail,
64they're telling us something important. My response is always to fix the root cause,
65never to bypass the check. If tests fail, I fix the tests or the code. If linting fails,
66I fix the style issues. If formatting is wrong, I run the formatter. The `--no-verify`
67flag is reserved for emergency situations where you explicitly tell me to use it.
68Otherwise, I treat every failed check as a problem to solve, not an obstacle to
69circumvent.
70 
71## Permission Model
72 
73I understand the distinction between these git operations:
74 
75**Committing to main** - Creating a local commit on the main branch. This is allowed
76when you give explicit permission with "please commit". The commit stays local until
77pushed.
78 
79**Pushing to main** - Sending local commits to the remote main branch. This affects the
80shared repository that others pull from. I'll ask for confirmation before proceeding.
81 
82**Merging into main** - Integrating changes from another branch or pull request into
83main. This combines branch histories and affects the shared codebase. I'll ask for
84confirmation before proceeding.
85 
86**Using --no-verify** - The `--no-verify` flag bypasses git hooks and checks that
87protect code quality and repository integrity. I must never use `--no-verify` unless you
88explicitly request it for an emergency bug fix. When pre-commit or pre-push hooks fail,
89I fix the underlying issues (linting errors, test failures, formatting problems) rather
90than bypassing them. Hooks exist to maintain code quality - respecting them is
91non-negotiable.
92 
93When you say "please commit", I'll create commits (including to main if that's the
94current branch). Operations that affect the remote repository (pushing to main, merging
95into main) require your confirmation. Force pushing anywhere or deleting branches also
96require explicit confirmation.
97 
98## Commit Message Standards
99 
100We write commit messages to communicate with our future selves and teammates. A great
101commit message tells the story of why we made a change, making code archaeology easier
102and helping others understand our reasoning and thought process.
103 
104### Core Principles
105 
106- Reflect on the full change before writing the message
107- Focus on motivation and reasoning, not just what changed (the diff shows that)
108- Scale message length to change importance and size - simple changes get one line,
109  major architectural changes deserve 2-3 paragraphs
110- Use imperative mood ("Add feature" not "Added feature")
111- Summary line under 72 characters, no period at the end
112- Capitalize the first word after any emoji
113 
114### Structure
115 
116```
117[optional emoji] Summary line under 72 characters
118 
119[Optional body when context is needed]
120```
121 
122Body is optional. Include when explaining why adds value beyond the summary and diff.
123When included: explain motivation, problem being solved, impact, trade-offs, or
124alternatives considered. Wrap at 72 characters. For large/important changes, write 2-3
125paragraphs if needed.
126 
127### Emoji Usage
128 
129You have complete freedom to choose ANY emoji that adds value. Start with gitmoji as
130your reference - if there's a clear gitmoji match, use it. But feel free to get creative
131and use any emoji that genuinely enhances meaning or clarity.
132 
133Include an emoji when it:
134 
135- Makes commit history more scannable at a glance
136- Provides instant visual categorization of the change type
137- Creates useful visual anchors in git log
138- Adds personality or context that words alone miss
139 
140Skip the emoji entirely when it would feel forced or add no real value. Many excellent
141commit messages need no emoji at all.
142 
143Common emoji patterns:
144 
145- 🐛 Bug fixes
146- ✨ New features
147- ♻️ Refactoring
148- 📝 Documentation
149- ⚡ Performance improvements
150- 🔧 Configuration changes
151- 🏗️ Architectural changes
152 
153### No-Deploy Marker
154 
155For changes that should not trigger deployment (documentation, tests, CI config, etc.),
156include `[no-deploy]` in the commit message. This signals both humans and CI/CD
157automation that deployment is unnecessary.
158 
159Place the marker either:
160 
161- At the end of the summary line if it fits:
162  `Update README with installation steps [no-deploy]`
163- On its own line after the summary for longer messages
164 
165### Commit Examples
166 
167Simple change (no body needed):
168 
169```
170🐛 Handle null values in user preferences
171```
172 
173Simple documentation change (no deploy):
174 
175```
176Fix typo in API documentation [no-deploy]
177```
178 
179Medium change with context:
180 
181```
182♻️ Extract validation logic into shared module
183 
184Validation was duplicated across registration, profile updates, and
185admin tools with slight variations causing inconsistent behavior.
186Consolidating into a shared module ensures consistency and makes
187future validation changes easier.
188```
189 
190Large architectural change (2-3 paragraphs for major changes):
191 
192```
193🏗️ Migrate from REST to event-driven architecture
194 
195Replace synchronous REST endpoints with event-driven processing to
196support real-time features and improve system resilience...
197 
198Previous architecture required services to block waiting for responses,
199creating cascading failures and poor user experience during high load.
200Events allow asynchronous processing and natural retry mechanisms...
201 
202This change affects order processing, notification system, and analytics
203pipeline. Services can now scale independently and handle partial
204failures gracefully. Trade-off: eventual consistency instead of
205immediate, but business requirements allow 2-3 second delay...
206```
207 
208## Pull Request Standards
209 
210PR descriptions should tell the complete story of a change, making review efficient and
211creating permanent documentation of why features exist.
212 
213### PR Structure
214 
215```
216## Summary
217[2-4 bullet points explaining what changed and why]
218 
219## Changes
220[Key technical changes, architectural decisions, or patterns introduced]
221 
222## Testing
223[How to verify this works - steps, commands, or scenarios]
224 
225## Notes
226[Optional: deployment considerations, breaking changes, follow-up work]
227```
228 
229### PR Title Format
230 
231Use the same format as commit messages: `[emoji] Clear description of the change`
232 
233Examples:
234 
235- ✨ Add OAuth2 authentication flow
236- 🐛 Fix race condition in cache invalidation
237- ♻️ Refactor payment processing for better testability
238 
239### PR Body Guidelines
240 
241**Summary**: Start with why this PR exists. What problem does it solve? What motivated
242the change?
243 
244**Changes**: Highlight the key technical decisions. Don't list every file - focus on the
245patterns, approaches, or architectural choices reviewers should understand.
246 
247**Testing**: Give reviewers a clear path to verify the changes work. Include commands to
248run, scenarios to test, or edge cases to check.
249 
250**Notes**: Call out anything that affects deployment, breaks compatibility, or needs
251follow-up work.
252 
253### PR Examples
254 
255Small bug fix:
256 
257```
258🐛 Fix user profile image upload on mobile
259 
260## Summary
261- Mobile uploads were failing silently due to CORS configuration
262- Added proper CORS headers for the upload endpoint
263 
264## Testing
265- Upload profile image from mobile browser
266- Verify image appears in profile immediately
267```
268 
269Feature with context:
270 
271```
272✨ Add real-time notification system
273 
274## Summary
275- Users need immediate feedback when important events happen
276- Implemented WebSocket-based notifications
277- Supports browser notifications and in-app toasts
278 
279## Changes
280- WebSocket server using Socket.io
281- Client notification manager with queue and deduplication
282- Database schema for notification preferences and history
283 
284## Testing
285- Run `npm run dev` and open two browser tabs
286- Trigger event in one tab (e.g., new message)
287- Verify notification appears in second tab within 1 second
288- Check browser notification permission flow
289 
290## Notes
291- Requires Redis for pub/sub between server instances
292- Add NOTIFICATION_WS_URL to environment variables
293- Will add email digest notifications in follow-up PR
294```
295 
296## Branch Naming Conventions
297 
298Branch names should be verb-first and descriptive. Type prefixes like `feat/` `fix/`
299`docs/` add no value - the branch name itself tells you what it does.
300 
301### Format
302 
303```
304verb-description
305```
306 
307Start with a verb that describes the action: add, fix, update, refactor, remove.
308 
309### Examples
310 
311- `add-oauth-authentication`
312- `fix-cache-race-condition`
313- `update-deployment-docs`
314- `refactor-payment-processing`
315- `remove-deprecated-api`
316 
317### Workflow Prefixes
318 
319The only useful prefixes signal different workflows, not change types:
320 
321**`hotfix/`** - Emergency production fix. Triggers expedited review (fewer nitpicks,
322focus on correctness). Use when something is broken in production and needs immediate
323attention.
324 
325Example: `hotfix/fix-payment-timeout`
326 
327### Guidelines
328 
329- Use lowercase with hyphens
330- Keep it short but meaningful (2-5 words)
331- Be specific enough to understand without context
332- The verb naturally categorizes the work
333 
334## Operating Philosophy
335 
336Your git history tells the story of your project's evolution. Every commit is a
337permanent record. The main branch represents your production-ready code. These aren't
338just technical details - they're why I default to caution and require explicit
339permission. You maintain control over what becomes permanent in your repository's
340history.
341 
342When uncertain, I make the changes but don't commit them. You decide when your git
343history updates.
344 
345The goal is clarity and kindness to our future selves and teammates. Every commit
346message is a small act of documentation that either helps or hinders. We choose to help.
347