From e894ce29860ce0cdd69f1971f3074ac13922f7af Mon Sep 17 00:00:00 2001 From: Matysh Date: Fri, 14 Aug 2026 12:31:12 +0300 Subject: [PATCH] docs: fix the working-tree layout in writing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two agents sharing one checkout share one HEAD, and twice in an hour a commit landed on someone else's task branch that way. The layout that ends it: the main clone belongs to the author and its task branches, hp-dev is the owner's permanent worktree on dev, and the reviewer and the infrastructure agent own no local tree at all — one runs in CI on a fresh checkout, the other reads through git show and publishes through the API, so it has no HEAD to collide with. Also recorded: a worktree is only usable on the machine that created it, because its .git file stores an absolute path in that machine's format. We hit this in both directions within a day. Issue: #115 User-Visible: no --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1495b972..4ec8b8aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -154,6 +154,28 @@ arrive. Cycles are counted per stage, so a code review spends its own budget. Everything else still requires the owner's explicit command: pushing `main`, creating tags, publishing betas and releases, closing issues. +## Working trees (#115) + +One checkout, one `HEAD`: two agents sharing a directory inherit each other's +branch, and twice in one hour a commit landed on someone else's task branch that +way. The layout is therefore fixed: + +- **`houseplan-card-src/houseplan-card`** — the author's tree. Task branches live + here; nobody else commits in it. Unfamiliar local changes belong to the author + or the owner — never reset or clean them away. +- **`houseplan-card-src/hp-dev`** — the owner's worktree, permanently on `dev`. For owner-side operations that must not disturb the + author's tree: pushing `dev`, restoring a hook's executable bit, emergencies. +- **The reviewer and the infrastructure agent own no local tree.** The reviewer + runs in CI on a fresh checkout. The infrastructure agent reads via `git show` + and publishes through the GitHub API; it makes no local commits at all, so it + needs no `HEAD` of its own. Its scratch worktrees live outside the repo and are + pruned after use. + +A worktree is only usable on the machine that created it: the `.git` file records +an absolute path in that machine's format. One created from a Linux sandbox is +dead on Windows and vice versa — create worktrees on the machine that will use +them, which for `hp-dev` means the owner's. + ## Two-agent workflow **Codex** writes analysis, specs and all product code. **Claude** reviews specs and