<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-01-29-17-auto-create-target-branch-on-first-implement/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-29-17-auto-create-target-branch-on-first-implement/</id>
  <title>Auto-Create Target Branch on First Implement</title>
  <updated>2026-01-29T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-01-29-17-auto-create-target-branch-on-first-implement/"/>
  <summary>Broke the bootstrap paradox by creating a missing target branch on the first implement call, which removed the hand-written branch-creation task from WP01.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Superseded on 2026-04-05 by
&lt;code dir=&quot;auto&quot;&gt;2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;.
The lane-only runtime no longer falls back to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; or auto-creates an
arbitrary target branch during &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;. Features are expected to target an
existing planning branch, and runtime-created execution branches are the
mission branch plus its lane branches.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;When a feature targets a non-existent branch (e.g., Feature 002 → 3.x), we have a bootstrap paradox:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The Problem:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Feature metadata says: &lt;code dir=&quot;auto&quot;&gt;target_branch: &quot;3.x&quot;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Branch 3.x doesn’t exist yet&lt;/li&gt;
&lt;li&gt;LLM planning agent creates WP01 with task: “T001: Create 3.x branch”&lt;/li&gt;
&lt;li&gt;Implementing agent runs: &lt;code dir=&quot;auto&quot;&gt;spec-kitty implement WP01&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;spec-kitty creates worktree from main (fallback, because 3.x missing)&lt;/li&gt;
&lt;li&gt;Agent is on WP01 branch, prompt says “Create 3.x”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Confusion:&lt;/strong&gt; “How do I create 3.x from inside WP01 worktree?”&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Current fallback behavior:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP01 branches from main (safe degradation)&lt;/li&gt;
&lt;li&gt;Status commits try 3.x, fallback to main with warning&lt;/li&gt;
&lt;li&gt;Branch 3.x never gets created (nobody owns this responsibility)&lt;/li&gt;
&lt;li&gt;Agent confused about workflow&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Question:&lt;/strong&gt; Should spec-kitty &lt;strong&gt;automatically create the target branch&lt;/strong&gt; when implementing the first WP if the branch doesn’t exist?&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Eliminate bootstrap paradox&lt;/strong&gt; - Remove “Create branch” from WP01’s responsibilities&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Just-in-time creation&lt;/strong&gt; - Create branch when first needed (implement), not earlier&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Automatic&lt;/strong&gt; - No user prompts or manual steps required&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Correct routing&lt;/strong&gt; - Enable status commits to route to target_branch from the start&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clear ownership&lt;/strong&gt; - spec-kitty creates infrastructure, WPs create features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agent-friendly&lt;/strong&gt; - Remove confusing bootstrap tasks from WP prompts&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Auto-create target branch during first implement (just-in-time)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Auto-create during /spec-kitty.specify (early creation)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Document bootstrap workflow in WP01 prompt (manual instructions)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Remove branch creation from WP01, require manual creation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 5:&lt;/strong&gt; Status quo (fallback to main, WP01 creates branch manually)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 1: Auto-create during first implement”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Just-in-time (creates branch when first needed)&lt;/li&gt;
&lt;li&gt;Automatic (no user prompts, no manual steps)&lt;/li&gt;
&lt;li&gt;Eliminates bootstrap task from WP01 (cleaner prompts)&lt;/li&gt;
&lt;li&gt;Enables correct routing from the start&lt;/li&gt;
&lt;li&gt;Clear ownership (spec-kitty creates infrastructure)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Bootstrap paradox eliminated&lt;/strong&gt; - WP01 doesn’t need “Create 3.x” task&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Automatic&lt;/strong&gt; - No user prompts or manual steps&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Just-in-time&lt;/strong&gt; - Branch created when first implement runs&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Correct routing&lt;/strong&gt; - Status commits go to target_branch from WP01 onward&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agent-friendly&lt;/strong&gt; - Clear workflow, no confusing bootstrap instructions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Separation of concerns&lt;/strong&gt; - spec-kitty creates infrastructure, WPs create features&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Implicit branch creation&lt;/strong&gt; - Users might not notice branch was created&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Naming conflicts&lt;/strong&gt; - What if branch name already exists? (check and error)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No user choice&lt;/strong&gt; - Branch created automatically (cannot opt-out)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Magic behavior&lt;/strong&gt; - Branch appears without explicit user action&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Creation location&lt;/strong&gt; - &lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;target&gt; main&lt;/code&gt; in main repo before worktree creation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Timing&lt;/strong&gt; - Only on FIRST implement for feature (subsequent WPs find existing branch)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Message&lt;/strong&gt; - Console: “[cyan]Creating target branch: 3.x[/cyan]”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fallback&lt;/strong&gt; - If creation fails (conflict, permissions), fall back to main&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We’ll validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;✅ Feature 002 WP01 implements without manual branch creation&lt;/li&gt;
&lt;li&gt;✅ Status commits route to 3.x (not fallback to main)&lt;/li&gt;
&lt;li&gt;✅ WP01 prompt doesn’t mention “Create branch”&lt;/li&gt;
&lt;li&gt;✅ Tests: test_auto_create_target_branch_on_implement&lt;/li&gt;
&lt;li&gt;✅ No errors when target_branch already exists (idempotent)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-auto-create-during-first-implement-chosen&quot;&gt;Option 1: Auto-create during first implement (CHOSEN)&lt;/h3&gt;
&lt;p&gt;Just-in-time: Create target branch automatically when first WP is implemented.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Automatic (no user input)&lt;/li&gt;
&lt;li&gt;Just-in-time (created when needed)&lt;/li&gt;
&lt;li&gt;Eliminates bootstrap task from WP01&lt;/li&gt;
&lt;li&gt;Enables correct routing immediately&lt;/li&gt;
&lt;li&gt;Clear ownership (tool creates infrastructure)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Implicit (might surprise users)&lt;/li&gt;
&lt;li&gt;No opt-out mechanism&lt;/li&gt;
&lt;li&gt;Naming conflict risk (must check existence)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-auto-create-during-spec-kittyspecify&quot;&gt;Option 2: Auto-create during /spec-kitty.specify&lt;/h3&gt;
&lt;p&gt;Early creation: Create target branch when feature is specified.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Branch exists before any implementation&lt;/li&gt;
&lt;li&gt;Explicit timing (during specify)&lt;/li&gt;
&lt;li&gt;No bootstrap paradox&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Creates branch too early (might not be needed)&lt;/li&gt;
&lt;li&gt;Requires user prompt (“Create 3.x now?”)&lt;/li&gt;
&lt;li&gt;Specify becomes interactive (slower)&lt;/li&gt;
&lt;li&gt;Branch created even if feature never implemented&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-document-bootstrap-workflow&quot;&gt;Option 3: Document bootstrap workflow&lt;/h3&gt;
&lt;p&gt;Instruct agent in WP01 prompt how to create branch manually.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Explicit instructions&lt;/li&gt;
&lt;li&gt;Agent has control&lt;/li&gt;
&lt;li&gt;No code changes&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Complex workflow (worktree → main repo → worktree)&lt;/li&gt;
&lt;li&gt;Error-prone (agent must get steps right)&lt;/li&gt;
&lt;li&gt;Confusing (not standard WP workflow)&lt;/li&gt;
&lt;li&gt;Still manual (defeats automation)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-remove-from-wp01-require-manual-creation&quot;&gt;Option 4: Remove from WP01, require manual creation&lt;/h3&gt;
&lt;p&gt;Don’t assign branch creation to WP01, require user to create manually.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Clean separation (WP01 focuses on features)&lt;/li&gt;
&lt;li&gt;User has control&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Manual step (user must remember)&lt;/li&gt;
&lt;li&gt;Easy to forget (causes fallback)&lt;/li&gt;
&lt;li&gt;Not automated&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-5-status-quo-fallback-to-main&quot;&gt;Option 5: Status quo (fallback to main)&lt;/h3&gt;
&lt;p&gt;Keep current behavior, let WP01 create branch manually if needed.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No changes needed&lt;/li&gt;
&lt;li&gt;Graceful degradation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Bootstrap paradox persists&lt;/li&gt;
&lt;li&gt;Agent confusion continues&lt;/li&gt;
&lt;li&gt;Fallback routing (not ideal)&lt;/li&gt;
&lt;li&gt;Manual branch creation required&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Implementation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/implement.py&lt;/code&gt; (auto-create logic before worktree creation)&lt;/li&gt;
&lt;li&gt;Check branch existence: &lt;code dir=&quot;auto&quot;&gt;git rev-parse --verify &amp;#x3C;branch&gt;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Create branch: &lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;target&gt; main&lt;/code&gt; (from main as base)&lt;/li&gt;
&lt;li&gt;Error handling: If branch exists, proceed normally; if creation fails, fallback to main&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Tests (to be written):&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_auto_create_target_branch_on_first_implement&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_subsequent_implement_uses_existing_target&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_auto_create_fails_gracefully_on_conflict&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_target_branch_routing_after_auto_create&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Affected Workflows:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Feature 002, 003, 004 in ~/tmp (all have non-existent targets)&lt;/li&gt;
&lt;li&gt;Any future feature targeting a new branch&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR-13: Target Branch Routing (uses target_branch for status commits)&lt;/li&gt;
&lt;li&gt;ADR-14: Explicit Metadata Fields (target_branch always set)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Version:&lt;/strong&gt; To be implemented in 0.13.9 or 0.14.0&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pattern:&lt;/strong&gt; “Just-in-Time Infrastructure Creation” - Let tool create infrastructure automatically when first needed&lt;/p&gt;</content>
</entry>
