neon-sprawl/.cursor/rules/git-workflow.md

description	alwaysApply
New Linear issue = new branch from kickoff; doc-only on main when not story-scoped	true

Git workflow (Neon Sprawl)

Agent: On story/ticket work, git commit as you go on the story branch—do not wait for an explicit “commit” from the user (see commit-and-review Commit as you go). Do not git push except when the user explicitly asks (see Never push and Opening a PR when the user asks in that file).

• Beginning work on a new Linear issue — Create a new branch as soon as story work starts (planning, implementation, or both). Branch names must start with the Linear issue id (e.g. NEO-6-position-state-api); see linear-git-naming. Stay on that branch for everything scoped to that issue, including docs/plans/{KEY}-implementation-plan.md, until the story is merged. Do not put ticketed story plans only on main while implementation lives on a branch.

• Branching from main requires a fresh pull first — before creating a new story branch from main, run git fetch origin, git checkout main, and git pull --ff-only so the branch starts from the latest remote main. Do not branch from a stale local main.

• Documentation-only work — Commit directly on main when the change is not tied to an active Linear issue branch: general Markdown under docs/ (except per-story implementation plans for an issue you are working on that branch), root and nested README.md files, neon_sprawl_vision.plan.md, and other cross-cutting prose. No feature branch required.

• Code or implementation changes — Use a branch, then merge to main when ready. Commit subjects must start with the Linear issue id when the work maps to an issue (e.g. NEO-5: …). See linear-git-naming. This includes application source (C#, GDScript), Godot scenes and project files, docker-compose.yml, .csproj / build config, CI workflows, JSON/YAML game data under content/, and JSON Schema when it ships with data pipelines—not standalone doc prose.

When a change mixes documentation and code, treat it as a code change (use a branch). Per-story implementation plans are part of the story branch, not an exception for main.

After the PR for a story branch is merged, clean up locally per story-end (checkout main, pull, branch -d).

When the user asks the agent to open a PR, use the GitHub MCP create_pull_request tool with a NEO-*: title prefix per commit-and-review Opening a PR when the user asks—not only a GitHub Compare & pull request link (the web UI mangles issue-key casing in the default title).