---
description: When starting Jira story work, move issue To Do → In Progress when applicable, create story branch, load issue + repo context; no implementation code until a plan exists under docs/plans/.
alwaysApply: true
---

# Story kickoff (Jira)

When the user starts work on a **Jira story** (e.g. issue key `NEON-2`, phrases like “begin work on story”, “implement NEON-…”), run this sequence **before** writing or changing application code.

## 1. Load Jira context

- Fetch the issue when possible (e.g. Atlassian MCP `getJiraIssue`), or use a URL / pasted description the user provides.
- Capture summary, description, acceptance criteria, and anything explicitly **out of scope**.
- **Hierarchy:** Expect **Epic → Story** (or Task/Bug). **Do not** add or assume a Jira **Feature** layer—**module / slice** grouping is **labels on the story** (see [Jira alignment](../../docs/decomposition/README.md#jira-alignment) in the decomposition README).

## 1a. Board status (To Do → In Progress)

- After the issue is known, if its status is **To Do** (or your workflow’s equivalent “not started” state), **transition it to In Progress** so the board matches active kickoff.
- When Atlassian MCP is available: `getTransitionsForJiraIssue` to find the transition id for **In Progress**, then `transitionJiraIssue`; otherwise do the same in the Jira UI.
- If the issue is already **In Progress** or later, do not move it backward.

## 1b. Story branch

- **Create and use a new branch** for this issue as soon as story work begins (planning counts). Name it with the **Jira key first** and a short kebab-case slug (e.g. `NEON-3-position-state-api`); see [jira-git-naming](jira-git-naming.md) and [git workflow](git-workflow.md).
- If the user is already on a branch whose **first path segment** matches this issue key, continue on it unless they ask to rename.
- Do not wait for implementation to start before branching; the implementation plan and all story commits belong on this branch.

## 2. Load codebase context (read-only)

- Open only what the story implies: entry scenes/scripts, related modules, configs, tests/CI, and relevant [`docs/`](docs/) files.
- **No edits** and **no new implementation or test files** in this phase.

## 3. No implementation yet

- Do not add or change source, Godot scenes/project, game data pipelines, or automated tests until step 4 is done **and** the user has moved past planning in chat (e.g. explicit go-ahead to implement).

## 4. Planning document

- Add **`docs/plans/{JIRA_KEY}-implementation-plan.md`** (example: `docs/plans/NEON-2-implementation-plan.md`). Create `docs/plans/` if it does not exist.
- **Commit** the plan on the **story branch** from step 1b when it is ready (at agent discretion per [commit-and-review](commit-and-review.md)); do not put ticketed plan-only work only on `main` while implementation stays on a branch—see [git workflow](git-workflow.md).

**Required sections** in that file (do **not** ship a plan that omits any of these):

- Story reference (key, title, link if available)
- Goal, scope, and out-of-scope (from Jira)
- Acceptance criteria checklist (from Jira)
- Technical approach (concise)
- **Files to add** — **mandatory:** explicit list of new file paths (or state “none” with one line why)
- **Files to modify** — **mandatory:** explicit list of paths **with a one-line rationale each** (or state “none” with one line why)
- **Tests** — **mandatory:** explicit list of test files to **add** or **change**, and what each will cover; if truly no automated tests, say why (e.g. no harness yet) and what manual verification replaces them
- Open questions / risks (if none, write “None.”)

These three lists (**files to add**, **files to modify**, **tests**) must **always** be generated during kickoff—they are not optional prose and must not be left implicit inside “Technical approach” only.

## 5. After the plan

- Implement only after the user confirms. All implementation commits stay on the **same story branch** from step 1b; follow [git workflow](git-workflow.md).

When the story is **done** and merged to `main`, follow [story-end](story-end.md) to return to `main`, pull, and remove the local story branch.