From e42ecc10986bab8474ecf67780f476f27ba90d09 Mon Sep 17 00:00:00 2001
From: postlog <scarfaceborn@gmail.com>
Date: Sun, 28 Jun 2026 16:36:16 +0300
Subject: [PATCH] chore: document feature worktree workflow

Every feature/fix is developed in its own git worktree under .worktrees/<slug>
on its own branch (branch -> commit -> push -> PR; never edit main directly).
Document the workflow in AGENTS.md and add .worktrees/ to .gitignore so those
in-repo checkouts stay out of git status.
---
 .gitignore   |  3 +++
 AGENTS.md    | 19 +++++++++++++++++++
 CHANGELOG.md |  7 +++++++
 3 files changed, 29 insertions(+)

diff --git a/.gitignore b/.gitignore
index 9d9f9c5..1ec37fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,6 +33,9 @@ go.work.sum
 # Tooling scratch (Playwright MCP traces/console logs)
 .playwright-mcp/
 
+# Feature worktrees live in-repo under .worktrees/<slug> (one branch per feature/fix)
+.worktrees/
+
 # OS / editor noise
 .DS_Store
 ._*
diff --git a/AGENTS.md b/AGENTS.md
index 4e7a387..c756fdf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -525,6 +525,25 @@ scenario. Turnkey run: `make -C apitest test`.
 - Required arrays (`groups`/`rules`/`providers`/`inbounds`/…) are decoded strictly by the server: `null`
   (what a nil slice is JSON-encoded into) is rejected — send empty `[]`.
 
+## Working on a change — worktree, branch, PR
+
+Every feature/fix is developed in its **own git worktree on its own branch** — never
+directly on `main` in the main checkout. This keeps `main` clean and switchable, isolates
+parallel work, and makes branch → commit → push → PR the only path into `main`.
+
+- **Create a worktree** off a clean `main`:
+  `git worktree add -b <type>/<slug> .worktrees/<slug>` — `<type>` ∈ `feat`/`fix`/`chore`
+  (e.g. `feat/subscription-link-catalog`). Worktrees live **in-repo** under `.worktrees/`,
+  which is gitignored, so the checkouts never show up in `git status`.
+- **Do all development and commits in the worktree** (`cd .worktrees/<slug>`); the main
+  checkout stays untouched.
+- **Run the full check before pushing** (`make all` — build+vet+lint+unit+integration+
+  apitest) and confirm it is green; a green push is not a substitute for the gate.
+- **Push the branch and open a PR.** Do **not** push to or merge straight into `main` —
+  changes land via a reviewed, approved PR (squash-merge). Each PR carries its CHANGELOG
+  entry (and an ADR for non-trivial changes — see below).
+- **After merge**, clean up: `git worktree remove .worktrees/<slug>` and delete the branch.
+
 ## Documenting changes — CHANGELOG + ADR
 
 Every PR leaves a trace, so that «what and why we changed» does not get lost in the
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c679c6..5b5a8b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ link to an ADR in [`docs/decisions/`](docs/decisions/). The rule and format are
 in [`AGENTS.md`](AGENTS.md) (section "Documenting changes"). There are no versions/tags:
 the service is not released, deploy is continuous.
 
+## 2026-06-28 — Feature worktree workflow (#120)
+
+Documented the per-feature workflow in `AGENTS.md`: every feature/fix is developed in its
+own git worktree under `.worktrees/<slug>` on its own branch (branch → commit → push → PR;
+never edit `main` directly). Added `.worktrees/` to `.gitignore` so those in-repo checkouts
+never pollute `git status`.
+
 ## 2026-06-19 — Responsive admin UI: phones, tablets, ultrawide (#115)
 
 Made the admin panel usable on every screen size — mini-phones (320px) through ultrawide.