fuj-management/docs/plans/2026-05-05-2144-branch-per-feature-workflow.md

Branch-per-feature + Gitea MR workflow

Context

Until now, Claude has been committing feature work directly to main (see recent history: feat: Lower adult monthly fee…, feat: Go rewrite M1…, all on main). The user wants to switch to a branch-per-feature flow with review via a Gitea merge request, so that:

• Feature work is reviewable as a self-contained diff before it lands.
• main stays releasable.
• The change history shows reviewed merges, not unsupervised pushes.

The remote is Gitea (https://gitea.home.hrajfrisbee.cz/kacerr/fuj-management.git), which supports the standard pull/merge-request flow.

This plan only modifies CLAUDE.md. No code changes.

Scope clarification (from user)

• MR creation method: Claude pushes the branch and prints the Gitea "compare" URL. The user opens / merges the MR in the browser. No tea CLI, no API calls.
• When the flow applies: Features only. Small bug fixes and hotfixes can still be committed straight to main. Claude decides feature-vs-fix based on scope; when uncertain, ask.
• Branch naming: feat/<slug> for features, fix/<slug> for the occasional bug-fix branch the user explicitly requests. <slug> is kebab-case, short, descriptive.

Change

Add a new top-level section to CLAUDE.md titled "Branching & merge requests", placed immediately before the existing ## Git Commits section so the workflow context appears before the commit-message convention.

Proposed section content

## Branching & merge requests

The remote is Gitea (`gitea.home.hrajfrisbee.cz/kacerr/fuj-management`).
For **features**, do not commit to `main` directly. Use a branch + merge
request flow:

1. **Create a branch off `main`** before starting work:
   - `feat/<slug>` for features (e.g. `feat/qr-code-overlay`)
   - `fix/<slug>` for bug-fix branches the user explicitly asks for
   - `<slug>` is short kebab-case
2. **Commit on the branch** following the existing commit conventions
   (Co-Authored-By trailer, etc.).
3. **Push the branch** to `origin` with `-u` so it tracks.
4. **Print the Gitea compare URL** so the user can open the MR in the
   browser:
   `https://gitea.home.hrajfrisbee.cz/kacerr/fuj-management/compare/main...<branch>`
   Do **not** use `tea`, `gh`, or call the Gitea API — the user opens and
   merges the MR themselves.
5. **Do not merge or delete the branch** from the CLI. The user does that
   in Gitea.

**Exceptions — when committing straight to `main` is fine:**
- Small bug fixes / hotfixes the user describes as such.
- Typo / comment / formatting tweaks.
- Edits the user explicitly says to push to `main`.

When uncertain whether something is "feature" or "small fix", ask before
committing.

Files to modify

• CLAUDE.md — insert the new ## Branching & merge requests section just above the existing ## Git Commits section (around line 95).

Verification

• Re-read CLAUDE.md and confirm the new section is well-placed and the existing structure (## Git Commits, ## Changelog, ## Plans) is intact.
• git diff CLAUDE.md should show only an additive change.
• No code, tests, or runtime behavior changes — nothing else to test.
• Behavior verification happens on the next feature request: Claude should create a feat/<slug> branch, commit there, push, and print the compare URL instead of committing on main.