# Feature Branch and Developer Handoff Guide

Use this workflow for a specific feature that starts from `main` and is handed
to another developer.

## 1. Protect existing work

```bash
git status --short
```

If the worktree contains changes you do not own, stop and coordinate. Do not
silently discard, stash, or include someone else's changes.

## 2. Create the feature branch from current main

```bash
git switch main
git pull --ff-only origin main
git switch -c feature/<feature-slug>
```

Use lowercase kebab-case based on the outcome, for example:
`feature/equipment-status-card`.

## 3. Work and verify

- Keep the branch focused on one feature.
- Reuse the component prompts and `/design-system` visual reference.
- Make small commits that describe completed outcomes.
- Follow `agents.md`; do not run its prohibited build/typecheck commands.
- Run focused linting plus `git diff --check`.

## 4. Publish the branch

```bash
git add <feature-files>
git commit -m "feat(<scope>): <short outcome>"
git push -u origin feature/<feature-slug>
```

Do not push feature work directly to `client/<slug>`. Those branches are
generated from `main`. Follow `GIT_BRANCHES.md` separately for additive,
client-only `overlay/<slug>` work.

## 5. Handoff template

```text
# Feature branch handoff

Branch: feature/<feature-slug>
Base branch: main
Scope: <feature area>

## Goal
<What this feature must achieve>

## Current state
- <Implemented behavior>
- <Important files changed>
- <Architecture or design decisions>

## Verification completed
- git diff --check
- npx eslint <changed-files> --quiet
- <Targeted route or interaction verification>

## Remaining work
- <Specific unfinished item, or "None">

## How to continue
git fetch origin
git switch feature/<feature-slug>
git pull --ff-only origin feature/<feature-slug>

Read agents.md, prompts/design-system.md, and the relevant component prompt
before editing. Preserve unrelated work.
```

## 6. Merge expectation

Review the feature against `main`. Address review feedback on the feature branch
and merge only after acceptance criteria and focused verification pass.

**TL;DR:** Branch from an updated `main`, keep the feature focused, push it, and
handoff the branch with completed work, verification, and exact next steps.