docs(agents): add branches-and-worktrees rule (dedicated integration worktree)
Document the worktree workflow: feature work in feature worktrees on their own feature/* branch; all development and main integration (and deploy) happens in a single dedicated integration worktree at ~/Repositories/sigit-si-integration. Branches can be created off development from anywhere; never force or merge into a branch another worktree holds except inside that worktree. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Seto Elkahfi committed
Jun 30, 2026 at 20:12 UTC
cd2bdcc0fa9657dde758a62d36391821eabc8408
1 file changed
+32
.agents/AGENTS.md
+32
@@ -60,6 +60,36 @@ The public `sigit` repo carries its own skills (`ai-assisted-coding`,
60
`agent-client-protocol`, `tool-calling`, `branding`, `sigit-code-release`). Those
61
stay public-safe.
62
63
+## Branches and worktrees
64
+
65
+This repo is developed with multiple git worktrees: one repository, several
66
+working directories, each pinned to its own branch. A branch can be checked out
67
+in only one worktree at a time. Treat that as a guard rail, not a bug: it stops
68
+two working trees from desyncing the same branch.
69
+
70
+Rules:
71
+
72
+- **Feature work lives in a feature worktree** on its own `feature/*` branch.
73
+ Never check out `development` or `main` into a feature worktree.
74
+- **Integration is centralised in one dedicated integration worktree** that
75
+ stays permanently on `development`. It is the only place `feature/* ->
76
+ development` merges happen, and the only place `development -> main` promotion
77
+ and deploy (`git push smbcloud main`) happen. Canonical path:
78
+ `~/Repositories/sigit-si-integration`.
79
+- **Branch off `development` from anywhere.** `git checkout -b feature/x
80
+ development` creates a new branch from `development`'s commit without checking
81
+ `development` out, so it works even while the integration worktree holds it.
82
+- **Standard flow.** In a feature worktree: branch `feature/x` off
83
+ `development`, commit. In the integration worktree: `git merge --no-ff
84
+ feature/x` into `development`; when releasing, `git merge --no-ff development`
85
+ into `main` and `git push smbcloud main`. Then delete the merged `feature/x`.
86
+- **Do not force a branch another worktree holds.** Never `git branch -f` or
87
+ push into a branch that is checked out elsewhere; it desyncs that working tree.
88
+ If you must merge into such a branch outside the normal flow, run the merge
89
+ inside the worktree that owns it (`git -C <path> merge ...`).
90
+- The `.claude/worktrees/*` directories are ephemeral per-session feature
91
+ worktrees; the integration worktree is stable and outside that tree.
92
+
93
## Validation
94
95
- Rust (`sigit`, `onde-cloud`): `cargo build`, `cargo test`, `cargo clippy`.
@@ -71,3 +101,5 @@ stay public-safe.
101
- Putting strategy, a provider name, or a secret into the public `sigit` repo.
102
- Leaving AI-writing tells in public prose.
103
- Mixing the product, CLI, and company names.
104
+- Checking out `development` or `main` into a feature worktree, or merging into
105
+ them anywhere but the integration worktree (see Branches and worktrees).