From e2da4cd1ea864ff2cbd013f50b4c1ad6ec5f799a Mon Sep 17 00:00:00 2001
From: Ed Heltzel <402910+edheltzel@users.noreply.github.com>
Date: Sat, 12 Sep 2026 09:51:50 -0400
Subject: [PATCH 1/2] docs(agents): document GitButler workflow, small commits,
 stacks, -wip worktrees

---
 AGENTS.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d8869a8..205fb7a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,17 @@ Closeout: re-check paths, update owning docs, refresh indexes, run verification,
 - One factory. Poteto-mode is per-session, never a process-wide boolean.
 - Official skills SoT is `cursor/plugins` `pstack/skills`. Update with `npm run sync` (`node scripts/pstack.mjs sync`). Writes into existing `skills/do-*` only. Not `backnotprop/pstack`, not skills.sh, not `npx skills add`.
 
+## Version control
+
+GitButler (`but`) is the VCS. The main checkout is the `gitbutler/workspace` branch; target is `origin/master`.
+
+- All writes go through `but` (`commit`, `push`, `pr new`, `move`, `squash`). Read-only git (`git log`, `git blame`) is fine.
+- One dedicated `but` branch per agent session. Commit only that session's changes to it.
+- Commit small and often: after every working checkpoint, not at the end of the task. Split unrelated hunks into separate commits. Large commits hide what changed from the human in the loop.
+- Stack when a change clearly builds on an unmerged branch: `but move <child> --above <parent>`. Do not mix dependent work into one branch.
+- Prefer `but` branches in the workspace over git worktrees (GitButler does not commit from linked worktrees). If a worktree is needed for a new feature, suffix it `-wip`.
+- PRs only when asked. Use `but pr new <top-branch> -t`, never `gh pr create`. Write the PR body; when the branch is stacked, name the branches it depends on with a `Stacked on:` line so the reviewer can find them.
+
 ## Native omp
 
 Tell operators plugin-link only:

From 80eeb478666691a79daadeb296359153e159a4b8 Mon Sep 17 00:00:00 2001
From: Ed Heltzel <402910+edheltzel@users.noreply.github.com>
Date: Sat, 12 Sep 2026 10:35:05 -0400
Subject: [PATCH 2/2] AGENTS.md update to make sure `but` is used for each
 feature not each session, that would ballon out of control for each session.

---
 AGENTS.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 205fb7a..435c682 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -60,7 +60,7 @@ Closeout: re-check paths, update owning docs, refresh indexes, run verification,
 GitButler (`but`) is the VCS. The main checkout is the `gitbutler/workspace` branch; target is `origin/master`.
 
 - All writes go through `but` (`commit`, `push`, `pr new`, `move`, `squash`). Read-only git (`git log`, `git blame`) is fine.
-- One dedicated `but` branch per agent session. Commit only that session's changes to it.
+- One dedicated `but` branch per feature. Commit only that session's changes to it.
 - Commit small and often: after every working checkpoint, not at the end of the task. Split unrelated hunks into separate commits. Large commits hide what changed from the human in the loop.
 - Stack when a change clearly builds on an unmerged branch: `but move <child> --above <parent>`. Do not mix dependent work into one branch.
 - Prefer `but` branches in the workspace over git worktrees (GitButler does not commit from linked worktrees). If a worktree is needed for a new feature, suffix it `-wip`.
@@ -96,13 +96,13 @@ npm test
 
 ## Child DOX Index
 
-| Path | Owns |
-| --- | --- |
-| [extensions/AGENTS.md](extensions/AGENTS.md) | Factory `pstack.ts`; per-session poteto-mode |
-| [e2e/AGENTS.md](e2e/AGENTS.md) | Static doctor/lint + Vitest; live RPC local-only via plugin-link |
-| [skills/AGENTS.md](skills/AGENTS.md) | Skill tree; SKILL.md frontmatter `name` + `description` |
-| [docs/AGENTS.md](docs/AGENTS.md) | original numbered `guide/`; first-run lives on README (omp plugin link + Claude plugin install) |
-| [automations/AGENTS.md](automations/AGENTS.md) | Dormant Benny pack; not slash skills |
-| [scripts/AGENTS.md](scripts/AGENTS.md) | `pstack sync`: vendor official skills from cursor/plugins into `skills/do-*` |
+| Path                                           | Owns                                                                                            |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [extensions/AGENTS.md](extensions/AGENTS.md)   | Factory `pstack.ts`; per-session poteto-mode                                                    |
+| [e2e/AGENTS.md](e2e/AGENTS.md)                 | Static doctor/lint + Vitest; live RPC local-only via plugin-link                                |
+| [skills/AGENTS.md](skills/AGENTS.md)           | Skill tree; SKILL.md frontmatter `name` + `description`                                         |
+| [docs/AGENTS.md](docs/AGENTS.md)               | original numbered `guide/`; first-run lives on README (omp plugin link + Claude plugin install) |
+| [automations/AGENTS.md](automations/AGENTS.md) | Dormant Benny pack; not slash skills                                                            |
+| [scripts/AGENTS.md](scripts/AGENTS.md)         | `pstack sync`: vendor official skills from cursor/plugins into `skills/do-*`                    |
 
 `agents/` and `commands/` have no child AGENTS.md; they follow this rail. Commands need frontmatter `description`.