<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/git-worktrees/">
  <id>https://docs.spec-kitty.ai/architecture/git-worktrees/</id>
  <title>Git Worktrees Explained</title>
  <updated>2026-11-17T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/git-worktrees/"/>
  <summary>What git worktrees are and why Spec Kitty gives each execution lane its own: what worktrees share and keep separate, plus lifecycle commands and crash recovery.</summary>
  <content type="html">&lt;span id=&quot;git-worktrees-explained&quot;&gt;&lt;/span&gt;
&lt;p&gt;Git worktrees are the technology that enables Spec Kitty’s parallel development model. This document explains what worktrees are, why Spec Kitty uses them, and how they work in the modern lane-based execution model.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Naming note:&lt;/strong&gt; a lane worktree path embeds &lt;code dir=&quot;auto&quot;&gt;mid8&lt;/code&gt; — the first 8 characters
of the mission’s ULID &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;, as in &lt;code dir=&quot;auto&quot;&gt;.worktrees/my-feature-01J6XW9K-lane-a/&lt;/code&gt;
— only when the recorded Mission slug itself embeds a mid8. Lane naming keys
on the recorded Mission slug and lane id alone; the Mission identity is
never an input to it (see ADR
&lt;a href=&quot;/adr/3.x/2026-09-26-2-lane-naming-keyed-on-creation-input/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-26-2&lt;/code&gt;&lt;/a&gt;
and &lt;a href=&quot;/architecture/execution-lanes/#naming&quot;&gt;Execution Lanes §Naming&lt;/a&gt;). The legacy
numeric-prefix form &lt;code dir=&quot;auto&quot;&gt;.worktrees/001-my-feature-lane-a/&lt;/code&gt; shown in some
examples below still resolves for pre-083 projects. See the
&lt;a href=&quot;/migrations/mission-id-canonical-identity/&quot;&gt;mission identity migration runbook&lt;/a&gt;
for upgrade steps.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;what-is-a-git-worktree&quot;&gt;What is a Git Worktree?&lt;/h2&gt;
&lt;p&gt;A git worktree is a linked working directory that lets you check out multiple branches simultaneously, each in its own directory. Unlike cloning a repository multiple times, all worktrees share the same &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; directory and repository history.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Normal git workflow&lt;/strong&gt; (one branch at a time):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# You can only have one branch checked out&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;checkout&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# To work on feature-b, you must switch branches&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;checkout&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Now you&apos;re on feature-b, feature-a is gone&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;With worktrees&lt;/strong&gt; (multiple branches simultaneously):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Main repo stays on main branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;my-repo/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;               &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# main branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Each worktree has its own branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;.worktrees/feature-a/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# feature-a branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;.worktrees/feature-b/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# feature-b branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;You can now have three terminal windows open, each in a different directory, each on a different branch, all editing the same repository.&lt;/p&gt;
&lt;h2 id=&quot;why-does-spec-kitty-use-worktrees&quot;&gt;Why Does Spec Kitty Use Worktrees?&lt;/h2&gt;
&lt;h3 id=&quot;parallel-development-without-branch-switching&quot;&gt;Parallel Development Without Branch Switching&lt;/h3&gt;
&lt;p&gt;Without worktrees, only one developer (or agent) can work at a time because git only allows one branch checked out per repository. With worktrees:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agent A works in &lt;code dir=&quot;auto&quot;&gt;.worktrees/feature-lane-a/&lt;/code&gt; on the WPs assigned to lane A&lt;/li&gt;
&lt;li&gt;Agent B works in &lt;code dir=&quot;auto&quot;&gt;.worktrees/feature-lane-b/&lt;/code&gt; on the WPs assigned to lane B&lt;/li&gt;
&lt;li&gt;Agent C works in &lt;code dir=&quot;auto&quot;&gt;.worktrees/feature-lane-c/&lt;/code&gt; on the WPs assigned to lane C&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All three agents work simultaneously, each with their own files, their own uncommitted changes, and their own branch.&lt;/p&gt;
&lt;h3 id=&quot;each-execution-lane-gets-an-isolated-workspace&quot;&gt;Each Execution Lane Gets an Isolated Workspace&lt;/h3&gt;
&lt;p&gt;Problems with shared workspaces:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agent A edits &lt;code dir=&quot;auto&quot;&gt;config.py&lt;/code&gt;, breaks it&lt;/li&gt;
&lt;li&gt;Agent B (working on unrelated task) tries to run tests—they fail&lt;/li&gt;
&lt;li&gt;Both agents are now debugging each other’s problems&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;With lane-based execution workspaces:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agent A’s broken &lt;code dir=&quot;auto&quot;&gt;config.py&lt;/code&gt; only exists in lane A’s workspace&lt;/li&gt;
&lt;li&gt;Agent B’s workspace has clean files&lt;/li&gt;
&lt;li&gt;Isolation prevents cross-contamination&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;multiple-agents-can-work-simultaneously&quot;&gt;Multiple Agents Can Work Simultaneously&lt;/h3&gt;
&lt;p&gt;Spec Kitty’s parallel model requires:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Multiple independent branches&lt;/li&gt;
&lt;li&gt;Multiple independent working directories&lt;/li&gt;
&lt;li&gt;Shared repository history (for merging later)&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Git worktrees provide all three.&lt;/p&gt;
&lt;h2 id=&quot;how-worktrees-work&quot;&gt;How Worktrees Work&lt;/h2&gt;
&lt;h3 id=&quot;the-git-directory&quot;&gt;The .git Directory&lt;/h3&gt;
&lt;p&gt;When you clone a repository, git creates a &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; directory containing:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;All commits&lt;/li&gt;
&lt;li&gt;All branches&lt;/li&gt;
&lt;li&gt;All tags&lt;/li&gt;
&lt;li&gt;Repository configuration&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A worktree doesn’t duplicate this. Instead, it creates a small file that points back to the main &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; directory.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;my-repo/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── .git/                     # The real git database&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── src/                      # Your source files&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├── .worktrees/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   ├── feature-lane-a/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   │   ├── .git              # Just a pointer file&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   │   └── src/              # Separate copy of source files&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│   └── feature-lane-b/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│       ├── .git              # Just a pointer file&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│       └── src/              # Another separate copy&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;what-worktrees-share&quot;&gt;What Worktrees Share&lt;/h3&gt;
&lt;p&gt;All worktrees share:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Commit history (all commits are in one place)&lt;/li&gt;
&lt;li&gt;Branch definitions (branches exist in main &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Configuration (global git settings)&lt;/li&gt;
&lt;li&gt;Remote references (origin, upstream, etc.)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-worktrees-dont-share&quot;&gt;What Worktrees Don’t Share&lt;/h3&gt;
&lt;p&gt;Each worktree has its own:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Working directory (files on disk)&lt;/li&gt;
&lt;li&gt;Index (staging area)&lt;/li&gt;
&lt;li&gt;Current HEAD (which commit is checked out)&lt;/li&gt;
&lt;li&gt;Uncommitted changes&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This means Agent A can have uncommitted changes to &lt;code dir=&quot;auto&quot;&gt;config.py&lt;/code&gt; without affecting Agent B’s &lt;code dir=&quot;auto&quot;&gt;config.py&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;cross-mission-concurrency-is-a-different-question&quot;&gt;Cross-Mission Concurrency Is a Different Question&lt;/h3&gt;
&lt;p&gt;Worktree isolation covers &lt;strong&gt;lanes within one mission&lt;/strong&gt; — each lane worktree
has its own HEAD, index, and working directory, so parallel WPs in the same
mission cannot collide. It does &lt;strong&gt;not&lt;/strong&gt; cover &lt;strong&gt;two different missions
sharing the same primary checkout&lt;/strong&gt;. Mission-lifecycle commands (&lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt;, status commits, &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt;, backfill-topology) run against the
primary checkout’s HEAD, branch, and index — the same ones every worktree’s
&lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt; file ultimately points back to — and there is no cross-mission lock
around those mutations. Two mission drivers issuing git operations from the
same primary checkout at the same time can interleave commits onto each
other’s branch tips or strand commits on the wrong branch.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; also cannot be run from inside a worktree, so a second
concurrent mission cannot cleanly sidestep the primary checkout that way. If
you need two missions active at once, use a &lt;strong&gt;separate clone&lt;/strong&gt; (its own
&lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt;) for the second mission rather than assuming worktrees provide
enough isolation — worktree isolation is per-lane-within-a-mission, not
per-mission.&lt;/p&gt;
&lt;h2 id=&quot;worktrees-vs-cloning&quot;&gt;Worktrees vs. Cloning&lt;/h2&gt;








































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Aspect&lt;/th&gt;&lt;th&gt;Worktree&lt;/th&gt;&lt;th&gt;Clone&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Repository data&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Shared&lt;/td&gt;&lt;td&gt;Duplicated&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Disk space&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Minimal&lt;/td&gt;&lt;td&gt;Full copy&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Branches&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Shared&lt;/td&gt;&lt;td&gt;Independent&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Fetching/pushing&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Once for all&lt;/td&gt;&lt;td&gt;Once per clone&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Merging between&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Direct (same repo)&lt;/td&gt;&lt;td&gt;Requires remote&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Independence&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Partial&lt;/td&gt;&lt;td&gt;Complete&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Use worktrees when&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Working on the same project&lt;/li&gt;
&lt;li&gt;Need to merge branches together later&lt;/li&gt;
&lt;li&gt;Want to minimize disk usage&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Use clones when&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Working on different projects&lt;/li&gt;
&lt;li&gt;Complete isolation is required&lt;/li&gt;
&lt;li&gt;May never merge together&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;git-commands-for-worktrees&quot;&gt;Git Commands for Worktrees&lt;/h2&gt;
&lt;h3 id=&quot;list-all-worktrees&quot;&gt;List All Worktrees&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Example output:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/path/to/my-repo               abc1234 [main]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/path/to/my-repo/.worktrees/feature-lane-a  def5678 [feature-lane-a]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/path/to/my-repo/.worktrees/feature-lane-b  ghi9012 [feature-lane-b]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;create-a-new-worktree&quot;&gt;Create a New Worktree&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Create worktree with existing branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Create worktree and create new branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-lane-a&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Create worktree from specific commit/branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-lane-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;remove-a-worktree&quot;&gt;Remove a Worktree&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Clean removal (worktree must be clean)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;remove&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Force removal (discards uncommitted changes)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;remove&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;clean-up-stale-worktrees&quot;&gt;Clean Up Stale Worktrees&lt;/h3&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Prune worktrees whose directories no longer exist&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;prune&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;worktree-vocabulary&quot;&gt;Worktree Vocabulary&lt;/h2&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Checkout&lt;/th&gt;&lt;th&gt;What it holds&lt;/th&gt;&lt;th&gt;Disposable?&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Repository root checkout&lt;/td&gt;&lt;td&gt;The operator’s working copy; for a default Mission before settlement, the write checkout on the &lt;a href=&quot;/context/topology/#topic-branch&quot;&gt;topic branch&lt;/a&gt;&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Write checkout&lt;/td&gt;&lt;td&gt;The one checkout a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; Mission writes code and status into&lt;/td&gt;&lt;td&gt;No while a WP is &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Lane worktree (&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-lane-&amp;#x3C;id&gt;&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;One code lane’s branch; no status files&lt;/td&gt;&lt;td&gt;Yes: &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; removes it as its last step&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Coordination worktree&lt;/td&gt;&lt;td&gt;The coordination branch, where status is written&lt;/td&gt;&lt;td&gt;Yes: torn down with the coordination branch and marker as one unit&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Merge scratch worktree (&lt;code dir=&quot;auto&quot;&gt;.kittify/runtime/merge/&amp;#x3C;id&gt;/workspace&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Consolidation’s internal scratch tree&lt;/td&gt;&lt;td&gt;Always cleaned up&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Status is never read from a lane worktree. Every reader goes through the one status read door (&lt;code dir=&quot;auto&quot;&gt;status/read_surface.py::resolve_status_read&lt;/code&gt;, ADR &lt;a href=&quot;/adr/4.x/2026-11-06-2-one-status-read-contract/&quot;&gt;4.x &lt;code dir=&quot;auto&quot;&gt;2026-11-06-2&lt;/code&gt;&lt;/a&gt;); from the CLI, use &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks status&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;lane-checkouts-hide-status&quot;&gt;Lane checkouts hide status&lt;/h2&gt;
&lt;p&gt;A lane worktree is a full checkout except for the Mission’s &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;, which a managed sparse exclusion keeps out. Every new lane checkout gets it from &lt;code dir=&quot;auto&quot;&gt;lanes/lane_checkout.py::open_lane_checkout&lt;/code&gt;. Isolation of code is otherwise enforced by lane computation, ownership metadata, workspace context and consolidation guards, and agents stay inside the files owned by the active WP and lane.&lt;/p&gt;
&lt;p&gt;Lane worktrees that already exist are brought in line by the clone-local migration &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_lane_checkout_status_exclusion&lt;/code&gt; (run by &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;). It finds them through the git worktree registry and reports one outcome per worktree:&lt;/p&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Outcome&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;excluded&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A clean copy; the exclusion is applied and the files leave the disk&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;flagged_redundant&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A dirty copy whose every event is already on the status surface; the exclusion is applied and git keeps the modified file on disk&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;refused_lane_only_events&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A dirty copy holding events found nowhere else; the worktree is left untouched and the event ids are reported&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;skipped_mid_operation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A merge, rebase or cherry-pick is in progress&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;already_excluded&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Nothing to do&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;skipped_legacy_mission&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A genuinely-legacy Mission (no coordination branch, no stored topology, not flattened) writes its status into the lane checkout, so the lane is left untouched&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;While any lane is &lt;code dir=&quot;auto&quot;&gt;refused_lane_only_events&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;skipped_mid_operation&lt;/code&gt;, the migration is skipped and selected again on the next upgrade. &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor sparse-checkout&lt;/code&gt; reports each such lane as &lt;code dir=&quot;auto&quot;&gt;LANE_STATUS_NOT_EXCLUDED&lt;/code&gt; with its remedy: for lane-only events, record each transition on the status surface with &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks move-task&lt;/code&gt;, discard the lane copy’s change to the two status files, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;consolidate-reads-git-state-through-a-run-scoped-cache&quot;&gt;Consolidate reads git state through a run-scoped cache&lt;/h2&gt;
&lt;p&gt;A consolidation run asks git the same questions many times across the repository root checkout, the coordination worktree and the lane worktrees. Examples are which branch a checkout holds, which worktree holds a branch, a branch’s tip, and the remote’s default branch. Since #7689, &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt; answers repeats from a cache that lives only for that one run (&lt;code dir=&quot;auto&quot;&gt;kernel/git/read_cache.py&lt;/code&gt;, entered by &lt;code dir=&quot;auto&quot;&gt;run_consolidate&lt;/code&gt;). No other command turns it on, and outside the run every read spawns git as before.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What decides whether an answer is reused.&lt;/strong&gt; Each cached read declares which git files its answer depends on: one ref, the checkout’s &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;, the repository config, or, for &lt;code dir=&quot;auto&quot;&gt;git worktree list&lt;/code&gt;, the whole metadata tree. Before reusing an answer, the cache re-reads those files’ bytes without spawning git. It reuses the answer only if the bytes are identical, comparing content and never timestamps. Any ref update, branch switch, worktree add or remove, config write or &lt;code dir=&quot;auto&quot;&gt;pack-refs&lt;/code&gt; therefore changes the bytes and forces git to run again, whoever made the change.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What may be cached.&lt;/strong&gt; Only a read whose answer is a pure function of git metadata files may use the cache. Never cache a read of the working tree or the index (&lt;code dir=&quot;auto&quot;&gt;git status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;git diff&lt;/code&gt;, file contents): their answer is not in the files the cache watches.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;When the cache stands aside.&lt;/strong&gt; Every read runs uncached, exactly as without the cache, in these cases:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;outside a consolidate run;&lt;/li&gt;
&lt;li&gt;when a &lt;code dir=&quot;auto&quot;&gt;GIT_DIR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;GIT_COMMON_DIR&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;GIT_WORK_TREE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;GIT_NAMESPACE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;GIT_OBJECT_DIRECTORY&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;GIT_CONFIG&lt;/code&gt; variable redirects git;&lt;/li&gt;
&lt;li&gt;when the repository cannot be located from the read’s directory;&lt;/li&gt;
&lt;li&gt;when the repository stores refs in &lt;strong&gt;reftable&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;extensions.refStorage = reftable&lt;/code&gt;), whose layout the cache does not model yet.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Safety-relevant reads.&lt;/strong&gt; Rollback’s read of a branch’s live tip may be answered from the cache, but the restore itself is a compare-and-swap &lt;code dir=&quot;auto&quot;&gt;update-ref&lt;/code&gt;: git, not the cache, enforces the expected old value. A failed lookup of the remote’s default branch (an unreachable remote) is never stored, so the next protection-policy resolution asks again.&lt;/p&gt;
&lt;h2 id=&quot;common-issues&quot;&gt;Common Issues&lt;/h2&gt;
&lt;h3 id=&quot;worktree-already-exists&quot;&gt;“Worktree already exists”&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Error&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;fatal: &apos;feature-lane-a&apos; already has a worktree at &apos;.worktrees/feature-lane-a&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Cause&lt;/strong&gt;: You’re trying to create a worktree for a branch that’s already checked out somewhere.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Solution&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Find where it&apos;s checked out&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Either remove the existing worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;remove&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Or use that existing worktree instead&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/feature-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;branch-is-already-checked-out&quot;&gt;“Branch is already checked out”&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Error&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;fatal: &apos;feature-lane-a&apos; is already checked out at &apos;/path/to/other/worktree&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Cause&lt;/strong&gt;: Git won’t let two worktrees have the same branch checked out.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Solution&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Find the other worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Remove it if not needed&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;remove&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/path/to/other/worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Or work in the existing worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/path/to/other/worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;cleanup-after-crashes&quot;&gt;Cleanup After Crashes&lt;/h3&gt;
&lt;p&gt;If Spec Kitty or your system crashes mid-operation, worktrees may be left in an inconsistent state.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Symptoms&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;git worktree list&lt;/code&gt; shows non-existent directories&lt;/li&gt;
&lt;li&gt;Errors about locked worktrees&lt;/li&gt;
&lt;li&gt;Can’t create new worktrees&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Solution&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Clean up stale worktree references&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;prune&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Force unlock if needed&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;unlock&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/stuck-worktree&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Verify cleanup&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;head-detached-in-worktree&quot;&gt;HEAD Detached in Worktree&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Symptom&lt;/strong&gt;: Commits in worktree aren’t on any branch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cause&lt;/strong&gt;: Worktree was created from a commit, not a branch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Solution&lt;/strong&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/my-feature-01J6XW9K-lane-a&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;checkout&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-b&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;kitty/mission-my-feature-01J6XW9K-lane-a&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Create and switch to branch&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;further-reading&quot;&gt;Further Reading&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://git-scm.com/docs/git-worktree&quot;&gt;Git Worktree Documentation&lt;/a&gt; - Official git documentation&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;Execution Lanes&lt;/a&gt; - How Spec Kitty uses worktrees&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/branch-target-routing/&quot;&gt;Branch-Target Routing&lt;/a&gt; - Where each diff type lands (planning, status, code, docs) and the simple-case flat collapse when no lanes are configured&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/spec-driven-development/&quot;&gt;Spec-Driven Development&lt;/a&gt; - The methodology that requires parallel work&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/kanban-workflow/&quot;&gt;Kanban Workflow&lt;/a&gt; - How work progresses through lanes&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;This document explains git worktrees for understanding. For practical steps in Spec Kitty, see the how-to guides.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;try-it&quot;&gt;Try It&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/tutorials/claude-code-workflow/&quot;&gt;Claude Code Workflow&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;how-to-guides&quot;&gt;How-To Guides&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-and-upgrade/&quot;&gt;Upgrade to 0.11.0&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-spec-kitty/&quot;&gt;Install Spec Kitty&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;reference&quot;&gt;Reference&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/api/file-structure/&quot;&gt;File Structure&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/cli-commands/&quot;&gt;CLI Commands&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
