---
description: Branch names and commit messages must lead with the Jira issue key
alwaysApply: true
---

# Jira keys in branches and commits (Neon Sprawl)

Project key in Jira is **`NS`** unless a different key is used for the issue (match the issue you are implementing).

## Branch names

- Put the **Jira key first**, then a short **kebab-case** slug (and optional type). The key must be the **first path segment** of the branch name.
- **Good:** `NS-14-click-to-move`, `NS-20-fix-health-desync`, `NS-14/feature/terrain-spike` (key still first segment if using slashes).
- **Avoid:** `feature/click-to-move` with no key, or `fix/ns-14-foo` with the key not at the start.

When suggesting or creating a branch for story **NS-14**, use something like **`NS-14-<slug>`**, not `feature/ns-14-…` with the key buried after a prefix.

## Commit messages

- For **any commit done as part of a Jira story, bug, or task** (work tracked under an issue), the **first token** of the subject line must be the **Jira key and number**, then **`:`** and the summary.
- **Good:** `NS-14: add direct click-to-move steering`, `NS-20: fix duplicate spawn on reconnect`
- **Avoid:** `fix(client): …` or `feat: …` **without** the Jira key at the front. If you use Conventional Commits, place them **after** the key: `NS-14: feat(client): click-to-move prototype`

**Multi-issue commits:** Prefer one issue per commit; if unavoidable, list keys: `NS-14, NS-18: shared nav refactor`.

**No Jira issue (rare):** Maintenance or repo-only changes with no ticket — use **`chore:`** as the prefix (e.g. `chore: update .gitignore`). Do not invent fake keys.

## Agent behavior

- When creating a **branch** or **commit** for tracked work, **infer the key** from the current story (e.g. user says NS-14), the branch already in use, or the Jira issue fetched via MCP.
- Follow [git workflow](git-workflow.md) (branch vs `main`) and [commit-and-review](commit-and-review.md) (no commit until the user asks).