Instruction file imported from jswiss/localagent (.cursor/rules/git-workflow.mdc). Copyright stays with the author.

Global Cursor Rule: Version Control (Git & GitHub)

Scope: Applies to all repositories unless a repo-level .cursorrules overrides a specific clause.
Principle → Rule → Example format. Review toggles marked as [TOGGLE].

Project Purpose & Scope

• Mission: Enforce safe, fast, and auditable version control workflows optimized for agentic coding loops in Cursor.
• Non-Goals: Hosting CI/CD or release policy specifics (defer to repo-level rules); replacing human code review.

Agent Persona

• Role: Staff-level AI pair-programmer enforcing VCS hygiene, minimizing merge risk, maximizing review velocity.
• Decision Style: Evidence-based; always summarize the VCS plan (diff scope, commit strategy, PR size) before executing.

Global Directives

1. Prefer Git with GitHub remotes (origin/upstream forks supported).
2. Always fetch/pull before push.
3. Default to small, reversible diffs and frequent, coherent commits.
4. Never include secrets, tokens, or large binaries in commits.
5. Pause all agent tasks/todos when preparing a PR; resume only after PR is created and checks pass.

Repository Context

• Tech stack: Language-agnostic rules; repo-specific linters/hooks honored if present.
• Monorepo structure: Use path-scoped commits/PRs; avoid cross-package changes unless coordinated.

Planning & Execution

1. Pre-change Plan (required):
   • List files to touch, expected LOC delta, commit grouping, and test impact.
   • Acceptance criteria: green linters, unit tests for touched area, ≤300 LOC preferred (hard cap 500 LOC) per PR.
2. Change Set Limits:
   • Default: ≤300 changed LOC; soft fail at >300 triggers “split-PR” suggestion; hard block at >500 without explicit user override.
   • Sensitive areas (auth, migrations, public APIs): cap ≤100 LOC and require a dedicated PR.
3. User Approval Gates:
   • If plan exceeds file/LOC caps or touches sensitive areas, request approval before edits.

[TOGGLE] Strict 300 LOC cap (block at 301): ON/OFF
[TOGGLE] Sensitive-area stricter cap (≤100 LOC): ON/OFF

Branching & Remotes

• Prompt for remote on first VCS action: “Connect GitHub remote?” Offer: create repo, set origin, set upstream for forks.
• Branch Naming: feat|fix|chore|docs|refactor/<scope>-<short-slug> (e.g., feat/search-index-dedup).
• Sync Discipline:
  1. git fetch --all --prune
  2. If default branch diverged, rebase feature branch (git rebase origin/main) unless repo mandates merge.
  3. Resolve conflicts locally; re-run tests; then push.

Rule: ALWAYS fetch/pull before push.
Example: Before git push -u origin feat/..., run git fetch --all + rebase check.

Commit Strategy (Auto & Assisted)

Principle: Commits should represent a single logical change that compiles/tests.

Rules:

1. Auto-suggest commits when a discrete unit is complete:
   • A function/class implemented or rewritten.
   • A test added to cover a case.
   • A refactor limited to one module or concern.
   • Config or script changes isolated from code changes.
2. Chunking Heuristics:
   • Split code + tests if either would push commit over ~150 LOC.
   • Keep API change + migration script in separate commit with clear order.
3. No WIP noise: Avoid wip commits; use local uncommitted changes + Cursor todo list until a coherent unit is ready.
4. Fixup/Squash Flow: For PR polish, propose git commit --fixup + git rebase -i --autosquash.

[TOGGLE] Auto-create commits for discrete units: ON/OFF
[TOGGLE] Enforce ≤150 LOC per commit: ON/OFF

Commit Message Policy (Auto-Generation)

Principle: Messages must be informative, scan-friendly, and conventional.

Rules:

1. Conventional Header:
   type(scope): summary where type ∈ {feat, fix, chore, docs, refactor, test, perf, ci, build}.
   • Summary: imperative mood, ≤65 chars.
2. Body (optional but preferred):
   • What & Why (not just how).
   • Bullet notable impacts; reference issue/PR (Closes #123).
3. Footer (when applicable):
   • BREAKING CHANGE: description.
   • Co-authored-by lines.

Auto-generation behavior:

• Parse the staged diff; infer type and scope from paths and change patterns.
• Suggest 1–3 candidate messages; default to best if user doesn’t respond in 10 seconds.
• Include issue keys if branch name contains one (e.g., ABC-123).

Example:

fix(search): guard against empty query in ranking
- Prevents nil pointer on empty term
- Adds unit tests for empty and whitespace-only queries
Closes #482

[TOGGLE] Require user confirm commit message: ON/OFF (default OFF)

Testing, Linting, and Hooks

• Before commit: run fast linters/formatters (pre-commit if present).
• Before push: run unit tests affected by changed paths (test impact heuristic); if flaky tests detected, prompt to re-run and isolate.
• On failure: do not commit/push; show concise failure summary and suggested fixes.

[TOGGLE] Block commit on lint errors: ON/OFF (default ON)
[TOGGLE] Block push on failing affected tests: ON/OFF (default ON)

Pull Requests (Size & Process)

Rules:

1. PR Size: Preferred ≤300 LOC; hard cap 500 LOC. If exceeded, tool must propose an automatic split plan (files/groups) and seek approval.

2. PR Prep:

   • Ensure branch is up to date (fetch/rebase).
   • Pause all agent tasks/todos; snapshot plan & checklist into PR description.
   • Verify CI config present; add minimal CI if missing (repo standard).

3. PR Description Template (auto-fill):

   • Summary: one paragraph.
   • Changes: bullet list grouped by module.
   • Tests: what added/updated; coverage note.
   • Risk & Rollback: impact, toggles, revert plan.
   • Screenshots/Logs: if UI or perf relevant.
   • Linked Issues: #refs.
   • Checklist: lint ✅ tests ✅ rebase ✅ secrets scan ✅

4. Labeling: area/<pkg>, type/<feat|fix|...>, risk/<low|med|high>.

5. Reviewers: suggest code owners or last editors of touched files.

[TOGGLE] Enforce PR <=300 LOC (warn) / 500 LOC (block): ON/OFF
[TOGGLE] Auto-split PR by folder or concern: ON/OFF

Security & Privacy Guardrails

• Block commits containing .env, keys, tokens, or files > 5MB unless extension whitelisted (e.g., .png in assets).
• Run secret scanners before push; redact findings in logs.
• Disallow committing PII or production dumps.
• Honor .gitignore; suggest updates when new generated files detected.

Performance & Observability Notes

• For code that adds background jobs or hot paths, require a one-line note in PR about metrics/logs added or existing signals observed.

Documentation Integration

• If public API changed, require doc updates (README/CHANGELOG/ADR).
• Auto-suggest CHANGELOG entry for feat, fix, perf, BREAKING CHANGE.

Review & Governance

• PR gating: code owner approval for sensitive areas.
• Rollout plan: if risk≥medium, include toggle or guarded release step; include rollback command or revert path.

Interaction Protocol

• When missing remote/repo or auth: prompt user to connect GitHub (token or CLI), then proceed.
• On conflicts or oversized diffs: propose 2–3 split strategies; pick smallest-risk by default if user silent.

Anti-Patterns & “Do NOT”

• Do not push without fetch/rebase.
• Do not mix refactor + feature in one commit.
• Do not exceed size caps without plan/approval.
• Do not commit commented-out code or debug prints.
• Do not squash away meaningful commit history unless requested at merge.

Examples

Positive:

• feat(auth): add PKCE flow for mobile clients + tests, <120 LOC, clear PR checklist.
  Negative:
• wip: misc changes 900 LOC PR combining refactor+feature+tests.

OPEN QUESTIONS

Rationale & Ops Notes

• Model behavior: Medium planning depth; always summarize VCS plan to reduce surprise diffs.
• Patch-size limits: Pref ≤300 LOC, hard cap 500 LOC to keep reviews fast and rollback cheap. Sensitive paths capped at 100 LOC.
• Auto-commit & messages: Encourages atomic, reviewable history; conventional headers improve changelog generation and blame clarity.
• Fetch-before-push: Prevents remote rejection and late conflict churn.
• Task pause before PR: Ensures attention is on review quality; avoids parallel uncommitted changes contaminating the PR.

Exploratory Options (Opt-In)

These are Exploratory—enable when useful.

1. Speculative Branching: Auto-fork large refactors into refactor/* branches with staged PRs.
   • Pros: reduces long-lived branches; safer review. Cons: more PR overhead.
2. Aggressive Test Synthesis: Generate minimal unit tests for uncovered lines in touched files.
   • Pros: coverage; catches regressions. Cons: brittle tests if APIs unstable.
3. Auto-Cherry-Pick Hotfixes: When branch protection allows, propose cherry-picks to release branches after a fix/ PR merges.
   • Pros: faster hotfix propagation. Cons: requires tight branch discipline.

Quick Review Toggles (copy into repo if you want overrides)

• [TOGGLE] Strict commit size cap (≤150 LOC/commit): ON
• [TOGGLE] Block PRs >300 LOC (warn) / >500 LOC (block): ON
• [TOGGLE] Auto-create commits for discrete units: ON
• [TOGGLE] Require user confirmation of commit message: OFF
• [TOGGLE] Block on lint/test failures pre-push: ON
• [TOGGLE] Sensitive-area reduced cap (≤100 LOC): ON

How the Agent Executes (Concrete Steps)

1. Detect git repo; if absent, git init and prompt to connect GitHub remote (create or link).
2. On edit completion: propose commit plan (groups, estimated LOC).
3. Stage by chunk (file or hunk) → run linters/formatters → generate 3 commit message candidates → commit.
4. Before push: git fetch --all --prune → rebase if needed → run affected tests → push.
5. PR creation: pause tasks, build PR body from template, apply labels, request reviewers, link issues.
6. If PR >300 LOC (warn) or >500 LOC (block): propose auto-split; execute upon approval.