From 928724ba393e1764018bb8d33249cde9325203cc Mon Sep 17 00:00:00 2001 From: curo1305 Date: Mon, 18 May 2026 15:29:58 +0200 Subject: [PATCH] docs: require git worktrees for all branch work Adds a Workflow Rules section mandating worktrees so parallel plugin and feature sessions never interfere with each other or with main. Includes setup commands, rules, and updated Plugin Branches section. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 661c3ec..db089a7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -261,13 +261,43 @@ chore: description - Always `git add` only the files relevant to that commit — never `git add .` blindly. - **Always push after committing** — every commit goes to the remote Gitea repository immediately. +### Git Worktrees — Required for All Branch Work + +**Never switch branches in the main working directory.** Always use a git worktree so that +multiple sessions (plugins, features, bugfixes) can run in parallel without interfering with +each other or with `main`. + +```bash +# Create a worktree for a plugin branch +git worktree add ../pyra-plugin-nextcloud -b plugin/nextcloud + +# Create a worktree for a feature branch +git worktree add ../pyra-feat-vault -b feat/vault-encryption + +# List active worktrees +git worktree list + +# Remove a worktree after merging +git worktree remove ../pyra-plugin-nextcloud +``` + +Each worktree is a full checkout at a separate path. Work on it exactly like the main repo — +commit, push, run tests — without touching the `main` worktree. + +**Rules:** +- The main working directory (`/Users/nik/Documents/Progamming/pyra`) always stays on `main`. +- Do **not** run `git checkout ` in the main directory — create a worktree instead. +- When a Claude Code session is asked to work on a branch, it must create (or reuse) a worktree + for that branch before making any changes. + ### Plugin Branches -- Every plugin is developed on its own branch: `plugin/` (e.g. `plugin/nextcloud`). +- Every plugin is developed on its own branch: `plugin/` (e.g. `plugin/nextcloud`), in its + own worktree (e.g. `../pyra-plugin-nextcloud`). - A plugin branch is **never merged to `main` until the plugin is complete and tested**. - `main` always contains only production-ready core source code (`src/pyra/` framework). - If plugin work uncovers a bug in core Pyra code, fix it on a dedicated `fix/...` branch - off `main`, commit it to `main`, push, then rebase the plugin branch onto the updated `main`. + off `main` (in its own worktree), merge to `main`, push, then rebase the plugin branch. - Plugin branches may be pushed to remote for backup/review at any time. - Do **not** merge plugin branches to `main` prematurely — a half-working plugin on `main` is worse than one that isn't there yet.