Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions design/orchestration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
8 changes: 7 additions & 1 deletion internal/assets/assets.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions internal/assets/templates/rules/delivery.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ git switch -c <type>/<slug>
```

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

Expand Down
Loading