Dual-workflow Git operating guide#

This repo is used from two environments:

• local Cursor app
• Cursor web agents

The goal is zero branch drift and safe handoff between both.

Core model#

• main is the stable integration branch.
• day-to-day work happens on short-lived topic branches.
• every environment pulls from/pushes to the same remote branch for that topic.

Branch naming#

Use names that identify intent and owner quickly:

• feature/<topic>
• fix/<topic>
• chore/<topic>
• cursor/<topic> (for agent-heavy runs)

Examples:

• feature/wider-home-converter
• fix/pdf-table-overflow
• cursor/pagination-hardening

Session start (both platforms)#

Run:

npm run git:sync

What this does:

1. fetches latest remote refs
2. ensures the current branch tracks its upstream (or creates it on remote)
3. rebases local work onto upstream with --autostash

Then inspect:

npm run git:status

Session end / handoff#

Before switching platforms:

1. commit all intended changes
2. push branch
3. confirm upstream is in sync

git add .
git commit -m "your message"
git push
npm run git:status

Keep flexibility without chaos#

• avoid direct work on main for ongoing tasks
• avoid force-push on shared branches
• keep commits focused and small so handoffs are easy
• when opening a new effort, branch from latest origin/main

Fast recovery recipe#

If the local branch looks wrong:

git fetch --all --prune
git status -sb
git log --oneline --decorate -n 10

If needed, explicitly compare with remote:

git rev-list --left-right --count @{u}...HEAD

This tells you exactly how far ahead/behind you are before taking action.