<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/guides/how-to/missions/keep-main-clean/">
  <id>https://docs.spec-kitty.ai/guides/how-to/missions/keep-main-clean/</id>
  <title>How to Keep Main Clean</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/guides/how-to/missions/keep-main-clean/"/>
  <summary>How to keep main clean with Spec Kitty 3.2: Use this guide when you want planning to happen from the repository root checkout but you do not want the.</summary>
  <content type="html">&lt;span id=&quot;how-to-keep-main-clean&quot;&gt;&lt;/span&gt;
&lt;p&gt;Use this guide when you want planning to happen from the repository root checkout but you do not want the mission to target &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;know-the-three-moving-parts&quot;&gt;Know the Three Moving Parts&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;repository root checkout&lt;/code&gt;: where &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.plan&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt; run&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;target branch&lt;/code&gt;: the branch the mission records planning artifacts and merge intent against&lt;/li&gt;
&lt;li&gt;worktrees: the per-work-package execution checkouts used during implementation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Planning location and target branch are separate choices. Running from the repository root checkout does not force &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;start-on-an-existing-branch-and-keep-it-as-the-target&quot;&gt;Start on an Existing Branch and Keep It as the Target&lt;/h2&gt;
&lt;p&gt;If you are already on the branch that should receive the feature, verify the branch contract first:&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&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;agent&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;mission&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;branch-context&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;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If the JSON shows the current branch, &lt;code dir=&quot;auto&quot;&gt;planning_base_branch&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;merge_target_branch&lt;/code&gt; all pointing at the branch you want, run &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; normally from the repository root checkout.&lt;/p&gt;
&lt;p&gt;This is the simplest way to keep &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; clean: start from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, your release branch, or your mission integration branch before planning begins.&lt;/p&gt;
&lt;h2 id=&quot;pick-an-explicit-target-branch&quot;&gt;Pick an Explicit target branch&lt;/h2&gt;
&lt;p&gt;If you want to plan from the repository root checkout but land somewhere other than the current branch, name it explicitly:&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&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;agent&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;mission&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;branch-context&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;--json&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;--target-branch&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;develop&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;spec-kitty&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;agent&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;mission&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;create&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;new-dashboard&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&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;--target-branch&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;develop&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;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The packaged &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; prompt now tells the agent to restate:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the current branch&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planning_base_branch&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;merge_target_branch&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;whether the current checkout matches the intended target&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If those values do not match the branch you want, the agent should stop and confirm before it creates artifacts.&lt;/p&gt;
&lt;h2 id=&quot;use-main-only-when-you-mean-main&quot;&gt;Use &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; Only When You Mean &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;If the feature should actually land on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, either:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;start from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; and let the default current-branch behavior apply, or&lt;/li&gt;
&lt;li&gt;pass &lt;code dir=&quot;auto&quot;&gt;--target-branch main&lt;/code&gt; explicitly&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Do not treat &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; as a synonym for “the repository root checkout.”&lt;/p&gt;
&lt;h2 id=&quot;plan-in-the-repository-root-checkout-implement-in-worktrees&quot;&gt;Plan in the repository root checkout, Implement in Worktrees&lt;/h2&gt;
&lt;p&gt;The normal flow is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Run &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.plan&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt; from the repository root checkout.&lt;/li&gt;
&lt;li&gt;Let those commands create and commit planning artifacts on the mission’s target branch.&lt;/li&gt;
&lt;li&gt;Start implementation with &lt;code dir=&quot;auto&quot;&gt;spec-kitty next --agent &amp;#x3C;agent&gt; --mission &amp;#x3C;handle&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Let Spec Kitty allocate or reuse per-lane worktrees for the work packages.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;If you need to inspect the recorded branch contract later, use:&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&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;agent&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;mission&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;branch-context&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;--json&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;--target-branch&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;&amp;#x3C;branch&gt;&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;override-the-merge-target-only-intentionally&quot;&gt;Override the Merge Target Only Intentionally&lt;/h2&gt;
&lt;p&gt;By default, &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge&lt;/code&gt; lands in the mission’s recorded target branch.&lt;/p&gt;
&lt;p&gt;Use this only when you intentionally need a different destination:&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:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&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;merge&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;--target&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;main&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If you are reaching for &lt;code dir=&quot;auto&quot;&gt;--target&lt;/code&gt;, confirm first that the mission was not simply created against the wrong target branch.&lt;/p&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;h3 id=&quot;im-in-the-repository-root-checkout-but-i-do-not-want-main&quot;&gt;I’m in the repository root checkout but I do not want &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Stay in the repository root checkout. Change the branch intent, not the location:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;check out the branch you actually want before &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;, or&lt;/li&gt;
&lt;li&gt;pass &lt;code dir=&quot;auto&quot;&gt;--target-branch &amp;#x3C;branch&gt;&lt;/code&gt; when resolving branch context or creating the mission&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;why-am-i-being-told-to-switch-branches&quot;&gt;Why am I being told to switch branches?&lt;/h3&gt;
&lt;p&gt;Because the current checkout branch and the intended target branch do not match.&lt;/p&gt;
&lt;p&gt;The planning prompts now use &lt;code dir=&quot;auto&quot;&gt;branch-context --json&lt;/code&gt; and should restate that mismatch. If the restated &lt;code dir=&quot;auto&quot;&gt;planning_base_branch&lt;/code&gt; is wrong, stop and pick the right target before creating more artifacts.&lt;/p&gt;
&lt;h3 id=&quot;how-do-i-plan-on-one-branch-and-implement-in-worktrees&quot;&gt;How do I plan on one branch and implement in worktrees?&lt;/h3&gt;
&lt;p&gt;Keep planning in the repository root checkout on the mission’s target branch. After &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.tasks&lt;/code&gt;, use &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement ...&lt;/code&gt; and let the CLI create worktrees for the execution lanes.&lt;/p&gt;
&lt;p&gt;The worktrees are for implementation only. They do not replace the repository root checkout as the planning location.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/create-specification/&quot;&gt;Create a Specification&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/create-plan/&quot;&gt;Create a Plan&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/generate-tasks/&quot;&gt;Generate Tasks&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/merge-mission/&quot;&gt;Merge a Feature&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
