From 9e86e0e2a12b90d5b6d77ee9790a001a7849d371 Mon Sep 17 00:00:00 2001 From: prode Date: Wed, 19 Aug 2026 20:46:11 -0300 Subject: [PATCH] =?UTF-8?q?feat(templates):=20drop=20the=20worktree=20from?= =?UTF-8?q?=20the=20delivery=20rule=20and=20=C2=A79?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Version 15 took the worktree out of the procedure and left `delivery.md` pointing at one anyway — a line preloaded into every request describing a step nothing in the flow performs. How a user arranges several sessions against one repo is theirs to set up, and saying that is enough; the rule keeps only what the worktree was ever really carrying, which is to leave the checkout back on `main` and clean. design/orchestration.md §9 loses the same offer, and "separate checkouts" becomes "separate sessions" where the cost of parallel runs is named. The record that it was rejected stays in §5, §8, and changelog entry 15. Template set 17 -> 18. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01KA9xRzo3xpYLMZjrtRbcge --- design/orchestration.md | 23 +++++++++++---------- internal/assets/assets.go | 8 ++++++- internal/assets/templates/rules/delivery.md | 4 ++-- 3 files changed, 21 insertions(+), 14 deletions(-) diff --git a/design/orchestration.md b/design/orchestration.md index 2ede386..738f394 100644 --- a/design/orchestration.md +++ b/design/orchestration.md @@ -779,15 +779,16 @@ Each unit of work — a spec, or a plan's leaf — gets its own branch, cut from `main` and clean once the work has landed. That last part is the whole discipline: the next unit of work starts where this one did. -**A git worktree is not part of this, and used to be.** It was there for one case — -**the user running several Claude Code sessions at once**, one per feature, each -needing a directory of its own, since a shared tree with `git switch` would have two -sessions fighting over one working directory. That case is real and still supported. -But it is the user's setup to make, once, for the runs they actually parallelize, and -making it a step of the ordinary procedure charged every single-session run for it: a -directory to create, one to switch into, one to remember to remove, and a stale -checkout left behind whenever a run died before the last step. What survives is the -line the worktree was really carrying — leave the checkout clean, on `main`. +**Nothing here needs a second directory, and the procedure used to make one.** It was +there for one case — **the user running several Claude Code sessions at once**, one per +feature, each needing a directory of its own, since a shared tree with `git switch` +would have two sessions fighting over one working directory. That case is real and +still supported, but arranging it is the user's own setup, made once for the runs they +actually parallelize. Making it a step of the ordinary procedure charged every +single-session run for it: a directory to create, one to switch into, one to remember +to remove, and a stale checkout left behind whenever a run died before the last step. +What survives is the line that setup was really carrying — leave the checkout clean, on +`main`. So parallelism is back, and it is worth being precise about why this version is fine when §8's was not. **The user drives this one; the orchestrator drove that one.** Four @@ -808,12 +809,12 @@ within each session the accumulated context prevents it outright. The risk drops ### What running several sessions still costs -Separate checkouts isolate files. They do not isolate the world outside them, so two of +Separate sessions isolate files. They do not isolate the world outside them, so two of these concerns from §8 survive at feature granularity and should be said plainly: - **Shared external resources.** Two sessions running the suite at the same time will fight over a fixed port, one test database, or a shared temp path. Either the suite - namespaces those per checkout, or the test runs have to be serialized. Nothing about + namespaces those per session, or the test runs have to be serialized. Nothing about a separate directory fixes this. - **Cross-feature breakage.** Two features green on their own branches can be broken together. Only CI on `main` after the merge sees that — which is a good reason to diff --git a/internal/assets/assets.go b/internal/assets/assets.go index 7f6d562..33848c6 100644 --- a/internal/assets/assets.go +++ b/internal/assets/assets.go @@ -131,7 +131,13 @@ import ( // pointed at, and what nobody can justify is reported by name instead of filled in. The // ADRs are last and strictest for that reason, and each says in its `## Context` that it // was reconstructed after the fact. -const Version = "17" +// 18: delivery.md stops naming a second-directory setup at all. Version 15 took it out +// of the procedure and left the rule pointing at one anyway, which is the same cost in +// a smaller font: a line preloaded into every request, describing a step nothing in the +// flow performs. How a user arranges several sessions against one repo is theirs, and +// saying so is enough — the rule keeps only what it was ever really carrying, which is +// to leave the checkout back on `main` and clean. +const Version = "18" // The embedded tree. "all:" so nothing is silently dropped for having a name the // default embed pattern skips. diff --git a/internal/assets/templates/rules/delivery.md b/internal/assets/templates/rules/delivery.md index 7d60a48..2a8dd90 100644 --- a/internal/assets/templates/rules/delivery.md +++ b/internal/assets/templates/rules/delivery.md @@ -8,8 +8,8 @@ git switch -c / ``` Branch from a green `main`, and leave the checkout back on `main` and clean once the -work lands. Nothing here needs a second directory: a user running several sessions -against one repo may give each its own `git worktree`, and that is theirs to set up. +work lands. Nothing here needs a second directory: how a user runs several sessions +against one repo at once is theirs to set up. ## Implementation is sequential — you write the code