docs(agents): add branches-and-worktrees rule (dedicated integration worktree)

index 9494730..7b0592e 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -60,6 +60,36 @@ The public `sigit` repo carries its own skills (`ai-assisted-coding`, `agent-client-protocol`, `tool-calling`, `branding`, `sigit-code-release`). Those stay public-safe. +## Branches and worktrees + +This repo is developed with multiple git worktrees: one repository, several +working directories, each pinned to its own branch. A branch can be checked out +in only one worktree at a time. Treat that as a guard rail, not a bug: it stops +two working trees from desyncing the same branch. + +Rules: + +- **Feature work lives in a feature worktree** on its own `feature/*` branch. + Never check out `development` or `main` into a feature worktree. +- **Integration is centralised in one dedicated integration worktree** that + stays permanently on `development`. It is the only place `feature/* -> + development` merges happen, and the only place `development -> main` promotion + and deploy (`git push smbcloud main`) happen. Canonical path: + `~/Repositories/sigit-si-integration`. +- **Branch off `development` from anywhere.** `git checkout -b feature/x + development` creates a new branch from `development`'s commit without checking + `development` out, so it works even while the integration worktree holds it. +- **Standard flow.** In a feature worktree: branch `feature/x` off + `development`, commit. In the integration worktree: `git merge --no-ff + feature/x` into `development`; when releasing, `git merge --no-ff development` + into `main` and `git push smbcloud main`. Then delete the merged `feature/x`. +- **Do not force a branch another worktree holds.** Never `git branch -f` or + push into a branch that is checked out elsewhere; it desyncs that working tree. + If you must merge into such a branch outside the normal flow, run the merge + inside the worktree that owns it (`git -C <path> merge ...`). +- The `.claude/worktrees/*` directories are ephemeral per-session feature + worktrees; the integration worktree is stable and outside that tree. + ## Validation - Rust (`sigit`, `onde-cloud`): `cargo build`, `cargo test`, `cargo clippy`. @@ -71,3 +101,5 @@ stay public-safe. - Putting strategy, a provider name, or a secret into the public `sigit` repo. - Leaving AI-writing tells in public prose. - Mixing the product, CLI, and company names. +- Checking out `development` or `main` into a feature worktree, or merging into + them anywhere but the integration worktree (see Branches and worktrees).